@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
@@ -0,0 +1,301 @@
1
+ import { existsSync, readFileSync } from 'node:fs';
2
+ import fs from 'node:fs/promises';
3
+ import path from 'node:path';
4
+ import { fileURLToPath } from 'node:url';
5
+ import { hasCredential } from '../credentials/identity.js';
6
+ import { runCaptureRoute } from '../providers/provider.js';
7
+ import { writeFileAtomic } from '../storage/atomic-file.js';
8
+ import { SECRET_FILE_MODE } from '../storage/constants/storage.constants.js';
9
+ import { CAPTURE_COPY_DIR, EDGE_PACKAGE_NAME, NODE_SHIM_PATH, PYTHON_SHIM_DIR, PYTHON_SHIM_FILE, RE_NEEDS_DOUBLE_QUOTES, RE_NODE_OPTIONS_ESCAPE, RE_NODE_OPTIONS_UNESCAPE, RE_OUR_PYTHON_DIR, RE_OUR_REQUIRE, RE_OUTER_QUOTES, RE_RELATIVE_PRELOAD, RE_REQUIRE_FLAG, RUN_CAPTURE_ENV_NODE, RUN_CAPTURE_ENV_PYTHON } from './constants/capture.constants.js';
10
+ /** This package's root, from the source file and the built one alike. */
11
+ const PACKAGE_ROOT = fileURLToPath(new URL('../../', import.meta.url));
12
+ /**
13
+ * The shim paths inside this package, which the copy under the data dir is made from.
14
+ *
15
+ * @param root - The package root; tests name their own.
16
+ * @returns The file `--require` loads and the folder PYTHONPATH adds.
17
+ */
18
+ export function shimPaths(root = PACKAGE_ROOT) {
19
+ return { node: path.join(root, NODE_SHIM_PATH), python: path.join(root, PYTHON_SHIM_DIR) };
20
+ }
21
+ async function shimsPresent(shims) {
22
+ const present = (file) => fs.access(file).then(() => true, () => false);
23
+ return (await present(shims.node)) && present(path.join(shims.python, PYTHON_SHIM_FILE));
24
+ }
25
+ function requireOption(file) {
26
+ return `--require ${RE_NEEDS_DOUBLE_QUOTES.test(file) ? `"${file.replace(RE_NODE_OPTIONS_ESCAPE, '\\$1')}"` : file}`;
27
+ }
28
+ /**
29
+ * Whether a path shaped like a shim's really lies inside an Edge install: this one, or
30
+ * another copy of this package (a moved install, an nvm switch). The shape alone is not
31
+ * enough, since `/home/me/tool/dist/capture/node.cjs` may be the developer's own.
32
+ *
33
+ * @param entry - A shim-shaped path, three levels below its package root either way.
34
+ * @param shims - This install's shim paths.
35
+ * @returns True when the package holding it is Edge.
36
+ */
37
+ function insideEdge(entry, shims) {
38
+ if (entry === shims.node || entry === shims.python)
39
+ return true;
40
+ const root = path.resolve(entry, '..', '..', '..');
41
+ if (root === path.resolve(PACKAGE_ROOT))
42
+ return true;
43
+ try {
44
+ return JSON.parse(readFileSync(path.join(root, 'package.json'), 'utf8')).name === EDGE_PACKAGE_NAME;
45
+ }
46
+ catch {
47
+ return false;
48
+ }
49
+ }
50
+ /*
51
+ * A `--require` of ours whose target is gone goes too, though no package is left to prove
52
+ * it: it stops every Node the agent starts, so nothing of the developer's can depend on
53
+ * it, and setup must be able to clear it after the package moved. A Python folder that is
54
+ * gone costs nothing, so it stays unless it is provably ours.
55
+ */
56
+ function withoutOurNodeOptions(value, shims) {
57
+ return value
58
+ .replace(RE_OUR_REQUIRE, (match) => {
59
+ const file = match.trim().replace(RE_REQUIRE_FLAG, '').replace(RE_OUTER_QUOTES, '').replace(RE_NODE_OPTIONS_UNESCAPE, '$1');
60
+ return !existsSync(file) || insideEdge(file, shims) ? '' : match;
61
+ })
62
+ .trim();
63
+ }
64
+ function withoutOurPythonPath(value, shims) {
65
+ return value.split(path.delimiter).filter((entry) => entry !== '' && !(RE_OUR_PYTHON_DIR.test(entry) && insideEdge(entry, shims))).join(path.delimiter);
66
+ }
67
+ // The ambient value goes machine-wide once written, so a relative entry goes no further:
68
+ // `PYTHONPATH=.` in setup's shell would run every repository's `sitecustomize.py`.
69
+ function absoluteNodeOptions(value) {
70
+ return value.replace(RE_RELATIVE_PRELOAD, '').trim();
71
+ }
72
+ function absolutePythonPath(value) {
73
+ return value.split(path.delimiter).filter((entry) => path.isAbsolute(entry)).join(path.delimiter);
74
+ }
75
+ /**
76
+ * The two variables that load the shims, each kept beside the developer's own.
77
+ *
78
+ * An agent's env block replaces what the shell set, so a developer's value has to
79
+ * move in with ours or `--max-old-space-size` and their imports quietly vanish:
80
+ * the block's value when it has one, else the ambient one setup was run with.
81
+ *
82
+ * ponytail: the ambient value is copied once, at setup. A later change in the
83
+ * developer's shell is masked for what the agent runs until setup runs again; a
84
+ * `sh -c`-time merge (Claude Code's env file) would lift that, per agent.
85
+ *
86
+ * @param block - The agent's env block as it stands.
87
+ * @param ambient - The environment setup runs in.
88
+ * @param shims - The shim paths to load.
89
+ * @returns The two values; empty on Windows, where no ancestry can be read.
90
+ */
91
+ export function captureEnv(block, ambient, shims = shimPaths()) {
92
+ if (path.delimiter === ';')
93
+ return {};
94
+ const stated = (key) => (typeof block[key] === 'string' ? block[key] : undefined);
95
+ const nodeOptions = withoutOurNodeOptions(stated(RUN_CAPTURE_ENV_NODE) ?? '', shims) || absoluteNodeOptions(withoutOurNodeOptions(ambient[RUN_CAPTURE_ENV_NODE] ?? '', shims));
96
+ const pythonPath = withoutOurPythonPath(stated(RUN_CAPTURE_ENV_PYTHON) ?? '', shims) || absolutePythonPath(withoutOurPythonPath(ambient[RUN_CAPTURE_ENV_PYTHON] ?? '', shims));
97
+ return {
98
+ [RUN_CAPTURE_ENV_NODE]: [requireOption(shims.node), ...(nodeOptions ? [nodeOptions] : [])].join(' '),
99
+ [RUN_CAPTURE_ENV_PYTHON]: [shims.python, ...(pythonPath ? [pythonPath] : [])].join(path.delimiter)
100
+ };
101
+ }
102
+ /**
103
+ * Where the shims an agent's environment loads live: a copy under the data dir.
104
+ *
105
+ * A copy because a `--require` naming a missing file stops every Node the agent starts,
106
+ * Edge's own hook included, so nothing can repair it from inside. The package can go
107
+ * from under a path into it (`npm uninstall -g`, a removed nvm version, an upgrade's
108
+ * file swap); this one goes only with `agentwatch uninstall`.
109
+ *
110
+ * @param dataDir - The data dir.
111
+ * @returns The copy's shim paths.
112
+ */
113
+ export function copiedShims(dataDir) {
114
+ return { node: path.join(dataDir, CAPTURE_COPY_DIR, path.basename(NODE_SHIM_PATH)), python: path.join(dataDir, CAPTURE_COPY_DIR, path.basename(PYTHON_SHIM_DIR)) };
115
+ }
116
+ /**
117
+ * Write the copy from this package, overwriting: every setup refreshes it after an update.
118
+ *
119
+ * Atomic per file, and the `--require` target last, so a Node starting meanwhile loads a
120
+ * whole file of one version or the other.
121
+ *
122
+ * @param dataDir - The data dir.
123
+ * @param source - The package's shims.
124
+ * @returns The copy's paths, or undefined when there is nothing to copy (an unbuilt checkout).
125
+ */
126
+ export async function installCaptureCopy(dataDir, source = shimPaths()) {
127
+ const copy = copiedShims(dataDir);
128
+ try {
129
+ const [node, python] = await Promise.all([fs.readFile(source.node, 'utf8'), fs.readFile(path.join(source.python, PYTHON_SHIM_FILE), 'utf8')]);
130
+ await fs.mkdir(copy.python, { recursive: true, mode: 0o700 });
131
+ await writeFileAtomic(path.join(copy.python, PYTHON_SHIM_FILE), python, SECRET_FILE_MODE);
132
+ await writeFileAtomic(copy.node, node, SECRET_FILE_MODE);
133
+ return copy;
134
+ }
135
+ catch {
136
+ return undefined;
137
+ }
138
+ }
139
+ /**
140
+ * Whether any agent's run-capture config file still names the copy, in whatever state that file is.
141
+ *
142
+ * @param dataDir - The data dir.
143
+ * @param env - Environment locating each agent's config.
144
+ * @param agents - Every provider; each run-capture route names its own file.
145
+ * @returns True when one of those files mentions the copy.
146
+ */
147
+ async function configNamesCopy(dataDir, env, agents) {
148
+ const files = agents.flatMap((agent) => runCaptureRoute(agent)?.configPath(env) ?? []);
149
+ const contents = await Promise.all(files.map((file) => fs.readFile(file, 'utf8').catch(() => '')));
150
+ return contents.some((raw) => raw.includes(path.join(dataDir, CAPTURE_COPY_DIR)));
151
+ }
152
+ /**
153
+ * Remove the copy, once no agent can still be loading it.
154
+ *
155
+ * Every agent shares the one copy, and a missing `--require` target stops every Node an
156
+ * agent starts, so it stays while either holds. Hooks: `agentwatch off`, the exporter sweep
157
+ * and `otel: none` take the env keys out and leave the hooks, with sessions still running
158
+ * that hold the `--require`; a detection that fails counts as installed. A config naming the
159
+ * copy: a removal that was refused leaves the keys, and a hook file that does not parse
160
+ * reads as no hooks. A copy left behind costs nothing.
161
+ *
162
+ * @param dataDir - The data dir.
163
+ * @param env - Environment supplying where each agent keeps its hooks and config.
164
+ */
165
+ export async function removeCaptureCopy(dataDir, env) {
166
+ // At call time: the registry loads every provider, and the hook path must not.
167
+ const { providers } = await import('../providers/registry.js');
168
+ const installed = await Promise.all(providers.map((provider) => provider.detect(env).then((found) => found.hooksInstalled, () => true)));
169
+ if (installed.some(Boolean) || (await configNamesCopy(dataDir, env, providers)))
170
+ return;
171
+ await fs.rm(path.join(dataDir, CAPTURE_COPY_DIR), { recursive: true, force: true }).catch(() => undefined);
172
+ }
173
+ /**
174
+ * Refresh the copy, and point an env block at it.
175
+ *
176
+ * @param block - The agent's env block as it stands.
177
+ * @param ambient - The environment setup runs in.
178
+ * @param dataDir - The data dir.
179
+ * @param source - The package's shims.
180
+ * @returns The block with the copy loaded; with no copy to load, the block with any
181
+ * earlier `--require` of ours taken out, since it could stop every Node.
182
+ */
183
+ export async function installedCaptureEnv(block, ambient, dataDir, source = shimPaths()) {
184
+ if (path.delimiter === ';')
185
+ return block;
186
+ const copy = await installCaptureCopy(dataDir, source);
187
+ return capturedBlock(block, ambient, copy !== undefined, copiedShims(dataDir));
188
+ }
189
+ /**
190
+ * An env block as setup should leave it.
191
+ *
192
+ * @param block - The agent's env block as it stands.
193
+ * @param ambient - The environment setup runs in.
194
+ * @param installed - Whether the shims are on disk.
195
+ * @param shims - The shim paths to load.
196
+ * @returns The next block.
197
+ */
198
+ export function capturedBlock(block, ambient, installed, shims = shimPaths()) {
199
+ return installed ? { ...block, ...captureEnv(block, ambient, shims) } : withoutCaptureEnv(block, shims);
200
+ }
201
+ /**
202
+ * An env block with only our part of the two variables gone.
203
+ *
204
+ * @param block - The agent's env block.
205
+ * @param shims - This install's shim paths.
206
+ * @returns The block; a variable left empty is removed, a developer's value stays.
207
+ */
208
+ export function withoutCaptureEnv(block, shims = shimPaths()) {
209
+ const next = {};
210
+ for (const [key, value] of Object.entries(block)) {
211
+ if (typeof value !== 'string' || (key !== RUN_CAPTURE_ENV_NODE && key !== RUN_CAPTURE_ENV_PYTHON)) {
212
+ next[key] = value;
213
+ continue;
214
+ }
215
+ const kept = key === RUN_CAPTURE_ENV_NODE ? withoutOurNodeOptions(value, shims) : withoutOurPythonPath(value, shims);
216
+ if (kept !== '')
217
+ next[key] = kept;
218
+ }
219
+ return next;
220
+ }
221
+ /**
222
+ * Whether the config is a link, usually into a dotfiles repository.
223
+ *
224
+ * Capture leaves one alone. Through the link, a machine-specific `--require` would reach
225
+ * every machine sharing the file, and it stops every Node where the copy is missing. In
226
+ * place of the link, the developer's file would quietly stop being the one in use.
227
+ *
228
+ * @param file - The config file.
229
+ * @returns True when it is a symbolic link.
230
+ */
231
+ export async function isLinkedConfig(file) {
232
+ return (await fs.lstat(file).catch(() => undefined))?.isSymbolicLink() ?? false;
233
+ }
234
+ /**
235
+ * Why a linked config gets no capture.
236
+ *
237
+ * @param file - The config file.
238
+ * @returns The sentence for setup, status and doctor.
239
+ */
240
+ export function linkedConfigReason(file) {
241
+ return `${file} is a link, and the capture path is specific to this machine, so Edge does not write it there`;
242
+ }
243
+ /**
244
+ * A capture write whose throw (a full disk, a read-only file) is said, not raised, for the
245
+ * reason `withCaptureOutcome` gives.
246
+ *
247
+ * @param step - The write.
248
+ * @returns Its outcome, or one naming what went wrong.
249
+ */
250
+ export function skippedOnError(step) {
251
+ return step.catch((error) => ({ ok: true, changed: false, messages: [`run capture skipped: ${error instanceof Error ? error.message : 'write failed'}`] }));
252
+ }
253
+ /**
254
+ * An agent's outcome with its run-capture step folded in.
255
+ *
256
+ * A capture step that cannot write says so and stays `ok`: it must not count as a failure
257
+ * of setup or `agentwatch on`, which would roll back every agent over one optional key. Only
258
+ * a removal that leaves our keys behind reports `ok: false`.
259
+ *
260
+ * @param outcome - What the agent's own step reported.
261
+ * @param capture - What the capture step reported.
262
+ * @returns The outcome the command prints.
263
+ */
264
+ export function withCaptureOutcome(outcome, capture) {
265
+ return { ...outcome, ok: outcome.ok && capture.ok, changed: outcome.changed || capture.changed, messages: [...outcome.messages, ...capture.messages] };
266
+ }
267
+ /**
268
+ * Whether an agent's environment loads the shims, and when not, why.
269
+ *
270
+ * @param block - The env block the agent runs with.
271
+ * @param config - The credential that would deliver what is captured.
272
+ * @param telemetryOn - Whether this machine's config allows the agent's telemetry.
273
+ * @param dataDir - The data dir holding the copy.
274
+ * @param source - The package's shims, which the copy should match.
275
+ * @returns On, or off with the reason; on with a warning when the copy is stale.
276
+ */
277
+ export async function inspectCaptureEnv(block, config, telemetryOn, dataDir, source = shimPaths()) {
278
+ const shims = copiedShims(dataDir);
279
+ if (path.delimiter === ';')
280
+ return { on: false, reason: 'not supported on Windows' };
281
+ if (!hasCredential(config))
282
+ return { on: false, reason: 'Edge is not signed in, so nothing is captured' };
283
+ if (!telemetryOn)
284
+ return { on: false, reason: 'telemetry is off in config (otel)' };
285
+ const expected = captureEnv(block, {}, shims);
286
+ if (block[RUN_CAPTURE_ENV_NODE] !== expected[RUN_CAPTURE_ENV_NODE] || block[RUN_CAPTURE_ENV_PYTHON] !== expected[RUN_CAPTURE_ENV_PYTHON]) {
287
+ return { on: false, reason: 'not configured; run `agentwatch setup` and restart the agent' };
288
+ }
289
+ // A missing --require target stops every Node the agent starts, so it is worth saying.
290
+ if (!(await shimsPresent(shims)))
291
+ return { on: false, reason: `the capture copy under ${path.dirname(shims.node)} is missing, which stops every Node the agent starts; run \`agentwatch setup\`` };
292
+ return (await copyIsStale(shims, source)) ? { on: true, warning: 'the capture copy does not match this Edge; run `agentwatch setup`' } : { on: true };
293
+ }
294
+ async function copyIsStale(copy, source) {
295
+ const read = (file) => fs.readFile(file, 'utf8').catch(() => undefined);
296
+ const [node, python] = await Promise.all([read(source.node), read(path.join(source.python, PYTHON_SHIM_FILE))]);
297
+ // A package with no built shim (a source checkout) has nothing to compare with.
298
+ if (node === undefined || python === undefined)
299
+ return false;
300
+ return node !== (await read(copy.node)) || python !== (await read(path.join(copy.python, PYTHON_SHIM_FILE)));
301
+ }
@@ -0,0 +1,88 @@
1
+ import type { StepOutcome } from '../core/types/core.types.js';
2
+ import { buildLlmCall } from '../events/llm-call.js';
3
+ import type { HookPipelineState } from '../pipeline/types/pipeline.types.js';
4
+ import type { EventQueue } from '../transport/queue.js';
5
+ import type { CapturedCallEvent, LaunchedRun, SpoolRecord } from './types/capture.types.js';
6
+ /**
7
+ * Usage as the ledger reads it under this agent's name.
8
+ *
9
+ * Shims report one convention (input without cache reads, output with reasoning).
10
+ * Core reads a row's counts by its `provider`, and a captured call's provider is
11
+ * the launching agent, so an OpenAI script under Claude Code must state its fresh
12
+ * input alone or its cached tokens are billed twice.
13
+ *
14
+ * @param usage - The shim's counts.
15
+ * @param agent - The wire provider.
16
+ * @returns The counts for `buildLlmCall`.
17
+ */
18
+ export declare function wireUsage(usage: SpoolRecord['usage'], agent: string): NonNullable<Parameters<typeof buildLlmCall>[0]['usage']> | undefined;
19
+ /**
20
+ * The `llm.call` of one captured record.
21
+ *
22
+ * `provider` is the id the agent's native route sends and `call_id` the provider's
23
+ * request id, exactly as that route sets it (`normalize.ts`): the idempotency key is
24
+ * then the native record's, so core keeps one row. `billing_mode: api`, because a
25
+ * script's metered call on a subscription session would otherwise inherit the
26
+ * session's mode and read as covered by plan.
27
+ *
28
+ * @param record - The spool line.
29
+ * @param input - Who launched it and which run it belongs to.
30
+ * @param input.providerId - The launching agent's provider id.
31
+ * @param input.surface - The surface it runs on.
32
+ * @param input.sessionId - The launching session.
33
+ * @param input.run - The run this call belongs to.
34
+ * @returns The event.
35
+ */
36
+ export declare function buildCapturedCall(record: SpoolRecord, input: {
37
+ providerId: string;
38
+ surface: string;
39
+ sessionId: string;
40
+ run: Pick<LaunchedRun, 'turnId' | 'entry'>;
41
+ }): CapturedCallEvent;
42
+ /**
43
+ * Create or remove the spool folder: shims write only while it exists.
44
+ *
45
+ * A stage of its own, before the sign-in stop, because it has to run when Edge is
46
+ * signed out, the one case that must capture nothing and must not hold back
47
+ * records to send under whoever signs in next.
48
+ *
49
+ * The machine's answer, not this folder's: the spool is shared, so a hook in a folder
50
+ * no root claims must not delete what a root's sessions have spooled.
51
+ *
52
+ * @param state - Current flow state.
53
+ * @returns The state, unchanged.
54
+ */
55
+ export declare function armCaptureStage(state: HookPipelineState): Promise<StepOutcome<HookPipelineState>>;
56
+ /**
57
+ * Remember this shell call as a run, and attach what the spool holds to its runs.
58
+ *
59
+ * Runs on every hook on the machine, because a background run's last calls arrive
60
+ * whenever the next hook does. Never fails the flow: every record not yet consumed
61
+ * is still on disk for the next hook.
62
+ *
63
+ * @param state - Current flow state.
64
+ * @param queue - The queue of the identity this hook sends as.
65
+ * @returns The state, unchanged.
66
+ */
67
+ export declare function capturedStage(state: HookPipelineState, queue: EventQueue): Promise<StepOutcome<HookPipelineState>>;
68
+ /**
69
+ * The same, on the one hook that is about to clear the session: the attach runs
70
+ * before the tracker removes what it maps a record to.
71
+ *
72
+ * @param state - Current flow state.
73
+ * @param queue - The queue of the identity this hook sends as.
74
+ * @returns The state, unchanged.
75
+ */
76
+ export declare function capturedAtSessionEnd(state: HookPipelineState, queue: EventQueue): Promise<StepOutcome<HookPipelineState>>;
77
+ /**
78
+ * Whether the session's current run has produced a captured call, so the
79
+ * untraced-runs notice has nothing to say.
80
+ *
81
+ * Before the attach step in the flow, so it looks at the spool as well as at what
82
+ * an earlier hook already attached.
83
+ *
84
+ * @param state - Current flow state.
85
+ * @param sessionId - The session whose shell call just completed.
86
+ * @returns True when a captured call of the current run exists.
87
+ */
88
+ export declare function runWasCaptured(state: HookPipelineState, sessionId: string): Promise<boolean>;