@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
@@ -0,0 +1,35 @@
1
+ import { z } from 'zod';
2
+ /**
3
+ * One spool line. Strip, not passthrough: this schema is the guarantee that a
4
+ * body, a header or a key can never travel, whatever a file under the data dir
5
+ * says, because nothing past it reads anything it does not name.
6
+ */
7
+ export declare const spoolRecordSchema: z.ZodObject<{
8
+ pid: z.ZodNumber;
9
+ started: z.ZodString;
10
+ ancestors: z.ZodArray<z.ZodObject<{
11
+ pid: z.ZodNumber;
12
+ started: z.ZodString;
13
+ }, z.core.$strip>>;
14
+ at: z.ZodString;
15
+ seq: z.ZodNumber;
16
+ script: z.ZodCatch<z.ZodOptional<z.ZodString>>;
17
+ provider: z.ZodEnum<{
18
+ anthropic: "anthropic";
19
+ openai: "openai";
20
+ google: "google";
21
+ vertex: "vertex";
22
+ bedrock: "bedrock";
23
+ }>;
24
+ model: z.ZodOptional<z.ZodString>;
25
+ request_id: z.ZodOptional<z.ZodString>;
26
+ status: z.ZodNumber;
27
+ usage: z.ZodOptional<z.ZodObject<{
28
+ input_tokens: z.ZodOptional<z.ZodNumber>;
29
+ cached_input_tokens: z.ZodOptional<z.ZodNumber>;
30
+ cache_creation_input_tokens: z.ZodOptional<z.ZodNumber>;
31
+ output_tokens: z.ZodOptional<z.ZodNumber>;
32
+ reasoning_output_tokens: z.ZodOptional<z.ZodNumber>;
33
+ total_tokens: z.ZodOptional<z.ZodNumber>;
34
+ }, z.core.$strip>>;
35
+ }, z.core.$strip>;
@@ -0,0 +1,31 @@
1
+ import { z } from 'zod';
2
+ import { MAX_ID_LENGTH } from '../constants/capture.constants.js';
3
+ const tokens = z.number().int().nonnegative().optional();
4
+ /**
5
+ * One spool line. Strip, not passthrough: this schema is the guarantee that a
6
+ * body, a header or a key can never travel, whatever a file under the data dir
7
+ * says, because nothing past it reads anything it does not name.
8
+ */
9
+ export const spoolRecordSchema = z.object({
10
+ pid: z.number().int().positive(),
11
+ started: z.string().min(1).max(64),
12
+ ancestors: z.array(z.object({ pid: z.number().int().positive(), started: z.string().min(1).max(64) })).max(64),
13
+ at: z.string().min(1).max(64),
14
+ seq: z.number().int().nonnegative(),
15
+ /** The file name the process runs: which run it is. Never sent. */
16
+ script: z.string().min(1).max(MAX_ID_LENGTH).optional().catch(undefined),
17
+ provider: z.enum(['anthropic', 'openai', 'google', 'vertex', 'bedrock']),
18
+ model: z.string().min(1).max(MAX_ID_LENGTH).optional(),
19
+ request_id: z.string().min(1).max(MAX_ID_LENGTH).optional(),
20
+ status: z.number().int(),
21
+ usage: z
22
+ .object({
23
+ input_tokens: tokens,
24
+ cached_input_tokens: tokens,
25
+ cache_creation_input_tokens: tokens,
26
+ output_tokens: tokens,
27
+ reasoning_output_tokens: tokens,
28
+ total_tokens: tokens
29
+ })
30
+ .optional()
31
+ });
@@ -0,0 +1,20 @@
1
+ import type { z } from 'zod';
2
+ import type { LlmCallEvent } from '../../events/types/llm-call.types.js';
3
+ import type { spoolRecordSchema } from '../schemas/capture.schema.js';
4
+ /** One line a shim wrote: usage only. Untrusted until the schema has read it. */
5
+ export type SpoolRecord = z.infer<typeof spoolRecordSchema>;
6
+ /** A shell call the session ran: the turn it belongs to and what it is called. */
7
+ export interface LaunchedRun {
8
+ /** The agent that ran it; another agent's hook may be the one to attach its calls. */
9
+ readonly providerId: string;
10
+ readonly surface: string;
11
+ readonly turnId?: string;
12
+ readonly entry: string;
13
+ /** ISO time of the hook before the shell call, which is before the process. */
14
+ readonly at: string;
15
+ }
16
+ /** What the bridge's `llm.call` adds for a captured call; see its `run_entry` comment. */
17
+ export interface CapturedCallEvent extends LlmCallEvent {
18
+ readonly run_entry: string;
19
+ readonly platform?: string;
20
+ }
@@ -6,6 +6,8 @@
6
6
  * entirely.
7
7
  */
8
8
  export declare const VALUE_FLAGS: ReadonlySet<string>;
9
+ /** The commands that take `--agent`; the help names the same three. Any other command refuses it. */
10
+ export declare const AGENT_COMMANDS: ReadonlySet<string>;
9
11
  export declare const FLAG_PREFIX = "--";
10
12
  /** `--enrollment-code -`: read the code from stdin. The only value the flag takes. */
11
13
  export declare const ENROLLMENT_CODE_STDIN = "-";
@@ -42,11 +44,6 @@ export declare const MAX_STDIN_BYTES: number;
42
44
  export declare const STDIN_TIMEOUT_MS = 5000;
43
45
  /** Node major version the runtime requires. */
44
46
  export declare const MIN_NODE_MAJOR = 20;
45
- /**
46
- * prompt_id (== OTel prompt.id) appeared in this Claude Code release; older
47
- * versions fall back to session-scoped turn tracking with an empty turn_id.
48
- */
49
- export declare const CLAUDE_MIN_VERSION_FOR_PROMPT_ID = "2.1.196";
50
47
  /**
51
48
  * Name of the one check an administrator's install script greps for: it carries
52
49
  * all four backend states — accepted, credential rejected, unreachable, and not
@@ -57,7 +54,6 @@ export declare const BACKEND_CONNECTIVITY_CHECK = "backend connectivity";
57
54
  export declare const BACKEND_PROBE_TIMEOUT_MS = 4000;
58
55
  /** What the gateway answers an authenticated `{ events: [] }`: it checks the credential first. */
59
56
  export declare const EMPTY_BATCH_REFUSED_STATUS = 422;
60
- export declare const CLAUDE_VERSION_TIMEOUT_MS = 5000;
61
57
  export declare const GIT_VERSION_TIMEOUT_MS = 2000;
62
58
  /** Longer than the hook path's budget: status is not on anyone's critical path. */
63
59
  export declare const STATUS_SEND_TIMEOUT_MS = 3000;
@@ -5,7 +5,9 @@
5
5
  * itself into a boolean — which is how `--otel none` once ignored the selection
6
6
  * entirely.
7
7
  */
8
- export const VALUE_FLAGS = new Set(['agent', 'endpoint', 'token', 'enrollment-code', 'developer-email', 'developer-name', 'otel', 'root']);
8
+ export const VALUE_FLAGS = new Set(['agent', 'endpoint', 'token', 'enrollment-code', 'developer-email', 'developer-name', 'otel', 'root', 'replay-days']);
9
+ /** The commands that take `--agent`; the help names the same three. Any other command refuses it. */
10
+ export const AGENT_COMMANDS = new Set(['setup', 'uninstall', 'hook']);
9
11
  export const FLAG_PREFIX = '--';
10
12
  /** `--enrollment-code -`: read the code from stdin. The only value the flag takes. */
11
13
  export const ENROLLMENT_CODE_STDIN = '-';
@@ -42,11 +44,6 @@ export const MAX_STDIN_BYTES = 10 * 1024 * 1024;
42
44
  export const STDIN_TIMEOUT_MS = 5_000;
43
45
  /** Node major version the runtime requires. */
44
46
  export const MIN_NODE_MAJOR = 20;
45
- /**
46
- * prompt_id (== OTel prompt.id) appeared in this Claude Code release; older
47
- * versions fall back to session-scoped turn tracking with an empty turn_id.
48
- */
49
- export const CLAUDE_MIN_VERSION_FOR_PROMPT_ID = '2.1.196';
50
47
  /**
51
48
  * Name of the one check an administrator's install script greps for: it carries
52
49
  * all four backend states — accepted, credential rejected, unreachable, and not
@@ -57,7 +54,6 @@ export const BACKEND_CONNECTIVITY_CHECK = 'backend connectivity';
57
54
  export const BACKEND_PROBE_TIMEOUT_MS = 4_000;
58
55
  /** What the gateway answers an authenticated `{ events: [] }`: it checks the credential first. */
59
56
  export const EMPTY_BATCH_REFUSED_STATUS = 422;
60
- export const CLAUDE_VERSION_TIMEOUT_MS = 5_000;
61
57
  export const GIT_VERSION_TIMEOUT_MS = 2_000;
62
58
  /** Longer than the hook path's budget: status is not on anyone's critical path. */
63
59
  export const STATUS_SEND_TIMEOUT_MS = 3_000;
@@ -1,7 +1,6 @@
1
1
  import type { Env } from '../core/types/core.types.js';
2
- import { BackendAuthBlock } from '../transport/auth-block.js';
3
- import { DeliveryStats } from '../transport/delivery-stats.js';
4
- import { EventQueue } from '../transport/queue.js';
2
+ import type { EventQueue } from '../transport/queue.js';
3
+ import type { IdentityDelivery } from '../transport/types/delivery-flow.types.js';
5
4
  import type { EventTransport } from '../transport/types/transport.types.js';
6
5
  import type { CliContext } from './types/cli.types.js';
7
6
  export type { CliContext } from './types/cli.types.js';
@@ -12,9 +11,10 @@ export type { CliContext } from './types/cli.types.js';
12
11
  * commands then work from this value instead of each reaching for the disk.
13
12
  *
14
13
  * @param env - Ambient environment.
14
+ * @param identityAt - A root to select explicitly, null for the machine, or the command cwd when omitted.
15
15
  * @returns The context.
16
16
  */
17
- export declare function buildCliContext(env: Env): Promise<CliContext>;
17
+ export declare function buildCliContext(env: Env, identityAt?: string | null): Promise<CliContext>;
18
18
  /**
19
19
  * The offline queue for this context.
20
20
  *
@@ -28,31 +28,21 @@ export declare function buildCliContext(env: Env): Promise<CliContext>;
28
28
  */
29
29
  export declare function buildQueue(context: CliContext): Promise<EventQueue>;
30
30
  /**
31
- * Open the selected partition without adopting or moving legacy records.
32
- * Setup can inspect ownership and ask for consent without changing the queue.
33
- * @param context - Resolved identity and storage paths.
34
- * @returns A queue handle; construction performs no filesystem writes.
35
- */
36
- export declare function openIdentityQueue(context: CliContext): EventQueue;
37
- /**
38
- * The delivery-loss tally for this context.
39
- *
40
- * @param context - Resolved CLI context.
41
- * @returns The tally.
42
- */
43
- export declare function buildDeliveryStats(context: CliContext): DeliveryStats;
44
- /**
45
- * The standing credential refusal for this context.
31
+ * Open this context's identity delivery state (queue partition, loss tally,
32
+ * cooldown, auth block) without adopting or moving legacy records. Setup can
33
+ * inspect ownership and ask for consent without changing the queue.
46
34
  *
47
- * @param context - Resolved CLI context.
48
- * @returns The block.
35
+ * @param context - Resolved identity and storage paths.
36
+ * @returns The handles; construction performs no filesystem writes.
49
37
  */
50
- export declare function buildAuthBlock(context: CliContext): BackendAuthBlock;
38
+ export declare function openIdentityDelivery(context: CliContext): IdentityDelivery;
51
39
  /**
52
40
  * The transport for this context, when a backend is configured.
53
41
  *
54
42
  * @param context - Resolved CLI context.
55
43
  * @param timeoutMs - Override for the configured send timeout.
44
+ * @param bearer - What to authenticate with, from `resolveContextBearer`; none
45
+ * while a credential exists makes the transport defer every send.
56
46
  * @returns The transport, or undefined before setup has run.
57
47
  */
58
48
  export declare function buildTransport(context: CliContext, timeoutMs?: number, bearer?: string): EventTransport | undefined;
@@ -80,3 +70,10 @@ export declare function resolveContextBearer(context: CliContext, timeoutMs: num
80
70
  * @returns The command line.
81
71
  */
82
72
  export declare function buildHookCommand(env: Env, providerId: string, scriptPath?: string | undefined): string;
73
+ /**
74
+ * Quote a path for embedding in a shell-executed command.
75
+ *
76
+ * @param value - The path.
77
+ * @returns The value, quoted only when it needs to be.
78
+ */
79
+ export declare function quoteArg(value: string): string;
@@ -1,18 +1,15 @@
1
1
  import path from 'node:path';
2
2
  import process from 'node:process';
3
- import { eventsUrl } from '../config/config.js';
4
3
  import { loadConfig } from '../config/config-store.js';
5
4
  import { resolveBearer } from '../credentials/credentials.js';
6
- import { hasCredential, identityOf } from '../credentials/identity.js';
5
+ import { identityOf } from '../credentials/identity.js';
7
6
  import { findExecutable } from '../core/which.js';
8
7
  import { isDisabled } from '../storage/disabled.js';
9
8
  import { loadInstallState } from '../storage/install-state.js';
10
9
  import { resolvePaths } from '../storage/paths.js';
11
- import { BackendAuthBlock } from '../transport/auth-block.js';
12
- import { DeliveryStats } from '../transport/delivery-stats.js';
13
- import { HttpTransport } from '../transport/http-transport.js';
14
- import { EventQueue } from '../transport/queue.js';
15
- import { identityPaths, settleLegacyQueue } from '../transport/queue-partition.js';
10
+ import { transportFor } from '../config/events-transport.js';
11
+ import { identityDelivery } from '../transport/identity-delivery.js';
12
+ import { settleLegacyQueue } from '../transport/queue-partition.js';
16
13
  import { applyRootOverride, credentialScope, servesMultipleIdentities } from '../config/root-config.js';
17
14
  import { RE_NEEDS_QUOTING, RE_QUOTE_ESCAPE } from './constants/cli.constants.js';
18
15
  /**
@@ -22,20 +19,22 @@ import { RE_NEEDS_QUOTING, RE_QUOTE_ESCAPE } from './constants/cli.constants.js'
22
19
  * commands then work from this value instead of each reaching for the disk.
23
20
  *
24
21
  * @param env - Ambient environment.
22
+ * @param identityAt - A root to select explicitly, null for the machine, or the command cwd when omitted.
25
23
  * @returns The context.
26
24
  */
27
- export async function buildCliContext(env) {
25
+ export async function buildCliContext(env, identityAt) {
28
26
  const paths = resolvePaths(env);
29
27
  const configResult = await loadConfig(paths);
30
28
  // Resolved once, here, because every identity-scoped file a command touches is
31
- // named after the token the *hooks in this directory* use. `buildAuthBlock`
32
- // reading the global token was a per-root block nothing could see or lift: a
29
+ // named after the token the *hooks in this directory* use. An auth block opened
30
+ // under the global token was a per-root block nothing could see or lift: a
33
31
  // 401 under a root's own token wrote a block file under that token's
34
32
  // fingerprint, `status` read the global one and printed nothing, and `doctor`
35
33
  // proved the global credential good and cleared a block that was never the
36
34
  // one standing. That root's telemetry stayed suspended with no diagnostic and
37
35
  // no remedy, and a block only ends when a re-probe is accepted.
38
- const rooted = applyRootOverride(configResult.config, env.cwd);
36
+ const { roots: _roots, ...machineConfig } = configResult.config;
37
+ const rooted = identityAt === null ? { config: machineConfig } : applyRootOverride(configResult.config, identityAt ?? env.cwd);
39
38
  const scope = credentialScope(rooted.root);
40
39
  return {
41
40
  env,
@@ -68,48 +67,26 @@ export async function buildQueue(context) {
68
67
  // bearers is a fact about the whole file, and which partition this command
69
68
  // owns is a fact about where it was run.
70
69
  await settleLegacyQueue(context.paths.queueDir, identityOf(context.identityConfig), servesMultipleIdentities(context.config));
71
- return openIdentityQueue(context);
70
+ return openIdentityDelivery(context).queue;
72
71
  }
73
72
  /**
74
- * Open the selected partition without adopting or moving legacy records.
75
- * Setup can inspect ownership and ask for consent without changing the queue.
76
- * @param context - Resolved identity and storage paths.
77
- * @returns A queue handle; construction performs no filesystem writes.
78
- */
79
- export function openIdentityQueue(context) {
80
- return new EventQueue({
81
- queueDir: identityPaths(context.paths, identityOf(context.identityConfig)).queueDir,
82
- locksDir: context.paths.locksDir,
83
- maxEvents: context.identityConfig.delivery.maxQueueEvents,
84
- maxAttempts: context.identityConfig.delivery.maxAttempts,
85
- maxEventAgeDays: context.identityConfig.delivery.maxEventAgeDays,
86
- now: context.env.now,
87
- stats: buildDeliveryStats(context)
88
- });
89
- }
90
- /**
91
- * The delivery-loss tally for this context.
92
- *
93
- * @param context - Resolved CLI context.
94
- * @returns The tally.
95
- */
96
- export function buildDeliveryStats(context) {
97
- return new DeliveryStats(identityPaths(context.paths, identityOf(context.identityConfig)).statsFile, context.env.now, context.paths.locksDir);
98
- }
99
- /**
100
- * The standing credential refusal for this context.
73
+ * Open this context's identity delivery state (queue partition, loss tally,
74
+ * cooldown, auth block) without adopting or moving legacy records. Setup can
75
+ * inspect ownership and ask for consent without changing the queue.
101
76
  *
102
- * @param context - Resolved CLI context.
103
- * @returns The block.
77
+ * @param context - Resolved identity and storage paths.
78
+ * @returns The handles; construction performs no filesystem writes.
104
79
  */
105
- export function buildAuthBlock(context) {
106
- return new BackendAuthBlock(identityPaths(context.paths, identityOf(context.identityConfig)).authBlockFile, context.env.now);
80
+ export function openIdentityDelivery(context) {
81
+ return identityDelivery(context.paths, identityOf(context.identityConfig), context.identityConfig.delivery, context.env.now);
107
82
  }
108
83
  /**
109
84
  * The transport for this context, when a backend is configured.
110
85
  *
111
86
  * @param context - Resolved CLI context.
112
87
  * @param timeoutMs - Override for the configured send timeout.
88
+ * @param bearer - What to authenticate with, from `resolveContextBearer`; none
89
+ * while a credential exists makes the transport defer every send.
113
90
  * @returns The transport, or undefined before setup has run.
114
91
  */
115
92
  export function buildTransport(context, timeoutMs, bearer) {
@@ -117,17 +94,9 @@ export function buildTransport(context, timeoutMs, bearer) {
117
94
  // in this directory present and `status` drains the partition they fill. Only
118
95
  // that credential can prove itself good, and only that proof may lift the
119
96
  // block standing against it.
120
- const url = eventsUrl(context.identityConfig);
121
- if (!url || context.disabled)
97
+ if (context.disabled)
122
98
  return undefined;
123
- return new HttpTransport({
124
- eventsUrl: url,
125
- capture: context.identityConfig.capture,
126
- token: bearer,
127
- credentialPending: hasCredential(context.identityConfig) && !bearer,
128
- installationId: context.identityConfig.installationId,
129
- timeoutMs: timeoutMs ?? context.identityConfig.delivery.timeoutMs
130
- });
99
+ return transportFor(context.identityConfig, bearer, { timeoutMs });
131
100
  }
132
101
  /**
133
102
  * The bearer this directory's hooks send, refreshed or exchanged when due.
@@ -171,7 +140,7 @@ export function buildHookCommand(env, providerId, scriptPath = process.argv[1])
171
140
  * @param value - The path.
172
141
  * @returns The value, quoted only when it needs to be.
173
142
  */
174
- function quoteArg(value) {
143
+ export function quoteArg(value) {
175
144
  if (!RE_NEEDS_QUOTING.test(value))
176
145
  return value;
177
146
  return `"${value.replace(RE_QUOTE_ESCAPE, '\\$1')}"`;
@@ -0,0 +1,13 @@
1
+ import type { AgentProvider, SetupContext } from '../providers/types/provider.types.js';
2
+ import type { Check } from './types/cli.types.js';
3
+ /**
4
+ * Whether one agent's environment route is in place, and what is missing when not.
5
+ *
6
+ * `warn`, never `fail`: unlike the native ledger, the agent's own usage does not depend on
7
+ * it, and an agent with no route yet is not something the developer can fix.
8
+ *
9
+ * @param provider - The agent's provider.
10
+ * @param context - The agent's setup context.
11
+ * @returns The check.
12
+ */
13
+ export declare function runCaptureCheck(provider: AgentProvider, context: SetupContext): Promise<Check>;
@@ -0,0 +1,19 @@
1
+ import { runCaptureRoute } from '../providers/provider.js';
2
+ /**
3
+ * Whether one agent's environment route is in place, and what is missing when not.
4
+ *
5
+ * `warn`, never `fail`: unlike the native ledger, the agent's own usage does not depend on
6
+ * it, and an agent with no route yet is not something the developer can fix.
7
+ *
8
+ * @param provider - The agent's provider.
9
+ * @param context - The agent's setup context.
10
+ * @returns The check.
11
+ */
12
+ export async function runCaptureCheck(provider, context) {
13
+ const name = `${provider.displayName} run capture`;
14
+ const route = runCaptureRoute(provider);
15
+ const status = route ? await route.inspect(context) : { on: false, reason: 'not available for this agent yet' };
16
+ if (!status.on)
17
+ return { name, level: 'warn', detail: `off: ${status.reason ?? 'unknown'}` };
18
+ return status.warning ? { name, level: 'warn', detail: `on: ${status.warning}` } : { name, level: 'ok', detail: 'on' };
19
+ }
@@ -1,4 +1,3 @@
1
- import { execFile } from 'node:child_process';
2
1
  import fs from 'node:fs/promises';
3
2
  import path from 'node:path';
4
3
  import process from 'node:process';
@@ -10,8 +9,7 @@ import { enabledSignalNames, enforcementUrl, eventsUrl, otlpBaseUrl } from '../c
10
9
  import { loadEffectiveConfig } from '../config/repo-config.js';
11
10
  import { storedRetiredCapture } from '../config/config-store.js';
12
11
  import { CONTENT_CAPTURE_KEYS } from '../config/constants/config.constants.js';
13
- import { meetsMinVersion, parseVersion } from '../core/version.js';
14
- import { findExecutable } from '../core/which.js';
12
+ import { execVersion } from '../core/version.js';
15
13
  import { developerDisplayName, developerIdentity } from '../git/git-context.js';
16
14
  import { providers } from '../providers/registry.js';
17
15
  import { removeRefusedExporters } from '../providers/shared/exporter-allowlist.js';
@@ -22,9 +20,10 @@ import { AUTH_REJECTED_STATUSES, CONTENT_TYPE_HEADER, JSON_CONTENT_TYPE } from '
22
20
  import { discardResponseBody } from '../transport/response-body.js';
23
21
  import { edgeHeaders } from '../transport/headers.js';
24
22
  import { DEVICE_SOURCE_BATCH_CODE } from '../credentials/constants/credentials.constants.js';
25
- import { buildAuthBlock, buildCliContext, buildHookCommand, buildQueue, resolveContextBearer } from './context.js';
23
+ import { buildCliContext, buildHookCommand, buildQueue, openIdentityDelivery, resolveContextBearer } from './context.js';
24
+ import { runCaptureCheck } from './doctor-run-capture.js';
26
25
  import { installedHookChecks } from './hook-check.js';
27
- import { BACKEND_CONNECTIVITY_CHECK, BACKEND_PROBE_TIMEOUT_MS, EMPTY_BATCH_REFUSED_STATUS, CLAUDE_MIN_VERSION_FOR_PROMPT_ID, CLAUDE_VERSION_TIMEOUT_MS, DEVELOPER_IDENTITY_CHECK, DEVELOPER_IDENTITY_REMEDIES, DEVELOPER_NAME_REMEDIES, GIT_VERSION_TIMEOUT_MS, MIN_NODE_MAJOR, NO_DEVELOPER_IDENTITY, NO_DEVELOPER_NAME, STALE_QUEUE_AGE_MS } from './constants/cli.constants.js';
26
+ import { BACKEND_CONNECTIVITY_CHECK, BACKEND_PROBE_TIMEOUT_MS, EMPTY_BATCH_REFUSED_STATUS, DEVELOPER_IDENTITY_CHECK, DEVELOPER_IDENTITY_REMEDIES, DEVELOPER_NAME_REMEDIES, GIT_VERSION_TIMEOUT_MS, MIN_NODE_MAJOR, NO_DEVELOPER_IDENTITY, NO_DEVELOPER_NAME, STALE_QUEUE_AGE_MS } from './constants/cli.constants.js';
28
27
  import { bold, customEndpointOverride, dim, levelSymbol, println } from './ui.js';
29
28
  /**
30
29
  * `agentwatch doctor` — every reason telemetry might not be arriving, in one
@@ -385,13 +384,13 @@ async function probeBackend(url, context) {
385
384
  });
386
385
  discardResponseBody(response);
387
386
  if (response.ok) {
388
- await buildAuthBlock(context).clear();
387
+ await openIdentityDelivery(context).authBlock.clear();
389
388
  return { name, level: 'ok', detail: `${url} -> HTTP ${response.status}` };
390
389
  }
391
390
  // The gateway authenticates before it validates the body, and answers an
392
391
  // empty batch 422: the credential passed, only the probe's payload did not.
393
392
  if (response.status === EMPTY_BATCH_REFUSED_STATUS) {
394
- await buildAuthBlock(context).clear();
393
+ await openIdentityDelivery(context).authBlock.clear();
395
394
  return { name, level: 'ok', detail: `${url} -> HTTP ${response.status}: credential accepted (the empty probe batch is refused by design)` };
396
395
  }
397
396
  if (AUTH_REJECTED_STATUSES.has(response.status)) {
@@ -413,7 +412,7 @@ async function gitCheck() {
413
412
  return { name: 'git available', level: version ? 'ok' : 'warn', detail: version?.trim() ?? 'git not found on PATH' };
414
413
  }
415
414
  /**
416
- * Per-agent checks: detected, hooked, and exporting telemetry.
415
+ * Per-agent checks: detected, hooked, exporting telemetry, and loading run capture.
417
416
  *
418
417
  * @param env - Ambient environment.
419
418
  * @param context - Resolved CLI context.
@@ -429,7 +428,7 @@ async function agentChecks(env, context) {
429
428
  continue;
430
429
  }
431
430
  checks.push({ name: `${provider.displayName} detected`, level: 'ok', detail: detection.evidence.join('; ') });
432
- checks.push(...(await providerCaveats(provider, env)));
431
+ checks.push(...(await providerChecks(provider, env)));
433
432
  checks.push({
434
433
  name: `${provider.displayName} hooks`,
435
434
  level: detection.hooksInstalled ? 'ok' : 'warn',
@@ -437,61 +436,24 @@ async function agentChecks(env, context) {
437
436
  });
438
437
  if (provider.nativeTelemetry && !context.disabled)
439
438
  checks.push(await otelCheck(provider, env, context));
439
+ if (!context.disabled)
440
+ checks.push(await runCaptureCheck(provider, { env, paths: context.paths, config: context.identityConfig, hookCommand: buildHookCommand(env, provider.id), installState: context.installState }));
440
441
  }
441
442
  return checks;
442
443
  }
443
444
  /**
444
- * Known limitations of one agent, reported as warnings.
445
+ * What the agent checks about itself, then its known limitations as warnings.
445
446
  *
446
- * These are not misconfigurations the developer can fix; they exist so an
447
+ * Caveats are not misconfigurations the developer can fix; they exist so an
447
448
  * absent number is explained rather than mistaken for a bug in the edge.
448
449
  *
449
450
  * @param provider - The agent's provider.
450
451
  * @param env - Ambient environment.
451
- * @returns The checks, empty for agents with no caveats.
452
+ * @returns The checks, empty for an agent with neither.
452
453
  */
453
- async function providerCaveats(provider, env) {
454
- if (provider.id === 'claude')
455
- return [await claudeVersionCheck(env)];
456
- if (provider.id !== 'cursor')
457
- return [];
458
- return [
459
- {
460
- name: 'Cursor token usage',
461
- level: 'warn',
462
- detail: 'Cursor transcripts carry no token usage yet — Cursor turn summaries stay usage_status=pending until Cursor enriches them'
463
- },
464
- {
465
- name: 'Cursor CLI hooks',
466
- level: 'warn',
467
- detail: 'cursor-agent (CLI) currently emits only shell hook events (known Cursor issue); IDE sessions are fully covered'
468
- }
469
- ];
470
- }
471
- /**
472
- * Whether Claude Code is new enough for prompt-id turn correlation.
473
- *
474
- * @param env - Ambient environment.
475
- * @returns The check.
476
- */
477
- async function claudeVersionCheck(env) {
478
- const name = 'Claude Code version';
479
- const bin = findExecutable(env, 'claude');
480
- if (!bin) {
481
- return { name, level: 'warn', detail: `claude not on PATH; cannot verify >= ${CLAUDE_MIN_VERSION_FOR_PROMPT_ID} (needed for turn correlation)` };
482
- }
483
- const output = await execVersion(bin, ['--version'], CLAUDE_VERSION_TIMEOUT_MS);
484
- const version = output ? parseVersion(output) : undefined;
485
- if (!version) {
486
- return { name, level: 'warn', detail: `could not determine version (need >= ${CLAUDE_MIN_VERSION_FOR_PROMPT_ID} for turn correlation)` };
487
- }
488
- if (meetsMinVersion(version, CLAUDE_MIN_VERSION_FOR_PROMPT_ID))
489
- return { name, level: 'ok', detail: version };
490
- return {
491
- name,
492
- level: 'warn',
493
- detail: `${version} — prompt_id turn correlation needs >= ${CLAUDE_MIN_VERSION_FOR_PROMPT_ID}; turn_id will be empty`
494
- };
454
+ async function providerChecks(provider, env) {
455
+ const caveats = (provider.caveats ?? []).map(({ name, detail }) => ({ name, level: 'warn', detail }));
456
+ return [...((await provider.checks?.(env)) ?? []), ...caveats];
495
457
  }
496
458
  /**
497
459
  * Whether one agent's native telemetry is configured.
@@ -680,19 +642,6 @@ async function newestMtime(dir) {
680
642
  }
681
643
  return newest;
682
644
  }
683
- /**
684
- * Run a `--version`-style command, treating any failure as no answer.
685
- *
686
- * @param command - Executable.
687
- * @param args - Its arguments.
688
- * @param timeoutMs - Kill budget.
689
- * @returns Its stdout, or undefined.
690
- */
691
- function execVersion(command, args, timeoutMs) {
692
- return new Promise((resolve) => {
693
- execFile(command, [...args], { timeout: timeoutMs }, (error, stdout) => resolve(error ? undefined : stdout));
694
- });
695
- }
696
645
  /**
697
646
  * The process exit code for a set of checks.
698
647
  *
@@ -18,3 +18,17 @@ export type { HookRunOptions } from './types/cli.types.js';
18
18
  * @returns The process exit code; always one the agent tolerates.
19
19
  */
20
20
  export declare function runHook(agentId: string, options: HookRunOptions): Promise<number>;
21
+ /**
22
+ * Start `agentwatch hook --agent <id> --attached` detached, with the payload on
23
+ * its stdin, so it outlives this process and the agent that started it.
24
+ *
25
+ * Only from the built CLI: run from source there is nothing to start, and the
26
+ * caller processes the payload in place. A spawn or pipe that fails does the
27
+ * same; at worst the turn is processed twice, and its summary id is derived
28
+ * from its inputs, so the second copy is a duplicate the backend drops.
29
+ *
30
+ * @param agentId - Value of `--agent`.
31
+ * @param input - The payload, as JSON text.
32
+ * @returns True when the child took the payload.
33
+ */
34
+ export declare function handOffDetached(agentId: string, input: string): Promise<boolean>;
package/dist/cli/hook.js CHANGED
@@ -1,5 +1,8 @@
1
+ import { spawn } from 'node:child_process';
2
+ import fs from 'node:fs';
1
3
  import path from 'node:path';
2
4
  import process from 'node:process';
5
+ import { fileURLToPath } from 'node:url';
3
6
  import { loadConfig } from '../config/config-store.js';
4
7
  import { notLongerThan } from '../core/async.js';
5
8
  import { debugLog, warnLog } from '../core/logger.js';
@@ -52,6 +55,11 @@ export async function runHook(agentId, options) {
52
55
  writeStdout(options, idle.stdout);
53
56
  return idle.exitCode;
54
57
  }
58
+ // A turn's close answers nothing, so the agent need not wait for its send:
59
+ // a detached process does the work and outlives this one.
60
+ if (payload !== undefined && options.handOff && provider.runsDetached?.(payload, options.env) && (await options.handOff(agentId, JSON.stringify(payload)))) {
61
+ return provider.getHookResponse(payload).exitCode;
62
+ }
55
63
  const result = payload === undefined ? undefined : await processPayload(provider, payload, options);
56
64
  const response = respondToDecision(provider, payload, result);
57
65
  if (response.stdout)
@@ -67,6 +75,38 @@ export async function runHook(agentId, options) {
67
75
  return answerSafely(provider, payload, options);
68
76
  }
69
77
  }
78
+ /**
79
+ * Start `agentwatch hook --agent <id> --attached` detached, with the payload on
80
+ * its stdin, so it outlives this process and the agent that started it.
81
+ *
82
+ * Only from the built CLI: run from source there is nothing to start, and the
83
+ * caller processes the payload in place. A spawn or pipe that fails does the
84
+ * same; at worst the turn is processed twice, and its summary id is derived
85
+ * from its inputs, so the second copy is a duplicate the backend drops.
86
+ *
87
+ * @param agentId - Value of `--agent`.
88
+ * @param input - The payload, as JSON text.
89
+ * @returns True when the child took the payload.
90
+ */
91
+ export function handOffDetached(agentId, input) {
92
+ const cli = fileURLToPath(new URL('../cli.js', import.meta.url));
93
+ if (!fs.existsSync(cli))
94
+ return Promise.resolve(false);
95
+ return new Promise((resolve) => {
96
+ try {
97
+ const child = spawn(process.execPath, [cli, 'hook', '--agent', agentId, '--attached'], { detached: true, stdio: ['pipe', 'ignore', 'ignore'], windowsHide: true });
98
+ child.on('error', () => resolve(false));
99
+ child.stdin.on('error', () => resolve(false));
100
+ // The callback carries a pipe error (EPIPE from a child that died at start): then it did not take the payload.
101
+ child.stdin.end(input, (error) => resolve(!error));
102
+ child.unref();
103
+ }
104
+ catch (error) {
105
+ debugLog('hook hand-off failed; processing in place:', error);
106
+ resolve(false);
107
+ }
108
+ });
109
+ }
70
110
  /**
71
111
  * Last-resort answer after something in the flow threw.
72
112
  *
@@ -4,7 +4,7 @@
4
4
  */
5
5
  export type { Check, CheckLevel, CliContext, HookRunOptions, ParsedArgs, SetupOptions, UninstallOptions } from './types/cli.types.js';
6
6
  export { boolFlag, parseArgs, stringFlag } from './args.js';
7
- export { buildCliContext, buildDeliveryStats, buildHookCommand, buildQueue, buildTransport, openIdentityQueue } from './context.js';
7
+ export { buildCliContext, buildHookCommand, buildQueue, buildTransport, openIdentityDelivery } from './context.js';
8
8
  export { runHook } from './hook.js';
9
9
  export { runSetup } from './setup.js';
10
10
  export { runStatus } from './status.js';
package/dist/cli/index.js CHANGED
@@ -1,5 +1,5 @@
1
1
  export { boolFlag, parseArgs, stringFlag } from './args.js';
2
- export { buildCliContext, buildDeliveryStats, buildHookCommand, buildQueue, buildTransport, openIdentityQueue } from './context.js';
2
+ export { buildCliContext, buildHookCommand, buildQueue, buildTransport, openIdentityDelivery } from './context.js';
3
3
  export { runHook } from './hook.js';
4
4
  export { runSetup } from './setup.js';
5
5
  export { runStatus } from './status.js';