@agent-watch-ai/edge 0.6.0 → 0.7.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 (309) hide show
  1. package/CHANGELOG.md +288 -9
  2. package/README.md +307 -5
  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 +7 -3
  10. package/dist/billing/session-billing.js +34 -13
  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 +503 -0
  16. package/dist/capture/constants/capture.constants.d.ts +85 -0
  17. package/dist/capture/constants/capture.constants.js +87 -0
  18. package/dist/capture/launched-runs.d.ts +43 -0
  19. package/dist/capture/launched-runs.js +157 -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 +832 -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/capture/venv-loader.d.ts +68 -0
  27. package/dist/capture/venv-loader.js +189 -0
  28. package/dist/cli/constants/cli.constants.d.ts +23 -6
  29. package/dist/cli/constants/cli.constants.js +24 -7
  30. package/dist/cli/context.d.ts +19 -22
  31. package/dist/cli/context.js +23 -54
  32. package/dist/cli/doctor-run-capture.d.ts +21 -0
  33. package/dist/cli/doctor-run-capture.js +33 -0
  34. package/dist/cli/doctor.js +21 -68
  35. package/dist/cli/hook-check.d.ts +7 -2
  36. package/dist/cli/hook-check.js +30 -15
  37. package/dist/cli/hook.d.ts +14 -0
  38. package/dist/cli/hook.js +82 -1
  39. package/dist/cli/index.d.ts +1 -1
  40. package/dist/cli/index.js +1 -1
  41. package/dist/cli/misc.js +10 -2
  42. package/dist/cli/npm-global.d.ts +24 -0
  43. package/dist/cli/npm-global.js +77 -0
  44. package/dist/cli/npx-install.js +22 -6
  45. package/dist/cli/replay.d.ts +33 -0
  46. package/dist/cli/replay.js +228 -0
  47. package/dist/cli/setup.d.ts +10 -2
  48. package/dist/cli/setup.js +200 -31
  49. package/dist/cli/status.js +45 -5
  50. package/dist/cli/toggle.js +10 -0
  51. package/dist/cli/types/cli.types.d.ts +15 -1
  52. package/dist/cli/uninstall.js +42 -23
  53. package/dist/cli/update.js +3 -2
  54. package/dist/cli.js +104 -17
  55. package/dist/config/config-store.d.ts +15 -4
  56. package/dist/config/config-store.js +31 -7
  57. package/dist/config/config.d.ts +0 -2
  58. package/dist/config/config.js +0 -1
  59. package/dist/config/constants/config.constants.d.ts +8 -1
  60. package/dist/config/constants/config.constants.js +10 -1
  61. package/dist/config/events-transport.d.ts +15 -0
  62. package/dist/config/events-transport.js +29 -0
  63. package/dist/config/index.d.ts +2 -1
  64. package/dist/config/index.js +1 -0
  65. package/dist/config/root-config.d.ts +12 -0
  66. package/dist/config/root-config.js +24 -0
  67. package/dist/config/schemas/config.schema.d.ts +15 -2
  68. package/dist/config/schemas/config.schema.js +52 -8
  69. package/dist/config/types/config.types.d.ts +7 -0
  70. package/dist/core/index.d.ts +1 -1
  71. package/dist/core/index.js +1 -1
  72. package/dist/core/version.d.ts +9 -0
  73. package/dist/core/version.js +14 -0
  74. package/dist/core/which.d.ts +11 -0
  75. package/dist/core/which.js +18 -0
  76. package/dist/credentials/cloud-claim.d.ts +34 -0
  77. package/dist/credentials/cloud-claim.js +61 -0
  78. package/dist/credentials/constants/credentials.constants.d.ts +16 -1
  79. package/dist/credentials/constants/credentials.constants.js +17 -2
  80. package/dist/credentials/credential-status.js +1 -1
  81. package/dist/credentials/credentials.d.ts +3 -3
  82. package/dist/credentials/credentials.js +26 -12
  83. package/dist/credentials/device-api.d.ts +15 -1
  84. package/dist/credentials/device-api.js +12 -1
  85. package/dist/credentials/identity.d.ts +2 -2
  86. package/dist/credentials/identity.js +2 -2
  87. package/dist/credentials/install-key.d.ts +31 -0
  88. package/dist/credentials/install-key.js +58 -0
  89. package/dist/credentials/migration.d.ts +9 -7
  90. package/dist/credentials/migration.js +58 -18
  91. package/dist/credentials/secret-store.d.ts +12 -0
  92. package/dist/credentials/secret-store.js +18 -1
  93. package/dist/credentials/sign-in.d.ts +27 -0
  94. package/dist/credentials/sign-in.js +31 -1
  95. package/dist/credentials/token-refresher.d.ts +5 -1
  96. package/dist/credentials/token-refresher.js +10 -2
  97. package/dist/enforcement/enforcement.js +1 -1
  98. package/dist/events/constants/events.constants.d.ts +5 -2
  99. package/dist/events/constants/events.constants.js +4 -1
  100. package/dist/events/enrich.d.ts +14 -0
  101. package/dist/events/enrich.js +1 -1
  102. package/dist/events/index.d.ts +1 -0
  103. package/dist/events/product-event.d.ts +6 -3
  104. package/dist/events/types/events.types.d.ts +6 -0
  105. package/dist/events/types/replay-progress.types.d.ts +26 -0
  106. package/dist/events/types/replay-progress.types.js +1 -0
  107. package/dist/events/types/repo-tree.types.d.ts +2 -1
  108. package/dist/feature/ticket-candidates.d.ts +1 -1
  109. package/dist/git/checkout-root.d.ts +15 -0
  110. package/dist/git/checkout-root.js +18 -0
  111. package/dist/git/code-state.d.ts +2 -16
  112. package/dist/git/code-state.js +11 -12
  113. package/dist/git/constants/git.constants.d.ts +33 -11
  114. package/dist/git/constants/git.constants.js +45 -12
  115. package/dist/git/fingerprint.d.ts +3 -6
  116. package/dist/git/fingerprint.js +5 -8
  117. package/dist/git/git-context.js +5 -1
  118. package/dist/git/index.d.ts +1 -2
  119. package/dist/git/index.js +1 -1
  120. package/dist/git/repo-snapshot.d.ts +13 -4
  121. package/dist/git/repo-snapshot.js +53 -9
  122. package/dist/git/types/snapshot.types.d.ts +6 -0
  123. package/dist/pipeline/constants/pipeline.constants.d.ts +3 -0
  124. package/dist/pipeline/constants/pipeline.constants.js +3 -0
  125. package/dist/pipeline/hook-pipeline.js +82 -57
  126. package/dist/privacy/product-capture.js +2 -0
  127. package/dist/providers/antigravity/antigravity.capture.d.ts +2 -0
  128. package/dist/providers/antigravity/antigravity.capture.js +5 -0
  129. package/dist/providers/antigravity/antigravity.detect.js +8 -22
  130. package/dist/providers/antigravity/antigravity.provider.js +10 -3
  131. package/dist/providers/antigravity/constants/antigravity.constants.d.ts +1 -0
  132. package/dist/providers/antigravity/constants/antigravity.constants.js +1 -0
  133. package/dist/providers/claude/claude.adapter.js +9 -6
  134. package/dist/providers/claude/claude.detect.js +2 -17
  135. package/dist/providers/claude/claude.otel.d.ts +21 -3
  136. package/dist/providers/claude/claude.otel.js +216 -61
  137. package/dist/providers/claude/claude.provider.js +21 -1
  138. package/dist/providers/claude/claude.version.d.ts +9 -0
  139. package/dist/providers/claude/claude.version.js +28 -0
  140. package/dist/providers/claude/constants/claude.constants.d.ts +27 -0
  141. package/dist/providers/claude/constants/claude.constants.js +27 -0
  142. package/dist/providers/claude/constants/claude.otel.constants.d.ts +27 -0
  143. package/dist/providers/claude/constants/claude.otel.constants.js +45 -5
  144. package/dist/providers/claude/types/claude.types.d.ts +13 -0
  145. package/dist/providers/codex/codex.capture.d.ts +76 -0
  146. package/dist/providers/codex/codex.capture.js +454 -0
  147. package/dist/providers/codex/codex.detect.js +2 -4
  148. package/dist/providers/codex/codex.otel.d.ts +38 -2
  149. package/dist/providers/codex/codex.otel.js +50 -6
  150. package/dist/providers/codex/codex.provider.js +8 -0
  151. package/dist/providers/codex/codex.surface.d.ts +9 -0
  152. package/dist/{turns/codex-originator.js → providers/codex/codex.surface.js} +17 -3
  153. package/dist/providers/codex/codex.titles.d.ts +14 -0
  154. package/dist/providers/codex/codex.titles.js +35 -0
  155. package/dist/providers/codex/constants/codex.constants.d.ts +4 -0
  156. package/dist/providers/codex/constants/codex.constants.js +4 -0
  157. package/dist/providers/cursor/constants/cursor.constants.d.ts +17 -4
  158. package/dist/providers/cursor/constants/cursor.constants.js +25 -5
  159. package/dist/providers/cursor/cursor-mcp-memo.d.ts +34 -0
  160. package/dist/providers/cursor/cursor-mcp-memo.js +94 -0
  161. package/dist/providers/cursor/cursor.adapter.js +20 -82
  162. package/dist/providers/cursor/cursor.capture.d.ts +1 -0
  163. package/dist/providers/cursor/cursor.capture.js +4 -0
  164. package/dist/providers/cursor/cursor.detect.d.ts +5 -1
  165. package/dist/providers/cursor/cursor.detect.js +11 -26
  166. package/dist/providers/cursor/cursor.hooks.js +2 -2
  167. package/dist/providers/cursor/cursor.provider.js +16 -7
  168. package/dist/providers/cursor/cursor.titles.d.ts +14 -0
  169. package/dist/providers/cursor/cursor.titles.js +20 -0
  170. package/dist/providers/cursor/schemas/cursor.schema.d.ts +3 -3
  171. package/dist/providers/cursor/schemas/cursor.schema.js +5 -3
  172. package/dist/providers/gemini/constants/gemini.constants.d.ts +16 -0
  173. package/dist/providers/gemini/constants/gemini.constants.js +17 -0
  174. package/dist/providers/gemini/gemini.capture.d.ts +81 -0
  175. package/dist/providers/gemini/gemini.capture.js +210 -0
  176. package/dist/providers/gemini/gemini.detect.js +57 -24
  177. package/dist/providers/gemini/gemini.otel.d.ts +38 -2
  178. package/dist/providers/gemini/gemini.otel.js +56 -125
  179. package/dist/providers/gemini/gemini.provider.js +5 -0
  180. package/dist/providers/index.d.ts +1 -0
  181. package/dist/providers/index.js +1 -0
  182. package/dist/providers/provider.d.ts +8 -0
  183. package/dist/providers/provider.js +9 -0
  184. package/dist/providers/registry.d.ts +14 -0
  185. package/dist/providers/registry.js +14 -0
  186. package/dist/providers/shared/constants/hook-config.constants.d.ts +2 -0
  187. package/dist/providers/shared/constants/hook-config.constants.js +2 -0
  188. package/dist/providers/shared/constants/terminal-capture.constants.d.ts +6 -0
  189. package/dist/providers/shared/constants/terminal-capture.constants.js +6 -0
  190. package/dist/providers/shared/editor-paths.d.ts +8 -0
  191. package/dist/providers/shared/editor-paths.js +18 -0
  192. package/dist/providers/shared/hook-config.d.ts +5 -0
  193. package/dist/providers/shared/hook-config.js +39 -1
  194. package/dist/providers/shared/hooks-marker.d.ts +14 -0
  195. package/dist/providers/shared/hooks-marker.js +23 -0
  196. package/dist/providers/shared/install-record.d.ts +29 -0
  197. package/dist/providers/shared/install-record.js +52 -0
  198. package/dist/providers/shared/session-title-store.d.ts +23 -0
  199. package/dist/providers/shared/session-title-store.js +50 -0
  200. package/dist/providers/shared/terminal-capture.d.ts +41 -0
  201. package/dist/providers/shared/terminal-capture.js +109 -0
  202. package/dist/providers/shared/tooling.d.ts +21 -0
  203. package/dist/providers/shared/tooling.js +36 -1
  204. package/dist/providers/types/provider.types.d.ts +57 -4
  205. package/dist/replay/checkout-resolver.d.ts +56 -0
  206. package/dist/replay/checkout-resolver.js +173 -0
  207. package/dist/replay/codex-turns.d.ts +24 -0
  208. package/dist/replay/codex-turns.js +221 -0
  209. package/dist/replay/constants/replay.constants.d.ts +99 -0
  210. package/dist/replay/constants/replay.constants.js +102 -0
  211. package/dist/replay/describe.d.ts +10 -0
  212. package/dist/replay/describe.js +31 -0
  213. package/dist/replay/gemini-turns.d.ts +36 -0
  214. package/dist/replay/gemini-turns.js +192 -0
  215. package/dist/replay/machine.d.ts +34 -0
  216. package/dist/replay/machine.js +68 -0
  217. package/dist/replay/progress-event.d.ts +21 -0
  218. package/dist/replay/progress-event.js +45 -0
  219. package/dist/replay/replay-runner.d.ts +60 -0
  220. package/dist/replay/replay-runner.js +581 -0
  221. package/dist/replay/replay-scan.d.ts +84 -0
  222. package/dist/replay/replay-scan.js +182 -0
  223. package/dist/replay/replay-state.d.ts +108 -0
  224. package/dist/replay/replay-state.js +199 -0
  225. package/dist/replay/resume.d.ts +18 -0
  226. package/dist/replay/resume.js +34 -0
  227. package/dist/replay/start.d.ts +23 -0
  228. package/dist/replay/start.js +39 -0
  229. package/dist/replay/throttle.d.ts +36 -0
  230. package/dist/replay/throttle.js +44 -0
  231. package/dist/replay/transcript-turns.d.ts +35 -0
  232. package/dist/replay/transcript-turns.js +241 -0
  233. package/dist/replay/turn-event.d.ts +40 -0
  234. package/dist/replay/turn-event.js +127 -0
  235. package/dist/replay/types/replay.types.d.ts +198 -0
  236. package/dist/replay/types/replay.types.js +1 -0
  237. package/dist/replay/window.d.ts +28 -0
  238. package/dist/replay/window.js +41 -0
  239. package/dist/replay/worktree-map.d.ts +42 -0
  240. package/dist/replay/worktree-map.js +134 -0
  241. package/dist/snapshot/branch-selection.d.ts +40 -23
  242. package/dist/snapshot/branch-selection.js +71 -41
  243. package/dist/snapshot/constants/snapshot-stages.constants.d.ts +3 -1
  244. package/dist/snapshot/constants/snapshot-stages.constants.js +3 -1
  245. package/dist/snapshot/constants/snapshot.constants.d.ts +34 -7
  246. package/dist/snapshot/constants/snapshot.constants.js +34 -7
  247. package/dist/snapshot/index.d.ts +2 -2
  248. package/dist/snapshot/index.js +1 -1
  249. package/dist/snapshot/snapshot-pipeline.js +100 -26
  250. package/dist/snapshot/snapshot-state.js +6 -2
  251. package/dist/snapshot/tree-pipeline.d.ts +1 -1
  252. package/dist/snapshot/tree-pipeline.js +34 -15
  253. package/dist/snapshot/types/snapshot.types.d.ts +22 -3
  254. package/dist/storage/schemas/storage.schema.d.ts +2 -0
  255. package/dist/storage/schemas/storage.schema.js +6 -0
  256. package/dist/transport/delivery-stats.d.ts +13 -1
  257. package/dist/transport/delivery-stats.js +18 -2
  258. package/dist/transport/delivery.d.ts +4 -3
  259. package/dist/transport/delivery.js +21 -7
  260. package/dist/transport/identity-delivery.d.ts +20 -0
  261. package/dist/transport/identity-delivery.js +41 -0
  262. package/dist/transport/index.d.ts +2 -0
  263. package/dist/transport/index.js +1 -0
  264. package/dist/transport/types/delivery-flow.types.d.ts +7 -0
  265. package/dist/turns/claude-transcript.js +4 -12
  266. package/dist/turns/codex-transcript.d.ts +9 -0
  267. package/dist/turns/codex-transcript.js +27 -19
  268. package/dist/turns/constants/turns.constants.d.ts +29 -12
  269. package/dist/turns/constants/turns.constants.js +31 -19
  270. package/dist/turns/gemini-transcript.d.ts +19 -1
  271. package/dist/turns/gemini-transcript.js +29 -18
  272. package/dist/turns/index.d.ts +3 -4
  273. package/dist/turns/index.js +2 -3
  274. package/dist/turns/run-state.d.ts +71 -0
  275. package/dist/turns/run-state.js +114 -0
  276. package/dist/turns/tool-events.d.ts +11 -1
  277. package/dist/turns/tool-events.js +32 -9
  278. package/dist/turns/transcript.d.ts +15 -14
  279. package/dist/turns/transcript.js +23 -4
  280. package/dist/turns/turn-state.d.ts +82 -7
  281. package/dist/turns/turn-state.js +157 -10
  282. package/dist/turns/turn-summary.js +7 -2
  283. package/dist/turns/turn-tracker.d.ts +9 -16
  284. package/dist/turns/turn-tracker.js +163 -87
  285. package/dist/turns/types/transcript.types.d.ts +11 -1
  286. package/dist/turns/types/turn-provider.types.d.ts +33 -0
  287. package/dist/turns/types/turn-provider.types.js +1 -0
  288. package/dist/turns/types/turn-state.types.d.ts +9 -0
  289. package/dist/turns/types/turn-summary.types.d.ts +17 -1
  290. package/dist/turns/types/turn-tracker.types.d.ts +3 -1
  291. package/dist/turns/work-checkout.js +1 -2
  292. package/docs/AUDIT_PROMPT.md +10 -0
  293. package/docs/DATA_HANDLING.md +201 -13
  294. package/docs/ENTERPRISE_DEPLOYMENT.md +3 -3
  295. package/docs/PERFORMANCE.md +10 -0
  296. package/package.json +3 -2
  297. package/dist/events/canonical-event.d.ts +0 -10
  298. package/dist/events/canonical-event.js +0 -9
  299. package/dist/git/repository-root.d.ts +0 -39
  300. package/dist/git/repository-root.js +0 -131
  301. package/dist/git/types/repository-root.types.d.ts +0 -11
  302. package/dist/transport/transport.d.ts +0 -6
  303. package/dist/turns/codex-originator.d.ts +0 -11
  304. package/dist/turns/cursor-transcript.d.ts +0 -21
  305. package/dist/turns/cursor-transcript.js +0 -66
  306. package/dist/turns/native-session-titles.d.ts +0 -26
  307. package/dist/turns/native-session-titles.js +0 -102
  308. /package/dist/{git/types/repository-root.types.js → billing/types/billing.types.js} +0 -0
  309. /package/dist/{transport/transport.js → capture/types/capture.types.js} +0 -0
@@ -0,0 +1,198 @@
1
+ import type { ReplayProgressState } from '../../events/types/replay-progress.types.js';
2
+ import type { AgentWatchConfig, CaptureConfig } from '../../config/types/config.types.js';
3
+ import type { Env } from '../../core/types/core.types.js';
4
+ import type { UsageBillingMode } from '../../events/types/events.types.js';
5
+ import type { AgentWatchPaths } from '../../storage/types/storage.types.js';
6
+ import type { BackendAuthBlock } from '../../transport/auth-block.js';
7
+ import type { BackendCooldown } from '../../transport/cooldown.js';
8
+ import type { EventQueue } from '../../transport/queue.js';
9
+ import type { EventTransport } from '../../transport/types/transport.types.js';
10
+ import type { TurnUsage } from '../../turns/types/transcript.types.js';
11
+ import type { CheckoutResolver } from '../checkout-resolver.js';
12
+ /** The span of time a replay may send turns from. */
13
+ export interface ReplayWindow {
14
+ readonly start: Date;
15
+ readonly end: Date;
16
+ }
17
+ /** One tool call read out of a transcript: its name and the absolute file it named, if any. */
18
+ export interface ReplayTool {
19
+ readonly name: string;
20
+ readonly access?: 'read' | 'edit';
21
+ /** Absolute, as the agent wrote it; made checkout-relative when the event is built. */
22
+ readonly path?: string;
23
+ /** The file lies in no checkout: sent as the live hook sends it, a basename and its home-relative place. */
24
+ readonly outside?: boolean;
25
+ }
26
+ /** What a transcript says about the folder a session ran in: its repository's remote, the commit and the branch, when it recorded them. */
27
+ export interface ReplayIdentity {
28
+ readonly cwd: string;
29
+ readonly remote?: string;
30
+ readonly commit?: string;
31
+ readonly branch?: string;
32
+ }
33
+ /** One prompt and everything the agent did before the next one, as a transcript recorded it. */
34
+ export interface ReplayTurn {
35
+ /** The agent that ran it, as its live hook names itself: `claude`, `codex`, `gemini`. */
36
+ readonly provider: string;
37
+ readonly sessionId: string;
38
+ /** The live hook's `turn_id` where the file records it (Claude's `promptId`, Codex's `turn_id`); derived otherwise. */
39
+ readonly turnId: string;
40
+ readonly startedAt: string;
41
+ readonly endedAt: string;
42
+ /** Where the agent sat at the turn's last line, and the branch git reported there then. */
43
+ readonly cwd?: string;
44
+ readonly branch?: string;
45
+ /** The remote the session started in, when the file records it (Codex `session_meta.git.repository_url`); used when the folder is gone. */
46
+ readonly remote?: string;
47
+ /** The full commit the session started at (Codex `session_meta.git.commit_hash`). */
48
+ readonly commit?: string;
49
+ readonly surface?: string;
50
+ readonly usage?: TurnUsage;
51
+ readonly tools: readonly ReplayTool[];
52
+ /** The prompt as typed; read only when the effective config allows prompt text. */
53
+ readonly promptText?: string;
54
+ }
55
+ /** One `git worktree add` a transcript recorded. */
56
+ export interface LearnedWorktree {
57
+ readonly root: string;
58
+ readonly branch?: string;
59
+ /** The folder the command ran from: a checkout of the repository, for a worktree since removed. */
60
+ readonly main: string;
61
+ readonly at: string;
62
+ }
63
+ /** The checkout a turn's `cwd` resolved to, cached per directory. */
64
+ export interface ReplayCheckout {
65
+ readonly root: string;
66
+ readonly repository: string;
67
+ /** How it was found when not by the turn's folder alone: `changed`, by a file a tool edited; `carried`, the session's last changed one. Absent: the folder (`cwd`). */
68
+ readonly evidence?: 'changed' | 'carried';
69
+ /** The branch the turn was on there, when known. Set by the ladder; a transcript's own branch only ever belongs to the turn's folder. */
70
+ readonly branch?: string;
71
+ /** The `git worktree add`s of this root the transcripts recorded, oldest first. */
72
+ readonly learned?: readonly LearnedWorktree[];
73
+ /** A linked worktree's branch today, or the main checkout's when it is a trunk: its branch today says nothing about history otherwise. */
74
+ readonly head?: string;
75
+ /** A checkout of the repository that can be asked, when this one is gone. */
76
+ readonly gitRoot?: string;
77
+ }
78
+ /** What one transcript file looked like when it was counted. */
79
+ export interface ReplayFileEntry {
80
+ readonly mtimeMs: number;
81
+ readonly size: number;
82
+ readonly turns: number;
83
+ readonly done: boolean;
84
+ /** The session the file's turns belong to; sessions are counted from it, because a resumed Codex session has one file per resume. */
85
+ readonly session?: string;
86
+ /** The source that listed it; absent in a record from before Codex and Gemini replay, which listed Claude Code only. */
87
+ readonly agent?: string;
88
+ }
89
+ /** One transcript file and what a stat says about it. */
90
+ export interface TranscriptFile {
91
+ readonly file: string;
92
+ readonly mtimeMs: number;
93
+ readonly size: number;
94
+ }
95
+ /** One agent's transcripts on this machine: where they are, how to count them cheaply, how to read them as turns. */
96
+ export interface ReplaySource {
97
+ /** The provider id its turns carry. */
98
+ readonly agent: string;
99
+ /** How the developer pays for this agent; the run's `billingMode` when absent. */
100
+ readonly billingMode?: UsageBillingMode;
101
+ /** The files that may hold a turn from the window. */
102
+ list(sinceMs: number): Promise<TranscriptFile[]>;
103
+ /** About how many turns a file holds from the window, without parsing it. */
104
+ estimate(file: string, sinceMs: number): Promise<number>;
105
+ /** What the file says about its folder, from its first rows, without reading the turns; undefined when it says nothing. */
106
+ identity?(file: string): Promise<ReplayIdentity | undefined>;
107
+ /** The file's turns, oldest first. */
108
+ read(file: string, promptText: boolean): AsyncIterable<ReplayTurn>;
109
+ /** Every `git worktree add` in this agent's transcripts, whatever their date; stops between files once `stop` says so. */
110
+ worktreeAdds?(stop?: () => boolean): Promise<readonly LearnedWorktree[]>;
111
+ }
112
+ /** Why a running replay is waiting. */
113
+ export type ReplayPause = 'busy' | 'battery' | 'agent-active' | 'backend' | 'budget';
114
+ /** A repository the replay's turns placed, as the record keeps it between legs. */
115
+ export interface SeenRepositoryRecord {
116
+ readonly repository: string;
117
+ readonly sessionId: string;
118
+ readonly surface: string;
119
+ readonly provider: string;
120
+ readonly branches: readonly string[];
121
+ }
122
+ /** A replay's persisted state: the one file `status`, a resumed run and the progress record read. */
123
+ export interface ReplayRecord {
124
+ readonly replayId: string;
125
+ /** Fingerprint of the identity it sends as; another identity starts over. */
126
+ readonly identity: string;
127
+ readonly state: ReplayProgressState;
128
+ readonly windowStart: string;
129
+ readonly windowEnd: string;
130
+ /** An operator chose this window; a resume keeps it and skips the local machine gates. */
131
+ readonly operator?: boolean;
132
+ readonly startedAt: string;
133
+ readonly updatedAt: string;
134
+ readonly pid?: number;
135
+ readonly heartbeatAt?: string;
136
+ readonly pause?: ReplayPause;
137
+ readonly turnsTotal: number;
138
+ readonly turnsSent: number;
139
+ readonly sessionsTotal: number;
140
+ readonly sessionsSent: number;
141
+ readonly batches: number;
142
+ /** Turns the backend refused outright (a 4xx that retrying cannot fix); never counted as sent. */
143
+ readonly refused: number;
144
+ /** Repositories whose snapshot has been queued. */
145
+ readonly snapshotted: readonly string[];
146
+ /** Every repository the run's sent turns placed, by snapshot root, with the branches they named: a resumed leg still snapshots them. */
147
+ readonly repositories?: Readonly<Record<string, SeenRepositoryRecord>>;
148
+ readonly files: Readonly<Record<string, ReplayFileEntry>>;
149
+ /** The sources a fresh run listed; absent in a record from before Codex and Gemini replay. */
150
+ readonly agents?: readonly string[];
151
+ }
152
+ /** What the machine says about itself, as the throttle reads it. */
153
+ export interface MachineLoad {
154
+ readonly load1: number;
155
+ readonly cores: number;
156
+ readonly onBattery: boolean;
157
+ /** Milliseconds since a hook last closed a turn; Infinity when none ever did. */
158
+ readonly hookAgeMs: number;
159
+ }
160
+ /**
161
+ * What a replay run needs from the machine it runs on, handed in whole so the
162
+ * run itself touches nothing it was not given (and a test hands it a fake).
163
+ */
164
+ export interface ReplayPorts {
165
+ readonly env: Env;
166
+ readonly paths: AgentWatchPaths;
167
+ readonly config: AgentWatchConfig;
168
+ /** The identity's replay state file. */
169
+ readonly stateFile: string;
170
+ /** Fingerprint of the credential the run sends as. */
171
+ readonly identity: string;
172
+ readonly developerId: string;
173
+ readonly developerName?: string;
174
+ readonly installationId?: string;
175
+ readonly billingMode?: UsageBillingMode;
176
+ /** One per agent whose transcripts are replayed: Claude Code, Codex, Gemini CLI. */
177
+ readonly sources: readonly ReplaySource[];
178
+ /** A transport with a fresh bearer, or undefined when nothing can be sent (no backend, disabled). */
179
+ transport(): Promise<EventTransport | undefined>;
180
+ /** The offline queue snapshots and a final progress record go through. */
181
+ readonly queue: EventQueue;
182
+ readonly authBlock: BackendAuthBlock;
183
+ readonly cooldown: BackendCooldown;
184
+ /** Whether a turn that ran in this folder belongs to the identity the run sends as. */
185
+ inScope(cwd: string): boolean;
186
+ checkout: CheckoutResolver;
187
+ /** Teach `checkout` what the transcripts say about worktrees; run before anything is resolved. */
188
+ learnWorktrees?(learned: readonly LearnedWorktree[]): void;
189
+ /** Local checkouts under the selected root, used to recover repositories whose archived review checkout is gone. */
190
+ localCheckouts?(): Promise<readonly ReplayCheckout[]>;
191
+ /** The capture flags in force for a folder: the global ones, narrowed by the folder's `.agentwatch.json`, as a live hook there would read them. */
192
+ captureFor: (cwd: string) => Promise<CaptureConfig>;
193
+ machine(): Promise<MachineLoad>;
194
+ sleep(ms: number): Promise<void>;
195
+ /** Whether a pid exists. */
196
+ alive?(pid: number): boolean;
197
+ log(line: string): void;
198
+ }
@@ -0,0 +1 @@
1
+ export {};
@@ -0,0 +1,28 @@
1
+ import type { ReplayWindow } from './types/replay.types.js';
2
+ /**
3
+ * The earliest instant whose charge period is not finalized.
4
+ *
5
+ * A copy of core's `firstOpenInstant` (packages/types/src/period-month.ts): the
6
+ * start of this UTC month from the grace day on, of last month before it. Spend
7
+ * before it sits in a month the monthly close may already have frozen, so
8
+ * nothing may arrive for it late: replay never sends a turn from before it.
9
+ *
10
+ * @param now - The clock.
11
+ * @returns The first instant a replayed turn may be from.
12
+ */
13
+ export declare function firstOpenInstant(now: Date): Date;
14
+ /**
15
+ * The span a replay of `days` days may send, cut at the open charge period.
16
+ *
17
+ * @param now - The clock.
18
+ * @param days - How far back the developer asked to go.
19
+ * @returns The window; its start is never before {@link firstOpenInstant}.
20
+ */
21
+ export declare function replayWindow(now: Date, days: number): ReplayWindow;
22
+ /**
23
+ * `--replay-days` as a count of days.
24
+ *
25
+ * @param raw - The flag's value, when given.
26
+ * @returns The default when absent, the integer when it is one from 1 to 366, undefined when it is anything else.
27
+ */
28
+ export declare function parseReplayDays(raw: string | undefined): number | undefined;
@@ -0,0 +1,41 @@
1
+ import { REPLAY_DEFAULT_DAYS, REPLAY_FINALIZATION_GRACE_DAYS, REPLAY_MAX_DAYS } from './constants/replay.constants.js';
2
+ const DAY_MS = 86_400_000;
3
+ /**
4
+ * The earliest instant whose charge period is not finalized.
5
+ *
6
+ * A copy of core's `firstOpenInstant` (packages/types/src/period-month.ts): the
7
+ * start of this UTC month from the grace day on, of last month before it. Spend
8
+ * before it sits in a month the monthly close may already have frozen, so
9
+ * nothing may arrive for it late: replay never sends a turn from before it.
10
+ *
11
+ * @param now - The clock.
12
+ * @returns The first instant a replayed turn may be from.
13
+ */
14
+ export function firstOpenInstant(now) {
15
+ const back = now.getUTCDate() >= REPLAY_FINALIZATION_GRACE_DAYS ? 0 : 1;
16
+ return new Date(Date.UTC(now.getUTCFullYear(), now.getUTCMonth() - back, 1));
17
+ }
18
+ /**
19
+ * The span a replay of `days` days may send, cut at the open charge period.
20
+ *
21
+ * @param now - The clock.
22
+ * @param days - How far back the developer asked to go.
23
+ * @returns The window; its start is never before {@link firstOpenInstant}.
24
+ */
25
+ export function replayWindow(now, days) {
26
+ const asked = now.getTime() - days * DAY_MS;
27
+ const open = firstOpenInstant(now).getTime();
28
+ return { start: new Date(Math.max(asked, open)), end: now };
29
+ }
30
+ /**
31
+ * `--replay-days` as a count of days.
32
+ *
33
+ * @param raw - The flag's value, when given.
34
+ * @returns The default when absent, the integer when it is one from 1 to 366, undefined when it is anything else.
35
+ */
36
+ export function parseReplayDays(raw) {
37
+ if (raw === undefined)
38
+ return REPLAY_DEFAULT_DAYS;
39
+ const days = Number(raw);
40
+ return Number.isInteger(days) && days >= 1 && days <= REPLAY_MAX_DAYS ? days : undefined;
41
+ }
@@ -0,0 +1,42 @@
1
+ import type { LearnedWorktree } from './types/replay.types.js';
2
+ /** What a transcript taught about `git worktree add`: each path, what branch it got and when, the latest last. */
3
+ export type WorktreeMap = Map<string, LearnedWorktree[]>;
4
+ /**
5
+ * The folder's learned worktree: the nearest parent directory some `git worktree add` created.
6
+ *
7
+ * @param worktrees - The map.
8
+ * @param folder - A folder, likely gone.
9
+ * @returns The worktree's root, or undefined.
10
+ */
11
+ export declare function learnedRootOf(worktrees: WorktreeMap, folder: string): string | undefined;
12
+ /**
13
+ * The worktrees one shell command creates.
14
+ *
15
+ * ponytail: a regex reader, as `shellDirectories` is. A worktree created by a script or a harness's own tool
16
+ * leaves no such line, and a variable in the path is skipped. Ceiling: such worktrees stay unknown; the upgrade
17
+ * path is the hooks' own per-session checkout memo, which a replay of an older history does not have.
18
+ *
19
+ * @param command - The command, in memory.
20
+ * @param cwd - The folder it ran in.
21
+ * @param home - Home, for `~/`.
22
+ * @param at - When it ran.
23
+ * @returns One entry per `git worktree add`.
24
+ */
25
+ export declare function worktreesCreatedBy(command: string, cwd: string, home: string | undefined, at: string): LearnedWorktree[];
26
+ /**
27
+ * The worktrees a transcript's Bash calls created.
28
+ *
29
+ * Only the top session and its sub-agents' lines in this file; Codex rollouts are not read.
30
+ *
31
+ * @param file - A Claude Code transcript.
32
+ * @param home - Home, for `~/`.
33
+ * @returns What it created.
34
+ */
35
+ export declare function worktreesInTranscript(file: string, home: string | undefined): Promise<LearnedWorktree[]>;
36
+ /**
37
+ * Put what was learned into the map, each path's entries oldest first.
38
+ *
39
+ * @param worktrees - The map.
40
+ * @param learned - The entries.
41
+ */
42
+ export declare function learnWorktrees(worktrees: WorktreeMap, learned: readonly LearnedWorktree[]): void;
@@ -0,0 +1,134 @@
1
+ import fs from 'node:fs';
2
+ import path from 'node:path';
3
+ import readline from 'node:readline';
4
+ import { asRecord } from '../core/object.js';
5
+ import { RE_DIRECTORY_ARGUMENTS, RE_HEREDOC, RE_HOME_PREFIX, HEREDOC_PLACEHOLDER, RE_SHELL_SEPARATORS, RE_SURROUNDING_QUOTES, RE_UNEXPANDED } from '../providers/shared/constants/shell-directories.constants.js';
6
+ import { shellDirectories } from '../providers/shared/shell-directories.js';
7
+ import { parseJsonLine } from '../turns/transcript.js';
8
+ const WORKTREE_ADD = 'worktree add';
9
+ const SHELL_TOOL = 'Bash';
10
+ const RE_SHELL_WORD = /"[^"]*"|'[^']*'|(?:\\ |\S)+/g;
11
+ /** A `git worktree add` argument that names a commit rather than a branch: a sha, a relative ref, a tag, a remote's. */
12
+ const RE_NOT_A_BRANCH = /^(?:[0-9a-f]{7,40}$|HEAD|@|v?\d+\.\d|(?:origin|upstream|refs|pull|tags)\/)|[~^]/;
13
+ const RE_CHANGE_DIRECTORY_COMMAND = /^(?:cd|pushd)\s/;
14
+ /** Only git itself creates a worktree: `grep "git worktree add" docs` names one and creates nothing. */
15
+ const RE_GIT_COMMAND = /^(?:\w+=\S*\s+)*git\s/;
16
+ const RE_SUBSHELL_PARENS = /^\(\s*|\s*\)$/g;
17
+ /** Where the command's arguments end and the shell's plumbing begins: a pipe, a background `&`, a redirect. */
18
+ const RE_SHELL_PLUMBING = /^(?:\||&|\d*[<>])/;
19
+ const RE_LEADING_TILDE = /^~/;
20
+ const RE_GIT_DASH_C = RE_DIRECTORY_ARGUMENTS[0];
21
+ /**
22
+ * The folder's learned worktree: the nearest parent directory some `git worktree add` created.
23
+ *
24
+ * @param worktrees - The map.
25
+ * @param folder - A folder, likely gone.
26
+ * @returns The worktree's root, or undefined.
27
+ */
28
+ export function learnedRootOf(worktrees, folder) {
29
+ for (let dir = folder; dir !== path.dirname(dir); dir = path.dirname(dir))
30
+ if (worktrees.has(dir))
31
+ return dir;
32
+ return undefined;
33
+ }
34
+ /**
35
+ * The worktrees one shell command creates.
36
+ *
37
+ * ponytail: a regex reader, as `shellDirectories` is. A worktree created by a script or a harness's own tool
38
+ * leaves no such line, and a variable in the path is skipped. Ceiling: such worktrees stay unknown; the upgrade
39
+ * path is the hooks' own per-session checkout memo, which a replay of an older history does not have.
40
+ *
41
+ * @param command - The command, in memory.
42
+ * @param cwd - The folder it ran in.
43
+ * @param home - Home, for `~/`.
44
+ * @param at - When it ran.
45
+ * @returns One entry per `git worktree add`.
46
+ */
47
+ export function worktreesCreatedBy(command, cwd, home, at) {
48
+ const added = [];
49
+ let base = cwd;
50
+ for (const piece of command.replace(RE_HEREDOC, HEREDOC_PLACEHOLDER).split(RE_SHELL_SEPARATORS)) {
51
+ const trimmed = piece.trim().replace(RE_SUBSHELL_PARENS, '');
52
+ if (RE_CHANGE_DIRECTORY_COMMAND.test(trimmed))
53
+ base = shellDirectories(trimmed, base, home)[0] ?? base;
54
+ const index = trimmed.indexOf(WORKTREE_ADD);
55
+ if (index < 0 || !RE_GIT_COMMAND.test(trimmed))
56
+ continue;
57
+ const { branch, target } = worktreeArguments(trimmed.slice(index + WORKTREE_ADD.length));
58
+ const dashC = [...trimmed.matchAll(RE_GIT_DASH_C)][0]?.[1];
59
+ const main = dashC ? (shellDirectories(`cd ${dashC}`, base, home)[0] ?? base) : base;
60
+ const expanded = target && home ? target.replace(RE_HOME_PREFIX, () => home) : target;
61
+ if (expanded && !RE_UNEXPANDED.test(expanded) && !RE_LEADING_TILDE.test(expanded))
62
+ added.push({ root: path.resolve(main, expanded), branch, main, at });
63
+ }
64
+ return added;
65
+ }
66
+ function worktreeArguments(text) {
67
+ const words = (text.match(RE_SHELL_WORD) ?? []).map((word) => word.replace(RE_SURROUNDING_QUOTES, '').replaceAll('\\ ', ' '));
68
+ const positional = [];
69
+ let branch;
70
+ let detached = false;
71
+ for (let i = 0; i < words.length; i += 1) {
72
+ const word = words[i];
73
+ if (RE_SHELL_PLUMBING.test(word))
74
+ break;
75
+ detached ||= word === '--detach' || word === '-d';
76
+ if (word === '-b' || word === '-B' || word === '--reason') {
77
+ i += 1;
78
+ branch = word === '--reason' ? branch : words[i];
79
+ continue;
80
+ }
81
+ if (!word.startsWith('-'))
82
+ positional.push(word);
83
+ }
84
+ const commitish = positional[1];
85
+ return { branch: branch ?? (commitish && !detached && !RE_NOT_A_BRANCH.test(commitish) ? commitish : undefined), target: positional[0] };
86
+ }
87
+ /**
88
+ * The worktrees a transcript's Bash calls created.
89
+ *
90
+ * Only the top session and its sub-agents' lines in this file; Codex rollouts are not read.
91
+ *
92
+ * @param file - A Claude Code transcript.
93
+ * @param home - Home, for `~/`.
94
+ * @returns What it created.
95
+ */
96
+ export async function worktreesInTranscript(file, home) {
97
+ const lines = readline.createInterface({ input: fs.createReadStream(file, { encoding: 'utf8' }), crlfDelay: Infinity });
98
+ const found = [];
99
+ try {
100
+ for await (const line of lines)
101
+ if (line.includes(WORKTREE_ADD))
102
+ found.push(...worktreesOfLine(line, home));
103
+ }
104
+ catch {
105
+ return found;
106
+ }
107
+ finally {
108
+ lines.close();
109
+ }
110
+ return found;
111
+ }
112
+ function worktreesOfLine(line, home) {
113
+ const entry = parseJsonLine(line);
114
+ const cwd = entry?.['cwd'];
115
+ const at = entry?.['timestamp'];
116
+ const content = asRecord(entry?.['message'])?.['content'];
117
+ if (typeof cwd !== 'string' || typeof at !== 'string' || !Array.isArray(content))
118
+ return [];
119
+ return content.flatMap((block) => {
120
+ const call = asRecord(block);
121
+ const command = asRecord(call?.['input'])?.['command'];
122
+ return call?.['type'] === 'tool_use' && call['name'] === SHELL_TOOL && typeof command === 'string' && command.includes(WORKTREE_ADD) ? worktreesCreatedBy(command, cwd, home, at) : [];
123
+ });
124
+ }
125
+ /**
126
+ * Put what was learned into the map, each path's entries oldest first.
127
+ *
128
+ * @param worktrees - The map.
129
+ * @param learned - The entries.
130
+ */
131
+ export function learnWorktrees(worktrees, learned) {
132
+ for (const entry of learned)
133
+ worktrees.set(entry.root, [...(worktrees.get(entry.root) ?? []), entry].sort((a, b) => a.at.localeCompare(b.at)));
134
+ }
@@ -1,37 +1,54 @@
1
1
  import type { BranchRef } from '../git/types/snapshot.types.js';
2
- import type { SelectionInput, SnapshotState } from './types/snapshot.types.js';
2
+ import type { SelectionInput, SnapshotCandidate, SnapshotState } from './types/snapshot.types.js';
3
3
  /**
4
- * Which branches are worth describing again.
4
+ * The branches the snapshot walks, newest commit first, and which of them are due.
5
5
  *
6
- * Four reasons, and each one is a bug if it is missing:
6
+ * A branch already found on the trunk, at the same head and against the same
7
+ * base, is left out without a git process: merged stays merged, and that is
8
+ * what lets the walk pass the dozens of finished branches a busy repository
9
+ * keeps to reach the live ones behind them. Every other branch is a candidate,
10
+ * due when one of these holds — and each one is a bug if it is missing:
7
11
  *
8
- * - the branch is new — nothing has ever been reported about it;
9
- * - its head moved — the obvious one;
10
- * - the default branch changed since the last send, because every delta was
11
- * computed against the wrong base and no head has to move for that to be
12
- * true;
13
- * - the entry is older than the heartbeat, which is the only thing that ever
14
- * re-offers a finished branch to a tracker connected after the fact.
12
+ * - the branch is new — nothing has ever been checked about it;
13
+ * - its head moved — the obvious one, and how a merged branch with new work
14
+ * comes back;
15
+ * - the default branch changed since it was checked, because its delta and its
16
+ * verdict were computed against the wrong base and no head has to move for
17
+ * that to be true;
18
+ * - it was last sent longer ago than the heartbeat, which is the only thing
19
+ * that ever re-offers a finished branch to a tracker connected after the fact.
15
20
  *
16
- * @param input - The refs git reported and what was last sent.
17
- * @returns The branches to describe. Empty means send nothing at all.
21
+ * @param input - The refs git reported and what was last recorded.
22
+ * @returns The candidates in walk order.
18
23
  */
19
- export declare function selectChangedBranches(input: SelectionInput): readonly BranchRef[];
24
+ export declare function snapshotCandidates(input: SelectionInput): readonly SnapshotCandidate[];
25
+ /**
26
+ * Whether the walk would reach a due branch before the window is full.
27
+ *
28
+ * The cheap exit on an ordinary closing turn: the first ten live branches are
29
+ * all as they were sent, so no git process runs and nothing is queued.
30
+ *
31
+ * @param candidates - The walk, from {@link snapshotCandidates}.
32
+ * @returns True when something has to be checked.
33
+ */
34
+ export declare function anyDue(candidates: readonly SnapshotCandidate[]): boolean;
20
35
  /**
21
36
  * The state to store once a snapshot has been queued.
22
37
  *
23
- * A branch is recorded as reported only if it was actually described. The
24
- * cache is a record of what the platform has been told, not of what git said:
25
- * a branch whose head moved and which then fell outside the budget must keep
26
- * its *old* head here, or the next turn compares the new head against the new
27
- * head, finds them equal, and the work disappears until the heartbeat six hours
28
- * later.
38
+ * A branch is recorded only if it was actually checked. The cache is a record
39
+ * of what the platform has been told, not of what git said: a branch whose head
40
+ * moved and which then fell outside the budget must keep its *old* head here,
41
+ * or the next turn compares the new head against the new head, finds them
42
+ * equal, and the work disappears until the heartbeat six hours later.
29
43
  *
30
- * A branch that was listed but never sent is therefore left exactly as it was —
31
- * and one that has never been sent at all is left out, so it stays new.
44
+ * A branch found on the trunk is recorded as merged: the platform has been told
45
+ * all there is, and the verdict is what keeps every later turn from checking it
46
+ * again. Each entry carries the base it was checked against, so a trunk change
47
+ * re-checks branch by branch and a budget cut part-way loses nothing.
32
48
  *
33
49
  * @param input - Refs, previous state and the send's own clock.
34
- * @param sent - The branches this snapshot actually described.
50
+ * @param sent - The live branches this snapshot described.
51
+ * @param merged - The branches it found already on the trunk.
35
52
  * @returns The state to write.
36
53
  */
37
- export declare function nextSnapshotState(input: SelectionInput, sent: readonly BranchRef[]): SnapshotState;
54
+ export declare function nextSnapshotState(input: SelectionInput, sent: readonly BranchRef[], merged?: readonly BranchRef[]): SnapshotState;