@agent-watch-ai/edge 0.5.0 → 0.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (298) hide show
  1. package/CHANGELOG.md +238 -7
  2. package/README.md +308 -8
  3. package/dist/billing/billing-mode.d.ts +37 -5
  4. package/dist/billing/billing-mode.js +28 -19
  5. package/dist/billing/constants/billing.constants.d.ts +0 -2
  6. package/dist/billing/constants/billing.constants.js +0 -2
  7. package/dist/billing/index.d.ts +2 -1
  8. package/dist/billing/index.js +1 -1
  9. package/dist/billing/session-billing.d.ts +3 -2
  10. package/dist/billing/session-billing.js +8 -8
  11. package/dist/billing/types/billing.types.d.ts +7 -0
  12. package/dist/capture/capture-env.d.ts +147 -0
  13. package/dist/capture/capture-env.js +301 -0
  14. package/dist/capture/captured-step.d.ts +88 -0
  15. package/dist/capture/captured-step.js +479 -0
  16. package/dist/capture/constants/capture.constants.d.ts +70 -0
  17. package/dist/capture/constants/capture.constants.js +72 -0
  18. package/dist/capture/launched-runs.d.ts +16 -0
  19. package/dist/capture/launched-runs.js +151 -0
  20. package/dist/capture/node.cjs +697 -0
  21. package/dist/capture/node.d.cts +32 -0
  22. package/dist/capture/python/sitecustomize.py +823 -0
  23. package/dist/capture/schemas/capture.schema.d.ts +35 -0
  24. package/dist/capture/schemas/capture.schema.js +31 -0
  25. package/dist/capture/types/capture.types.d.ts +20 -0
  26. package/dist/cli/constants/cli.constants.d.ts +2 -6
  27. package/dist/cli/constants/cli.constants.js +3 -7
  28. package/dist/cli/context.d.ts +19 -22
  29. package/dist/cli/context.js +23 -54
  30. package/dist/cli/doctor-run-capture.d.ts +13 -0
  31. package/dist/cli/doctor-run-capture.js +19 -0
  32. package/dist/cli/doctor.js +16 -67
  33. package/dist/cli/hook.d.ts +14 -0
  34. package/dist/cli/hook.js +40 -0
  35. package/dist/cli/index.d.ts +1 -1
  36. package/dist/cli/index.js +1 -1
  37. package/dist/cli/misc.js +10 -2
  38. package/dist/cli/replay.d.ts +33 -0
  39. package/dist/cli/replay.js +193 -0
  40. package/dist/cli/setup.d.ts +10 -2
  41. package/dist/cli/setup.js +154 -26
  42. package/dist/cli/status.js +45 -5
  43. package/dist/cli/toggle.js +10 -0
  44. package/dist/cli/types/cli.types.d.ts +15 -1
  45. package/dist/cli/uninstall.js +8 -22
  46. package/dist/cli.js +104 -17
  47. package/dist/config/config.d.ts +0 -2
  48. package/dist/config/config.js +0 -1
  49. package/dist/config/constants/config.constants.js +2 -0
  50. package/dist/config/events-transport.d.ts +15 -0
  51. package/dist/config/events-transport.js +29 -0
  52. package/dist/config/index.d.ts +2 -1
  53. package/dist/config/index.js +1 -0
  54. package/dist/config/root-config.d.ts +12 -0
  55. package/dist/config/root-config.js +24 -0
  56. package/dist/config/schemas/config.schema.d.ts +13 -0
  57. package/dist/config/schemas/config.schema.js +42 -6
  58. package/dist/config/types/config.types.d.ts +7 -0
  59. package/dist/core/index.d.ts +1 -1
  60. package/dist/core/index.js +1 -1
  61. package/dist/core/version.d.ts +9 -0
  62. package/dist/core/version.js +14 -0
  63. package/dist/core/which.d.ts +11 -0
  64. package/dist/core/which.js +18 -0
  65. package/dist/credentials/cloud-claim.d.ts +32 -0
  66. package/dist/credentials/cloud-claim.js +42 -0
  67. package/dist/credentials/constants/credentials.constants.d.ts +8 -1
  68. package/dist/credentials/constants/credentials.constants.js +9 -2
  69. package/dist/credentials/device-api.d.ts +15 -1
  70. package/dist/credentials/device-api.js +12 -1
  71. package/dist/credentials/sign-in.d.ts +27 -0
  72. package/dist/credentials/sign-in.js +31 -1
  73. package/dist/credentials/token-refresher.d.ts +5 -1
  74. package/dist/credentials/token-refresher.js +10 -2
  75. package/dist/events/constants/events.constants.d.ts +8 -2
  76. package/dist/events/constants/events.constants.js +7 -1
  77. package/dist/events/index.d.ts +2 -0
  78. package/dist/events/product-event.d.ts +10 -4
  79. package/dist/events/types/events.types.d.ts +6 -0
  80. package/dist/events/types/replay-progress.types.d.ts +26 -0
  81. package/dist/events/types/replay-progress.types.js +1 -0
  82. package/dist/events/types/repo-snapshot.types.d.ts +1 -4
  83. package/dist/events/types/repo-tree.types.d.ts +25 -0
  84. package/dist/events/types/repo-tree.types.js +1 -0
  85. package/dist/feature/ticket-candidates.d.ts +1 -1
  86. package/dist/git/checkout-root.d.ts +15 -0
  87. package/dist/git/checkout-root.js +18 -0
  88. package/dist/git/code-state.d.ts +2 -16
  89. package/dist/git/code-state.js +11 -12
  90. package/dist/git/constants/git.constants.d.ts +31 -11
  91. package/dist/git/constants/git.constants.js +36 -12
  92. package/dist/git/constants/tree.constants.d.ts +71 -0
  93. package/dist/git/constants/tree.constants.js +92 -0
  94. package/dist/git/fingerprint.d.ts +3 -6
  95. package/dist/git/fingerprint.js +5 -8
  96. package/dist/git/git-context.d.ts +1 -0
  97. package/dist/git/git-context.js +8 -3
  98. package/dist/git/index.d.ts +1 -2
  99. package/dist/git/index.js +1 -1
  100. package/dist/git/repo-snapshot.d.ts +13 -4
  101. package/dist/git/repo-snapshot.js +47 -9
  102. package/dist/git/repo-tree.d.ts +69 -0
  103. package/dist/git/repo-tree.js +130 -0
  104. package/dist/git/types/git.types.d.ts +5 -2
  105. package/dist/git/types/snapshot.types.d.ts +14 -0
  106. package/dist/pipeline/constants/pipeline.constants.d.ts +3 -0
  107. package/dist/pipeline/constants/pipeline.constants.js +3 -0
  108. package/dist/pipeline/hook-pipeline.js +112 -72
  109. package/dist/privacy/product-capture.js +36 -5
  110. package/dist/providers/antigravity/antigravity.capture.d.ts +2 -0
  111. package/dist/providers/antigravity/antigravity.capture.js +5 -0
  112. package/dist/providers/antigravity/antigravity.detect.js +8 -22
  113. package/dist/providers/antigravity/antigravity.provider.js +10 -3
  114. package/dist/providers/antigravity/constants/antigravity.constants.d.ts +1 -0
  115. package/dist/providers/antigravity/constants/antigravity.constants.js +1 -0
  116. package/dist/providers/claude/claude.adapter.js +9 -6
  117. package/dist/providers/claude/claude.detect.js +2 -17
  118. package/dist/providers/claude/claude.otel.d.ts +21 -3
  119. package/dist/providers/claude/claude.otel.js +216 -61
  120. package/dist/providers/claude/claude.provider.js +17 -1
  121. package/dist/providers/claude/claude.version.d.ts +9 -0
  122. package/dist/providers/claude/claude.version.js +28 -0
  123. package/dist/providers/claude/constants/claude.constants.d.ts +27 -0
  124. package/dist/providers/claude/constants/claude.constants.js +27 -0
  125. package/dist/providers/claude/constants/claude.otel.constants.d.ts +27 -0
  126. package/dist/providers/claude/constants/claude.otel.constants.js +45 -5
  127. package/dist/providers/claude/types/claude.types.d.ts +13 -0
  128. package/dist/providers/codex/codex.capture.d.ts +76 -0
  129. package/dist/providers/codex/codex.capture.js +454 -0
  130. package/dist/providers/codex/codex.detect.js +2 -4
  131. package/dist/providers/codex/codex.otel.d.ts +38 -2
  132. package/dist/providers/codex/codex.otel.js +50 -6
  133. package/dist/providers/codex/codex.provider.js +8 -0
  134. package/dist/providers/codex/codex.surface.d.ts +9 -0
  135. package/dist/{turns/codex-originator.js → providers/codex/codex.surface.js} +17 -3
  136. package/dist/providers/codex/codex.titles.d.ts +14 -0
  137. package/dist/providers/codex/codex.titles.js +35 -0
  138. package/dist/providers/codex/constants/codex.constants.d.ts +4 -0
  139. package/dist/providers/codex/constants/codex.constants.js +4 -0
  140. package/dist/providers/cursor/constants/cursor.constants.d.ts +17 -4
  141. package/dist/providers/cursor/constants/cursor.constants.js +25 -5
  142. package/dist/providers/cursor/cursor-mcp-memo.d.ts +34 -0
  143. package/dist/providers/cursor/cursor-mcp-memo.js +94 -0
  144. package/dist/providers/cursor/cursor.adapter.js +20 -82
  145. package/dist/providers/cursor/cursor.capture.d.ts +1 -0
  146. package/dist/providers/cursor/cursor.capture.js +4 -0
  147. package/dist/providers/cursor/cursor.detect.d.ts +5 -1
  148. package/dist/providers/cursor/cursor.detect.js +11 -26
  149. package/dist/providers/cursor/cursor.hooks.js +2 -2
  150. package/dist/providers/cursor/cursor.provider.js +16 -7
  151. package/dist/providers/cursor/cursor.titles.d.ts +14 -0
  152. package/dist/providers/cursor/cursor.titles.js +20 -0
  153. package/dist/providers/cursor/schemas/cursor.schema.d.ts +3 -3
  154. package/dist/providers/cursor/schemas/cursor.schema.js +5 -3
  155. package/dist/providers/gemini/constants/gemini.constants.d.ts +16 -0
  156. package/dist/providers/gemini/constants/gemini.constants.js +17 -0
  157. package/dist/providers/gemini/gemini.capture.d.ts +81 -0
  158. package/dist/providers/gemini/gemini.capture.js +210 -0
  159. package/dist/providers/gemini/gemini.detect.js +57 -24
  160. package/dist/providers/gemini/gemini.otel.d.ts +38 -2
  161. package/dist/providers/gemini/gemini.otel.js +56 -125
  162. package/dist/providers/gemini/gemini.provider.js +5 -0
  163. package/dist/providers/index.d.ts +1 -0
  164. package/dist/providers/index.js +1 -0
  165. package/dist/providers/provider.d.ts +8 -0
  166. package/dist/providers/provider.js +9 -0
  167. package/dist/providers/registry.d.ts +14 -0
  168. package/dist/providers/registry.js +14 -0
  169. package/dist/providers/shared/constants/hook-config.constants.d.ts +2 -0
  170. package/dist/providers/shared/constants/hook-config.constants.js +2 -0
  171. package/dist/providers/shared/constants/terminal-capture.constants.d.ts +6 -0
  172. package/dist/providers/shared/constants/terminal-capture.constants.js +6 -0
  173. package/dist/providers/shared/editor-paths.d.ts +8 -0
  174. package/dist/providers/shared/editor-paths.js +18 -0
  175. package/dist/providers/shared/hook-config.d.ts +5 -0
  176. package/dist/providers/shared/hook-config.js +39 -1
  177. package/dist/providers/shared/hooks-marker.d.ts +14 -0
  178. package/dist/providers/shared/hooks-marker.js +23 -0
  179. package/dist/providers/shared/install-record.d.ts +29 -0
  180. package/dist/providers/shared/install-record.js +52 -0
  181. package/dist/providers/shared/session-title-store.d.ts +23 -0
  182. package/dist/providers/shared/session-title-store.js +50 -0
  183. package/dist/providers/shared/terminal-capture.d.ts +41 -0
  184. package/dist/providers/shared/terminal-capture.js +109 -0
  185. package/dist/providers/shared/tooling.d.ts +21 -0
  186. package/dist/providers/shared/tooling.js +36 -1
  187. package/dist/providers/types/provider.types.d.ts +57 -4
  188. package/dist/replay/checkout-resolver.d.ts +29 -0
  189. package/dist/replay/checkout-resolver.js +69 -0
  190. package/dist/replay/codex-turns.d.ts +24 -0
  191. package/dist/replay/codex-turns.js +221 -0
  192. package/dist/replay/constants/replay.constants.d.ts +99 -0
  193. package/dist/replay/constants/replay.constants.js +102 -0
  194. package/dist/replay/describe.d.ts +10 -0
  195. package/dist/replay/describe.js +31 -0
  196. package/dist/replay/gemini-turns.d.ts +36 -0
  197. package/dist/replay/gemini-turns.js +192 -0
  198. package/dist/replay/machine.d.ts +34 -0
  199. package/dist/replay/machine.js +68 -0
  200. package/dist/replay/progress-event.d.ts +21 -0
  201. package/dist/replay/progress-event.js +45 -0
  202. package/dist/replay/replay-runner.d.ts +58 -0
  203. package/dist/replay/replay-runner.js +529 -0
  204. package/dist/replay/replay-scan.d.ts +83 -0
  205. package/dist/replay/replay-scan.js +170 -0
  206. package/dist/replay/replay-state.d.ts +108 -0
  207. package/dist/replay/replay-state.js +199 -0
  208. package/dist/replay/resume.d.ts +18 -0
  209. package/dist/replay/resume.js +34 -0
  210. package/dist/replay/start.d.ts +23 -0
  211. package/dist/replay/start.js +39 -0
  212. package/dist/replay/throttle.d.ts +35 -0
  213. package/dist/replay/throttle.js +41 -0
  214. package/dist/replay/transcript-turns.d.ts +35 -0
  215. package/dist/replay/transcript-turns.js +215 -0
  216. package/dist/replay/turn-event.d.ts +38 -0
  217. package/dist/replay/turn-event.js +116 -0
  218. package/dist/replay/types/replay.types.d.ts +162 -0
  219. package/dist/replay/types/replay.types.js +1 -0
  220. package/dist/replay/window.d.ts +28 -0
  221. package/dist/replay/window.js +41 -0
  222. package/dist/snapshot/branch-selection.d.ts +40 -23
  223. package/dist/snapshot/branch-selection.js +74 -42
  224. package/dist/snapshot/budget.js +2 -2
  225. package/dist/snapshot/constants/snapshot-stages.constants.d.ts +10 -0
  226. package/dist/snapshot/constants/snapshot-stages.constants.js +10 -0
  227. package/dist/snapshot/constants/snapshot.constants.d.ts +37 -4
  228. package/dist/snapshot/constants/snapshot.constants.js +37 -4
  229. package/dist/snapshot/index.d.ts +6 -1
  230. package/dist/snapshot/index.js +3 -1
  231. package/dist/snapshot/snapshot-event.d.ts +7 -0
  232. package/dist/snapshot/snapshot-event.js +8 -5
  233. package/dist/snapshot/snapshot-pipeline.js +89 -26
  234. package/dist/snapshot/snapshot-state.js +24 -2
  235. package/dist/snapshot/tree-event.d.ts +14 -0
  236. package/dist/snapshot/tree-event.js +91 -0
  237. package/dist/snapshot/tree-pipeline.d.ts +12 -0
  238. package/dist/snapshot/tree-pipeline.js +172 -0
  239. package/dist/snapshot/types/snapshot.types.d.ts +62 -2
  240. package/dist/storage/schemas/storage.schema.d.ts +2 -0
  241. package/dist/storage/schemas/storage.schema.js +6 -0
  242. package/dist/transport/constants/transport.constants.d.ts +5 -0
  243. package/dist/transport/constants/transport.constants.js +5 -0
  244. package/dist/transport/delivery-stats.d.ts +13 -1
  245. package/dist/transport/delivery-stats.js +18 -2
  246. package/dist/transport/delivery.d.ts +4 -3
  247. package/dist/transport/delivery.js +21 -7
  248. package/dist/transport/identity-delivery.d.ts +20 -0
  249. package/dist/transport/identity-delivery.js +41 -0
  250. package/dist/transport/index.d.ts +2 -0
  251. package/dist/transport/index.js +1 -0
  252. package/dist/transport/queue.js +40 -6
  253. package/dist/transport/types/delivery-flow.types.d.ts +7 -0
  254. package/dist/turns/claude-transcript.js +4 -12
  255. package/dist/turns/codex-transcript.d.ts +9 -0
  256. package/dist/turns/codex-transcript.js +27 -19
  257. package/dist/turns/constants/turns.constants.d.ts +13 -12
  258. package/dist/turns/constants/turns.constants.js +15 -19
  259. package/dist/turns/gemini-transcript.d.ts +19 -1
  260. package/dist/turns/gemini-transcript.js +29 -18
  261. package/dist/turns/index.d.ts +3 -4
  262. package/dist/turns/index.js +2 -3
  263. package/dist/turns/run-state.d.ts +71 -0
  264. package/dist/turns/run-state.js +114 -0
  265. package/dist/turns/tool-events.d.ts +11 -1
  266. package/dist/turns/tool-events.js +32 -9
  267. package/dist/turns/transcript.d.ts +15 -14
  268. package/dist/turns/transcript.js +23 -4
  269. package/dist/turns/turn-state.d.ts +49 -7
  270. package/dist/turns/turn-state.js +78 -10
  271. package/dist/turns/turn-summary.js +10 -6
  272. package/dist/turns/turn-tracker.d.ts +9 -16
  273. package/dist/turns/turn-tracker.js +162 -86
  274. package/dist/turns/types/transcript.types.d.ts +11 -1
  275. package/dist/turns/types/turn-provider.types.d.ts +33 -0
  276. package/dist/turns/types/turn-provider.types.js +1 -0
  277. package/dist/turns/types/turn-state.types.d.ts +9 -0
  278. package/dist/turns/types/turn-summary.types.d.ts +20 -6
  279. package/dist/turns/types/turn-tracker.types.d.ts +3 -1
  280. package/dist/turns/work-checkout.js +1 -2
  281. package/docs/AUDIT_PROMPT.md +10 -0
  282. package/docs/DATA_HANDLING.md +269 -32
  283. package/docs/ENTERPRISE_DEPLOYMENT.md +1 -1
  284. package/docs/PERFORMANCE.md +27 -0
  285. package/package.json +3 -2
  286. package/dist/events/canonical-event.d.ts +0 -10
  287. package/dist/events/canonical-event.js +0 -9
  288. package/dist/git/repository-root.d.ts +0 -39
  289. package/dist/git/repository-root.js +0 -131
  290. package/dist/git/types/repository-root.types.d.ts +0 -11
  291. package/dist/transport/transport.d.ts +0 -6
  292. package/dist/turns/codex-originator.d.ts +0 -11
  293. package/dist/turns/cursor-transcript.d.ts +0 -21
  294. package/dist/turns/cursor-transcript.js +0 -66
  295. package/dist/turns/native-session-titles.d.ts +0 -26
  296. package/dist/turns/native-session-titles.js +0 -102
  297. /package/dist/{git/types/repository-root.types.js → billing/types/billing.types.js} +0 -0
  298. /package/dist/{transport/transport.js → capture/types/capture.types.js} +0 -0
@@ -2,12 +2,12 @@ import { debugLog } from '../core/logger.js';
2
2
  import { next, runFlow, step, stop } from '../core/pipe.js';
3
3
  import { collectBranchCommits, collectBranchRefs, resolveDefaultBranch } from '../git/repo-snapshot.js';
4
4
  import { sanitizeValue } from '../privacy/sanitizer.js';
5
- import { nextSnapshotState, selectChangedBranches } from './branch-selection.js';
5
+ import { anyDue, nextSnapshotState, snapshotCandidates } from './branch-selection.js';
6
6
  import { budgetedRunner, remainingMs, withinBudget } from './budget.js';
7
7
  import { buildRepoSnapshot } from './snapshot-event.js';
8
8
  import { emptyState } from './snapshot-state.js';
9
- import { SNAPSHOT_BRANCH_COUNT, SNAPSHOT_COMMITS_PER_BRANCH } from './constants/snapshot.constants.js';
10
- import { STAGE_COLLECT_COMMITS, STAGE_COLLECT_REFS, STAGE_ENQUEUE, STAGE_SANITIZE, STAGE_SELECT_CHANGED, STOP_BUDGET_SPENT, STOP_NOTHING_CHANGED, STOP_NO_EVENT, STOP_NOT_A_REPOSITORY } from './constants/snapshot-stages.constants.js';
9
+ import { SNAPSHOT_BRANCH_COUNT, SNAPSHOT_COMMITS_PER_BRANCH, SNAPSHOT_MAX_CHECKS, SNAPSHOT_SCAN_COUNT, SNAPSHOT_WRITE_RESERVE_MS } from './constants/snapshot.constants.js';
10
+ import { STAGE_COLLECT_COMMITS, STAGE_COLLECT_REFS, STAGE_ENQUEUE, STAGE_SANITIZE, STAGE_SELECT_CHANGED, STOP_ALL_ON_TRUNK, STOP_BUDGET_SPENT, STOP_NOTHING_CHANGED, STOP_NO_EVENT, STOP_NOT_A_REPOSITORY } from './constants/snapshot-stages.constants.js';
11
11
  /**
12
12
  * The snapshot flow, as the list of stages it is.
13
13
  *
@@ -43,7 +43,8 @@ export function runSnapshotPipeline(pipeline) {
43
43
  // sequential seconds of the hook's answer if nothing bounds them.
44
44
  run: budgetedRunner(pipeline.input.run, pipeline.input.deadline),
45
45
  refs: [],
46
- selected: [],
46
+ candidates: [],
47
+ merged: [],
47
48
  branches: []
48
49
  };
49
50
  return runFlow(SNAPSHOT_STAGES, initial, (trace) => {
@@ -60,48 +61,92 @@ export function runSnapshotPipeline(pipeline) {
60
61
  */
61
62
  async function collectRefs(state) {
62
63
  const { cwd } = state.input;
63
- const refs = await collectBranchRefs({ cwd, branchCount: SNAPSHOT_BRANCH_COUNT }, state.run);
64
+ const refs = await collectBranchRefs({ cwd, branchCount: SNAPSHOT_SCAN_COUNT }, state.run);
64
65
  if (refs.length === 0)
65
66
  return stop(state, STOP_NOT_A_REPOSITORY);
66
67
  const defaultBranch = await resolveDefaultBranch(cwd, state.run);
67
68
  return next({ ...state, refs, defaultBranch });
68
69
  }
69
70
  /**
70
- * Compare the heads against what was last sent.
71
+ * Compare the heads against what was last recorded.
71
72
  *
72
73
  * @param state - Current flow state.
73
- * @returns The state with its selection, or a stop when nothing is due.
74
+ * @returns The state with its walk, or a stop when nothing in reach is due.
74
75
  */
75
76
  async function selectChanged(state) {
76
77
  const stored = await state.store.read(state.input.repository);
77
- const selected = selectChangedBranches(selectionInput({ ...state, stored }));
78
- if (selected.length === 0)
78
+ const candidates = snapshotCandidates(selectionInput({ ...state, stored }));
79
+ if (!anyDue(candidates))
79
80
  return stop({ ...state, stored }, STOP_NOTHING_CHANGED);
80
- return next({ ...state, stored, selected });
81
+ return next({ ...state, stored, candidates });
81
82
  }
82
83
  /**
83
- * The commits each selected branch has that the trunk does not.
84
+ * Walk the branches newest first until ten live ones are in hand.
84
85
  *
85
- * The budget is checked per branch rather than once: the listing is cheap and
86
- * the logs are not, so an overrun stops here with the branches already
87
- * described rather than discarding the work.
86
+ * A branch found already on the trunk does not count toward the ten, so the
87
+ * window fills from the next-newest live branches instead of shrinking. One
88
+ * that was described and has not moved counts without a git process. The walk
89
+ * ends at ten, at {@link SNAPSHOT_MAX_CHECKS} checks, or when the checks have
90
+ * spent all but the reserve the queue write needs; what it did not reach keeps
91
+ * its old entry and is checked on a later turn.
92
+ *
93
+ * A gone upstream is a verdict without a git process, but only for a branch
94
+ * the cache has never recorded: once one is recorded, a moved head or a
95
+ * heartbeat means a real check, so commits made after its pull request merged
96
+ * are seen as the new work they are, on this turn and every later one.
88
97
  *
89
98
  * @param state - Current flow state.
90
- * @returns The state with its branches, or a stop when the budget ran out
91
- * before any branch was described.
99
+ * @returns The state with its live and merged branches, or a stop when the
100
+ * budget ran out before any branch was checked.
92
101
  */
93
102
  async function collectCommits(state) {
94
- const { cwd, deadline } = state.input;
103
+ const checkDeadline = state.input.deadline - SNAPSHOT_WRITE_RESERVE_MS;
104
+ const run = budgetedRunner(state.run, checkDeadline);
105
+ const merged = [];
95
106
  const branches = [];
96
- for (const ref of state.selected) {
97
- if (remainingMs(deadline) === 0)
107
+ let live = 0;
108
+ let checks = 0;
109
+ for (const { ref, due } of state.candidates) {
110
+ if (live >= SNAPSHOT_BRANCH_COUNT)
111
+ break;
112
+ if (!due) {
113
+ live += 1;
114
+ continue;
115
+ }
116
+ if (ref.upstreamGone && !state.stored?.branches[ref.name]) {
117
+ merged.push(ref);
118
+ continue;
119
+ }
120
+ if (checks >= SNAPSHOT_MAX_CHECKS || remainingMs(checkDeadline) === 0)
98
121
  break;
99
- const commits = await collectBranchCommits(ref.name, { cwd, defaultBranch: state.defaultBranch, commitCount: SNAPSHOT_COMMITS_PER_BRANCH, withFiles: state.input.files }, state.run);
122
+ checks += 1;
123
+ const commits = await checkBranch(ref, state, run);
124
+ // A check the budget cut short is unknown, not live: its merge test may
125
+ // have been the call that was skipped, and failing open there would send
126
+ // a merged branch.
127
+ if (remainingMs(checkDeadline) === 0)
128
+ break;
129
+ if (!commits) {
130
+ merged.push(ref);
131
+ continue;
132
+ }
133
+ live += 1;
100
134
  branches.push({ ...ref, commits });
101
135
  }
102
- if (branches.length === 0)
136
+ if (merged.length === 0 && branches.length === 0)
103
137
  return stop(state, STOP_BUDGET_SPENT);
104
- return next({ ...state, branches });
138
+ return next({ ...state, merged, branches });
139
+ }
140
+ /**
141
+ * One branch's delta, or undefined when its work is already on the trunk.
142
+ *
143
+ * @param ref - The branch.
144
+ * @param state - Current flow state.
145
+ * @param run - The checks' budgeted runner.
146
+ * @returns What {@link collectBranchCommits} says.
147
+ */
148
+ function checkBranch(ref, state, run) {
149
+ return collectBranchCommits(ref.name, { cwd: state.input.cwd, defaultBranch: state.defaultBranch, commitCount: SNAPSHOT_COMMITS_PER_BRANCH, withFiles: state.input.files }, run);
105
150
  }
106
151
  /**
107
152
  * Build the event and put it through the same scrubber prompt text gets.
@@ -114,6 +159,8 @@ async function collectCommits(state) {
114
159
  * @returns The state carrying the event to send.
115
160
  */
116
161
  async function sanitize(state) {
162
+ if (state.branches.length === 0)
163
+ return next(state);
117
164
  const event = buildRepoSnapshot({
118
165
  identity: state.input,
119
166
  defaultBranch: state.defaultBranch,
@@ -122,27 +169,43 @@ async function sanitize(state) {
122
169
  return next({ ...state, event: sanitizeValue(event) });
123
170
  }
124
171
  /**
125
- * Queue the event, then record what was sent.
172
+ * Queue the event, then record what was checked.
126
173
  *
127
174
  * The cache is written only after the queue accepted the event. Written first,
128
175
  * a failed enqueue would mark the branches as reported and nothing would ever
129
176
  * offer them again.
130
177
  *
178
+ * Branches already on the trunk are recorded too, as merged, with nothing
179
+ * queued when they are all there is: otherwise every turn would check them
180
+ * again. Their heads are what is recorded, so new commits select them again.
181
+ *
131
182
  * @param state - Current flow state.
132
183
  * @returns The state, unchanged.
133
184
  */
134
185
  async function enqueue(state) {
186
+ if (state.branches.length === 0) {
187
+ await record(state);
188
+ return stop(state, STOP_ALL_ON_TRUNK);
189
+ }
135
190
  if (!state.event)
136
191
  return stop(state, STOP_NO_EVENT);
137
- const { deadline } = state.input;
138
- const queued = await withinBudget(state.queue.enqueue([state.event]), deadline);
192
+ const queued = await withinBudget(state.queue.enqueue([state.event]), state.input.deadline);
139
193
  // Recording a send that may not have happened is the one thing this flow must
140
194
  // never do: the branches would be marked reported and never offered again.
141
195
  if (!queued)
142
196
  return stop(state, STOP_BUDGET_SPENT);
143
- await withinBudget(state.store.write(state.input.repository, nextSnapshotState(selectionInput(state), state.branches)), deadline);
197
+ await record(state);
144
198
  return next(state);
145
199
  }
200
+ /**
201
+ * Write the checked branches to the cache, within the budget.
202
+ *
203
+ * @param state - Current flow state.
204
+ * @returns Nothing; an abandoned write only means the branches are offered again.
205
+ */
206
+ async function record(state) {
207
+ await withinBudget(state.store.write(state.input.repository, nextSnapshotState(selectionInput(state), state.branches, state.merged)), state.input.deadline);
208
+ }
146
209
  /**
147
210
  * The selection's view of this flow.
148
211
  *
@@ -42,7 +42,8 @@ export class SnapshotStateStore {
42
42
  return emptyState();
43
43
  return {
44
44
  defaultBranch: typeof record.defaultBranch === 'string' ? record.defaultBranch : undefined,
45
- branches: readEntries(record.branches)
45
+ branches: readEntries(record.branches),
46
+ tree: readTree(record.tree)
46
47
  };
47
48
  }
48
49
  /**
@@ -85,11 +86,32 @@ function readEntries(value) {
85
86
  continue;
86
87
  entries[name] = {
87
88
  headSha: entry.headSha,
88
- lastSentAt: typeof entry.lastSentAt === 'number' ? entry.lastSentAt : 0
89
+ lastSentAt: typeof entry.lastSentAt === 'number' ? entry.lastSentAt : 0,
90
+ ...(typeof entry.base === 'string' ? { base: entry.base } : {}),
91
+ ...(entry.merged === true ? { merged: true } : {})
89
92
  };
90
93
  }
91
94
  return entries;
92
95
  }
96
+ /**
97
+ * The tree entry out of a stored record, or none when malformed.
98
+ *
99
+ * @param value - The `tree` field as read from disk.
100
+ * @returns The entry, or undefined.
101
+ */
102
+ function readTree(value) {
103
+ const record = asRecord(value);
104
+ if (!record)
105
+ return undefined;
106
+ return {
107
+ sha: typeof record.sha === 'string' ? record.sha : undefined,
108
+ sentAt: typeof record.sentAt === 'number' ? record.sentAt : undefined,
109
+ sentFor: typeof record.sentFor === 'string' ? record.sentFor : undefined,
110
+ checkedAt: typeof record.checkedAt === 'number' ? record.checkedAt : undefined,
111
+ triedAt: typeof record.triedAt === 'number' ? record.triedAt : undefined,
112
+ triedFor: typeof record.triedFor === 'string' ? record.triedFor : undefined
113
+ };
114
+ }
93
115
  /**
94
116
  * The state of a repository nothing has been sent for.
95
117
  *
@@ -0,0 +1,14 @@
1
+ import type { RepoTreeEvent } from '../events/types/repo-tree.types.js';
2
+ import type { BuildTreeInput } from './types/snapshot.types.js';
3
+ /**
4
+ * Build the record one default-branch tree becomes.
5
+ *
6
+ * The id is the repository and what is sent — each path with its names,
7
+ * sorted — and nothing else, not the agent: a retry, or a second developer or
8
+ * agent sending the same trunk, is the same record, and the gateway
9
+ * deduplicates it. Core identifies a tree the same way; no git oid is sent.
10
+ *
11
+ * @param input - Identity and the tree.
12
+ * @returns The tree event, within the contract's caps.
13
+ */
14
+ export declare function buildRepoTree(input: BuildTreeInput): RepoTreeEvent;
@@ -0,0 +1,91 @@
1
+ import { deriveEventId, sha256Hex } from '../events/event-id.js';
2
+ import { EVENT_SCHEMA_VERSION } from '../events/constants/events.constants.js';
3
+ import { TREE_EVENT_ID_PROVIDER, TREE_MAX_EVENT_BYTES, TREE_MAX_FILES, TREE_MAX_NAME_LENGTH, TREE_MAX_NAMES_PER_FILE } from '../git/constants/tree.constants.js';
4
+ import { compact } from '../core/object.js';
5
+ import { sendable } from './snapshot-event.js';
6
+ /**
7
+ * Build the record one default-branch tree becomes.
8
+ *
9
+ * The id is the repository and what is sent — each path with its names,
10
+ * sorted — and nothing else, not the agent: a retry, or a second developer or
11
+ * agent sending the same trunk, is the same record, and the gateway
12
+ * deduplicates it. Core identifies a tree the same way; no git oid is sent.
13
+ *
14
+ * @param input - Identity and the tree.
15
+ * @returns The tree event, within the contract's caps.
16
+ */
17
+ export function buildRepoTree(input) {
18
+ const { identity, tree } = input;
19
+ const capped = capFiles(tree.files);
20
+ return compact({
21
+ schemaVersion: EVENT_SCHEMA_VERSION,
22
+ id: deriveEventId({
23
+ provider: TREE_EVENT_ID_PROVIDER,
24
+ providerEventType: 'repo.tree',
25
+ payloadFingerprint: contentFingerprint(identity.repository, capped.files)
26
+ }),
27
+ timestamp: identity.capturedAt,
28
+ event: { type: 'repo.tree', providerEventType: 'repo.tree' },
29
+ agent: { provider: identity.provider, name: identity.agentName },
30
+ session: { id: identity.sessionId, providerId: identity.sessionId },
31
+ developer: identity.installationId ? { installationId: identity.installationId } : undefined,
32
+ provider: identity.provider,
33
+ surface: identity.surface,
34
+ repository: identity.repository,
35
+ developer_id: identity.developerId,
36
+ captured_at: identity.capturedAt,
37
+ truncated: capped.truncated || tree.partial,
38
+ files: capped.files
39
+ });
40
+ }
41
+ /**
42
+ * The files one event carries, in `ls-tree` order, within the schema's caps.
43
+ *
44
+ * Over a cap the contract says stop adding and mark the tree truncated: core
45
+ * still names it, and a name it never saw costs less than a 413, which loses
46
+ * the whole tree. A withheld path (credential-named, over-long) is not a
47
+ * truncation — it would never be sent.
48
+ *
49
+ * @param files - The tree's source files.
50
+ * @returns The files to send and whether any were cut.
51
+ */
52
+ function capFiles(files) {
53
+ const kept = [];
54
+ let bytes = 0;
55
+ let truncated = false;
56
+ for (const file of files) {
57
+ if (!sendable(file.path))
58
+ continue;
59
+ const names = capNames(file.names);
60
+ const entry = { path: file.path, names: names.names };
61
+ const size = Buffer.byteLength(JSON.stringify(entry)) + 1;
62
+ if (kept.length === TREE_MAX_FILES || bytes + size > TREE_MAX_EVENT_BYTES)
63
+ return { files: kept, truncated: true };
64
+ truncated ||= names.truncated;
65
+ bytes += size;
66
+ kept.push(entry);
67
+ }
68
+ return { files: kept, truncated };
69
+ }
70
+ /**
71
+ * One file's names within the schema's caps: names over the length dropped, the first 64 kept.
72
+ *
73
+ * @param names - Declaration names in first-seen order.
74
+ * @returns The names to send and whether any were dropped.
75
+ */
76
+ function capNames(names) {
77
+ const fitting = names.filter((name) => name.length <= TREE_MAX_NAME_LENGTH);
78
+ const kept = fitting.slice(0, TREE_MAX_NAMES_PER_FILE);
79
+ return { names: kept, truncated: kept.length < names.length };
80
+ }
81
+ /**
82
+ * A digest of what one tree event says: the repository and every `path:names` line, sorted.
83
+ *
84
+ * @param repository - Sanitized repository identity.
85
+ * @param files - The files the event carries.
86
+ * @returns Hex digest.
87
+ */
88
+ function contentFingerprint(repository, files) {
89
+ const lines = files.map((file) => `${file.path}:${file.names.join(',')}`).sort();
90
+ return sha256Hex([repository, ...lines].join('\n'));
91
+ }
@@ -0,0 +1,12 @@
1
+ import type { FlowResult } from '../core/types/core.types.js';
2
+ import type { TreeFlowState, TreePipelineInput } from './types/snapshot.types.js';
3
+ /**
4
+ * Send the default branch's source paths and declaration names, and again whenever the trunk's tree changes.
5
+ *
6
+ * Shares the snapshot's deadline and never outlives it: an overrun stops
7
+ * without recording anything, so the next turn tries again. Never throws.
8
+ *
9
+ * @param pipeline - The snapshot flow's input, the state cache and the offline queue.
10
+ * @returns The final state and where the flow stopped.
11
+ */
12
+ export declare function runTreePipeline(pipeline: TreePipelineInput): Promise<FlowResult<TreeFlowState>>;
@@ -0,0 +1,172 @@
1
+ import { debugLog } from '../core/logger.js';
2
+ import { next, runFlow, step, stop } from '../core/pipe.js';
3
+ import { resolveDefaultBranch } from '../git/repo-snapshot.js';
4
+ import { collectRepoTree, resolveTreeSha } from '../git/repo-tree.js';
5
+ import { sanitizeValue } from '../privacy/sanitizer.js';
6
+ import { budgetedRunner, remainingMs, withinBudget } from './budget.js';
7
+ import { TREE_RETRY_INTERVAL_MS } from './constants/snapshot.constants.js';
8
+ import { STAGE_ENQUEUE, STAGE_SANITIZE, STAGE_TREE_CHANGED, STAGE_TREE_COLLECT, STAGE_TREE_DUE, STAGE_TREE_RESOLVE, STOP_BUDGET_SPENT, STOP_NO_EVENT, STOP_TREE_NOT_DUE, STOP_TREE_NO_TRUNK, STOP_TREE_SENT, STOP_TREE_UNLISTED } from './constants/snapshot-stages.constants.js';
9
+ import { emptyState } from './snapshot-state.js';
10
+ import { buildRepoTree } from './tree-event.js';
11
+ /**
12
+ * The tree flow, as the list of stages it is.
13
+ *
14
+ * Cheapest first: the stored state costs no git at all, and between hourly
15
+ * checks of a sent tree it is the only stage that runs.
16
+ */
17
+ const TREE_STAGES = [
18
+ step(STAGE_TREE_DUE, due),
19
+ step(STAGE_TREE_RESOLVE, resolve),
20
+ step(STAGE_TREE_CHANGED, changed),
21
+ step(STAGE_TREE_COLLECT, collect),
22
+ step(STAGE_SANITIZE, sanitize),
23
+ step(STAGE_ENQUEUE, enqueue)
24
+ ];
25
+ /**
26
+ * Send the default branch's source paths and declaration names, and again whenever the trunk's tree changes.
27
+ *
28
+ * Shares the snapshot's deadline and never outlives it: an overrun stops
29
+ * without recording anything, so the next turn tries again. Never throws.
30
+ *
31
+ * @param pipeline - The snapshot flow's input, the state cache and the offline queue.
32
+ * @returns The final state and where the flow stopped.
33
+ */
34
+ export function runTreePipeline(pipeline) {
35
+ const initial = {
36
+ input: pipeline.input,
37
+ store: pipeline.store,
38
+ queue: pipeline.queue,
39
+ run: budgetedRunner(pipeline.input.run, pipeline.input.deadline)
40
+ };
41
+ return runFlow(TREE_STAGES, initial, (trace) => {
42
+ if (trace.outcome === 'next')
43
+ return;
44
+ debugLog(`tree flow ${trace.outcome} at ${trace.step}${trace.reason ? `: ${trace.reason}` : ''}`);
45
+ });
46
+ }
47
+ /**
48
+ * Whether this repository owes a tree, or a check of the one it sent.
49
+ *
50
+ * A tree not yet sent for this identity is owed — a new identity (a re-setup
51
+ * with a new credential, a different account) owes it again. A sent tree is
52
+ * owed again when the trunk's tree oid moved, which only git can tell: so the
53
+ * oid is compared at most once per {@link TREE_RETRY_INTERVAL_MS} since the
54
+ * last send or check, and every other turn pays one small state read and no
55
+ * git process. State without a stored oid is checked once. An attempt that
56
+ * failed waits out the same interval, so a repository the budget cannot list
57
+ * costs its second once an hour, not on every turn.
58
+ *
59
+ * @param state - Current flow state.
60
+ * @returns The state with what was stored, or a stop when nothing is owed yet.
61
+ */
62
+ async function due(state) {
63
+ const stored = await state.store.read(state.input.repository);
64
+ const tree = stored.tree;
65
+ const sent = tree?.sentAt !== undefined && tree.sentFor === state.input.identity;
66
+ const now = Date.parse(state.input.capturedAt);
67
+ const waiting = now - Math.max(tree?.sentAt ?? 0, tree?.checkedAt ?? 0, tree?.triedAt ?? 0) < TREE_RETRY_INTERVAL_MS;
68
+ if (sent && tree?.sha !== undefined && waiting)
69
+ return stop({ ...state, stored }, STOP_TREE_SENT);
70
+ if (tree?.triedAt !== undefined && (tree.triedFor ?? state.input.identity) === state.input.identity && !(sent && tree.sha !== undefined) && now - tree.triedAt < TREE_RETRY_INTERVAL_MS)
71
+ return stop({ ...state, stored }, STOP_TREE_NOT_DUE);
72
+ return next({ ...state, stored });
73
+ }
74
+ /**
75
+ * The trunk and its tree oid.
76
+ *
77
+ * @param state - Current flow state.
78
+ * @returns The state with the trunk and the tree, or a stop when there is none.
79
+ */
80
+ async function resolve(state) {
81
+ const { cwd } = state.input;
82
+ const defaultBranch = await resolveDefaultBranch(cwd, state.run);
83
+ const treeSha = defaultBranch ? await resolveTreeSha(cwd, defaultBranch, state.run) : undefined;
84
+ if (!defaultBranch || !treeSha)
85
+ return stop(await triedNow(state), STOP_TREE_NO_TRUNK);
86
+ return next({ ...state, treeSha });
87
+ }
88
+ /**
89
+ * Stop when the trunk's tree is the one already sent, noting the check so the next one waits an hour.
90
+ *
91
+ * @param state - Current flow state, with the resolved tree oid.
92
+ * @returns The state, or a stop when the sent tree is still the trunk's.
93
+ */
94
+ async function changed(state) {
95
+ const tree = state.stored?.tree;
96
+ if (tree?.sentAt === undefined || tree.sentFor !== state.input.identity || tree.sha !== state.treeSha)
97
+ return next(state);
98
+ const stored = state.stored ?? emptyState();
99
+ await state.store.write(state.input.repository, { ...stored, tree: { ...tree, checkedAt: Date.parse(state.input.capturedAt) } }).catch(() => undefined);
100
+ return stop(state, STOP_TREE_SENT);
101
+ }
102
+ /**
103
+ * List the tree and search it for declaration names.
104
+ *
105
+ * The budget is checked after, not only before: a search the budget cut short
106
+ * returns nothing, which reads exactly like a tree with no declarations, and
107
+ * sending that would record the tree as named when it was not.
108
+ *
109
+ * ponytail: a tree that never fits in what the branch snapshot leaves of one
110
+ * second is never sent (agent-watch-core, 1,704 source files, takes ~200 ms).
111
+ * Upgrade: give the tree its own budget on its hourly attempt, or search it
112
+ * in slices across turns.
113
+ *
114
+ * @param state - Current flow state.
115
+ * @returns The state with the tree, or a stop when it could not be listed in time.
116
+ */
117
+ async function collect(state) {
118
+ const tree = await collectRepoTree(state.input.cwd, state.treeSha, state.run);
119
+ if (remainingMs(state.input.deadline) === 0)
120
+ return stop(await triedNow(state), STOP_BUDGET_SPENT);
121
+ if (!tree)
122
+ return stop(await triedNow(state), STOP_TREE_UNLISTED);
123
+ return next({ ...state, tree });
124
+ }
125
+ /**
126
+ * Record a failed attempt, so the next one waits out the retry interval.
127
+ *
128
+ * Written whatever is left of the deadline — usually nothing, which is why
129
+ * the attempt failed — because it is one small local file, and skipping it
130
+ * would put the same failing listing on every following turn.
131
+ *
132
+ * @param state - Current flow state.
133
+ * @returns The state, unchanged.
134
+ */
135
+ async function triedNow(state) {
136
+ const stored = state.stored ?? emptyState();
137
+ await state.store.write(state.input.repository, { ...stored, tree: { ...stored.tree, triedAt: Date.parse(state.input.capturedAt), triedFor: state.input.identity } }).catch(() => undefined);
138
+ return state;
139
+ }
140
+ /**
141
+ * Build the event and put it through the same scrubber every record gets.
142
+ *
143
+ * @param state - Current flow state.
144
+ * @returns The state carrying the event to send.
145
+ */
146
+ async function sanitize(state) {
147
+ const event = buildRepoTree({ identity: state.input, tree: state.tree });
148
+ return next({ ...state, event: sanitizeValue(event) });
149
+ }
150
+ /**
151
+ * Queue the event, then record the tree as sent — never the other way round.
152
+ * The tree oid stays in this local marker; it is not sent.
153
+ *
154
+ * Queued is sent: the queue retries until it is delivered. ponytail: a tree
155
+ * the queue gives up on (attempts or age exhausted) is not offered again for
156
+ * this identity; clearing `tree.sentAt` when the queue drops a `repo.tree`
157
+ * is the upgrade if that ever bites.
158
+ *
159
+ * @param state - Current flow state.
160
+ * @returns The state, unchanged.
161
+ */
162
+ async function enqueue(state) {
163
+ if (!state.event)
164
+ return stop(state, STOP_NO_EVENT);
165
+ const { deadline, repository, capturedAt } = state.input;
166
+ const queued = await withinBudget(state.queue.enqueue([state.event]), deadline);
167
+ if (!queued)
168
+ return stop(await triedNow(state), STOP_BUDGET_SPENT);
169
+ const stored = state.stored ?? emptyState();
170
+ await withinBudget(state.store.write(repository, { ...stored, tree: { sha: state.treeSha, sentAt: Date.parse(capturedAt), sentFor: state.input.identity } }), deadline);
171
+ return next(state);
172
+ }
@@ -1,11 +1,21 @@
1
1
  import type { RepoSnapshotEvent } from '../../events/types/repo-snapshot.types.js';
2
- import type { BranchRef, SnapshotBranch } from '../../git/types/snapshot.types.js';
2
+ import type { RepoTreeEvent } from '../../events/types/repo-tree.types.js';
3
+ import type { BranchRef, RepoTree, SnapshotBranch } from '../../git/types/snapshot.types.js';
3
4
  import type { GitRunner } from '../../git/types/git.types.js';
4
5
  /** What was last reported about one branch. */
5
6
  export interface SnapshotStateEntry {
6
7
  readonly headSha: string;
7
8
  /** Epoch milliseconds, so an unchanged branch is still re-offered eventually. */
8
9
  readonly lastSentAt: number;
10
+ /** The default branch it was checked against; absent on entries written before it was per branch. */
11
+ readonly base?: string;
12
+ /** Found already on the trunk: not sent, and not checked again until its head or base moves. */
13
+ readonly merged?: boolean;
14
+ }
15
+ /** One branch of the snapshot's walk, and whether it has to be checked. */
16
+ export interface SnapshotCandidate {
17
+ readonly ref: BranchRef;
18
+ readonly due: boolean;
9
19
  }
10
20
  /** What was last reported about one repository. */
11
21
  export interface SnapshotState {
@@ -18,6 +28,23 @@ export interface SnapshotState {
18
28
  */
19
29
  readonly defaultBranch?: string;
20
30
  readonly branches: Record<string, SnapshotStateEntry>;
31
+ /** The default-branch tree last sent as `repo.tree`, and when. */
32
+ readonly tree?: SnapshotTreeEntry;
33
+ }
34
+ /** Whether one repository's trunk tree has been sent, and for whom, or when it was last tried. */
35
+ export interface SnapshotTreeEntry {
36
+ /** The trunk tree oid that was sent; the next hourly check resends when the trunk's differs. Absent when none has been yet. */
37
+ readonly sha?: string;
38
+ /** Epoch milliseconds the tree was queued. */
39
+ readonly sentAt?: number;
40
+ /** The identity fingerprint it was sent as: a different identity owes the tree again. */
41
+ readonly sentFor?: string;
42
+ /** When the trunk's tree oid was last compared with the sent one and found unchanged. */
43
+ readonly checkedAt?: number;
44
+ /** When an attempt last failed, so the next waits out {@link TREE_RETRY_INTERVAL_MS}. */
45
+ readonly triedAt?: number;
46
+ /** The identity that attempt was for, so another identity is not held back by it. */
47
+ readonly triedFor?: string;
21
48
  }
22
49
  /**
23
50
  * Who and where a snapshot is about: everything the event itself carries.
@@ -41,6 +68,8 @@ export interface SnapshotFlowInput extends SnapshotIdentity {
41
68
  readonly cwd: string;
42
69
  /** Whether the effective capture policy allows file names; when not, no files listing runs. */
43
70
  readonly files: boolean;
71
+ /** Fingerprint of the identity events are sent as; the tree is owed again for a new identity, or when the trunk's tree changes. */
72
+ readonly identity?: string;
44
73
  readonly deadline: number;
45
74
  readonly run: GitRunner;
46
75
  }
@@ -57,6 +86,29 @@ export interface BuildSnapshotInput {
57
86
  readonly defaultBranch?: string;
58
87
  readonly branches: readonly SnapshotBranch[];
59
88
  }
89
+ /** Identity and the tree one `repo.tree` describes. */
90
+ export interface BuildTreeInput {
91
+ readonly identity: SnapshotIdentity;
92
+ readonly tree: RepoTree;
93
+ }
94
+ /** Everything one run of the tree flow needs beyond its own state. */
95
+ export interface TreePipelineInput {
96
+ /** Reuses the snapshot flow's input; its `files` flag must already be on to get here. */
97
+ readonly input: SnapshotFlowInput;
98
+ readonly store: SnapshotStateReader;
99
+ readonly queue: TreeQueue;
100
+ }
101
+ /** State threaded through the tree flow's stages. */
102
+ export interface TreeFlowState {
103
+ readonly input: SnapshotFlowInput;
104
+ readonly store: SnapshotStateReader;
105
+ readonly queue: TreeQueue;
106
+ readonly run: GitRunner;
107
+ readonly stored?: SnapshotState;
108
+ readonly treeSha?: string;
109
+ readonly tree?: RepoTree;
110
+ readonly event?: RepoTreeEvent;
111
+ }
60
112
  /** Everything one run of the flow needs beyond its own state. */
61
113
  export interface SnapshotPipelineInput {
62
114
  readonly input: SnapshotFlowInput;
@@ -73,7 +125,11 @@ export interface SnapshotFlowState {
73
125
  readonly stored?: SnapshotState;
74
126
  readonly defaultBranch?: string;
75
127
  readonly refs: readonly BranchRef[];
76
- readonly selected: readonly BranchRef[];
128
+ /** The walk, newest commit first, without the branches already known to be merged. */
129
+ readonly candidates: readonly SnapshotCandidate[];
130
+ /** The checked branches found already on the trunk. */
131
+ readonly merged: readonly BranchRef[];
132
+ /** The checked live branches, which the event describes. */
77
133
  readonly branches: readonly SnapshotBranch[];
78
134
  readonly event?: RepoSnapshotEvent;
79
135
  }
@@ -86,3 +142,7 @@ export interface SnapshotStateReader {
86
142
  export interface SnapshotQueue {
87
143
  enqueue(events: readonly RepoSnapshotEvent[]): Promise<void>;
88
144
  }
145
+ /** The one thing the tree flow asks of the offline queue. */
146
+ export interface TreeQueue {
147
+ enqueue(events: readonly RepoTreeEvent[]): Promise<void>;
148
+ }
@@ -8,6 +8,7 @@ import { z } from 'zod';
8
8
  */
9
9
  export declare const agentInstallSchema: z.ZodObject<{
10
10
  hooksInstalledAt: z.ZodOptional<z.ZodString>;
11
+ hooksFirstInstalledAt: z.ZodOptional<z.ZodString>;
11
12
  hookConfigPath: z.ZodOptional<z.ZodString>;
12
13
  hookEvents: z.ZodDefault<z.ZodArray<z.ZodString>>;
13
14
  hookCommand: z.ZodOptional<z.ZodString>;
@@ -23,6 +24,7 @@ export declare const installStateSchema: z.ZodObject<{
23
24
  schemaVersion: z.ZodDefault<z.ZodLiteral<1>>;
24
25
  agents: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
25
26
  hooksInstalledAt: z.ZodOptional<z.ZodString>;
27
+ hooksFirstInstalledAt: z.ZodOptional<z.ZodString>;
26
28
  hookConfigPath: z.ZodOptional<z.ZodString>;
27
29
  hookEvents: z.ZodDefault<z.ZodArray<z.ZodString>>;
28
30
  hookCommand: z.ZodOptional<z.ZodString>;
@@ -9,6 +9,12 @@ import { z } from 'zod';
9
9
  export const agentInstallSchema = z
10
10
  .object({
11
11
  hooksInstalledAt: z.string().optional(),
12
+ /**
13
+ * When AgentWatch first installed this agent's hooks on this machine, kept
14
+ * on every later setup. Replay sends no Gemini turn after it: those went
15
+ * live. Absent on an agent hooked before this was recorded.
16
+ */
17
+ hooksFirstInstalledAt: z.string().optional(),
12
18
  hookConfigPath: z.string().optional(),
13
19
  hookEvents: z.array(z.string()).default([]),
14
20
  hookCommand: z.string().optional(),