@agent-watch-ai/edge 0.5.0 → 0.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (298) hide show
  1. package/CHANGELOG.md +238 -7
  2. package/README.md +308 -8
  3. package/dist/billing/billing-mode.d.ts +37 -5
  4. package/dist/billing/billing-mode.js +28 -19
  5. package/dist/billing/constants/billing.constants.d.ts +0 -2
  6. package/dist/billing/constants/billing.constants.js +0 -2
  7. package/dist/billing/index.d.ts +2 -1
  8. package/dist/billing/index.js +1 -1
  9. package/dist/billing/session-billing.d.ts +3 -2
  10. package/dist/billing/session-billing.js +8 -8
  11. package/dist/billing/types/billing.types.d.ts +7 -0
  12. package/dist/capture/capture-env.d.ts +147 -0
  13. package/dist/capture/capture-env.js +301 -0
  14. package/dist/capture/captured-step.d.ts +88 -0
  15. package/dist/capture/captured-step.js +479 -0
  16. package/dist/capture/constants/capture.constants.d.ts +70 -0
  17. package/dist/capture/constants/capture.constants.js +72 -0
  18. package/dist/capture/launched-runs.d.ts +16 -0
  19. package/dist/capture/launched-runs.js +151 -0
  20. package/dist/capture/node.cjs +697 -0
  21. package/dist/capture/node.d.cts +32 -0
  22. package/dist/capture/python/sitecustomize.py +823 -0
  23. package/dist/capture/schemas/capture.schema.d.ts +35 -0
  24. package/dist/capture/schemas/capture.schema.js +31 -0
  25. package/dist/capture/types/capture.types.d.ts +20 -0
  26. package/dist/cli/constants/cli.constants.d.ts +2 -6
  27. package/dist/cli/constants/cli.constants.js +3 -7
  28. package/dist/cli/context.d.ts +19 -22
  29. package/dist/cli/context.js +23 -54
  30. package/dist/cli/doctor-run-capture.d.ts +13 -0
  31. package/dist/cli/doctor-run-capture.js +19 -0
  32. package/dist/cli/doctor.js +16 -67
  33. package/dist/cli/hook.d.ts +14 -0
  34. package/dist/cli/hook.js +40 -0
  35. package/dist/cli/index.d.ts +1 -1
  36. package/dist/cli/index.js +1 -1
  37. package/dist/cli/misc.js +10 -2
  38. package/dist/cli/replay.d.ts +33 -0
  39. package/dist/cli/replay.js +193 -0
  40. package/dist/cli/setup.d.ts +10 -2
  41. package/dist/cli/setup.js +154 -26
  42. package/dist/cli/status.js +45 -5
  43. package/dist/cli/toggle.js +10 -0
  44. package/dist/cli/types/cli.types.d.ts +15 -1
  45. package/dist/cli/uninstall.js +8 -22
  46. package/dist/cli.js +104 -17
  47. package/dist/config/config.d.ts +0 -2
  48. package/dist/config/config.js +0 -1
  49. package/dist/config/constants/config.constants.js +2 -0
  50. package/dist/config/events-transport.d.ts +15 -0
  51. package/dist/config/events-transport.js +29 -0
  52. package/dist/config/index.d.ts +2 -1
  53. package/dist/config/index.js +1 -0
  54. package/dist/config/root-config.d.ts +12 -0
  55. package/dist/config/root-config.js +24 -0
  56. package/dist/config/schemas/config.schema.d.ts +13 -0
  57. package/dist/config/schemas/config.schema.js +42 -6
  58. package/dist/config/types/config.types.d.ts +7 -0
  59. package/dist/core/index.d.ts +1 -1
  60. package/dist/core/index.js +1 -1
  61. package/dist/core/version.d.ts +9 -0
  62. package/dist/core/version.js +14 -0
  63. package/dist/core/which.d.ts +11 -0
  64. package/dist/core/which.js +18 -0
  65. package/dist/credentials/cloud-claim.d.ts +32 -0
  66. package/dist/credentials/cloud-claim.js +42 -0
  67. package/dist/credentials/constants/credentials.constants.d.ts +8 -1
  68. package/dist/credentials/constants/credentials.constants.js +9 -2
  69. package/dist/credentials/device-api.d.ts +15 -1
  70. package/dist/credentials/device-api.js +12 -1
  71. package/dist/credentials/sign-in.d.ts +27 -0
  72. package/dist/credentials/sign-in.js +31 -1
  73. package/dist/credentials/token-refresher.d.ts +5 -1
  74. package/dist/credentials/token-refresher.js +10 -2
  75. package/dist/events/constants/events.constants.d.ts +8 -2
  76. package/dist/events/constants/events.constants.js +7 -1
  77. package/dist/events/index.d.ts +2 -0
  78. package/dist/events/product-event.d.ts +10 -4
  79. package/dist/events/types/events.types.d.ts +6 -0
  80. package/dist/events/types/replay-progress.types.d.ts +26 -0
  81. package/dist/events/types/replay-progress.types.js +1 -0
  82. package/dist/events/types/repo-snapshot.types.d.ts +1 -4
  83. package/dist/events/types/repo-tree.types.d.ts +25 -0
  84. package/dist/events/types/repo-tree.types.js +1 -0
  85. package/dist/feature/ticket-candidates.d.ts +1 -1
  86. package/dist/git/checkout-root.d.ts +15 -0
  87. package/dist/git/checkout-root.js +18 -0
  88. package/dist/git/code-state.d.ts +2 -16
  89. package/dist/git/code-state.js +11 -12
  90. package/dist/git/constants/git.constants.d.ts +31 -11
  91. package/dist/git/constants/git.constants.js +36 -12
  92. package/dist/git/constants/tree.constants.d.ts +71 -0
  93. package/dist/git/constants/tree.constants.js +92 -0
  94. package/dist/git/fingerprint.d.ts +3 -6
  95. package/dist/git/fingerprint.js +5 -8
  96. package/dist/git/git-context.d.ts +1 -0
  97. package/dist/git/git-context.js +8 -3
  98. package/dist/git/index.d.ts +1 -2
  99. package/dist/git/index.js +1 -1
  100. package/dist/git/repo-snapshot.d.ts +13 -4
  101. package/dist/git/repo-snapshot.js +47 -9
  102. package/dist/git/repo-tree.d.ts +69 -0
  103. package/dist/git/repo-tree.js +130 -0
  104. package/dist/git/types/git.types.d.ts +5 -2
  105. package/dist/git/types/snapshot.types.d.ts +14 -0
  106. package/dist/pipeline/constants/pipeline.constants.d.ts +3 -0
  107. package/dist/pipeline/constants/pipeline.constants.js +3 -0
  108. package/dist/pipeline/hook-pipeline.js +112 -72
  109. package/dist/privacy/product-capture.js +36 -5
  110. package/dist/providers/antigravity/antigravity.capture.d.ts +2 -0
  111. package/dist/providers/antigravity/antigravity.capture.js +5 -0
  112. package/dist/providers/antigravity/antigravity.detect.js +8 -22
  113. package/dist/providers/antigravity/antigravity.provider.js +10 -3
  114. package/dist/providers/antigravity/constants/antigravity.constants.d.ts +1 -0
  115. package/dist/providers/antigravity/constants/antigravity.constants.js +1 -0
  116. package/dist/providers/claude/claude.adapter.js +9 -6
  117. package/dist/providers/claude/claude.detect.js +2 -17
  118. package/dist/providers/claude/claude.otel.d.ts +21 -3
  119. package/dist/providers/claude/claude.otel.js +216 -61
  120. package/dist/providers/claude/claude.provider.js +17 -1
  121. package/dist/providers/claude/claude.version.d.ts +9 -0
  122. package/dist/providers/claude/claude.version.js +28 -0
  123. package/dist/providers/claude/constants/claude.constants.d.ts +27 -0
  124. package/dist/providers/claude/constants/claude.constants.js +27 -0
  125. package/dist/providers/claude/constants/claude.otel.constants.d.ts +27 -0
  126. package/dist/providers/claude/constants/claude.otel.constants.js +45 -5
  127. package/dist/providers/claude/types/claude.types.d.ts +13 -0
  128. package/dist/providers/codex/codex.capture.d.ts +76 -0
  129. package/dist/providers/codex/codex.capture.js +454 -0
  130. package/dist/providers/codex/codex.detect.js +2 -4
  131. package/dist/providers/codex/codex.otel.d.ts +38 -2
  132. package/dist/providers/codex/codex.otel.js +50 -6
  133. package/dist/providers/codex/codex.provider.js +8 -0
  134. package/dist/providers/codex/codex.surface.d.ts +9 -0
  135. package/dist/{turns/codex-originator.js → providers/codex/codex.surface.js} +17 -3
  136. package/dist/providers/codex/codex.titles.d.ts +14 -0
  137. package/dist/providers/codex/codex.titles.js +35 -0
  138. package/dist/providers/codex/constants/codex.constants.d.ts +4 -0
  139. package/dist/providers/codex/constants/codex.constants.js +4 -0
  140. package/dist/providers/cursor/constants/cursor.constants.d.ts +17 -4
  141. package/dist/providers/cursor/constants/cursor.constants.js +25 -5
  142. package/dist/providers/cursor/cursor-mcp-memo.d.ts +34 -0
  143. package/dist/providers/cursor/cursor-mcp-memo.js +94 -0
  144. package/dist/providers/cursor/cursor.adapter.js +20 -82
  145. package/dist/providers/cursor/cursor.capture.d.ts +1 -0
  146. package/dist/providers/cursor/cursor.capture.js +4 -0
  147. package/dist/providers/cursor/cursor.detect.d.ts +5 -1
  148. package/dist/providers/cursor/cursor.detect.js +11 -26
  149. package/dist/providers/cursor/cursor.hooks.js +2 -2
  150. package/dist/providers/cursor/cursor.provider.js +16 -7
  151. package/dist/providers/cursor/cursor.titles.d.ts +14 -0
  152. package/dist/providers/cursor/cursor.titles.js +20 -0
  153. package/dist/providers/cursor/schemas/cursor.schema.d.ts +3 -3
  154. package/dist/providers/cursor/schemas/cursor.schema.js +5 -3
  155. package/dist/providers/gemini/constants/gemini.constants.d.ts +16 -0
  156. package/dist/providers/gemini/constants/gemini.constants.js +17 -0
  157. package/dist/providers/gemini/gemini.capture.d.ts +81 -0
  158. package/dist/providers/gemini/gemini.capture.js +210 -0
  159. package/dist/providers/gemini/gemini.detect.js +57 -24
  160. package/dist/providers/gemini/gemini.otel.d.ts +38 -2
  161. package/dist/providers/gemini/gemini.otel.js +56 -125
  162. package/dist/providers/gemini/gemini.provider.js +5 -0
  163. package/dist/providers/index.d.ts +1 -0
  164. package/dist/providers/index.js +1 -0
  165. package/dist/providers/provider.d.ts +8 -0
  166. package/dist/providers/provider.js +9 -0
  167. package/dist/providers/registry.d.ts +14 -0
  168. package/dist/providers/registry.js +14 -0
  169. package/dist/providers/shared/constants/hook-config.constants.d.ts +2 -0
  170. package/dist/providers/shared/constants/hook-config.constants.js +2 -0
  171. package/dist/providers/shared/constants/terminal-capture.constants.d.ts +6 -0
  172. package/dist/providers/shared/constants/terminal-capture.constants.js +6 -0
  173. package/dist/providers/shared/editor-paths.d.ts +8 -0
  174. package/dist/providers/shared/editor-paths.js +18 -0
  175. package/dist/providers/shared/hook-config.d.ts +5 -0
  176. package/dist/providers/shared/hook-config.js +39 -1
  177. package/dist/providers/shared/hooks-marker.d.ts +14 -0
  178. package/dist/providers/shared/hooks-marker.js +23 -0
  179. package/dist/providers/shared/install-record.d.ts +29 -0
  180. package/dist/providers/shared/install-record.js +52 -0
  181. package/dist/providers/shared/session-title-store.d.ts +23 -0
  182. package/dist/providers/shared/session-title-store.js +50 -0
  183. package/dist/providers/shared/terminal-capture.d.ts +41 -0
  184. package/dist/providers/shared/terminal-capture.js +109 -0
  185. package/dist/providers/shared/tooling.d.ts +21 -0
  186. package/dist/providers/shared/tooling.js +36 -1
  187. package/dist/providers/types/provider.types.d.ts +57 -4
  188. package/dist/replay/checkout-resolver.d.ts +29 -0
  189. package/dist/replay/checkout-resolver.js +69 -0
  190. package/dist/replay/codex-turns.d.ts +24 -0
  191. package/dist/replay/codex-turns.js +221 -0
  192. package/dist/replay/constants/replay.constants.d.ts +99 -0
  193. package/dist/replay/constants/replay.constants.js +102 -0
  194. package/dist/replay/describe.d.ts +10 -0
  195. package/dist/replay/describe.js +31 -0
  196. package/dist/replay/gemini-turns.d.ts +36 -0
  197. package/dist/replay/gemini-turns.js +192 -0
  198. package/dist/replay/machine.d.ts +34 -0
  199. package/dist/replay/machine.js +68 -0
  200. package/dist/replay/progress-event.d.ts +21 -0
  201. package/dist/replay/progress-event.js +45 -0
  202. package/dist/replay/replay-runner.d.ts +58 -0
  203. package/dist/replay/replay-runner.js +529 -0
  204. package/dist/replay/replay-scan.d.ts +83 -0
  205. package/dist/replay/replay-scan.js +170 -0
  206. package/dist/replay/replay-state.d.ts +108 -0
  207. package/dist/replay/replay-state.js +199 -0
  208. package/dist/replay/resume.d.ts +18 -0
  209. package/dist/replay/resume.js +34 -0
  210. package/dist/replay/start.d.ts +23 -0
  211. package/dist/replay/start.js +39 -0
  212. package/dist/replay/throttle.d.ts +35 -0
  213. package/dist/replay/throttle.js +41 -0
  214. package/dist/replay/transcript-turns.d.ts +35 -0
  215. package/dist/replay/transcript-turns.js +215 -0
  216. package/dist/replay/turn-event.d.ts +38 -0
  217. package/dist/replay/turn-event.js +116 -0
  218. package/dist/replay/types/replay.types.d.ts +162 -0
  219. package/dist/replay/types/replay.types.js +1 -0
  220. package/dist/replay/window.d.ts +28 -0
  221. package/dist/replay/window.js +41 -0
  222. package/dist/snapshot/branch-selection.d.ts +40 -23
  223. package/dist/snapshot/branch-selection.js +74 -42
  224. package/dist/snapshot/budget.js +2 -2
  225. package/dist/snapshot/constants/snapshot-stages.constants.d.ts +10 -0
  226. package/dist/snapshot/constants/snapshot-stages.constants.js +10 -0
  227. package/dist/snapshot/constants/snapshot.constants.d.ts +37 -4
  228. package/dist/snapshot/constants/snapshot.constants.js +37 -4
  229. package/dist/snapshot/index.d.ts +6 -1
  230. package/dist/snapshot/index.js +3 -1
  231. package/dist/snapshot/snapshot-event.d.ts +7 -0
  232. package/dist/snapshot/snapshot-event.js +8 -5
  233. package/dist/snapshot/snapshot-pipeline.js +89 -26
  234. package/dist/snapshot/snapshot-state.js +24 -2
  235. package/dist/snapshot/tree-event.d.ts +14 -0
  236. package/dist/snapshot/tree-event.js +91 -0
  237. package/dist/snapshot/tree-pipeline.d.ts +12 -0
  238. package/dist/snapshot/tree-pipeline.js +172 -0
  239. package/dist/snapshot/types/snapshot.types.d.ts +62 -2
  240. package/dist/storage/schemas/storage.schema.d.ts +2 -0
  241. package/dist/storage/schemas/storage.schema.js +6 -0
  242. package/dist/transport/constants/transport.constants.d.ts +5 -0
  243. package/dist/transport/constants/transport.constants.js +5 -0
  244. package/dist/transport/delivery-stats.d.ts +13 -1
  245. package/dist/transport/delivery-stats.js +18 -2
  246. package/dist/transport/delivery.d.ts +4 -3
  247. package/dist/transport/delivery.js +21 -7
  248. package/dist/transport/identity-delivery.d.ts +20 -0
  249. package/dist/transport/identity-delivery.js +41 -0
  250. package/dist/transport/index.d.ts +2 -0
  251. package/dist/transport/index.js +1 -0
  252. package/dist/transport/queue.js +40 -6
  253. package/dist/transport/types/delivery-flow.types.d.ts +7 -0
  254. package/dist/turns/claude-transcript.js +4 -12
  255. package/dist/turns/codex-transcript.d.ts +9 -0
  256. package/dist/turns/codex-transcript.js +27 -19
  257. package/dist/turns/constants/turns.constants.d.ts +13 -12
  258. package/dist/turns/constants/turns.constants.js +15 -19
  259. package/dist/turns/gemini-transcript.d.ts +19 -1
  260. package/dist/turns/gemini-transcript.js +29 -18
  261. package/dist/turns/index.d.ts +3 -4
  262. package/dist/turns/index.js +2 -3
  263. package/dist/turns/run-state.d.ts +71 -0
  264. package/dist/turns/run-state.js +114 -0
  265. package/dist/turns/tool-events.d.ts +11 -1
  266. package/dist/turns/tool-events.js +32 -9
  267. package/dist/turns/transcript.d.ts +15 -14
  268. package/dist/turns/transcript.js +23 -4
  269. package/dist/turns/turn-state.d.ts +49 -7
  270. package/dist/turns/turn-state.js +78 -10
  271. package/dist/turns/turn-summary.js +10 -6
  272. package/dist/turns/turn-tracker.d.ts +9 -16
  273. package/dist/turns/turn-tracker.js +162 -86
  274. package/dist/turns/types/transcript.types.d.ts +11 -1
  275. package/dist/turns/types/turn-provider.types.d.ts +33 -0
  276. package/dist/turns/types/turn-provider.types.js +1 -0
  277. package/dist/turns/types/turn-state.types.d.ts +9 -0
  278. package/dist/turns/types/turn-summary.types.d.ts +20 -6
  279. package/dist/turns/types/turn-tracker.types.d.ts +3 -1
  280. package/dist/turns/work-checkout.js +1 -2
  281. package/docs/AUDIT_PROMPT.md +10 -0
  282. package/docs/DATA_HANDLING.md +269 -32
  283. package/docs/ENTERPRISE_DEPLOYMENT.md +1 -1
  284. package/docs/PERFORMANCE.md +27 -0
  285. package/package.json +3 -2
  286. package/dist/events/canonical-event.d.ts +0 -10
  287. package/dist/events/canonical-event.js +0 -9
  288. package/dist/git/repository-root.d.ts +0 -39
  289. package/dist/git/repository-root.js +0 -131
  290. package/dist/git/types/repository-root.types.d.ts +0 -11
  291. package/dist/transport/transport.d.ts +0 -6
  292. package/dist/turns/codex-originator.d.ts +0 -11
  293. package/dist/turns/cursor-transcript.d.ts +0 -21
  294. package/dist/turns/cursor-transcript.js +0 -66
  295. package/dist/turns/native-session-titles.d.ts +0 -26
  296. package/dist/turns/native-session-titles.js +0 -102
  297. /package/dist/{git/types/repository-root.types.js → billing/types/billing.types.js} +0 -0
  298. /package/dist/{transport/transport.js → capture/types/capture.types.js} +0 -0
@@ -1,6 +1,7 @@
1
1
  import type { Env } from '../../core/types/core.types.js';
2
2
  import type { AgentWatchConfig, OtelSignalName } from '../../config/types/config.types.js';
3
3
  import type { BearerRewriteContext, NativeTelemetryConfigurator, NativeTelemetryStatus, SetupContext, SetupOutcome } from '../types/provider.types.js';
4
+ import { codexConfigTomlPath } from './codex.detect.js';
4
5
  /**
5
6
  * Configures Codex's own OTLP export.
6
7
  *
@@ -9,6 +10,21 @@ import type { BearerRewriteContext, NativeTelemetryConfigurator, NativeTelemetry
9
10
  * The backend normalizes both into llm.call.
10
11
  */
11
12
  export declare class CodexOtelConfigurator implements NativeTelemetryConfigurator {
13
+ private readonly captureSource;
14
+ /**
15
+ * Bind to the shims setup copies.
16
+ *
17
+ * @param captureSource - The package's shims; tests name their own.
18
+ */
19
+ constructor(captureSource?: {
20
+ node: string;
21
+ python: string;
22
+ });
23
+ /** Run capture lives in the same file, and comes and goes with the exporters. */
24
+ readonly runCapture: {
25
+ configPath: typeof codexConfigTomlPath;
26
+ inspect: (context: SetupContext) => Promise<import("../types/provider.types.js").RunCaptureStatus>;
27
+ };
12
28
  /**
13
29
  * Whether this agent can export native telemetry at all.
14
30
  *
@@ -24,13 +40,33 @@ export declare class CodexOtelConfigurator implements NativeTelemetryConfigurato
24
40
  */
25
41
  inspect(context: SetupContext): Promise<NativeTelemetryStatus>;
26
42
  /**
27
- * Write the managed `[otel]` block into Codex's config.toml.
43
+ * Write the exporters and run capture into Codex's config.toml.
44
+ *
45
+ * Capture does not wait on the export: a developer's own `[otel]`, or content consent
46
+ * withheld, leaves the export out, and neither has anything to do with counting a
47
+ * script's calls.
28
48
  *
29
49
  * @param context - Environment, paths, config and install state.
30
50
  * @returns Whether the file changed, what to tell the user, and the next
31
51
  * install state.
32
52
  */
33
53
  configure(context: SetupContext): Promise<SetupOutcome>;
54
+ /**
55
+ * Take the exporters and run capture out of Codex's config.toml.
56
+ *
57
+ * @param context - Environment, paths and install state.
58
+ * @returns Whether the file changed, what to tell the user, and the next
59
+ * install state.
60
+ */
61
+ uninstall(context: SetupContext): Promise<SetupOutcome>;
62
+ /**
63
+ * Write the managed `[otel]` block into Codex's config.toml.
64
+ *
65
+ * @param context - Environment, paths, config and install state.
66
+ * @returns Whether the file changed, what to tell the user, and the next
67
+ * install state.
68
+ */
69
+ private configureExport;
34
70
  /**
35
71
  * Remove the managed block from Codex's config.toml.
36
72
  *
@@ -43,7 +79,7 @@ export declare class CodexOtelConfigurator implements NativeTelemetryConfigurato
43
79
  * @returns Whether the file changed, what to tell the user, and the next
44
80
  * install state.
45
81
  */
46
- uninstall(context: SetupContext): Promise<SetupOutcome>;
82
+ private removeExport;
47
83
  /**
48
84
  * Swap the bearer in our exporters for the current one.
49
85
  *
@@ -1,13 +1,15 @@
1
1
  import fs from 'node:fs/promises';
2
2
  import { parse as parseToml } from 'smol-toml';
3
+ import { shimPaths, skippedOnError, withCaptureOutcome } from '../../capture/capture-env.js';
3
4
  import { asRecord } from '../../core/object.js';
4
- import { joinUrl, otlpBaseUrl, toolContentConsented } from '../../config/config.js';
5
+ import { joinUrl, otelEnabled, otlpBaseUrl, toolContentConsented } from '../../config/config.js';
5
6
  import { backupFile, currentMode, writeFileAtomic, writeIfUnchanged } from '../../storage/atomic-file.js';
6
7
  import { SECRET_FILE_MODE } from '../../storage/constants/storage.constants.js';
7
8
  import { deviceFor, hasCredential } from '../../credentials/identity.js';
8
9
  import { BEARER_PLACEHOLDER } from '../constants/provider.constants.js';
9
10
  import { withOtelInstall, withoutOtelInstall } from '../shared/install-record.js';
10
11
  import { INSTALLATION_HEADER } from '../../transport/constants/transport.constants.js';
12
+ import { applyCodexCapture, inspectCodexCapture, removeCodexCapture } from './codex.capture.js';
11
13
  import { codexConfigTomlPath } from './codex.detect.js';
12
14
  import { CODEX_PROVIDER_ID } from './constants/codex.constants.js';
13
15
  import { BLOCK_END, BLOCK_START, CODEX_EXPORTER_KEYS, CODEX_OTEL_SIGNALS, LOGS_PATH, OTEL_TABLE_KEY, OTLP_HTTP_KEY, RE_BEARER_HEADER, RE_LEADING_NEWLINE, RE_TOML_BACKSLASH, RE_TOML_QUOTE, RE_TOML_TABLE_HEADER, RE_TRAILING_NEWLINES, TRACES_PATH } from './constants/codex.otel.constants.js';
@@ -19,6 +21,20 @@ import { BLOCK_END, BLOCK_START, CODEX_EXPORTER_KEYS, CODEX_OTEL_SIGNALS, LOGS_P
19
21
  * The backend normalizes both into llm.call.
20
22
  */
21
23
  export class CodexOtelConfigurator {
24
+ captureSource;
25
+ /**
26
+ * Bind to the shims setup copies.
27
+ *
28
+ * @param captureSource - The package's shims; tests name their own.
29
+ */
30
+ constructor(captureSource = shimPaths()) {
31
+ this.captureSource = captureSource;
32
+ }
33
+ /** Run capture lives in the same file, and comes and goes with the exporters. */
34
+ runCapture = {
35
+ configPath: codexConfigTomlPath,
36
+ inspect: (context) => inspectCodexCapture(context, this.captureSource)
37
+ };
22
38
  /**
23
39
  * Whether this agent can export native telemetry at all.
24
40
  *
@@ -58,13 +74,40 @@ export class CodexOtelConfigurator {
58
74
  return { supported: true, configured: false };
59
75
  }
60
76
  /**
61
- * Write the managed `[otel]` block into Codex's config.toml.
77
+ * Write the exporters and run capture into Codex's config.toml.
78
+ *
79
+ * Capture does not wait on the export: a developer's own `[otel]`, or content consent
80
+ * withheld, leaves the export out, and neither has anything to do with counting a
81
+ * script's calls.
62
82
  *
63
83
  * @param context - Environment, paths, config and install state.
64
84
  * @returns Whether the file changed, what to tell the user, and the next
65
85
  * install state.
66
86
  */
67
87
  async configure(context) {
88
+ const outcome = await this.configureExport(context);
89
+ const capture = otelEnabled(context.config) ? await skippedOnError(applyCodexCapture(context, this.captureSource)) : await removeCodexCapture(context);
90
+ return withCaptureOutcome(outcome, capture);
91
+ }
92
+ /**
93
+ * Take the exporters and run capture out of Codex's config.toml.
94
+ *
95
+ * @param context - Environment, paths and install state.
96
+ * @returns Whether the file changed, what to tell the user, and the next
97
+ * install state.
98
+ */
99
+ async uninstall(context) {
100
+ const capture = await removeCodexCapture(context);
101
+ return withCaptureOutcome(await this.removeExport(context), capture);
102
+ }
103
+ /**
104
+ * Write the managed `[otel]` block into Codex's config.toml.
105
+ *
106
+ * @param context - Environment, paths, config and install state.
107
+ * @returns Whether the file changed, what to tell the user, and the next
108
+ * install state.
109
+ */
110
+ async configureExport(context) {
68
111
  if (!codexOtelEnabled(context.config))
69
112
  return this.configureDisabled(context);
70
113
  const otlpBase = otlpBaseUrl(context.config);
@@ -75,7 +118,7 @@ export class CodexOtelConfigurator {
75
118
  const block = renderBlock(otlpBase, context.bearer, context.config.otel, context.config.installationId);
76
119
  const next = raw.includes(BLOCK_START) ? replaceBlock(raw, block) : appendBlock(raw, block);
77
120
  if (typeof next !== 'string')
78
- return { ok: false, changed: false, messages: [next.error(configPath)] };
121
+ return { ok: false, changed: false, ...(next.conflict ? { conflict: true } : {}), messages: [next.error(configPath)] };
79
122
  if (next === raw)
80
123
  return { ok: true, changed: false, messages: ['native OpenTelemetry already configured'] };
81
124
  // Belt and braces: a generated file the agent cannot parse would disable
@@ -113,7 +156,7 @@ export class CodexOtelConfigurator {
113
156
  * @returns Whether the file changed, what to tell the user, and the next
114
157
  * install state.
115
158
  */
116
- async uninstall(context) {
159
+ async removeExport(context) {
117
160
  const configPath = codexConfigTomlPath(context.env);
118
161
  const raw = await readFileOrUndefined(configPath);
119
162
  if (raw === undefined || !raw.includes(BLOCK_START)) {
@@ -197,7 +240,7 @@ export class CodexOtelConfigurator {
197
240
  * @returns The outcome.
198
241
  */
199
242
  async configureDisabled(context) {
200
- const removed = await this.uninstall(context);
243
+ const removed = await this.removeExport(context);
201
244
  if (!removed.ok)
202
245
  return removed;
203
246
  return {
@@ -488,5 +531,6 @@ function tryParseToml(raw) {
488
531
  const malformedMarkers = { error: (configPath) => `malformed AgentWatch block markers in ${configPath}; fix manually` };
489
532
  const unparseableConfig = { error: (configPath) => `refusing to modify unparseable ${configPath}` };
490
533
  const foreignOtelTable = {
491
- error: (configPath) => `skipping native OpenTelemetry: ${configPath} already has an [otel] section (not AgentWatch-owned)`
534
+ error: (configPath) => `skipping native OpenTelemetry: ${configPath} already has an [otel] section (not AgentWatch-owned)`,
535
+ conflict: true
492
536
  };
@@ -1,9 +1,13 @@
1
+ import { codexBillingMode } from '../../billing/billing-mode.js';
1
2
  import { hookNotice, hookRefusal } from '../shared/hook-refusal.js';
3
+ import { readCodexTurnUsage } from '../../turns/codex-transcript.js';
2
4
  import { CODEX_PROMPT_SUBMIT_EVENTS } from './constants/codex.constants.js';
3
5
  import { detectCodex } from './codex.detect.js';
4
6
  import { installCodexHooks, uninstallCodexHooks } from './codex.hooks.js';
5
7
  import { codexShellCall, parseCodexHookEvent } from './codex.adapter.js';
6
8
  import { CodexOtelConfigurator } from './codex.otel.js';
9
+ import { codexSurface } from './codex.surface.js';
10
+ import { readCodexSessionTitles } from './codex.titles.js';
7
11
  export const codexProvider = {
8
12
  id: 'codex',
9
13
  displayName: 'OpenAI Codex',
@@ -24,5 +28,9 @@ export const codexProvider = {
24
28
  /** A line for the developer after a shell run, as `systemMessage`; never plain stdout. */
25
29
  getNoticeResponse: (payload, message) => hookNotice(payload, message),
26
30
  shellCall: codexShellCall,
31
+ readTurnUsage: readCodexTurnUsage,
32
+ billingMode: codexBillingMode,
33
+ readSessionTitles: readCodexSessionTitles,
34
+ surface: codexSurface,
27
35
  nativeTelemetry: new CodexOtelConfigurator()
28
36
  };
@@ -0,0 +1,9 @@
1
+ import type { Env } from '../../core/types/core.types.js';
2
+ /**
3
+ * `exec` for a headless `codex exec` run, else nothing (the default surface).
4
+ *
5
+ * @param _env - Unused; Codex says how it started only in its transcript.
6
+ * @param rawPayload - Hook payload naming the transcript.
7
+ * @returns The surface, when it is not the default.
8
+ */
9
+ export declare function codexSurface(_env: Env, rawPayload: unknown): Promise<string | undefined>;
@@ -1,6 +1,20 @@
1
1
  import fs from 'node:fs/promises';
2
- import { asRecord } from '../core/object.js';
3
- import { CODEX_EXEC_ORIGINATOR, CODEX_META_HEAD_BYTES } from './constants/turns.constants.js';
2
+ import { asRecord } from '../../core/object.js';
3
+ import { EXEC_SURFACE, TRANSCRIPT_PATH_KEY } from '../../turns/constants/turns.constants.js';
4
+ import { CODEX_EXEC_ORIGINATOR, CODEX_META_HEAD_BYTES } from './constants/codex.constants.js';
5
+ /**
6
+ * `exec` for a headless `codex exec` run, else nothing (the default surface).
7
+ *
8
+ * @param _env - Unused; Codex says how it started only in its transcript.
9
+ * @param rawPayload - Hook payload naming the transcript.
10
+ * @returns The surface, when it is not the default.
11
+ */
12
+ export async function codexSurface(_env, rawPayload) {
13
+ const transcriptPath = asRecord(rawPayload)?.[TRANSCRIPT_PATH_KEY];
14
+ if (typeof transcriptPath !== 'string')
15
+ return undefined;
16
+ return (await isCodexExecTranscript(transcriptPath)) ? EXEC_SURFACE : undefined;
17
+ }
4
18
  /**
5
19
  * Whether a Codex transcript belongs to a headless `codex exec` run.
6
20
  *
@@ -11,7 +25,7 @@ import { CODEX_EXEC_ORIGINATOR, CODEX_META_HEAD_BYTES } from './constants/turns.
11
25
  * @param transcriptPath - Path Codex reported in the hook payload.
12
26
  * @returns True only when the originator is `codex_exec`.
13
27
  */
14
- export async function isCodexExecTranscript(transcriptPath) {
28
+ async function isCodexExecTranscript(transcriptPath) {
15
29
  try {
16
30
  const handle = await fs.open(transcriptPath, 'r');
17
31
  try {
@@ -0,0 +1,14 @@
1
+ import type { Env } from '../../core/types/core.types.js';
2
+ import type { SessionTitles } from '../../turns/types/transcript.types.js';
3
+ /**
4
+ * Read the name and generated title Codex keeps for one thread.
5
+ *
6
+ * Codex does not put either value in its hook payload or rollout. Its own
7
+ * read-model database is therefore the source, opened read-only and queried by
8
+ * the hook's session id.
9
+ *
10
+ * @param env - Environment locating `$CODEX_HOME` or `~/.codex`.
11
+ * @param sessionId - Codex thread id from the hook payload.
12
+ * @returns Codex's latest name and generated title, or neither when unavailable.
13
+ */
14
+ export declare function readCodexSessionTitles(env: Env, sessionId: string): Promise<SessionTitles>;
@@ -0,0 +1,35 @@
1
+ import fs from 'node:fs/promises';
2
+ import path from 'node:path';
3
+ import { readTitles, sqliteModule } from '../shared/session-title-store.js';
4
+ import { codexHome } from './codex.detect.js';
5
+ const CODEX_STATE_DATABASE = /^state_(\d+)\.sqlite$/;
6
+ /**
7
+ * Read the name and generated title Codex keeps for one thread.
8
+ *
9
+ * Codex does not put either value in its hook payload or rollout. Its own
10
+ * read-model database is therefore the source, opened read-only and queried by
11
+ * the hook's session id.
12
+ *
13
+ * @param env - Environment locating `$CODEX_HOME` or `~/.codex`.
14
+ * @param sessionId - Codex thread id from the hook payload.
15
+ * @returns Codex's latest name and generated title, or neither when unavailable.
16
+ */
17
+ export async function readCodexSessionTitles(env, sessionId) {
18
+ const sqlite = sqliteModule();
19
+ if (!sqlite)
20
+ return {};
21
+ const home = codexHome(env);
22
+ const entries = await fs.readdir(home, { withFileTypes: true });
23
+ const databases = entries
24
+ .flatMap((entry) => {
25
+ const match = entry.isFile() && CODEX_STATE_DATABASE.exec(entry.name);
26
+ return match ? [{ path: path.join(home, entry.name), version: Number(match[1]) }] : [];
27
+ })
28
+ .sort((left, right) => right.version - left.version);
29
+ for (const database of databases) {
30
+ const titles = readTitles(sqlite, database.path, 'SELECT title, name FROM threads WHERE id = ?', sessionId);
31
+ if (titles.custom || titles.generated)
32
+ return titles;
33
+ }
34
+ return {};
35
+ }
@@ -41,3 +41,7 @@ export declare const CODEX_SHELL_CALL_EVENTS: ReadonlySet<string>;
41
41
  */
42
42
  export declare const CODEX_PROMPT_SUBMIT_EVENTS: ReadonlySet<string>;
43
43
  export declare const CODEX_UNKNOWN_EVENT = "unknown";
44
+ /** `session_meta.originator` Codex writes for a headless `codex exec` run. */
45
+ export declare const CODEX_EXEC_ORIGINATOR = "codex_exec";
46
+ /** How much of a Codex transcript to read for its `session_meta` line (about 20 KB in practice). */
47
+ export declare const CODEX_META_HEAD_BYTES: number;
@@ -76,3 +76,7 @@ export const CODEX_PROMPT_SUBMIT_EVENTS = new Set(['UserPromptSubmit']);
76
76
  * the same way. Accepted: exec runs are headless, with nobody to read it.
77
77
  */
78
78
  export const CODEX_UNKNOWN_EVENT = 'unknown';
79
+ /** `session_meta.originator` Codex writes for a headless `codex exec` run. */
80
+ export const CODEX_EXEC_ORIGINATOR = 'codex_exec';
81
+ /** How much of a Codex transcript to read for its `session_meta` line (about 20 KB in practice). */
82
+ export const CODEX_META_HEAD_BYTES = 256 * 1024;
@@ -1,9 +1,10 @@
1
1
  import type { CanonicalEventType } from '../../../events/types/events.types.js';
2
- import type { ToolKind } from '../../types/provider.types.js';
2
+ import type { ProviderCaveat, ToolKind } from '../../types/provider.types.js';
3
3
  export declare const CURSOR_PROVIDER_ID = "cursor";
4
4
  export declare const CURSOR_DISPLAY_NAME = "Cursor";
5
5
  export declare const CURSOR_HOME_DIR = ".cursor";
6
6
  export declare const CURSOR_HOOKS_FILE = "hooks.json";
7
+ /** The editor ships `cursor`; the CLI agent ships `cursor-agent`, and a machine may have either. */
7
8
  export declare const CURSOR_EXECUTABLES: readonly ["cursor", "cursor-agent"];
8
9
  /**
9
10
  * Cursor lifecycle hooks (verified against cursor.com/docs/hooks, 2026-08).
@@ -16,16 +17,18 @@ export declare const CURSOR_EXECUTABLES: readonly ["cursor", "cursor-agent"];
16
17
  *
17
18
  * `beforeTabFileRead` is deliberately NOT registered: it fires on every inline
18
19
  * completion and carries the full file content — pure noise with a privacy cost.
20
+ * `afterTabFileEdit` is not registered either: a hook process per Tab accept,
21
+ * with no conversation id, so no turn could take it.
19
22
  * `afterAgentThought` and `workspaceOpen` carry nothing the data model uses.
20
23
  */
21
- export declare const CURSOR_HOOK_EVENTS: readonly ["sessionStart", "sessionEnd", "beforeSubmitPrompt", "preToolUse", "postToolUse", "postToolUseFailure", "beforeShellExecution", "afterShellExecution", "beforeMCPExecution", "afterMCPExecution", "beforeReadFile", "afterFileEdit", "subagentStart", "subagentStop", "preCompact", "afterAgentResponse", "stop", "afterTabFileEdit"];
24
+ export declare const CURSOR_HOOK_EVENTS: readonly ["sessionStart", "sessionEnd", "beforeSubmitPrompt", "preToolUse", "postToolUse", "postToolUseFailure", "beforeShellExecution", "afterShellExecution", "beforeMCPExecution", "afterMCPExecution", "beforeReadFile", "afterFileEdit", "subagentStart", "subagentStop", "preCompact", "afterAgentResponse", "stop"];
22
25
  /** Cursor reads this field as seconds. */
23
26
  export declare const CURSOR_HOOK_TIMEOUT_SECONDS = 30;
24
27
  /** Cursor's documented hooks.json schema version. */
25
28
  export declare const CURSOR_HOOKS_VERSION = 1;
26
29
  export declare const CURSOR_VERSION_KEY = "version";
27
- /** Note surfaced at install time about Cursor's missing token usage. */
28
- export declare const CURSOR_USAGE_NOTE = "note: Cursor transcripts carry no token usage yet \u2014 Cursor turn summaries stay usage_status=pending until Cursor enriches them.";
30
+ /** What Cursor cannot report; setup, status and doctor show these. */
31
+ export declare const CURSOR_CAVEATS: readonly ProviderCaveat[];
29
32
  /** Provider hook name to canonical event type, where the mapping is direct. */
30
33
  export declare const CURSOR_EVENT_TYPE_MAP: Readonly<Record<string, CanonicalEventType>>;
31
34
  /**
@@ -65,3 +68,13 @@ export declare const ATTACHMENT_FILE_PATH_KEY = "file_path";
65
68
  */
66
69
  export declare const CURSOR_PROMPT_SUBMIT_EVENTS: ReadonlySet<string>;
67
70
  export declare const CURSOR_UNKNOWN_EVENT = "unknown";
71
+ /** Hooks an older install registered that carry nothing a turn can use; they map to no event. */
72
+ export declare const CURSOR_DROPPED_EVENTS: ReadonlySet<string>;
73
+ /** Per-conversation MCP server memos, under the data dir (see `cursor-mcp-memo.ts`). */
74
+ export declare const CURSOR_MCP_MEMO_DIR = "cursor-mcp";
75
+ /** Memo file names: this many hex characters of sha256(conversation_id). */
76
+ export declare const CURSOR_MCP_MEMO_HASH_LENGTH = 32;
77
+ /** A memo untouched this long belongs to a finished conversation and is pruned on the next write. */
78
+ export declare const CURSOR_MCP_MEMO_MAX_AGE_MS: number;
79
+ /** How often a memo write walks the folder for old memos. */
80
+ export declare const CURSOR_MCP_MEMO_SWEEP_INTERVAL_MS: number;
@@ -2,6 +2,7 @@ export const CURSOR_PROVIDER_ID = 'cursor';
2
2
  export const CURSOR_DISPLAY_NAME = 'Cursor';
3
3
  export const CURSOR_HOME_DIR = '.cursor';
4
4
  export const CURSOR_HOOKS_FILE = 'hooks.json';
5
+ /** The editor ships `cursor`; the CLI agent ships `cursor-agent`, and a machine may have either. */
5
6
  export const CURSOR_EXECUTABLES = ['cursor', 'cursor-agent'];
6
7
  /**
7
8
  * Cursor lifecycle hooks (verified against cursor.com/docs/hooks, 2026-08).
@@ -14,6 +15,8 @@ export const CURSOR_EXECUTABLES = ['cursor', 'cursor-agent'];
14
15
  *
15
16
  * `beforeTabFileRead` is deliberately NOT registered: it fires on every inline
16
17
  * completion and carries the full file content — pure noise with a privacy cost.
18
+ * `afterTabFileEdit` is not registered either: a hook process per Tab accept,
19
+ * with no conversation id, so no turn could take it.
17
20
  * `afterAgentThought` and `workspaceOpen` carry nothing the data model uses.
18
21
  */
19
22
  export const CURSOR_HOOK_EVENTS = [
@@ -33,16 +36,24 @@ export const CURSOR_HOOK_EVENTS = [
33
36
  'subagentStop',
34
37
  'preCompact',
35
38
  'afterAgentResponse',
36
- 'stop',
37
- 'afterTabFileEdit'
39
+ 'stop'
38
40
  ];
39
41
  /** Cursor reads this field as seconds. */
40
42
  export const CURSOR_HOOK_TIMEOUT_SECONDS = 30;
41
43
  /** Cursor's documented hooks.json schema version. */
42
44
  export const CURSOR_HOOKS_VERSION = 1;
43
45
  export const CURSOR_VERSION_KEY = 'version';
44
- /** Note surfaced at install time about Cursor's missing token usage. */
45
- export const CURSOR_USAGE_NOTE = 'note: Cursor transcripts carry no token usage yet — Cursor turn summaries stay usage_status=pending until Cursor enriches them.';
46
+ /** What Cursor cannot report; setup, status and doctor show these. */
47
+ export const CURSOR_CAVEATS = [
48
+ {
49
+ name: 'Cursor token usage',
50
+ detail: 'Cursor hooks and transcripts carry no token usage, so Cursor turn summaries stay usage_status=pending; Cursor cost comes from the Cursor Admin API connection in Integrations'
51
+ },
52
+ {
53
+ name: 'Cursor CLI hooks',
54
+ detail: 'cursor-agent (CLI) currently emits only shell hook events (known Cursor issue); IDE sessions are fully covered'
55
+ }
56
+ ];
46
57
  /** Provider hook name to canonical event type, where the mapping is direct. */
47
58
  export const CURSOR_EVENT_TYPE_MAP = {
48
59
  sessionStart: 'session.started',
@@ -54,7 +65,6 @@ export const CURSOR_EVENT_TYPE_MAP = {
54
65
  afterMCPExecution: 'mcp.completed',
55
66
  beforeReadFile: 'file.read',
56
67
  afterFileEdit: 'file.edited',
57
- afterTabFileEdit: 'file.edited',
58
68
  subagentStart: 'subagent.started',
59
69
  subagentStop: 'subagent.completed',
60
70
  preCompact: 'compaction.started',
@@ -102,3 +112,13 @@ export const ATTACHMENT_FILE_PATH_KEY = 'file_path';
102
112
  */
103
113
  export const CURSOR_PROMPT_SUBMIT_EVENTS = new Set(['beforeSubmitPrompt']);
104
114
  export const CURSOR_UNKNOWN_EVENT = 'unknown';
115
+ /** Hooks an older install registered that carry nothing a turn can use; they map to no event. */
116
+ export const CURSOR_DROPPED_EVENTS = new Set(['afterTabFileEdit']);
117
+ /** Per-conversation MCP server memos, under the data dir (see `cursor-mcp-memo.ts`). */
118
+ export const CURSOR_MCP_MEMO_DIR = 'cursor-mcp';
119
+ /** Memo file names: this many hex characters of sha256(conversation_id). */
120
+ export const CURSOR_MCP_MEMO_HASH_LENGTH = 32;
121
+ /** A memo untouched this long belongs to a finished conversation and is pruned on the next write. */
122
+ export const CURSOR_MCP_MEMO_MAX_AGE_MS = 7 * 24 * 60 * 60 * 1000;
123
+ /** How often a memo write walks the folder for old memos. */
124
+ export const CURSOR_MCP_MEMO_SWEEP_INTERVAL_MS = 24 * 60 * 60 * 1000;
@@ -0,0 +1,34 @@
1
+ /**
2
+ * The folder of per-conversation MCP memos.
3
+ *
4
+ * `afterMCPExecution` carries neither url nor command, and only completions
5
+ * become turn records, so the server the before-hook saw has to outlive it.
6
+ *
7
+ * @param dataDir - The edge's data dir.
8
+ * @returns The memo folder.
9
+ */
10
+ export declare function mcpMemoDir(dataDir: string): string;
11
+ /**
12
+ * Remember which server a tool resolved to, for the completion hook. Every
13
+ * write refreshes the memo's mtime, so a memo in use is never old. At most once
14
+ * a day a write also drops memos idle past `CURSOR_MCP_MEMO_MAX_AGE_MS`.
15
+ *
16
+ * ponytail: last write wins per tool name; two servers exposing the same tool
17
+ * name in one conversation share an entry. Upgrade: key by tool_use_id if Cursor sends it.
18
+ *
19
+ * @param dataDir - The edge's data dir.
20
+ * @param conversationId - Cursor conversation id.
21
+ * @param tool - Tool name.
22
+ * @param server - Resolved server.
23
+ * @param now - The hook's clock, for the prune.
24
+ */
25
+ export declare function rememberMcpServer(dataDir: string, conversationId: string, tool: string, server: string, now: Date): void;
26
+ /**
27
+ * The server a tool resolved to in this conversation's before-hook.
28
+ *
29
+ * @param dataDir - The edge's data dir.
30
+ * @param conversationId - Cursor conversation id.
31
+ * @param tool - Tool name.
32
+ * @returns The server, or undefined when none was remembered.
33
+ */
34
+ export declare function rememberedMcpServer(dataDir: string, conversationId: string, tool: string): string | undefined;
@@ -0,0 +1,94 @@
1
+ import fs from 'node:fs';
2
+ import path from 'node:path';
3
+ import { asRecord } from '../../core/object.js';
4
+ import { sha256Hex } from '../../events/event-id.js';
5
+ import { SECRET_FILE_MODE, SWEEP_MARKER_FILE } from '../../storage/constants/storage.constants.js';
6
+ import { CURSOR_MCP_MEMO_DIR, CURSOR_MCP_MEMO_HASH_LENGTH, CURSOR_MCP_MEMO_MAX_AGE_MS, CURSOR_MCP_MEMO_SWEEP_INTERVAL_MS } from './constants/cursor.constants.js';
7
+ /**
8
+ * The folder of per-conversation MCP memos.
9
+ *
10
+ * `afterMCPExecution` carries neither url nor command, and only completions
11
+ * become turn records, so the server the before-hook saw has to outlive it.
12
+ *
13
+ * @param dataDir - The edge's data dir.
14
+ * @returns The memo folder.
15
+ */
16
+ export function mcpMemoDir(dataDir) {
17
+ return path.join(dataDir, CURSOR_MCP_MEMO_DIR);
18
+ }
19
+ /**
20
+ * Remember which server a tool resolved to, for the completion hook. Every
21
+ * write refreshes the memo's mtime, so a memo in use is never old. At most once
22
+ * a day a write also drops memos idle past `CURSOR_MCP_MEMO_MAX_AGE_MS`.
23
+ *
24
+ * ponytail: last write wins per tool name; two servers exposing the same tool
25
+ * name in one conversation share an entry. Upgrade: key by tool_use_id if Cursor sends it.
26
+ *
27
+ * @param dataDir - The edge's data dir.
28
+ * @param conversationId - Cursor conversation id.
29
+ * @param tool - Tool name.
30
+ * @param server - Resolved server.
31
+ * @param now - The hook's clock, for the prune.
32
+ */
33
+ export function rememberMcpServer(dataDir, conversationId, tool, server, now) {
34
+ const file = memoFile(dataDir, conversationId);
35
+ try {
36
+ fs.mkdirSync(path.dirname(file), { recursive: true });
37
+ fs.writeFileSync(file, JSON.stringify({ ...readMemo(file), [tool]: server }), { mode: SECRET_FILE_MODE });
38
+ pruneMemosWhenDue(dataDir, now);
39
+ }
40
+ catch {
41
+ // Hooks never fail the agent; the completion just keys as unknown.
42
+ }
43
+ }
44
+ /**
45
+ * The server a tool resolved to in this conversation's before-hook.
46
+ *
47
+ * @param dataDir - The edge's data dir.
48
+ * @param conversationId - Cursor conversation id.
49
+ * @param tool - Tool name.
50
+ * @returns The server, or undefined when none was remembered.
51
+ */
52
+ export function rememberedMcpServer(dataDir, conversationId, tool) {
53
+ const server = readMemo(memoFile(dataDir, conversationId))[tool];
54
+ return typeof server === 'string' ? server : undefined;
55
+ }
56
+ function memoFile(dataDir, conversationId) {
57
+ return path.join(mcpMemoDir(dataDir), `${sha256Hex(conversationId).slice(0, CURSOR_MCP_MEMO_HASH_LENGTH)}.json`);
58
+ }
59
+ function readMemo(file) {
60
+ try {
61
+ return asRecord(JSON.parse(fs.readFileSync(file, 'utf8'))) ?? {};
62
+ }
63
+ catch {
64
+ return {};
65
+ }
66
+ }
67
+ /**
68
+ * Delete memos untouched past the age bound, when the daily sweep is due.
69
+ *
70
+ * The same marker-mtime clock as `claimSweep` (storage/sweep-marker.ts), kept
71
+ * synchronous because the adapter that calls it is: one `stat` on the common path.
72
+ */
73
+ function pruneMemosWhenDue(dataDir, now) {
74
+ const dir = mcpMemoDir(dataDir);
75
+ const marker = path.join(dir, SWEEP_MARKER_FILE);
76
+ const last = fs.statSync(marker, { throwIfNoEntry: false })?.mtimeMs;
77
+ if (last !== undefined && now.getTime() - last < CURSOR_MCP_MEMO_SWEEP_INTERVAL_MS)
78
+ return;
79
+ fs.writeFileSync(marker, '', { mode: SECRET_FILE_MODE });
80
+ fs.utimesSync(marker, now, now);
81
+ const cutoff = now.getTime() - CURSOR_MCP_MEMO_MAX_AGE_MS;
82
+ for (const name of fs.readdirSync(dir)) {
83
+ if (name === SWEEP_MARKER_FILE)
84
+ continue;
85
+ const file = path.join(dir, name);
86
+ try {
87
+ if (fs.statSync(file).mtimeMs < cutoff)
88
+ fs.rmSync(file, { force: true });
89
+ }
90
+ catch {
91
+ // Another hook pruned it first.
92
+ }
93
+ }
94
+ }