@agent-watch-ai/edge 0.6.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 (282) hide show
  1. package/CHANGELOG.md +219 -9
  2. package/README.md +303 -4
  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 +5 -2
  76. package/dist/events/constants/events.constants.js +4 -1
  77. package/dist/events/index.d.ts +1 -0
  78. package/dist/events/product-event.d.ts +6 -3
  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-tree.types.d.ts +2 -1
  83. package/dist/feature/ticket-candidates.d.ts +1 -1
  84. package/dist/git/checkout-root.d.ts +15 -0
  85. package/dist/git/checkout-root.js +18 -0
  86. package/dist/git/code-state.d.ts +2 -16
  87. package/dist/git/code-state.js +11 -12
  88. package/dist/git/constants/git.constants.d.ts +31 -11
  89. package/dist/git/constants/git.constants.js +36 -12
  90. package/dist/git/fingerprint.d.ts +3 -6
  91. package/dist/git/fingerprint.js +5 -8
  92. package/dist/git/git-context.js +5 -1
  93. package/dist/git/index.d.ts +1 -2
  94. package/dist/git/index.js +1 -1
  95. package/dist/git/repo-snapshot.d.ts +13 -4
  96. package/dist/git/repo-snapshot.js +47 -9
  97. package/dist/git/types/snapshot.types.d.ts +2 -0
  98. package/dist/pipeline/constants/pipeline.constants.d.ts +3 -0
  99. package/dist/pipeline/constants/pipeline.constants.js +3 -0
  100. package/dist/pipeline/hook-pipeline.js +81 -57
  101. package/dist/privacy/product-capture.js +2 -0
  102. package/dist/providers/antigravity/antigravity.capture.d.ts +2 -0
  103. package/dist/providers/antigravity/antigravity.capture.js +5 -0
  104. package/dist/providers/antigravity/antigravity.detect.js +8 -22
  105. package/dist/providers/antigravity/antigravity.provider.js +10 -3
  106. package/dist/providers/antigravity/constants/antigravity.constants.d.ts +1 -0
  107. package/dist/providers/antigravity/constants/antigravity.constants.js +1 -0
  108. package/dist/providers/claude/claude.adapter.js +9 -6
  109. package/dist/providers/claude/claude.detect.js +2 -17
  110. package/dist/providers/claude/claude.otel.d.ts +21 -3
  111. package/dist/providers/claude/claude.otel.js +216 -61
  112. package/dist/providers/claude/claude.provider.js +17 -1
  113. package/dist/providers/claude/claude.version.d.ts +9 -0
  114. package/dist/providers/claude/claude.version.js +28 -0
  115. package/dist/providers/claude/constants/claude.constants.d.ts +27 -0
  116. package/dist/providers/claude/constants/claude.constants.js +27 -0
  117. package/dist/providers/claude/constants/claude.otel.constants.d.ts +27 -0
  118. package/dist/providers/claude/constants/claude.otel.constants.js +45 -5
  119. package/dist/providers/claude/types/claude.types.d.ts +13 -0
  120. package/dist/providers/codex/codex.capture.d.ts +76 -0
  121. package/dist/providers/codex/codex.capture.js +454 -0
  122. package/dist/providers/codex/codex.detect.js +2 -4
  123. package/dist/providers/codex/codex.otel.d.ts +38 -2
  124. package/dist/providers/codex/codex.otel.js +50 -6
  125. package/dist/providers/codex/codex.provider.js +8 -0
  126. package/dist/providers/codex/codex.surface.d.ts +9 -0
  127. package/dist/{turns/codex-originator.js → providers/codex/codex.surface.js} +17 -3
  128. package/dist/providers/codex/codex.titles.d.ts +14 -0
  129. package/dist/providers/codex/codex.titles.js +35 -0
  130. package/dist/providers/codex/constants/codex.constants.d.ts +4 -0
  131. package/dist/providers/codex/constants/codex.constants.js +4 -0
  132. package/dist/providers/cursor/constants/cursor.constants.d.ts +17 -4
  133. package/dist/providers/cursor/constants/cursor.constants.js +25 -5
  134. package/dist/providers/cursor/cursor-mcp-memo.d.ts +34 -0
  135. package/dist/providers/cursor/cursor-mcp-memo.js +94 -0
  136. package/dist/providers/cursor/cursor.adapter.js +20 -82
  137. package/dist/providers/cursor/cursor.capture.d.ts +1 -0
  138. package/dist/providers/cursor/cursor.capture.js +4 -0
  139. package/dist/providers/cursor/cursor.detect.d.ts +5 -1
  140. package/dist/providers/cursor/cursor.detect.js +11 -26
  141. package/dist/providers/cursor/cursor.hooks.js +2 -2
  142. package/dist/providers/cursor/cursor.provider.js +16 -7
  143. package/dist/providers/cursor/cursor.titles.d.ts +14 -0
  144. package/dist/providers/cursor/cursor.titles.js +20 -0
  145. package/dist/providers/cursor/schemas/cursor.schema.d.ts +3 -3
  146. package/dist/providers/cursor/schemas/cursor.schema.js +5 -3
  147. package/dist/providers/gemini/constants/gemini.constants.d.ts +16 -0
  148. package/dist/providers/gemini/constants/gemini.constants.js +17 -0
  149. package/dist/providers/gemini/gemini.capture.d.ts +81 -0
  150. package/dist/providers/gemini/gemini.capture.js +210 -0
  151. package/dist/providers/gemini/gemini.detect.js +57 -24
  152. package/dist/providers/gemini/gemini.otel.d.ts +38 -2
  153. package/dist/providers/gemini/gemini.otel.js +56 -125
  154. package/dist/providers/gemini/gemini.provider.js +5 -0
  155. package/dist/providers/index.d.ts +1 -0
  156. package/dist/providers/index.js +1 -0
  157. package/dist/providers/provider.d.ts +8 -0
  158. package/dist/providers/provider.js +9 -0
  159. package/dist/providers/registry.d.ts +14 -0
  160. package/dist/providers/registry.js +14 -0
  161. package/dist/providers/shared/constants/hook-config.constants.d.ts +2 -0
  162. package/dist/providers/shared/constants/hook-config.constants.js +2 -0
  163. package/dist/providers/shared/constants/terminal-capture.constants.d.ts +6 -0
  164. package/dist/providers/shared/constants/terminal-capture.constants.js +6 -0
  165. package/dist/providers/shared/editor-paths.d.ts +8 -0
  166. package/dist/providers/shared/editor-paths.js +18 -0
  167. package/dist/providers/shared/hook-config.d.ts +5 -0
  168. package/dist/providers/shared/hook-config.js +39 -1
  169. package/dist/providers/shared/hooks-marker.d.ts +14 -0
  170. package/dist/providers/shared/hooks-marker.js +23 -0
  171. package/dist/providers/shared/install-record.d.ts +29 -0
  172. package/dist/providers/shared/install-record.js +52 -0
  173. package/dist/providers/shared/session-title-store.d.ts +23 -0
  174. package/dist/providers/shared/session-title-store.js +50 -0
  175. package/dist/providers/shared/terminal-capture.d.ts +41 -0
  176. package/dist/providers/shared/terminal-capture.js +109 -0
  177. package/dist/providers/shared/tooling.d.ts +21 -0
  178. package/dist/providers/shared/tooling.js +36 -1
  179. package/dist/providers/types/provider.types.d.ts +57 -4
  180. package/dist/replay/checkout-resolver.d.ts +29 -0
  181. package/dist/replay/checkout-resolver.js +69 -0
  182. package/dist/replay/codex-turns.d.ts +24 -0
  183. package/dist/replay/codex-turns.js +221 -0
  184. package/dist/replay/constants/replay.constants.d.ts +99 -0
  185. package/dist/replay/constants/replay.constants.js +102 -0
  186. package/dist/replay/describe.d.ts +10 -0
  187. package/dist/replay/describe.js +31 -0
  188. package/dist/replay/gemini-turns.d.ts +36 -0
  189. package/dist/replay/gemini-turns.js +192 -0
  190. package/dist/replay/machine.d.ts +34 -0
  191. package/dist/replay/machine.js +68 -0
  192. package/dist/replay/progress-event.d.ts +21 -0
  193. package/dist/replay/progress-event.js +45 -0
  194. package/dist/replay/replay-runner.d.ts +58 -0
  195. package/dist/replay/replay-runner.js +529 -0
  196. package/dist/replay/replay-scan.d.ts +83 -0
  197. package/dist/replay/replay-scan.js +170 -0
  198. package/dist/replay/replay-state.d.ts +108 -0
  199. package/dist/replay/replay-state.js +199 -0
  200. package/dist/replay/resume.d.ts +18 -0
  201. package/dist/replay/resume.js +34 -0
  202. package/dist/replay/start.d.ts +23 -0
  203. package/dist/replay/start.js +39 -0
  204. package/dist/replay/throttle.d.ts +35 -0
  205. package/dist/replay/throttle.js +41 -0
  206. package/dist/replay/transcript-turns.d.ts +35 -0
  207. package/dist/replay/transcript-turns.js +215 -0
  208. package/dist/replay/turn-event.d.ts +38 -0
  209. package/dist/replay/turn-event.js +116 -0
  210. package/dist/replay/types/replay.types.d.ts +162 -0
  211. package/dist/replay/types/replay.types.js +1 -0
  212. package/dist/replay/window.d.ts +28 -0
  213. package/dist/replay/window.js +41 -0
  214. package/dist/snapshot/branch-selection.d.ts +40 -23
  215. package/dist/snapshot/branch-selection.js +71 -41
  216. package/dist/snapshot/constants/snapshot-stages.constants.d.ts +3 -1
  217. package/dist/snapshot/constants/snapshot-stages.constants.js +3 -1
  218. package/dist/snapshot/constants/snapshot.constants.d.ts +34 -7
  219. package/dist/snapshot/constants/snapshot.constants.js +34 -7
  220. package/dist/snapshot/index.d.ts +2 -2
  221. package/dist/snapshot/index.js +1 -1
  222. package/dist/snapshot/snapshot-pipeline.js +89 -26
  223. package/dist/snapshot/snapshot-state.js +6 -2
  224. package/dist/snapshot/tree-pipeline.d.ts +1 -1
  225. package/dist/snapshot/tree-pipeline.js +34 -15
  226. package/dist/snapshot/types/snapshot.types.d.ts +20 -3
  227. package/dist/storage/schemas/storage.schema.d.ts +2 -0
  228. package/dist/storage/schemas/storage.schema.js +6 -0
  229. package/dist/transport/delivery-stats.d.ts +13 -1
  230. package/dist/transport/delivery-stats.js +18 -2
  231. package/dist/transport/delivery.d.ts +4 -3
  232. package/dist/transport/delivery.js +21 -7
  233. package/dist/transport/identity-delivery.d.ts +20 -0
  234. package/dist/transport/identity-delivery.js +41 -0
  235. package/dist/transport/index.d.ts +2 -0
  236. package/dist/transport/index.js +1 -0
  237. package/dist/transport/types/delivery-flow.types.d.ts +7 -0
  238. package/dist/turns/claude-transcript.js +4 -12
  239. package/dist/turns/codex-transcript.d.ts +9 -0
  240. package/dist/turns/codex-transcript.js +27 -19
  241. package/dist/turns/constants/turns.constants.d.ts +13 -12
  242. package/dist/turns/constants/turns.constants.js +15 -19
  243. package/dist/turns/gemini-transcript.d.ts +19 -1
  244. package/dist/turns/gemini-transcript.js +29 -18
  245. package/dist/turns/index.d.ts +3 -4
  246. package/dist/turns/index.js +2 -3
  247. package/dist/turns/run-state.d.ts +71 -0
  248. package/dist/turns/run-state.js +114 -0
  249. package/dist/turns/tool-events.d.ts +11 -1
  250. package/dist/turns/tool-events.js +32 -9
  251. package/dist/turns/transcript.d.ts +15 -14
  252. package/dist/turns/transcript.js +23 -4
  253. package/dist/turns/turn-state.d.ts +49 -7
  254. package/dist/turns/turn-state.js +78 -10
  255. package/dist/turns/turn-summary.js +7 -2
  256. package/dist/turns/turn-tracker.d.ts +9 -16
  257. package/dist/turns/turn-tracker.js +162 -86
  258. package/dist/turns/types/transcript.types.d.ts +11 -1
  259. package/dist/turns/types/turn-provider.types.d.ts +33 -0
  260. package/dist/turns/types/turn-provider.types.js +1 -0
  261. package/dist/turns/types/turn-state.types.d.ts +9 -0
  262. package/dist/turns/types/turn-summary.types.d.ts +17 -1
  263. package/dist/turns/types/turn-tracker.types.d.ts +3 -1
  264. package/dist/turns/work-checkout.js +1 -2
  265. package/docs/AUDIT_PROMPT.md +10 -0
  266. package/docs/DATA_HANDLING.md +193 -7
  267. package/docs/ENTERPRISE_DEPLOYMENT.md +1 -1
  268. package/docs/PERFORMANCE.md +10 -0
  269. package/package.json +3 -2
  270. package/dist/events/canonical-event.d.ts +0 -10
  271. package/dist/events/canonical-event.js +0 -9
  272. package/dist/git/repository-root.d.ts +0 -39
  273. package/dist/git/repository-root.js +0 -131
  274. package/dist/git/types/repository-root.types.d.ts +0 -11
  275. package/dist/transport/transport.d.ts +0 -6
  276. package/dist/turns/codex-originator.d.ts +0 -11
  277. package/dist/turns/cursor-transcript.d.ts +0 -21
  278. package/dist/turns/cursor-transcript.js +0 -66
  279. package/dist/turns/native-session-titles.d.ts +0 -26
  280. package/dist/turns/native-session-titles.js +0 -102
  281. /package/dist/{git/types/repository-root.types.js → billing/types/billing.types.js} +0 -0
  282. /package/dist/{transport/transport.js → capture/types/capture.types.js} +0 -0
@@ -76,7 +76,7 @@ fields.
76
76
  Current policy is reapplied to old turn state before queueing, and to every queued
77
77
  record before HTTP delivery: summaries always lose `prompt` and `response` text an
78
78
  older release may have written, lose `prompt_text`, `tool_inputs`, `session_name` and `session_title` unless their
79
- flag is on with consent, lose every path list once `capture.files` is off, lose `tool_events` once `capture.git` is off, and repository snapshots are dropped entirely once
79
+ flag is on with consent, lose every path list once `capture.files` is off, lose `tool_events` and `command` once `capture.git` is off, and repository snapshots are dropped entirely once
80
80
  `capture.git` is off. Old files are not erased by an upgrade; their original content
81
81
  may remain locally until consumed or expired, but it is never sent.
82
82
 
@@ -100,15 +100,17 @@ puts the totals on the turn summary; no rollout content is read into it or sent.
100
100
 
101
101
  ## Outbound records
102
102
 
103
- There are five public event types, not a raw lifecycle or tool event stream:
103
+ There are six public event types, not a raw lifecycle or tool event stream:
104
104
 
105
105
  | Type | Source and purpose |
106
106
  | --- | --- |
107
107
  | `turn.summary` | Edge hooks assemble one completed turn and send it to the events endpoint, or queue it. |
108
108
  | `llm.call` | Agents export native OTLP directly. The backend/library normalizes supported completed request records into per-call usage. Edge does not proxy native OTLP. |
109
+ | `llm.call` (captured) | Edge's shim records the provider calls of a process the coding agent starts through its shell tool, and Edge queues them as calls of the launching session and turn. See "Captured runs". |
109
110
  | `repo.snapshot` | Edge queues changed repository branch/commit metadata after a closed turn when Git capture is enabled. |
110
111
  | `session.billing` | Edge states how the session's developer pays (`api` or `subscription`, detected from the agent's local auth state), once, when the session opens. |
111
112
  | `repo.tree` | Edge queues the default branch's source file paths and top-level declaration names after a closed turn when Git and file capture are enabled, once per repository per install identity. Never file contents. |
113
+ | `replay.progress` | Edge states how far a replay of the developer's earlier Claude Code, Codex and Gemini CLI sessions has got: counts and the window, nothing else. See "Replay of earlier sessions". |
112
114
 
113
115
  Generated records share `schemaVersion`, `id`, `timestamp`, `event.type`,
114
116
  `event.providerEventType`, `agent.provider`, `agent.name`, session identifiers,
@@ -118,10 +120,10 @@ availability determines which identifiers and usage values exist.
118
120
  ### `turn.summary`
119
121
 
120
122
  The hook-generated flat fields are `provider`, `surface`, `session_id`, `turn_id`,
121
- `developer_id`, `repository`, `branch`, `commit`, `jira_ids`, `prompt_jira_ids`, `work_evidence`,
123
+ `developer_id`, `account_email`, `session_mode`, `is_cloud_agent`, `repository`, `branch`, `commit`, `jira_ids`, `prompt_jira_ids`, `work_evidence`,
122
124
  `parent_session_id`, `content_hashes`, `manifest_repository`, `files_changed`, `files_touched`, `files_read`, `external_files_touched`,
123
125
  `external_files_read`, `prompt_text`, `session_name`, `session_title`, `tool_inputs`,
124
- `tool_calls`, `tools_used`, `tool_events`, `model`, `billing_mode`, `input_tokens`,
126
+ `tool_calls`, `tools_used`, `tool_events`, `command`, `model`, `billing_mode`, `input_tokens`,
125
127
  `cached_input_tokens`, `cache_creation_input_tokens`, `output_tokens`,
126
128
  `usage_status`, `started_at`, and `ended_at`. The nested `session` contains `id`,
127
129
  `providerId`, and optionally `turnId`.
@@ -192,7 +194,7 @@ text the developer typed or the agent answered.
192
194
  calls), `started_at` (from the provider's duration, or from the call's start
193
195
  hook paired on its call id or Antigravity's step index; a call with neither, such
194
196
  as a Gemini CLI call without `tool_use_id`, sends none), `ended_at`, `input_fp`, `check`,
195
- `commit` and `diff_fp`. There is no field for a command, a path, arguments or
197
+ `commit`, `diff_fp` and `skill`. There is no field for a command, a path, arguments or
196
198
  an output.
197
199
  - `input_fp`: for a shell call, the sha256 of the command after normalization
198
200
  (quotes undone, whitespace collapsed, `cd` segments, redirections and leading
@@ -218,6 +220,17 @@ text the developer typed or the agent answered.
218
220
  only extra work a check costs the hook: `git rev-parse HEAD` and `git diff`,
219
221
  both read-only and run with `--no-optional-locks`, so they write nothing to
220
222
  the repository and never take the agent's index lock.
223
+ - `skill`, on a Claude Code `Skill` call only: the name of the skill it ran
224
+ (`build-ticket`, `plugin:name`), read in memory from the call's input. Never
225
+ its arguments. A name that is not 1-80 characters of letters, digits and
226
+ `_ . : / -` (starting with a letter or digit) is dropped; the call is still sent.
227
+ - `command` (under `git`, on by default, withheld with `tool_events`): the name of
228
+ the slash command the turn's first prompt opens with, without the slash and
229
+ without anything after it: `/ship-it now` sends `ship-it`. Read in memory from
230
+ the prompt in the hook; nothing else of the prompt is kept for it. A first
231
+ token holding a further `/` (a path such as `/Users/me/a.ts`) or failing the
232
+ name rule above sends nothing. Claude Code only: Codex, Cursor, Gemini CLI and
233
+ Antigravity send neither field.
221
234
 
222
235
  On the machine, a tool call's start is kept in local turn state (mode 0600) until
223
236
  the turn closes, only while `capture.git` is on: its time and the agent's call id
@@ -279,10 +292,82 @@ but the content gate above can prevent their provider configuration; traces and
279
292
  metrics default off. See [Claude telemetry](https://code.claude.com/docs/en/monitoring-usage)
280
293
  and [Gemini telemetry](https://geminicli.com/docs/cli/telemetry/) for provider gates.
281
294
 
295
+ ### Captured runs
296
+
297
+ Setup copies Edge's shims to `<data dir>/capture/`, mode 0600 in a 0700 folder,
298
+ overwriting them on every run, and adds that copy to what a coding agent's shell tool
299
+ starts: `NODE_OPTIONS` gains `--require <data dir>/capture/node.cjs`, and `PYTHONPATH`
300
+ gains `<data dir>/capture/python`. Both run inside that process, as the developer. The
301
+ target is a copy because Node refuses to start when a `--require` target is missing, so
302
+ it must not depend on the package staying where it is. A value the developer already
303
+ had is kept beside ours. Setup and uninstall remove an entry only when it lies in an
304
+ Edge install or is this copy, or when it is a shim-shaped `--require` whose target is
305
+ gone. `agentwatch uninstall` removes the entries, and the copy once no agent's hooks are
306
+ left. `agentwatch off` keeps the copy, because sessions already running still load it;
307
+ restart those sessions after an uninstall. A process whose entry is a coding agent
308
+ (`claude`, `codex`, `gemini`, `cursor`, `cursor-agent`, `antigravity`, `agy`) captures
309
+ nothing. `AGENTWATCH_CAPTURE=off` in a process's environment turns the shim off for it.
310
+
311
+ The entries live in Claude Code's `settings.json` `env` block, in
312
+ `[shell_environment_policy.set]` of Codex's `config.toml`, and in `~/.gemini/.env`. For
313
+ Cursor and Antigravity nothing is written, and status says there is no environment route,
314
+ until that route is verified on the app. Capture is usage only, so it does not wait on
315
+ `contentCaptureConsent`, which holds back the native export of Codex and Gemini CLI
316
+ because those logs carry tool content.
317
+
318
+ Codex's default sandbox denies a command's write outside the workspace, so setup also adds
319
+ `<data dir>/captured`, and only that folder, to `[sandbox_workspace_write] writable_roots`
320
+ in `config.toml`. A sandboxed command can therefore write to the spool, and nothing else in
321
+ the data dir: credentials stay outside the sandbox's writable set. Entries already in the
322
+ array stay, and uninstall takes out only that one, along with the table if Edge created it
323
+ and nothing else is in it. With `default_permissions` set, nothing is added, as Codex says
324
+ not to combine the two; status warns that what runs is counted only if that profile allows
325
+ the write. `sandbox_mode = "read-only"` and `codex exec`'s read-only default deny it too.
326
+ Inside the workspace-write sandbox on macOS the write is allowed but `ps` is denied, so the
327
+ shim cannot record its ancestors and such a record is dropped, and the network is off unless
328
+ `network_access = true`. A script's call is counted under `danger-full-access` or as an
329
+ escalated command; status says so.
330
+
331
+ For a response from Anthropic, OpenAI, Google (Gemini, Vertex AI) or Bedrock, a shim
332
+ reads the request's host, method and URL path up to `?` (a Gemini key can follow it),
333
+ and the response's status, request id header, model and usage fields. It holds a
334
+ non-streamed body in memory, up to 8 MB, only to find those fields. It never reads a
335
+ request body or a request header other than the host, and it opens no socket.
336
+
337
+ It appends one line per call to `<data dir>/captured/<pid>.jsonl`, mode 0600, at most
338
+ 10,000 lines per file: `pid`, `started`, `ancestors` (pid and start time of the
339
+ processes above it), `at`, `seq`, `script` (its own file name, used only to find its
340
+ run), `provider`, `model`, `request_id`, `status`, `usage`.
341
+ To read its ancestors, a shim runs `ps -A` once, at the process's first provider call,
342
+ and keeps only its own chain. The shims write only while the `captured` folder exists:
343
+ a hook creates it when Edge holds a credential, and removes it and its contents when
344
+ Edge does not. So a signed-out machine captures nothing and holds nothing back.
345
+
346
+ At the next hook on the machine, Edge reads and deletes those files. It discards `pid`,
347
+ `ancestors`, `script` and the other process details, and queues an `llm.call` per record, with
348
+ `billing_mode: api` and two more fields:
349
+
350
+ - `run_entry`: the file the shell command ran, relative to its checkout, or the file
351
+ name alone outside one. An inline program (`python -c`), a package script
352
+ (`npm run dev`) or any other command is named by its runner or first word, and
353
+ `capture.files: false` keeps it to that. It is scrubbed like a turn summary's paths.
354
+ The command's other text is read in memory and kept nowhere, and a `VAR=value`
355
+ prefix is not read.
356
+ - `platform`: which provider's API served the call.
357
+
358
+ To name the entry file, each session keeps a list of its shell calls' entries in its
359
+ own state folder, removed with the session. A record no session or run claims is
360
+ dropped and counted in `agentwatch status`, and no event is built from it. On a
361
+ machine with several identities, a hook leaves another tenant's spool file for that
362
+ session's own hook.
363
+
282
364
  ### `repo.snapshot` and Git metadata
283
365
 
284
366
  Snapshots contain `provider`, `surface`, `repository`, optional `developer_id`,
285
- `default_branch`, `captured_at`, and `branches`. Each branch has `name`,
367
+ `default_branch`, `captured_at`, and `branches`. A branch whose work is already
368
+ on the default branch (no commits of its own, or a squash or rebase merge git can
369
+ see), or whose upstream is gone, is left out, and the ten branches sent are the
370
+ newest ten that remain. Each branch has `name`,
286
371
  `head_sha` and `commits`; each commit has `sha`, `subject` and optional `files`.
287
372
  `files` lists the files that commit changed as `{ path }`, repository-relative as
288
373
  git names it (a rename is listed as both its old and its new path). No commit or
@@ -306,6 +391,92 @@ sensitive business information even though they are classified as metadata.
306
391
  Set global `capture.git: false` to disable new snapshots; already-queued snapshots
307
392
  are then discarded at delivery rather than sent.
308
393
 
394
+ ### Replay of earlier sessions
395
+
396
+ `agentwatch setup` starts, in the background, a replay of the developer's
397
+ **earlier Claude Code, Codex and Gemini CLI sessions** so the platform shows
398
+ the developer's recent history right after install. It sends nothing the live
399
+ hooks do not already send, built by the same code. It reads:
400
+
401
+ - **Claude Code:** `~/.claude/projects/<folder>/<session>.jsonl`.
402
+ - **Codex:** `$CODEX_HOME/sessions/YYYY/MM/DD/rollout-*.jsonl` (`~/.codex` by
403
+ default). Only the session row (session id, folder, how Codex was started,
404
+ and the branch, remote address and commit it records at session start) and
405
+ the turn, model and token-count rows are decoded; message, reasoning and
406
+ tool-output rows are skipped without being parsed.
407
+ - **Gemini CLI:** `$GEMINI_HOME/tmp/<project>/chats/session-*.jsonl`
408
+ (`~/.gemini` by default), placed in a folder through `projects.json`. Only
409
+ message ids, times, types, models and reply token counts are kept; reply and
410
+ thought content never is.
411
+
412
+ Only metadata leaves the machine, as listed below:
413
+
414
+ - **What each replayed turn carries.** A `turn.summary` per typed prompt: the
415
+ session and turn ids, the turn's start and end time, model and token counts
416
+ (summed once per message), tool counts and names, the files the agent's tools
417
+ named (checkout-relative, and only inside a checkout), the repository (read
418
+ from the folder the agent was in when the turn ended if that folder is still
419
+ a checkout; otherwise the checkout of a file the agent's tools edited, or,
420
+ for a folder that is gone, the remote address a Codex rollout recorded), the
421
+ branch the transcript records, and ticket keys from the branch name.
422
+ `work_evidence` is `cwd`, or `changed` when the repository came from an edited
423
+ file. Codex turns carry the branch recorded at session start (and so ticket
424
+ keys from it) and no tool names or files; Gemini CLI turns carry no branch
425
+ and no tool names or files: their files do not record them per turn.
426
+ - **What it does not carry.** No commit, except the full commit id a Codex
427
+ rollout recorded at session start, sent only for a folder that is gone and
428
+ never for a folder that is still a checkout; no `tool_events`, no session names or titles, no shell or
429
+ connector inputs, no response text, ever. **No prompt text** unless the
430
+ developer has already turned `capture.promptText` on (and given content
431
+ consent); it is then scrubbed and bounded as a live prompt is.
432
+ - **Status.** Every replayed turn is sent with `usage_status: pending` and its
433
+ token counts, so it can never overwrite the same turn if a live hook sent it.
434
+ - **Which turns.** Those that started in the last `--replay-days` days (30 by
435
+ default) and **never before the start of the open charge period**: the start
436
+ of the current UTC month, or of the previous month during the first four days
437
+ of a month. Money already settled is never reopened. A turn that ended in the
438
+ last ten minutes is left to the live hook.
439
+ - **Same turns as live, once.** A replayed Claude Code turn's `turn_id` is the
440
+ transcript's prompt id, and a Codex turn's is the rollout's `turn_id`: both are
441
+ the id the live hook sends, and the event id is derived from the agent, the
442
+ session and that id, so replaying twice, or replaying a turn a hook already
443
+ sent, changes nothing on the platform. Gemini CLI's chat files do not record
444
+ the live hook's id, so a Gemini turn is replayed only when it began before
445
+ AgentWatch first installed Gemini hooks on the machine; an install that hooked
446
+ Gemini before that time was recorded replays no Gemini turns. A Gemini session
447
+ written before gemini-cli 0.46 records no token counts and is not replayed.
448
+ - **After the turns.** One `repo.snapshot` and, with `capture.files`, one
449
+ `repo.tree` per repository the turns ran in that still exists on the machine:
450
+ the same records a live turn sends, with the same bounds.
451
+ - **`replay.progress`.** Counts and times only: `replay_id`, `state`
452
+ (`scanning`, `running`, `paused`, `done`, `stopped`), `window_start`,
453
+ `window_end`, `turns_total`, `turns_sent`, `sessions_total`, `sessions_sent`,
454
+ `started_at` and the developer id. No path or text. `turns_sent` counts turns
455
+ handed to the backend, not turns the backend has finished processing.
456
+ - **Gentle by design.** It runs at the lowest scheduling priority in a process of
457
+ its own with a small memory ceiling, 20 turns per request, one request every
458
+ five seconds, newest sessions first. It waits while the machine is busy (load
459
+ above half the cores), on battery power, or while an agent is closing turns,
460
+ and backs off on `429`, `5xx` and network errors. One run works for at most 20
461
+ minutes; an unfinished replay continues when the next agent session starts.
462
+ - **Control.** `agentwatch setup --no-replay` skips without claiming the machine's
463
+ one automatic replay; `--replay-days N` changes that first window. After the
464
+ detached replay has initialized, it atomically writes `replay-attempted` in
465
+ the config directory; a process that never starts leaves setup free to retry.
466
+ Later setups, including one after a new sign-in, start nothing.
467
+ Existing replay state from an older Edge also creates that marker. Explicit
468
+ `agentwatch replay --machine` or `--root <path>` can still start fresh; add
469
+ `--resume` to carry on or `--stop` to abandon that selected identity's run.
470
+ `agentwatch replay --dry-run` builds and counts every record and sends and
471
+ writes nothing. `agentwatch status` shows its progress. The same
472
+ capture switches that govern live records govern replay: `capture.git: false`
473
+ sends no repository, branch or ticket keys; `capture.files: false` no paths.
474
+ - **On disk.** `replay-attempted` in the config directory records the machine's
475
+ automatic attempt. `identity/<id>/replay.json` holds progress and completed
476
+ transcript files; an empty `replay-pending` marker exists while one is unfinished. The
477
+ transcripts themselves are only read, never copied or changed. `uninstall
478
+ --purge` removes both.
479
+
309
480
  ### `repo.tree`
310
481
 
311
482
  A tree contains the same identity fields as a snapshot (`provider`, `surface`,
@@ -517,6 +688,21 @@ them, with the rest of the message, in the dead-letter topic until Pub/Sub expir
517
688
  Developer identity is the configured `developerEmail`, falling back to Git email
518
689
  resolution. Setup requires an identity. The email is sent as `developer_id` and
519
690
  used for enforcement. It is not currently pseudonymized with a tenant HMAC.
691
+ Cursor also names the email its own account is signed in as (`user_email` on
692
+ every hook). That address is sent as `account_email` on Cursor turn summaries,
693
+ beside `developer_id` and never in its place, under the same rule: identity, not
694
+ content, so no capture flag gates it and it is not pseudonymized. It can differ
695
+ from the git or configured email; the platform uses it to join Cursor's own
696
+ usage export to the turns. It is the login for the whole machine, while
697
+ `developer_id` is chosen per root, so it is withheld on a machine whose config
698
+ serves more than one tenant (two install keys or devices). Cursor's
699
+ `composer_mode` and `is_background_agent`, named on its sessionStart only, are
700
+ kept in local turn state (mode 0600) and sent as `session_mode` and
701
+ `is_cloud_agent` on each later turn summary of that session. The memo survives
702
+ SessionEnd, like the opening prompt keys, for a conversation continued without
703
+ a new start, and goes with the 24 h idle sweep. They state the mode the session
704
+ started in; a switch inside the conversation is not seen, and a conversation
705
+ idle past the sweep, or started before AgentWatch was installed, carries none.
520
706
  An installation UUID also identifies the installation. Native providers may send
521
707
  their own session/account/resource identifiers independently.
522
708
 
@@ -565,7 +751,7 @@ The data root is `$XDG_DATA_HOME/agentwatch`, falling back to
565
751
  is used; Windows deployment is not verified. `AGENTWATCH_DATA_DIR` overrides it.
566
752
 
567
753
  The data root contains `queue/`, `turns/`, `backups/`, `locks/`, `snapshots/`,
568
- `checkouts/`, delivery/cooldown/enforcement state, and `disabled.json` when off.
754
+ `checkouts/`, delivery/cooldown/enforcement state, replay progress (`identity/<id>/replay.json`), and `disabled.json` when off.
569
755
  The queue contains sanitized product records and their destination, attempts,
570
756
  and retry timestamps. Defaults are 2,000 events, 20 attempts, and 7 days.
571
757
  Expiration is processed during activity, not by a daemon or scheduled erasure.
@@ -135,7 +135,7 @@ did, so no dependency lifecycle script executes in the job that builds the
135
135
  published tarball; `npm audit --omit=dev --audit-level=high` gates on advisories
136
136
  in what actually ships; the release workflow is dispatch-only, nothing runs on pull requests; and Dependabot
137
137
  opens grouped weekly updates for both npm and the pinned actions. Package verification permits built JS/types and public
138
- documentation only, with a 2 MB unpacked review ceiling. Hundreds of small files
138
+ documentation only, with a 3 MB unpacked review ceiling. Hundreds of small files
139
139
  are expected from the existing module layout and declarations; bundling solely
140
140
  to reduce the file count is deferred.
141
141
 
@@ -57,6 +57,16 @@ a ten-branch snapshot whose every branch is at the cap carries at most ~210 KB o
57
57
  25 such snapshots in one drain pass stay under the gateway's 8 MiB body limit. If the output
58
58
  ceiling (1 MiB) cuts a listing short, the commits it did not reach are sent without `files`.
59
59
 
60
+ Branches already on trunk, October 25, 2026: same machine, git 2.50. Each checked branch
61
+ with commits costs one `merge-tree --write-tree` and one `rev-parse` more (~25–50 ms on
62
+ agent-watch-core); a branch with no delta or a `[gone]` upstream costs less than before, and a
63
+ remembered merged one costs nothing. Merged branches take no slot, so the walk reads deeper:
64
+ agent-watch-core (294 local branches) found its ten live branches 46 down the listing, with 18
65
+ git checks and 27 gone upstreams. First snapshot from an empty cache, one-second budget:
66
+ agent-watch-core 561 ms, agent-watch-edge 544 ms, infra-live 464 ms, the rest under 110 ms;
67
+ every repository finished in that first turn, and the next turn stopped at the cache diff in
68
+ 20–31 ms.
69
+
60
70
  Trunk tree in `repo.tree`, October 25, 2026: same machine. Once per repository per
61
71
  install identity, the first closing hook in a repository runs `ls-tree -r -l -z` and three
62
72
  `git grep -o <tree>` searches side by side (the spike's declarations as one anchored ERE,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@agent-watch-ai/edge",
3
- "version": "0.6.0",
3
+ "version": "0.7.0",
4
4
  "description": "Usage and cost telemetry for Claude Code, Codex, Cursor, Gemini CLI and Antigravity. No daemon, no proxy.",
5
5
  "license": "MIT",
6
6
  "type": "module",
@@ -34,6 +34,7 @@
34
34
  },
35
35
  "files": [
36
36
  "dist",
37
+ "!dist/capture/python/__pycache__",
37
38
  "README.md",
38
39
  "SECURITY.md",
39
40
  "docs/AUDIT_PROMPT.md",
@@ -44,7 +45,7 @@
44
45
  "CHANGELOG.md"
45
46
  ],
46
47
  "scripts": {
47
- "build": "tsc -p tsconfig.build.json",
48
+ "build": "tsc -p tsconfig.build.json && node -e \"require('node:fs').cpSync('src/capture/python/sitecustomize.py','dist/capture/python/sitecustomize.py')\"",
48
49
  "typecheck": "tsc --noEmit",
49
50
  "coverage": "vitest run --coverage",
50
51
  "benchmark": "npm run build && node scripts/benchmark.mjs",
@@ -1,10 +0,0 @@
1
- /**
2
- * The canonical event vocabulary and shape.
3
- *
4
- * Kept as the module's stable entry point: the vocabulary lives in
5
- * `constants/events.constants.ts` and the shape in `types/events.types.ts`, so
6
- * a reader looking for "what can happen" and a reader looking for "what a
7
- * record looks like" each land in one file.
8
- */
9
- export { CANONICAL_EVENT_TYPES, EVENT_SCHEMA_VERSION, INTERNAL_HOOK_EVENT_TYPES, PRODUCT_EVENT_TYPES, PRODUCT_EVENT_TYPE_SET, TURN_CLOSING_EVENT_TYPE } from './constants/events.constants.js';
10
- export type { AgentWatchEvent, CanonicalEventType, ContentEvidence, EventAi, EventGit, EventIdInput, EventPatch, EventSession, EventTool, EventUsage, FeatureCandidate, InternalHookEventType, ProductEventType, UsageBillingMode, UsageSource } from './types/events.types.js';
@@ -1,9 +0,0 @@
1
- /**
2
- * The canonical event vocabulary and shape.
3
- *
4
- * Kept as the module's stable entry point: the vocabulary lives in
5
- * `constants/events.constants.ts` and the shape in `types/events.types.ts`, so
6
- * a reader looking for "what can happen" and a reader looking for "what a
7
- * record looks like" each land in one file.
8
- */
9
- export { CANONICAL_EVENT_TYPES, EVENT_SCHEMA_VERSION, INTERNAL_HOOK_EVENT_TYPES, PRODUCT_EVENT_TYPES, PRODUCT_EVENT_TYPE_SET, TURN_CLOSING_EVENT_TYPE } from './constants/events.constants.js';
@@ -1,39 +0,0 @@
1
- import type { RepositoryRootFinder } from './types/repository-root.types.js';
2
- export type { RepositoryRootFinder } from './types/repository-root.types.js';
3
- /**
4
- * A finder for the repository each file belongs to, when the session's own
5
- * folder is not one.
6
- *
7
- * Bounded by `boundary` — the folder the session started in — for two reasons:
8
- * a repository outside it is another project's, possibly another tenant's, and
9
- * a bounded walk is a handful of `stat` calls rather than an unbounded climb to
10
- * the filesystem root.
11
- *
12
- * ponytail: presence of a `.git` entry is the whole test, and the answer is the
13
- * *nearest* ancestor that has one — so a file inside a submodule or a vendored
14
- * checkout belongs to that inner repository, which is also what git itself
15
- * would answer from that directory. It does not understand `GIT_DIR`, a bare
16
- * repository, or a `.git` file pointing outside the tree. The upgrade path is
17
- * `git rev-parse --show-toplevel` behind this same cache — deliberately not the
18
- * implementation: a subprocess per tool call would sit on the coding agent's
19
- * critical path.
20
- *
21
- * @param boundary - Folder the walk stops at, inclusive.
22
- * @returns A finder whose answers are memoized per directory.
23
- */
24
- export declare function repositoryRootFinder(boundary: string): RepositoryRootFinder;
25
- /**
26
- * Whether a path is a directory or lies inside it.
27
- *
28
- * The two answers that disqualify it are a relative path that climbs out and
29
- * one that stays absolute (a different drive or root). A sibling named
30
- * `..foo` climbs nowhere, which is why the separator is part of the test.
31
- *
32
- * Exported because the same question is asked of a repository path read back
33
- * out of local turn state: one answer, not two that could disagree.
34
- *
35
- * @param boundary - Folder that bounds the walk.
36
- * @param target - Path to test against it.
37
- * @returns True when the target is the boundary or beneath it.
38
- */
39
- export declare function isBeneath(boundary: string, target: string): boolean;
@@ -1,131 +0,0 @@
1
- import fs from 'node:fs/promises';
2
- import path from 'node:path';
3
- import { GIT_ENTRY_ABSENT_CODES, GIT_ENTRY_NAME } from './constants/git.constants.js';
4
- /**
5
- * A finder for the repository each file belongs to, when the session's own
6
- * folder is not one.
7
- *
8
- * Bounded by `boundary` — the folder the session started in — for two reasons:
9
- * a repository outside it is another project's, possibly another tenant's, and
10
- * a bounded walk is a handful of `stat` calls rather than an unbounded climb to
11
- * the filesystem root.
12
- *
13
- * ponytail: presence of a `.git` entry is the whole test, and the answer is the
14
- * *nearest* ancestor that has one — so a file inside a submodule or a vendored
15
- * checkout belongs to that inner repository, which is also what git itself
16
- * would answer from that directory. It does not understand `GIT_DIR`, a bare
17
- * repository, or a `.git` file pointing outside the tree. The upgrade path is
18
- * `git rev-parse --show-toplevel` behind this same cache — deliberately not the
19
- * implementation: a subprocess per tool call would sit on the coding agent's
20
- * critical path.
21
- *
22
- * @param boundary - Folder the walk stops at, inclusive.
23
- * @returns A finder whose answers are memoized per directory.
24
- */
25
- export function repositoryRootFinder(boundary) {
26
- // Directory → its repository root, or undefined for "none, and asked".
27
- // One turn touches the same handful of directories over and over.
28
- const cache = new Map();
29
- return { find: (filePath) => rootFor(path.dirname(filePath), boundary, cache) };
30
- }
31
- /**
32
- * The repository root at or above one directory, memoizing every level.
33
- *
34
- * @param dir - Directory to resolve.
35
- * @param boundary - Folder the walk stops at, inclusive.
36
- * @param cache - Directory answers resolved so far.
37
- * @returns The root, or undefined when there is none inside the boundary.
38
- */
39
- async function rootFor(dir, boundary, cache) {
40
- if (cache.has(dir))
41
- return cache.get(dir);
42
- // A file outside the start folder contributes no repository at all: its
43
- // repository is not the session's business and could be another tenant's.
44
- if (!isBeneath(boundary, dir))
45
- return undefined;
46
- const root = await walkUp(dir, boundary, cache);
47
- cache.set(dir, root);
48
- return root;
49
- }
50
- /**
51
- * One rung of the walk: this directory, else its parent.
52
- *
53
- * @param dir - Directory to test.
54
- * @param boundary - Folder the walk stops at, inclusive.
55
- * @param cache - Directory answers resolved so far.
56
- * @returns The root, or undefined once the boundary is passed.
57
- */
58
- async function walkUp(dir, boundary, cache) {
59
- const entry = await gitEntry(dir);
60
- if (entry === 'present')
61
- return (await isReallyBeneath(boundary, dir)) ? dir : undefined;
62
- // A `.git` that could not be checked may well be there: climbing past it
63
- // would hand the file to an enclosing repository — the wrong branch, the
64
- // wrong config. No repository is the answer this walk gives when unsure.
65
- if (entry === 'unknown')
66
- return undefined;
67
- const parent = path.dirname(dir);
68
- // `dir === boundary` ends the walk; `parent === dir` is the filesystem root,
69
- // which only happens when the boundary is not an ancestor at all.
70
- if (dir === boundary || parent === dir)
71
- return undefined;
72
- return rootFor(parent, boundary, cache);
73
- }
74
- /**
75
- * `isBeneath`, asked of where the two really are.
76
- *
77
- * A symlink inside the start folder can point at a checkout anywhere on the
78
- * machine, and `.git` is found through it: lexically beneath, on disk another
79
- * project's. Asked only once a root is found, so the walk itself stays `stat`s.
80
- * A refused root ends the walk rather than climbing past it — the file belongs
81
- * to that repository, whoever's it is. A path that cannot be resolved — a link
82
- * removed or retargeted since the `.git` check — is refused too: its real
83
- * location was never proven to be inside.
84
- *
85
- * @param boundary - Folder that bounds the walk.
86
- * @param dir - Directory a `.git` entry was found in.
87
- * @returns True when the directory really lies within the boundary.
88
- */
89
- async function isReallyBeneath(boundary, dir) {
90
- try {
91
- const [realBoundary, realDir] = await Promise.all([fs.realpath(boundary), fs.realpath(dir)]);
92
- return isBeneath(realBoundary, realDir);
93
- }
94
- catch {
95
- return false;
96
- }
97
- }
98
- /**
99
- * Whether a `.git` entry sits directly in a directory.
100
- *
101
- * @param dir - Directory to test.
102
- * @returns `present`, `absent`, or `unknown` when the check itself failed.
103
- */
104
- async function gitEntry(dir) {
105
- try {
106
- await fs.access(path.join(dir, GIT_ENTRY_NAME));
107
- return 'present';
108
- }
109
- catch (error) {
110
- const code = error.code;
111
- return code !== undefined && GIT_ENTRY_ABSENT_CODES.has(code) ? 'absent' : 'unknown';
112
- }
113
- }
114
- /**
115
- * Whether a path is a directory or lies inside it.
116
- *
117
- * The two answers that disqualify it are a relative path that climbs out and
118
- * one that stays absolute (a different drive or root). A sibling named
119
- * `..foo` climbs nowhere, which is why the separator is part of the test.
120
- *
121
- * Exported because the same question is asked of a repository path read back
122
- * out of local turn state: one answer, not two that could disagree.
123
- *
124
- * @param boundary - Folder that bounds the walk.
125
- * @param target - Path to test against it.
126
- * @returns True when the target is the boundary or beneath it.
127
- */
128
- export function isBeneath(boundary, target) {
129
- const relative = path.relative(boundary, target);
130
- return !path.isAbsolute(relative) && relative !== '..' && !relative.startsWith(`..${path.sep}`);
131
- }
@@ -1,11 +0,0 @@
1
- /**
2
- * Finds the repository a file belongs to, bounded by one directory and
3
- * memoized for the life of the finder.
4
- */
5
- export interface RepositoryRootFinder {
6
- /**
7
- * The root of the repository containing `filePath`, or undefined when none
8
- * lies between the file and the boundary.
9
- */
10
- find(filePath: string): Promise<string | undefined>;
11
- }
@@ -1,6 +0,0 @@
1
- /**
2
- * The contract between delivery and whatever actually moves bytes. Kept
3
- * separate from the HTTP implementation so the queue, the cooldown and the
4
- * whole test suite can substitute their own.
5
- */
6
- export type { DeliveryCounters, DeliveryResult, EventTransport, HttpTransportOptions } from './types/transport.types.js';
@@ -1,11 +0,0 @@
1
- /**
2
- * Whether a Codex transcript belongs to a headless `codex exec` run.
3
- *
4
- * The hook payload does not say how Codex was started; the transcript's first
5
- * line (`session_meta`) does. Any failure answers false, so an unreadable
6
- * transcript reports the default surface rather than failing the hook.
7
- *
8
- * @param transcriptPath - Path Codex reported in the hook payload.
9
- * @returns True only when the originator is `codex_exec`.
10
- */
11
- export declare function isCodexExecTranscript(transcriptPath: string): Promise<boolean>;
@@ -1,21 +0,0 @@
1
- import type { ReadTurnUsageRetry, TurnUsage } from './types/transcript.types.js';
2
- /**
3
- * Forward-compatible token usage from Cursor's transcript JSONL.
4
- *
5
- * Today (verified 2026-08) Cursor transcript rows carry only role/message with
6
- * tool_use blocks — no usage, no timestamps, no message ids — so this reader
7
- * returns undefined and Cursor turn summaries stay usage_status=pending. Cursor
8
- * has logged the enrichment request; the parser already accepts `usage` and
9
- * `message.usage` objects with Anthropic-style token fields, so tokens will
10
- * appear here without a code change once the format grows them.
11
- *
12
- * Rows have no timestamps, so unlike the Claude reader there is no time window:
13
- * a turn claims every not-yet-claimed usage row, and exactly-once attribution
14
- * rests entirely on the persisted message-id ledger.
15
- *
16
- * @param transcriptPath - Path Cursor reported in the hook payload.
17
- * @param retry - How long to wait for the transcript flush to settle.
18
- * @param excludeMessageIds - Rows another turn already claimed.
19
- * @returns The turn's usage, or undefined while the format carries none.
20
- */
21
- export declare function readCursorTurnUsage(transcriptPath: string, retry?: ReadTurnUsageRetry, excludeMessageIds?: ReadonlySet<string>): Promise<TurnUsage | undefined>;
@@ -1,66 +0,0 @@
1
- import { asRecord, firstStringOf } from '../core/object.js';
2
- import { accumulateUsage, messageIdFor, parseJsonLine, readTranscriptTail, readUntilSettled } from './transcript.js';
3
- /**
4
- * Forward-compatible token usage from Cursor's transcript JSONL.
5
- *
6
- * Today (verified 2026-08) Cursor transcript rows carry only role/message with
7
- * tool_use blocks — no usage, no timestamps, no message ids — so this reader
8
- * returns undefined and Cursor turn summaries stay usage_status=pending. Cursor
9
- * has logged the enrichment request; the parser already accepts `usage` and
10
- * `message.usage` objects with Anthropic-style token fields, so tokens will
11
- * appear here without a code change once the format grows them.
12
- *
13
- * Rows have no timestamps, so unlike the Claude reader there is no time window:
14
- * a turn claims every not-yet-claimed usage row, and exactly-once attribution
15
- * rests entirely on the persisted message-id ledger.
16
- *
17
- * @param transcriptPath - Path Cursor reported in the hook payload.
18
- * @param retry - How long to wait for the transcript flush to settle.
19
- * @param excludeMessageIds - Rows another turn already claimed.
20
- * @returns The turn's usage, or undefined while the format carries none.
21
- */
22
- export async function readCursorTurnUsage(transcriptPath, retry, excludeMessageIds) {
23
- return readUntilSettled(() => readOnce(transcriptPath, excludeMessageIds), retry, { bailOnFirstEmpty: true });
24
- }
25
- /**
26
- * One pass over the transcript tail.
27
- *
28
- * @param transcriptPath - Transcript file.
29
- * @param excludeMessageIds - Rows another turn already claimed.
30
- * @returns The usage found in this pass.
31
- */
32
- async function readOnce(transcriptPath, excludeMessageIds) {
33
- const raw = await readTranscriptTail(transcriptPath);
34
- if (raw === undefined)
35
- return undefined;
36
- const byMessageId = new Map();
37
- for (const line of raw.split('\n')) {
38
- if (!line.trim())
39
- continue;
40
- const entry = usageRow(line, excludeMessageIds);
41
- if (entry)
42
- byMessageId.set(entry.id, entry.value);
43
- }
44
- return accumulateUsage(byMessageId);
45
- }
46
- /**
47
- * The usage of one transcript row, when it reports any and no other turn has
48
- * claimed it.
49
- *
50
- * @param line - Verbatim JSONL line.
51
- * @param excludeMessageIds - Rows another turn already claimed.
52
- * @returns The entry, or undefined when the row carries no usage.
53
- */
54
- function usageRow(line, excludeMessageIds) {
55
- const entry = parseJsonLine(line);
56
- if (!entry)
57
- return undefined;
58
- const message = asRecord(entry['message']);
59
- const usage = asRecord(entry['usage']) ?? asRecord(message?.['usage']);
60
- if (!usage)
61
- return undefined;
62
- const id = messageIdFor(firstStringOf(message?.['id'], entry['id'], entry['message_id']), line);
63
- if (excludeMessageIds?.has(id))
64
- return undefined;
65
- return { id, value: { model: firstStringOf(message?.['model'], entry['model']), usage } };
66
- }