@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
@@ -139,17 +139,14 @@ function judgeUrl(value, trusted) {
139
139
  if (!url)
140
140
  return { kind: 'undeliverable' };
141
141
  const origin = originOf(url);
142
- // Without the trailing dot: `host.` is the same DNS name as `host`.
143
- const host = url.hostname.endsWith('.') ? url.hostname.slice(0, -1) : url.hostname;
142
+ const host = bareHost(url);
144
143
  const loopback = LOOPBACK_HOSTS.has(host);
145
144
  if (url.protocol !== 'https:' && !(url.protocol === 'http:' && loopback)) {
146
145
  return { kind: 'undeliverable', ...(url.protocol === 'http:' ? { origin } : {}) };
147
146
  }
148
147
  if (loopback || trusted.has(origin))
149
148
  return { kind: 'allowed', origin };
150
- // A port other than the default needs trust: a different port on the right
151
- // name is a different service.
152
- if (url.protocol === 'https:' && url.port === '' && AGENT_WATCH_HOSTS.has(host))
149
+ if (isAgentWatchHost(url))
153
150
  return { kind: 'allowed', origin };
154
151
  return { kind: 'untrusted', origin };
155
152
  }
@@ -162,7 +159,7 @@ function judgeUrl(value, trusted) {
162
159
  * @returns The origin.
163
160
  */
164
161
  function originOf(url) {
165
- const host = url.hostname.endsWith('.') ? url.hostname.slice(0, -1) : url.hostname;
162
+ const host = bareHost(url);
166
163
  return `${url.protocol}//${host}${url.port ? `:${url.port}` : ''}`;
167
164
  }
168
165
  /**
@@ -175,6 +172,40 @@ function originOf(url) {
175
172
  export function isAllowedHost(value, trusted) {
176
173
  return judgeUrl(value, trusted).kind === 'allowed';
177
174
  }
175
+ /**
176
+ * Whether a URL is one AgentWatch itself sends to: an Agent Watch host or an
177
+ * origin this machine trusts. Unlike `isAllowedHost`, loopback alone does not
178
+ * count, because a collector on localhost is as likely the developer's own.
179
+ *
180
+ * @param value - The URL as written.
181
+ * @param trusted - Origins this machine trusts (`customEndpoints`).
182
+ * @returns True when the URL points at Agent Watch.
183
+ */
184
+ export function isAgentWatchEndpoint(value, trusted) {
185
+ const url = parseUrl(value);
186
+ if (!url || judgeUrl(value, trusted).kind !== 'allowed')
187
+ return false;
188
+ return trusted.has(originOf(url)) || isAgentWatchHost(url);
189
+ }
190
+ /**
191
+ * Whether a parsed URL is an Agent Watch host on the default https port: a
192
+ * different port on the right name is a different service.
193
+ *
194
+ * @param url - A parsed URL.
195
+ * @returns True for an Agent Watch host.
196
+ */
197
+ function isAgentWatchHost(url) {
198
+ return url.protocol === 'https:' && url.port === '' && AGENT_WATCH_HOSTS.has(bareHost(url));
199
+ }
200
+ /**
201
+ * A URL's host without the trailing dot: `host.` is the same DNS name as `host`.
202
+ *
203
+ * @param url - A parsed URL.
204
+ * @returns The host.
205
+ */
206
+ function bareHost(url) {
207
+ return url.hostname.endsWith('.') ? url.hostname.slice(0, -1) : url.hostname;
208
+ }
178
209
  /**
179
210
  * The origin of a URL the edge could deliver to, for recording trust in it.
180
211
  *
@@ -452,6 +483,11 @@ export const configSchema = z
452
483
  * wins, so a nested checkout can override the workspace above it.
453
484
  */
454
485
  roots: z.record(z.string(), rootOverrideSchema).optional(),
486
+ /**
487
+ * Absolute directories whose hooks answer the agent and capture nothing; `<dir>/**` covers the subtree.
488
+ * No `.catch`: a malformed list invalidates the file loudly instead of quietly capturing where the developer opted out.
489
+ */
490
+ ignoredRoots: z.array(z.string()).default([]),
455
491
  contentCaptureConsent: z.boolean().default(false),
456
492
  /**
457
493
  * Origins this machine sends to outside the Agent Watch hosts. Written by
@@ -45,3 +45,10 @@ export interface EffectiveConfig extends MergedConfig {
45
45
  /** Project root whose identity was applied, when one matched. */
46
46
  readonly rootPath?: string;
47
47
  }
48
+ /** Ceilings for one transport; both in milliseconds, so they are named, never positional. */
49
+ export interface TransportLimits {
50
+ /** Ceiling for one request; defaults to the config's `delivery.timeoutMs`. */
51
+ readonly timeoutMs?: number;
52
+ /** Ceiling for the whole send; the hook passes what is left of its budget. */
53
+ readonly budgetMs?: number;
54
+ }
@@ -6,7 +6,7 @@ export type { Env, FlowObserver, FlowResult, FlowTrace, Step, StepOutcome, Unkno
6
6
  export { realEnv } from './env.js';
7
7
  export { debugEnabled, debugLog, setVerbose, warnLog } from './logger.js';
8
8
  export { meetsMinVersion, parseVersion } from './version.js';
9
- export { findExecutable } from './which.js';
9
+ export { findExecutable, findFirstExecutable } from './which.js';
10
10
  export { asArray, asRecord, compact, firstNumber, firstString, firstStringOf, isRecord, omitKeys } from './object.js';
11
11
  export { add, finiteOrZero, sumPresent } from './number.js';
12
12
  export { pollUntil, sleep } from './async.js';
@@ -1,7 +1,7 @@
1
1
  export { realEnv } from './env.js';
2
2
  export { debugEnabled, debugLog, setVerbose, warnLog } from './logger.js';
3
3
  export { meetsMinVersion, parseVersion } from './version.js';
4
- export { findExecutable } from './which.js';
4
+ export { findExecutable, findFirstExecutable } from './which.js';
5
5
  export { asArray, asRecord, compact, firstNumber, firstString, firstStringOf, isRecord, omitKeys } from './object.js';
6
6
  export { add, finiteOrZero, sumPresent } from './number.js';
7
7
  export { pollUntil, sleep } from './async.js';
@@ -17,3 +17,12 @@ export declare function parseVersion(output: string): string | undefined;
17
17
  * @returns True when version >= min.
18
18
  */
19
19
  export declare function meetsMinVersion(version: string, min: string): boolean;
20
+ /**
21
+ * Run a `--version`-style command, treating any failure as no answer.
22
+ *
23
+ * @param command - Executable.
24
+ * @param args - Its arguments.
25
+ * @param timeoutMs - Kill budget.
26
+ * @returns Its stdout, or undefined.
27
+ */
28
+ export declare function execVersion(command: string, args: readonly string[], timeoutMs: number): Promise<string | undefined>;
@@ -1,3 +1,4 @@
1
+ import { execFile } from 'node:child_process';
1
2
  import { RE_SEMVER } from './constants/core.constants.js';
2
3
  /**
3
4
  * First dotted version (x.y.z) found in CLI output.
@@ -33,3 +34,16 @@ export function meetsMinVersion(version, min) {
33
34
  }
34
35
  return true;
35
36
  }
37
+ /**
38
+ * Run a `--version`-style command, treating any failure as no answer.
39
+ *
40
+ * @param command - Executable.
41
+ * @param args - Its arguments.
42
+ * @param timeoutMs - Kill budget.
43
+ * @returns Its stdout, or undefined.
44
+ */
45
+ export function execVersion(command, args, timeoutMs) {
46
+ return new Promise((resolve) => {
47
+ execFile(command, [...args], { timeout: timeoutMs }, (error, stdout) => resolve(error ? undefined : stdout));
48
+ });
49
+ }
@@ -11,6 +11,17 @@ import type { Env } from './types/core.types.js';
11
11
  * @returns Absolute path of the first match, or undefined when not found.
12
12
  */
13
13
  export declare function findExecutable(env: Env, name: string): string | undefined;
14
+ /**
15
+ * The first of several executable names found on PATH.
16
+ *
17
+ * For an agent that ships under more than one name (editor and CLI, old and
18
+ * new): the names are tried in order, so the preferred one wins.
19
+ *
20
+ * @param env - Environment supplying PATH and the platform.
21
+ * @param names - Executable names without extension, most preferred first.
22
+ * @returns Absolute path of the first match, or undefined when none is found.
23
+ */
24
+ export declare function findFirstExecutable(env: Env, names: readonly string[]): string | undefined;
14
25
  /**
15
26
  * Locate a tool the OS ships, in the OS's own directories only.
16
27
  *
@@ -15,6 +15,24 @@ import { POSIX_EXECUTABLE_MASK, WINDOWS_EXECUTABLE_EXTENSIONS } from './constant
15
15
  export function findExecutable(env, name) {
16
16
  return findIn((env.vars['PATH'] ?? '').split(path.delimiter).filter(Boolean), env.platform, name);
17
17
  }
18
+ /**
19
+ * The first of several executable names found on PATH.
20
+ *
21
+ * For an agent that ships under more than one name (editor and CLI, old and
22
+ * new): the names are tried in order, so the preferred one wins.
23
+ *
24
+ * @param env - Environment supplying PATH and the platform.
25
+ * @param names - Executable names without extension, most preferred first.
26
+ * @returns Absolute path of the first match, or undefined when none is found.
27
+ */
28
+ export function findFirstExecutable(env, names) {
29
+ for (const name of names) {
30
+ const found = findExecutable(env, name);
31
+ if (found)
32
+ return found;
33
+ }
34
+ return undefined;
35
+ }
18
36
  /**
19
37
  * Locate a tool the OS ships, in the OS's own directories only.
20
38
  *
@@ -0,0 +1,32 @@
1
+ import type { Env } from '../core/types/core.types.js';
2
+ /** What a Claude Code cloud VM claims a device with: the managed settings and the session's Claude account. */
3
+ export interface CloudIdentity {
4
+ readonly organizationId: string;
5
+ /** Base64url PKCS8 DER Ed25519 private key. Never printed, logged or written. */
6
+ readonly key: string;
7
+ /** The signed-in Claude account's email; never git's (in a cloud VM that is `noreply@anthropic.com`). */
8
+ readonly email: string;
9
+ }
10
+ /**
11
+ * What the managed settings and the Claude account give this VM to claim with,
12
+ * or the one line that says why it cannot.
13
+ *
14
+ * @param env - Environment and home of this VM.
15
+ * @returns The identity, or the reason to install nothing.
16
+ */
17
+ export declare function cloudIdentity(env: Env): Promise<CloudIdentity | {
18
+ readonly skip: string;
19
+ }>;
20
+ /**
21
+ * The claim text and its Ed25519 signature over the text's exact UTF-8 bytes
22
+ * (the Contract: the gateway verifies the bytes before it parses them, so no
23
+ * one canonicalizes JSON). A fresh nonce every call: the gateway spends each once.
24
+ *
25
+ * @param identity - Organization, key and email.
26
+ * @param now - The time the claim is issued at; the gateway allows ±5 minutes.
27
+ * @returns The claim and signature, or undefined when the key is no Ed25519 private key.
28
+ */
29
+ export declare function signCloudClaim(identity: CloudIdentity, now: Date): {
30
+ readonly claim: string;
31
+ readonly signature: string;
32
+ } | undefined;
@@ -0,0 +1,42 @@
1
+ import { createPrivateKey, randomBytes, sign } from 'node:crypto';
2
+ import { claudeAccountEmail } from '../billing/billing-mode.js';
3
+ import { AGENTWATCH_CLOUD_KEY, AGENTWATCH_CLOUD_ORGANIZATION } from './constants/credentials.constants.js';
4
+ /**
5
+ * What the managed settings and the Claude account give this VM to claim with,
6
+ * or the one line that says why it cannot.
7
+ *
8
+ * @param env - Environment and home of this VM.
9
+ * @returns The identity, or the reason to install nothing.
10
+ */
11
+ export async function cloudIdentity(env) {
12
+ const organizationId = env.vars[AGENTWATCH_CLOUD_ORGANIZATION]?.trim();
13
+ const key = env.vars[AGENTWATCH_CLOUD_KEY]?.trim();
14
+ if (!organizationId || !key)
15
+ return { skip: `no ${AGENTWATCH_CLOUD_ORGANIZATION} or ${AGENTWATCH_CLOUD_KEY} in the managed settings; Agent Watch not installed` };
16
+ const email = await claudeAccountEmail(env.home).catch(() => undefined);
17
+ if (!email)
18
+ return { skip: 'no Claude account email in ~/.claude.json; Agent Watch not installed' };
19
+ return { organizationId, key, email };
20
+ }
21
+ /**
22
+ * The claim text and its Ed25519 signature over the text's exact UTF-8 bytes
23
+ * (the Contract: the gateway verifies the bytes before it parses them, so no
24
+ * one canonicalizes JSON). A fresh nonce every call: the gateway spends each once.
25
+ *
26
+ * @param identity - Organization, key and email.
27
+ * @param now - The time the claim is issued at; the gateway allows ±5 minutes.
28
+ * @returns The claim and signature, or undefined when the key is no Ed25519 private key.
29
+ */
30
+ export function signCloudClaim(identity, now) {
31
+ const claim = JSON.stringify({ v: 1, organizationId: identity.organizationId, email: identity.email, issuedAt: now.toISOString(), nonce: randomBytes(16).toString('base64url') });
32
+ try {
33
+ const key = createPrivateKey({ key: Buffer.from(identity.key, 'base64url'), format: 'der', type: 'pkcs8' });
34
+ if (key.asymmetricKeyType !== 'ed25519')
35
+ return undefined;
36
+ return { claim, signature: sign(null, Buffer.from(claim, 'utf8'), key).toString('base64url') };
37
+ }
38
+ catch {
39
+ // Never the error: it may quote the key.
40
+ return undefined;
41
+ }
42
+ }
@@ -55,6 +55,13 @@ export declare const ENROLLMENT_SESSION_PATH = "/v1/devices/enrollment-sessions"
55
55
  export declare const ENROLLMENT_SESSION_TOKEN_PATH = "/v1/devices/enrollment-sessions/token";
56
56
  /** AWT-275 unattended enrollment: an admin-issued, single-use code in the body. */
57
57
  export declare const ENROLL_CODE_PATH = "/v1/devices/enroll-code";
58
+ /** Cloud claim: a Claude Code cloud VM trades a claim signed with its organization's cloud session key for a device. Public; the signature is the credential. */
59
+ export declare const CLOUD_CLAIM_PATH = "/v1/devices/cloud-claim";
60
+ /** Set to `true` by Claude Code in a cloud session; the only place `setup --cloud` claims a device. */
61
+ export declare const CLAUDE_CODE_REMOTE_VAR = "CLAUDE_CODE_REMOTE";
62
+ /** The managed-settings env names Settings renders (core `AGENTWATCH_CLOUD_ORGANIZATION`, `AGENTWATCH_CLOUD_KEY`): the organization's id and its base64url PKCS8 DER Ed25519 private key. */
63
+ export declare const AGENTWATCH_CLOUD_ORGANIZATION = "AGENTWATCH_CLOUD_ORGANIZATION";
64
+ export declare const AGENTWATCH_CLOUD_KEY = "AGENTWATCH_CLOUD_KEY";
58
65
  /** Recorded on a device enrolled with an admin-issued code, so `status` can say so (core `DeviceCredentialSource.BatchCode`). */
59
66
  export declare const DEVICE_SOURCE_BATCH_CODE = "batch-code";
60
67
  /** The RFC 8628 answers of a poll that are not failures: keep waiting. */
@@ -81,7 +88,7 @@ export declare const REFUSAL_SECRET_EXPIRED = "device_secret_expired";
81
88
  * backend cooldown.
82
89
  */
83
90
  export declare const DEVICE_REFUSALS: ReadonlySet<string>;
84
- /** Every reason the edge acts on, from any route. */
91
+ /** Every reason the edge acts on, from any route. `installation_mismatch` is read so a plain-401 refresh never fires on it. */
85
92
  export declare const KNOWN_REFUSALS: ReadonlySet<string>;
86
93
  /**
87
94
  * The share of the hook's delivery budget credential work may spend: a
@@ -56,6 +56,13 @@ export const ENROLLMENT_SESSION_PATH = '/v1/devices/enrollment-sessions';
56
56
  export const ENROLLMENT_SESSION_TOKEN_PATH = '/v1/devices/enrollment-sessions/token';
57
57
  /** AWT-275 unattended enrollment: an admin-issued, single-use code in the body. */
58
58
  export const ENROLL_CODE_PATH = '/v1/devices/enroll-code';
59
+ /** Cloud claim: a Claude Code cloud VM trades a claim signed with its organization's cloud session key for a device. Public; the signature is the credential. */
60
+ export const CLOUD_CLAIM_PATH = '/v1/devices/cloud-claim';
61
+ /** Set to `true` by Claude Code in a cloud session; the only place `setup --cloud` claims a device. */
62
+ export const CLAUDE_CODE_REMOTE_VAR = 'CLAUDE_CODE_REMOTE';
63
+ /** The managed-settings env names Settings renders (core `AGENTWATCH_CLOUD_ORGANIZATION`, `AGENTWATCH_CLOUD_KEY`): the organization's id and its base64url PKCS8 DER Ed25519 private key. */
64
+ export const AGENTWATCH_CLOUD_ORGANIZATION = 'AGENTWATCH_CLOUD_ORGANIZATION';
65
+ export const AGENTWATCH_CLOUD_KEY = 'AGENTWATCH_CLOUD_KEY';
59
66
  /** Recorded on a device enrolled with an admin-issued code, so `status` can say so (core `DeviceCredentialSource.BatchCode`). */
60
67
  export const DEVICE_SOURCE_BATCH_CODE = 'batch-code';
61
68
  /** The RFC 8628 answers of a poll that are not failures: keep waiting. */
@@ -82,8 +89,8 @@ export const REFUSAL_SECRET_EXPIRED = 'device_secret_expired';
82
89
  * backend cooldown.
83
90
  */
84
91
  export const DEVICE_REFUSALS = new Set([REFUSAL_DEVICE_REVOKED, 'device_unknown', REFUSAL_SECRET_EXPIRED]);
85
- /** Every reason the edge acts on, from any route. */
86
- export const KNOWN_REFUSALS = new Set([REFUSAL_TOKEN_EXPIRED, REFUSAL_INSTALL_KEY_RETIRED, REFUSAL_ENROLLMENT_CODE_INVALID, ...DEVICE_REFUSALS]);
92
+ /** Every reason the edge acts on, from any route. `installation_mismatch` is read so a plain-401 refresh never fires on it. */
93
+ export const KNOWN_REFUSALS = new Set([REFUSAL_TOKEN_EXPIRED, REFUSAL_INSTALL_KEY_RETIRED, REFUSAL_ENROLLMENT_CODE_INVALID, 'installation_mismatch', ...DEVICE_REFUSALS]);
87
94
  /**
88
95
  * The share of the hook's delivery budget credential work may spend: a
89
96
  * keychain read, a refresh or an exchange together. The send gets the rest, so
@@ -1,4 +1,4 @@
1
- import type { DeviceApiResult, EnrollInput, IssuedDeviceCredential, PollSessionInput, RedeemCodeInput, RefreshedAccessToken, RefreshInput, RevokeInput, StartedEnrollmentSession, StartSessionInput } from './types/credentials.types.js';
1
+ import type { DeviceApiResult, DeviceRouteInput, EnrollInput, IssuedDeviceCredential, PollSessionInput, RedeemCodeInput, RefreshedAccessToken, RefreshInput, RevokeInput, StartedEnrollmentSession, StartSessionInput } from './types/credentials.types.js';
2
2
  /**
3
3
  * Trade the install key for a device credential of this machine's own.
4
4
  *
@@ -19,6 +19,20 @@ export declare function enrollDevice(input: EnrollInput): Promise<DeviceApiResul
19
19
  * @returns The credential, or why not (`enrollment_code_invalid` for any code it cannot redeem).
20
20
  */
21
21
  export declare function redeemEnrollmentCode(input: RedeemCodeInput): Promise<DeviceApiResult<IssuedDeviceCredential>>;
22
+ /**
23
+ * Trade a claim signed with the organization's cloud session key for a device
24
+ * of this Claude Code cloud VM's own. Public on the gateway: the signature is
25
+ * the credential. Every refusal is `401 cloud_claim_refused`.
26
+ *
27
+ * @param input - Gateway base URL, the claim text and its signature, installation, machine label, timeout.
28
+ * @returns The credential, or why not.
29
+ */
30
+ export declare function claimCloudDevice(input: DeviceRouteInput & {
31
+ readonly claim: string;
32
+ readonly signature: string;
33
+ readonly installationId: string;
34
+ readonly name: string;
35
+ }): Promise<DeviceApiResult<IssuedDeviceCredential>>;
22
36
  /**
23
37
  * Open a browser sign-in session. Public on the gateway: the organization's id
24
38
  * is all it takes, and no install key travels on this path.
@@ -2,7 +2,7 @@ import { joinUrl } from '../config/config.js';
2
2
  import { asRecord } from '../core/object.js';
3
3
  import { AUTHORIZATION_HEADER, CONTENT_TYPE_HEADER, JSON_CONTENT_TYPE, USER_AGENT, USER_AGENT_HEADER } from '../transport/constants/transport.constants.js';
4
4
  import { discardResponseBody, readCappedJson } from '../transport/response-body.js';
5
- import { ENROLL_CODE_PATH, ENROLL_PATH, ENROLLMENT_SESSION_PATH, ENROLLMENT_SESSION_TOKEN_PATH, KNOWN_REFUSALS, REVOKE_PATH, TOKEN_PATH } from './constants/credentials.constants.js';
5
+ import { CLOUD_CLAIM_PATH, ENROLL_CODE_PATH, ENROLL_PATH, ENROLLMENT_SESSION_PATH, ENROLLMENT_SESSION_TOKEN_PATH, KNOWN_REFUSALS, REVOKE_PATH, TOKEN_PATH } from './constants/credentials.constants.js';
6
6
  import { issuedDeviceCredentialSchema, pollErrorSchema, refreshedAccessTokenSchema, startedEnrollmentSessionSchema } from './schemas/device-api.schema.js';
7
7
  /**
8
8
  * Trade the install key for a device credential of this machine's own.
@@ -28,6 +28,17 @@ export async function enrollDevice(input) {
28
28
  export async function redeemEnrollmentCode(input) {
29
29
  return post(input, ENROLL_CODE_PATH, { code: input.code, installationId: input.installationId, name: input.name }, issuedDeviceCredentialSchema);
30
30
  }
31
+ /**
32
+ * Trade a claim signed with the organization's cloud session key for a device
33
+ * of this Claude Code cloud VM's own. Public on the gateway: the signature is
34
+ * the credential. Every refusal is `401 cloud_claim_refused`.
35
+ *
36
+ * @param input - Gateway base URL, the claim text and its signature, installation, machine label, timeout.
37
+ * @returns The credential, or why not.
38
+ */
39
+ export async function claimCloudDevice(input) {
40
+ return post(input, CLOUD_CLAIM_PATH, { claim: input.claim, signature: input.signature, installationId: input.installationId, name: input.name }, issuedDeviceCredentialSchema);
41
+ }
31
42
  /**
32
43
  * Open a browser sign-in session. Public on the gateway: the organization's id
33
44
  * is all it takes, and no install key travels on this path.
@@ -1,3 +1,4 @@
1
+ import { type CloudIdentity } from './cloud-claim.js';
1
2
  import type { CredentialContext, RedeemCodeInput, SignedIn, SignInInput } from './types/credentials.types.js';
2
3
  /**
3
4
  * Enroll this machine through the browser: show the verification code, wait
@@ -29,3 +30,29 @@ export declare function signInDevice(ctx: CredentialContext, input: SignInInput)
29
30
  export declare function enrollWithCode(ctx: CredentialContext, input: Omit<RedeemCodeInput, 'timeoutMs' | 'fetchFn'>): Promise<SignedIn | {
30
31
  readonly error: string;
31
32
  }>;
33
+ /**
34
+ * Enroll a Claude Code cloud VM with a claim signed by its organization's
35
+ * cloud session key. No install key, no prompt, no code: the signature names
36
+ * the organization and the claim the developer. The credential is kept
37
+ * exactly as a sign-in's is. Never prints the key or the signature.
38
+ *
39
+ * ponytail: the device is stored with no `source` (like a sign-in's), because
40
+ * the config schema only knows `batch-code`; recording `cloud` there is a
41
+ * config.schema.ts change.
42
+ *
43
+ * @param ctx - Paths, environment, timeout, fetch and keychain runner.
44
+ * @param input - Gateway, the managed-settings identity, installation and label.
45
+ * @param input.endpoint - The gateway to claim from.
46
+ * @param input.identity - Organization, key and Claude account email.
47
+ * @param input.installationId - This VM's own installation.
48
+ * @param input.name - The machine label.
49
+ * @returns The device to name in the config and its secret, or the reason there is none.
50
+ */
51
+ export declare function enrollWithCloudClaim(ctx: CredentialContext, input: {
52
+ readonly endpoint: string;
53
+ readonly identity: CloudIdentity;
54
+ readonly installationId: string;
55
+ readonly name: string;
56
+ }): Promise<SignedIn | {
57
+ readonly error: string;
58
+ }>;
@@ -1,7 +1,8 @@
1
1
  import { sleep } from '../core/async.js';
2
2
  import { identityPaths } from '../transport/queue-partition.js';
3
3
  import { DEVICE_SOURCE_BATCH_CODE, POLL_DENIED, POLL_EXPIRED, POLL_PENDING, POLL_SLOW_DOWN, RE_PLAIN_EMAIL, SLOW_DOWN_STEP_MS } from './constants/credentials.constants.js';
4
- import { pollEnrollmentSession, redeemEnrollmentCode, revokeDevice, startEnrollmentSession } from './device-api.js';
4
+ import { signCloudClaim } from './cloud-claim.js';
5
+ import { claimCloudDevice, pollEnrollmentSession, redeemEnrollmentCode, revokeDevice, startEnrollmentSession } from './device-api.js';
5
6
  import { writeAccessToken } from './device-state.js';
6
7
  import { credentialId } from './identity.js';
7
8
  import { saveSecret } from './secret-store.js';
@@ -79,6 +80,35 @@ export async function enrollWithCode(ctx, input) {
79
80
  return { error: `the enrollment code was refused (${redeemed.refusal}): it is unknown, used, expired or revoked; ask your admin for a new one. Nothing was written` };
80
81
  return { error: `could not redeem the enrollment code with ${input.endpoint} (${redeemed.status ?? 'no response'}); nothing was written` };
81
82
  }
83
+ /**
84
+ * Enroll a Claude Code cloud VM with a claim signed by its organization's
85
+ * cloud session key. No install key, no prompt, no code: the signature names
86
+ * the organization and the claim the developer. The credential is kept
87
+ * exactly as a sign-in's is. Never prints the key or the signature.
88
+ *
89
+ * ponytail: the device is stored with no `source` (like a sign-in's), because
90
+ * the config schema only knows `batch-code`; recording `cloud` there is a
91
+ * config.schema.ts change.
92
+ *
93
+ * @param ctx - Paths, environment, timeout, fetch and keychain runner.
94
+ * @param input - Gateway, the managed-settings identity, installation and label.
95
+ * @param input.endpoint - The gateway to claim from.
96
+ * @param input.identity - Organization, key and Claude account email.
97
+ * @param input.installationId - This VM's own installation.
98
+ * @param input.name - The machine label.
99
+ * @returns The device to name in the config and its secret, or the reason there is none.
100
+ */
101
+ export async function enrollWithCloudClaim(ctx, input) {
102
+ const signed = signCloudClaim(input.identity, ctx.env.now());
103
+ if (!signed)
104
+ return { error: 'AGENTWATCH_CLOUD_KEY is not an Ed25519 private key (base64url PKCS8 DER); copy the block from Settings again. Nothing was written' };
105
+ const claimed = await claimCloudDevice({ endpoint: input.endpoint, ...signed, installationId: input.installationId, name: input.name, timeoutMs: ctx.timeoutMs, fetchFn: ctx.fetchFn });
106
+ if (claimed.ok)
107
+ return keep(ctx, input.endpoint, claimed.value);
108
+ if (claimed.status === 401)
109
+ return { error: 'the cloud claim was refused: check the organization id and key in the managed settings, and that the Claude account email is at the organization\'s verified domain. Nothing was written' };
110
+ return { error: `could not claim a cloud device from ${input.endpoint} (${claimed.status ?? 'no response'}); nothing was written, the next session start tries again` };
111
+ }
82
112
  /**
83
113
  * Store an approved credential. The gateway has issued it by now, so a store
84
114
  * that fails is undone on the platform too: nothing would name the device, and
@@ -34,6 +34,10 @@ export declare function cachedAccessToken(ctx: CredentialContext, config: AgentW
34
34
  *
35
35
  * @param ctx - Paths, clock, timeout, deadline, fetch and keychain runner.
36
36
  * @param config - Effective config holding a device credential.
37
+ * @param options - Refresh options.
38
+ * @param options.force - Refresh whatever the cache holds (after a plain 401).
37
39
  * @returns The token, or undefined when there is none to send.
38
40
  */
39
- export declare function currentAccessToken(ctx: CredentialContext, config: AgentWatchConfig): Promise<string | undefined>;
41
+ export declare function currentAccessToken(ctx: CredentialContext, config: AgentWatchConfig, options?: {
42
+ readonly force?: boolean;
43
+ }): Promise<string | undefined>;
@@ -58,9 +58,11 @@ export async function cachedAccessToken(ctx, config) {
58
58
  *
59
59
  * @param ctx - Paths, clock, timeout, deadline, fetch and keychain runner.
60
60
  * @param config - Effective config holding a device credential.
61
+ * @param options - Refresh options.
62
+ * @param options.force - Refresh whatever the cache holds (after a plain 401).
61
63
  * @returns The token, or undefined when there is none to send.
62
64
  */
63
- export async function currentAccessToken(ctx, config) {
65
+ export async function currentAccessToken(ctx, config, options = {}) {
64
66
  const device = config.device;
65
67
  if (!device)
66
68
  return undefined;
@@ -70,7 +72,8 @@ export async function currentAccessToken(ctx, config) {
70
72
  destination ? new BackendAuthBlock(files.authBlockFile, ctx.env.now).active(destination) : undefined,
71
73
  readAccessToken(files.accessTokenFile)
72
74
  ]);
73
- const expired = block?.reason === REFUSAL_TOKEN_EXPIRED;
75
+ // `force` (a plain 401) is handled as an expired token: same lock, cooldown and refusal rules.
76
+ const expired = options.force === true || block?.reason === REFUSAL_TOKEN_EXPIRED;
74
77
  if (cached && !expired && !needsRefresh(cached, ctx.env.now(), ctx.minRemainingMs))
75
78
  return cached.accessToken;
76
79
  const fallback = expired ? undefined : usable(cached, ctx.env.now());
@@ -83,6 +86,11 @@ export async function currentAccessToken(ctx, config) {
83
86
  // `agentwatch refresh-credential` refreshes under the same lock, and this
84
87
  // hook sends what it has (or queues).
85
88
  if (ctx.hookPath && device.store === 'windows-dpapi') {
89
+ // The refresher only refreshes what is due, so a forced refresh drops the
90
+ // cache to make it due. This hook cannot resend: the next send after the
91
+ // block's re-probe goes on the new token.
92
+ if (options.force === true)
93
+ await fs.promises.rm(files.accessTokenFile, { force: true }).catch(() => undefined);
86
94
  await startBackgroundRefresh(ctx, files.deviceStateFile);
87
95
  return fallback;
88
96
  }
@@ -20,9 +20,15 @@ export declare const INTERNAL_HOOK_EVENT_TYPES: readonly ["session.started", "se
20
20
  * `session.billing` states how the session's developer pays, once, when the
21
21
  * session opens: a turn that never reaches its Stop hook has no summary to
22
22
  * carry that fact, and its calls would be priced as metered spend (AWT-476).
23
+ *
24
+ * `repo.tree` is the default branch's source paths and declaration names, once
25
+ * per repository and identity: what a tenant with no GitHub App gets its feature catalog named from.
26
+ *
27
+ * `replay.progress` counts how far a replay of the developer's earlier sessions
28
+ * has got, so the platform can say a history is still arriving. Counts only.
23
29
  */
24
- export declare const PRODUCT_EVENT_TYPES: readonly ["llm.call", "turn.summary", "repo.snapshot", "session.billing"];
25
- export declare const CANONICAL_EVENT_TYPES: readonly ["session.started", "session.ended", "prompt.submitted", "tool.started", "tool.completed", "tool.failed", "permission.requested", "file.read", "file.edited", "shell.started", "shell.completed", "mcp.started", "mcp.completed", "subagent.started", "subagent.completed", "generation.completed", "compaction.started", "compaction.completed", "agent.error", "agent.other", "llm.call", "turn.summary", "repo.snapshot", "session.billing"];
30
+ export declare const PRODUCT_EVENT_TYPES: readonly ["llm.call", "turn.summary", "repo.snapshot", "session.billing", "repo.tree", "replay.progress"];
31
+ export declare const CANONICAL_EVENT_TYPES: readonly ["session.started", "session.ended", "prompt.submitted", "tool.started", "tool.completed", "tool.failed", "permission.requested", "file.read", "file.edited", "shell.started", "shell.completed", "mcp.started", "mcp.completed", "subagent.started", "subagent.completed", "generation.completed", "compaction.started", "compaction.completed", "agent.error", "agent.other", "llm.call", "turn.summary", "repo.snapshot", "session.billing", "repo.tree", "replay.progress"];
26
32
  /** O(1) membership for the hot path: queue drain checks this per entry. */
27
33
  export declare const PRODUCT_EVENT_TYPE_SET: ReadonlySet<string>;
28
34
  /** Canonical event types that close a turn. */
@@ -42,8 +42,14 @@ export const INTERNAL_HOOK_EVENT_TYPES = [
42
42
  * `session.billing` states how the session's developer pays, once, when the
43
43
  * session opens: a turn that never reaches its Stop hook has no summary to
44
44
  * carry that fact, and its calls would be priced as metered spend (AWT-476).
45
+ *
46
+ * `repo.tree` is the default branch's source paths and declaration names, once
47
+ * per repository and identity: what a tenant with no GitHub App gets its feature catalog named from.
48
+ *
49
+ * `replay.progress` counts how far a replay of the developer's earlier sessions
50
+ * has got, so the platform can say a history is still arriving. Counts only.
45
51
  */
46
- export const PRODUCT_EVENT_TYPES = ['llm.call', 'turn.summary', 'repo.snapshot', 'session.billing'];
52
+ export const PRODUCT_EVENT_TYPES = ['llm.call', 'turn.summary', 'repo.snapshot', 'session.billing', 'repo.tree', 'replay.progress'];
47
53
  export const CANONICAL_EVENT_TYPES = [...INTERNAL_HOOK_EVENT_TYPES, ...PRODUCT_EVENT_TYPES];
48
54
  /** O(1) membership for the hot path: queue drain checks this per entry. */
49
55
  export const PRODUCT_EVENT_TYPE_SET = new Set(PRODUCT_EVENT_TYPES);
@@ -5,6 +5,8 @@
5
5
  export type { AgentWatchEvent, CanonicalEventType, ContentEvidence, EventAi, EventGit, EventIdInput, EventPatch, EventSession, EventTool, EventUsage, FeatureCandidate, InternalHookEventType, ProductEventType, UsageBillingMode, UsageSource } from './types/events.types.js';
6
6
  export type { BuildLlmCallInput, LlmCallCorrelation, LlmCallEvent, LlmCallStatus, LlmCallUsage } from './types/llm-call.types.js';
7
7
  export type { RepoSnapshotBranch, RepoSnapshotCommit, RepoSnapshotCommitFile, RepoSnapshotEvent } from './types/repo-snapshot.types.js';
8
+ export type { RepoTreeEvent, RepoTreeFile } from './types/repo-tree.types.js';
9
+ export type { ReplayProgressEvent, ReplayProgressState } from './types/replay-progress.types.js';
8
10
  export type { EnrichOptions, PathRewriter, PathRule } from './types/enrich.types.js';
9
11
  export type { ProductEvent } from './product-event.js';
10
12
  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,24 +1,30 @@
1
1
  import type { TurnSummaryEvent } from '../turns/types/turn-summary.types.js';
2
2
  import type { LlmCallEvent } from './types/llm-call.types.js';
3
3
  import type { RepoSnapshotEvent } from './types/repo-snapshot.types.js';
4
+ import type { RepoTreeEvent } from './types/repo-tree.types.js';
5
+ import type { ReplayProgressEvent, ReplayProgressState } from './types/replay-progress.types.js';
4
6
  import type { SessionBillingEvent } from './types/session-billing.types.js';
5
7
  export { PRODUCT_EVENT_TYPES } from './constants/events.constants.js';
6
8
  export type { ProductEventType } from './types/events.types.js';
7
9
  export type { LlmCallEvent, LlmCallCorrelation, LlmCallStatus } from './types/llm-call.types.js';
8
10
  export type { RepoSnapshotBranch, RepoSnapshotCommit, RepoSnapshotCommitFile, RepoSnapshotEvent } from './types/repo-snapshot.types.js';
11
+ export type { RepoTreeEvent, RepoTreeFile } from './types/repo-tree.types.js';
12
+ export type { ReplayProgressEvent, ReplayProgressState };
9
13
  export type { SessionBillingEvent } from './types/session-billing.types.js';
10
14
  export type { AgentUsageSummary, TurnSummaryEvent, TurnUsageStatus } from '../turns/types/turn-summary.types.js';
11
15
  /**
12
16
  * The complete public AgentWatch domain contract.
13
17
  *
14
- * Four record types, deliberately: `llm.call` is the lossless per-request
18
+ * Six record types, deliberately: `llm.call` is the lossless per-request
15
19
  * usage ledger, `turn.summary` is the human unit of work, `repo.snapshot`
16
- * is what the working copy says the work *is* when no tracker can be asked, and
17
- * `session.billing` is how the session's developer pays. No
20
+ * is what the working copy says the work *is* when no tracker can be asked,
21
+ * `session.billing` is how the session's developer pays, and `repo.tree` is
22
+ * what the trunk's code is called when nothing can clone it, and `replay.progress`
23
+ * counts how far a replay of earlier sessions has got. No
18
24
  * lifecycle or tool event is public — those exist only to assemble a summary
19
25
  * locally.
20
26
  */
21
- export type ProductEvent = LlmCallEvent | TurnSummaryEvent | RepoSnapshotEvent | SessionBillingEvent;
27
+ export type ProductEvent = LlmCallEvent | TurnSummaryEvent | RepoSnapshotEvent | SessionBillingEvent | RepoTreeEvent | ReplayProgressEvent;
22
28
  /** The least a value must look like for {@link isProductEvent} to judge it. */
23
29
  export interface EventTypeCarrier {
24
30
  readonly event?: {
@@ -32,6 +32,10 @@ export interface EventSession {
32
32
  readonly turnId?: string;
33
33
  readonly generationId?: string;
34
34
  readonly agentId?: string;
35
+ /** The agent's mode when the session started, where its start hook names one (Cursor `composer_mode`). */
36
+ readonly mode?: string;
37
+ /** Whether the agent runs the session in the vendor's cloud (Cursor `is_background_agent`). */
38
+ readonly isCloudAgent?: boolean;
35
39
  }
36
40
  export interface EventGit {
37
41
  readonly repository?: string;
@@ -78,6 +82,8 @@ export interface AgentWatchEvent<TType extends CanonicalEventType = CanonicalEve
78
82
  readonly session: EventSession;
79
83
  readonly developer?: {
80
84
  readonly installationId?: string;
85
+ /** The email the agent's own account is signed in as, where its hook names one (Cursor `user_email`). */
86
+ readonly accountEmail?: string;
81
87
  };
82
88
  readonly git?: EventGit;
83
89
  readonly feature?: {