@agent-watch-ai/edge 0.7.1 → 0.7.3

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 (56) hide show
  1. package/CHANGELOG.md +29 -0
  2. package/README.md +2 -1
  3. package/dist/capture/capture-env.d.ts +3 -3
  4. package/dist/capture/capture-env.js +5 -5
  5. package/dist/capture/captured-step.js +1 -1
  6. package/dist/cli/constants/cli.constants.js +1 -1
  7. package/dist/cli/setup.js +26 -3
  8. package/dist/cli/types/cli.types.d.ts +2 -0
  9. package/dist/cli/uninstall.js +1 -1
  10. package/dist/cli.js +7 -4
  11. package/dist/config/config.d.ts +8 -0
  12. package/dist/config/config.js +10 -0
  13. package/dist/config/constants/config.constants.d.ts +5 -0
  14. package/dist/config/constants/config.constants.js +5 -0
  15. package/dist/config/repo-config.js +7 -2
  16. package/dist/config/schemas/config.schema.d.ts +4 -0
  17. package/dist/config/schemas/config.schema.js +7 -1
  18. package/dist/enrollment/enrollment.js +7 -4
  19. package/dist/pipeline/hook-pipeline.js +3 -1
  20. package/dist/providers/antigravity/antigravity.adapter.d.ts +14 -0
  21. package/dist/providers/antigravity/antigravity.adapter.js +86 -18
  22. package/dist/providers/antigravity/antigravity.provider.js +7 -4
  23. package/dist/providers/antigravity/constants/antigravity.constants.d.ts +10 -0
  24. package/dist/providers/antigravity/constants/antigravity.constants.js +10 -0
  25. package/dist/providers/antigravity/schemas/antigravity.schema.js +7 -13
  26. package/dist/providers/claude/claude.otel.d.ts +33 -1
  27. package/dist/providers/claude/claude.otel.js +81 -12
  28. package/dist/providers/claude/claude.provider.js +3 -1
  29. package/dist/providers/codex/codex.capture.d.ts +1 -1
  30. package/dist/providers/codex/codex.capture.js +3 -3
  31. package/dist/providers/codex/codex.otel.js +2 -2
  32. package/dist/providers/codex/codex.provider.js +2 -1
  33. package/dist/providers/gemini/gemini.capture.js +2 -2
  34. package/dist/providers/gemini/gemini.otel.js +2 -2
  35. package/dist/providers/gemini/gemini.provider.js +2 -1
  36. package/dist/providers/shared/terminal-capture.js +3 -3
  37. package/dist/turns/antigravity-transcript.d.ts +40 -0
  38. package/dist/turns/antigravity-transcript.js +102 -0
  39. package/dist/turns/claude-transcript.d.ts +35 -1
  40. package/dist/turns/claude-transcript.js +185 -2
  41. package/dist/turns/codex-transcript.d.ts +22 -1
  42. package/dist/turns/codex-transcript.js +161 -2
  43. package/dist/turns/constants/turns.constants.d.ts +51 -0
  44. package/dist/turns/constants/turns.constants.js +51 -0
  45. package/dist/turns/gemini-transcript.d.ts +17 -1
  46. package/dist/turns/gemini-transcript.js +36 -2
  47. package/dist/turns/transcript.d.ts +31 -1
  48. package/dist/turns/transcript.js +74 -0
  49. package/dist/turns/turn-state.d.ts +18 -1
  50. package/dist/turns/turn-state.js +45 -10
  51. package/dist/turns/turn-tracker.js +154 -16
  52. package/dist/turns/types/transcript.types.d.ts +25 -0
  53. package/dist/turns/types/turn-provider.types.d.ts +18 -1
  54. package/dist/turns/types/turn-state.types.d.ts +10 -0
  55. package/docs/DATA_HANDLING.md +3 -0
  56. package/package.json +1 -1
@@ -35,6 +35,26 @@ export declare const USAGE_RETRY: ReadTurnUsageRetry;
35
35
  * parsing tens of megabytes each pass would be pure waste on long sessions.
36
36
  */
37
37
  export declare const TRANSCRIPT_TAIL_BYTES: number;
38
+ /** Claude Code's folder of subagent transcripts, beside the session's own (`<session>/subagents/`). */
39
+ export declare const CLAUDE_SUBAGENTS_DIR = "subagents";
40
+ /** Claude Code names a subagent's transcript `agent-<agentId>.jsonl`. */
41
+ export declare const RE_CLAUDE_SUBAGENT_FILE: RegExp;
42
+ /**
43
+ * A prompt id as a Claude Code user line states it. Assistant lines say
44
+ * `"promptId":null`, and one quoted inside message content is escaped, so
45
+ * neither matches.
46
+ */
47
+ export declare const RE_CLAUDE_PROMPT_ID: RegExp;
48
+ /**
49
+ * How far back before a subagent transcript's tail to look for the prompt its
50
+ * first tail lines ran under, in chunks, overlapping so a match split across
51
+ * two chunks is still seen.
52
+ */
53
+ export declare const PROMPT_SEED_SCAN_BYTES: number;
54
+ export declare const PROMPT_SEED_CHUNK_BYTES: number;
55
+ export declare const PROMPT_SEED_OVERLAP_BYTES = 256;
56
+ /** An agent id safe to put in a file name: no separators, no dots. */
57
+ export declare const RE_CLAUDE_AGENT_ID: RegExp;
38
58
  /** Payload key every supported agent reports its transcript path under. */
39
59
  export declare const TRANSCRIPT_PATH_KEY = "transcript_path";
40
60
  /** Marker of a closed turn; no `.json`, so it is never read as a record (AWT-701). */
@@ -55,6 +75,11 @@ export declare const SESSION_ENDED_FILE = "session-ended";
55
75
  * must not keep the state from clearing.
56
76
  */
57
77
  export declare const DETACHED_CLOSE_MAX_AGE_MS = 60000;
78
+ /**
79
+ * The summary a turn closed with, kept so a background subagent finishing later
80
+ * can re-send it with its usage added. No `.json`, so it is never read as a record.
81
+ */
82
+ export declare const SENT_TURN_PREFIX = "sent-turn--";
58
83
  /** Prefix distinguishing usage-claim files from turn records in a session dir. */
59
84
  export declare const USAGE_CLAIM_PREFIX = "usage-claim--";
60
85
  /**
@@ -214,12 +239,38 @@ export declare const TRANSCRIPT_CACHE_READ_TOKENS = "cache_read_input_tokens";
214
239
  export declare const TRANSCRIPT_CACHE_CREATION_TOKENS = "cache_creation_input_tokens";
215
240
  /** Codex rollout rows the usage reader needs; every other row is skipped unparsed. */
216
241
  export declare const CODEX_TOKEN_COUNT = "token_count";
242
+ /** A Codex rollout's file name; a child thread's is one too, in the same day folders. */
243
+ export declare const RE_CODEX_ROLLOUT: RegExp;
244
+ /** How many spawn levels a descendant is followed up; Codex reports `depth` 1 for a direct child. */
245
+ export declare const CODEX_MAX_SPAWN_DEPTH = 8;
246
+ /** How many day folders, back from today, a session's descendants are looked for in. */
247
+ export declare const CODEX_MAX_SCAN_DAYS = 7;
248
+ export declare const DAY_MS: number;
249
+ /** How much of a rollout's head to read for its `session_meta` line (about 20 KB, 2026-11). */
250
+ export declare const CODEX_META_HEAD_BYTES: number;
251
+ /** Gemini CLI 0.46 writes a subagent's chat to `chats/<parent session id>/<agent id>.jsonl`. */
252
+ export declare const RE_GEMINI_CHAT_FILE: RegExp;
217
253
  export declare const CODEX_TURN_CONTEXT = "turn_context";
218
254
  export declare const CODEX_LAST_TOKEN_USAGE = "last_token_usage";
219
255
  export declare const CODEX_CACHED_INPUT_TOKENS = "cached_input_tokens";
220
256
  /** Gemini CLI chat-file row type that carries a model reply, and its usage block. */
221
257
  export declare const GEMINI_REPLY_TYPE = "gemini";
222
258
  export declare const GEMINI_TOKENS = "tokens";
259
+ /**
260
+ * Antigravity transcript (`brain/<conversationId>/.system_generated/logs/transcript_full.jsonl`)
261
+ * model-step fields. Its counts are disjoint: `input_tokens` excludes
262
+ * `cache_read_tokens` (an 11-04 IDE transcript's input drops 16896 -> 3374 as
263
+ * 14865 cache reads appear), so they map onto the Anthropic-style fields as is.
264
+ */
265
+ export declare const ANTIGRAVITY_MODEL_SOURCE = "MODEL";
266
+ export declare const ANTIGRAVITY_INPUT_TOKENS = "input_tokens";
267
+ export declare const ANTIGRAVITY_OUTPUT_TOKENS = "output_tokens";
268
+ export declare const ANTIGRAVITY_CACHE_READ_TOKENS = "cache_read_tokens";
269
+ /** The count fields; a transcript line with none of them is skipped unparsed. */
270
+ export declare const ANTIGRAVITY_COUNT_FIELDS: readonly ["input_tokens", "output_tokens", "cache_read_tokens"];
271
+ export declare const ANTIGRAVITY_STEP_ID_PREFIX = "step-";
272
+ /** Antigravity's `created_at` has whole-second precision. */
273
+ export declare const ANTIGRAVITY_TIMESTAMP_RESOLUTION_MS = 1000;
223
274
  /** Every transcript token field, for weighting which model dominated a turn. */
224
275
  export declare const TRANSCRIPT_TOKEN_FIELDS: readonly ["input_tokens", "output_tokens", "cache_read_input_tokens", "cache_creation_input_tokens"];
225
276
  /** Prefix for the content-hash id given to a transcript entry without one. */
@@ -41,6 +41,26 @@ export const USAGE_RETRY = { attempts: 6, delayMs: 250, minSettleMs: 500 };
41
41
  * parsing tens of megabytes each pass would be pure waste on long sessions.
42
42
  */
43
43
  export const TRANSCRIPT_TAIL_BYTES = 4 * 1024 * 1024;
44
+ /** Claude Code's folder of subagent transcripts, beside the session's own (`<session>/subagents/`). */
45
+ export const CLAUDE_SUBAGENTS_DIR = 'subagents';
46
+ /** Claude Code names a subagent's transcript `agent-<agentId>.jsonl`. */
47
+ export const RE_CLAUDE_SUBAGENT_FILE = /^agent-[A-Za-z0-9_-]+\.jsonl$/;
48
+ /**
49
+ * A prompt id as a Claude Code user line states it. Assistant lines say
50
+ * `"promptId":null`, and one quoted inside message content is escaped, so
51
+ * neither matches.
52
+ */
53
+ export const RE_CLAUDE_PROMPT_ID = /"promptId":"([0-9A-Za-z-]+)"/g;
54
+ /**
55
+ * How far back before a subagent transcript's tail to look for the prompt its
56
+ * first tail lines ran under, in chunks, overlapping so a match split across
57
+ * two chunks is still seen.
58
+ */
59
+ export const PROMPT_SEED_SCAN_BYTES = 16 * 1024 * 1024;
60
+ export const PROMPT_SEED_CHUNK_BYTES = 1024 * 1024;
61
+ export const PROMPT_SEED_OVERLAP_BYTES = 256;
62
+ /** An agent id safe to put in a file name: no separators, no dots. */
63
+ export const RE_CLAUDE_AGENT_ID = /^[A-Za-z0-9_-]+$/;
44
64
  /** Payload key every supported agent reports its transcript path under. */
45
65
  export const TRANSCRIPT_PATH_KEY = 'transcript_path';
46
66
  /** Marker of a closed turn; no `.json`, so it is never read as a record (AWT-701). */
@@ -61,6 +81,11 @@ export const SESSION_ENDED_FILE = 'session-ended';
61
81
  * must not keep the state from clearing.
62
82
  */
63
83
  export const DETACHED_CLOSE_MAX_AGE_MS = 60_000;
84
+ /**
85
+ * The summary a turn closed with, kept so a background subagent finishing later
86
+ * can re-send it with its usage added. No `.json`, so it is never read as a record.
87
+ */
88
+ export const SENT_TURN_PREFIX = 'sent-turn--';
64
89
  /** Prefix distinguishing usage-claim files from turn records in a session dir. */
65
90
  export const USAGE_CLAIM_PREFIX = 'usage-claim--';
66
91
  /**
@@ -230,12 +255,38 @@ export const TRANSCRIPT_CACHE_READ_TOKENS = 'cache_read_input_tokens';
230
255
  export const TRANSCRIPT_CACHE_CREATION_TOKENS = 'cache_creation_input_tokens';
231
256
  /** Codex rollout rows the usage reader needs; every other row is skipped unparsed. */
232
257
  export const CODEX_TOKEN_COUNT = 'token_count';
258
+ /** A Codex rollout's file name; a child thread's is one too, in the same day folders. */
259
+ export const RE_CODEX_ROLLOUT = /^rollout-.+-([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})\.jsonl$/;
260
+ /** How many spawn levels a descendant is followed up; Codex reports `depth` 1 for a direct child. */
261
+ export const CODEX_MAX_SPAWN_DEPTH = 8;
262
+ /** How many day folders, back from today, a session's descendants are looked for in. */
263
+ export const CODEX_MAX_SCAN_DAYS = 7;
264
+ export const DAY_MS = 24 * 60 * 60 * 1000;
265
+ /** How much of a rollout's head to read for its `session_meta` line (about 20 KB, 2026-11). */
266
+ export const CODEX_META_HEAD_BYTES = 64 * 1024;
267
+ /** Gemini CLI 0.46 writes a subagent's chat to `chats/<parent session id>/<agent id>.jsonl`. */
268
+ export const RE_GEMINI_CHAT_FILE = /^[^/]+\.jsonl$/;
233
269
  export const CODEX_TURN_CONTEXT = 'turn_context';
234
270
  export const CODEX_LAST_TOKEN_USAGE = 'last_token_usage';
235
271
  export const CODEX_CACHED_INPUT_TOKENS = 'cached_input_tokens';
236
272
  /** Gemini CLI chat-file row type that carries a model reply, and its usage block. */
237
273
  export const GEMINI_REPLY_TYPE = 'gemini';
238
274
  export const GEMINI_TOKENS = 'tokens';
275
+ /**
276
+ * Antigravity transcript (`brain/<conversationId>/.system_generated/logs/transcript_full.jsonl`)
277
+ * model-step fields. Its counts are disjoint: `input_tokens` excludes
278
+ * `cache_read_tokens` (an 11-04 IDE transcript's input drops 16896 -> 3374 as
279
+ * 14865 cache reads appear), so they map onto the Anthropic-style fields as is.
280
+ */
281
+ export const ANTIGRAVITY_MODEL_SOURCE = 'MODEL';
282
+ export const ANTIGRAVITY_INPUT_TOKENS = 'input_tokens';
283
+ export const ANTIGRAVITY_OUTPUT_TOKENS = 'output_tokens';
284
+ export const ANTIGRAVITY_CACHE_READ_TOKENS = 'cache_read_tokens';
285
+ /** The count fields; a transcript line with none of them is skipped unparsed. */
286
+ export const ANTIGRAVITY_COUNT_FIELDS = [ANTIGRAVITY_INPUT_TOKENS, ANTIGRAVITY_OUTPUT_TOKENS, ANTIGRAVITY_CACHE_READ_TOKENS];
287
+ export const ANTIGRAVITY_STEP_ID_PREFIX = 'step-';
288
+ /** Antigravity's `created_at` has whole-second precision. */
289
+ export const ANTIGRAVITY_TIMESTAMP_RESOLUTION_MS = 1000;
239
290
  /** Every transcript token field, for weighting which model dominated a turn. */
240
291
  export const TRANSCRIPT_TOKEN_FIELDS = [
241
292
  TRANSCRIPT_INPUT_TOKENS,
@@ -1,4 +1,4 @@
1
- import type { ReadTurnUsageRetry, TranscriptUsageEntry, TurnUsage } from './types/transcript.types.js';
1
+ import type { ReadTurnUsageRetry, SubagentTurn, TranscriptUsageEntry, TurnUsage } from './types/transcript.types.js';
2
2
  /**
3
3
  * Per-turn token usage from a Gemini CLI chat file
4
4
  * (`~/.gemini/tmp/<project>/chats/session-*.jsonl`).
@@ -28,6 +28,22 @@ import type { ReadTurnUsageRetry, TranscriptUsageEntry, TurnUsage } from './type
28
28
  * @returns The turn's usage, or undefined when the file reports none.
29
29
  */
30
30
  export declare function readGeminiTurnUsage(transcriptPath: string, sinceIso: string, retry?: ReadTurnUsageRetry, untilIso?: string, excludeMessageIds?: ReadonlySet<string>): Promise<TurnUsage | undefined>;
31
+ /**
32
+ * The usage of the session's subagents inside the turn's window, out of their
33
+ * own chat files.
34
+ *
35
+ * Gemini CLI 0.46 writes a subagent's chat to `chats/<session id>/<agent
36
+ * id>.jsonl`, beside the session's own chat file, and fires no hook for it. Its
37
+ * rows carry no prompt id, so they join the turn by window, read the way the
38
+ * session's own file is. Not seen on a real machine yet (2026-11): written from
39
+ * the 0.46 source layout and checked against a fixture. Never throws.
40
+ *
41
+ * @param payload - The raw hook payload, naming the session's chat file and id.
42
+ * @param turn - The turn's window.
43
+ * @param excludeMessageIds - Replies already claimed.
44
+ * @returns The subagents' usage in the window, or undefined when there is none.
45
+ */
46
+ export declare function readGeminiSubagentUsage(payload: unknown, turn: SubagentTurn, excludeMessageIds: ReadonlySet<string>): Promise<TurnUsage | undefined>;
31
47
  /**
32
48
  * The usage one chat-file record carries, when it is a reply with `tokens`.
33
49
  *
@@ -1,7 +1,8 @@
1
+ import path from 'node:path';
1
2
  import { asRecord, firstStringOf } from '../core/object.js';
2
3
  import { finiteOrZero } from '../core/number.js';
3
- import { accumulateUsage, parseJsonLine, readUntilSettled, readWindowedTail } from './transcript.js';
4
- import { GEMINI_REPLY_TYPE, GEMINI_TOKENS, TRANSCRIPT_CACHE_READ_TOKENS, TRANSCRIPT_INPUT_TOKENS, TRANSCRIPT_OUTPUT_TOKENS } from './constants/turns.constants.js';
4
+ import { accumulateUsage, filesWrittenSince, mergeUsage, parseJsonLine, readUntilSettled, readWindowedTail } from './transcript.js';
5
+ import { RE_GEMINI_CHAT_FILE, TRANSCRIPT_PATH_KEY, GEMINI_REPLY_TYPE, GEMINI_TOKENS, TRANSCRIPT_CACHE_READ_TOKENS, TRANSCRIPT_INPUT_TOKENS, TRANSCRIPT_OUTPUT_TOKENS } from './constants/turns.constants.js';
5
6
  /**
6
7
  * Per-turn token usage from a Gemini CLI chat file
7
8
  * (`~/.gemini/tmp/<project>/chats/session-*.jsonl`).
@@ -65,6 +66,39 @@ async function readOnce(transcriptPath, sinceIso, untilIso, excludeMessageIds) {
65
66
  }
66
67
  return accumulateUsage(byId);
67
68
  }
69
+ /**
70
+ * The usage of the session's subagents inside the turn's window, out of their
71
+ * own chat files.
72
+ *
73
+ * Gemini CLI 0.46 writes a subagent's chat to `chats/<session id>/<agent
74
+ * id>.jsonl`, beside the session's own chat file, and fires no hook for it. Its
75
+ * rows carry no prompt id, so they join the turn by window, read the way the
76
+ * session's own file is. Not seen on a real machine yet (2026-11): written from
77
+ * the 0.46 source layout and checked against a fixture. Never throws.
78
+ *
79
+ * @param payload - The raw hook payload, naming the session's chat file and id.
80
+ * @param turn - The turn's window.
81
+ * @param excludeMessageIds - Replies already claimed.
82
+ * @returns The subagents' usage in the window, or undefined when there is none.
83
+ */
84
+ export async function readGeminiSubagentUsage(payload, turn, excludeMessageIds) {
85
+ const record = asRecord(payload);
86
+ const transcriptPath = record?.[TRANSCRIPT_PATH_KEY];
87
+ const sessionId = record?.['session_id'];
88
+ // The session id becomes a folder name: one path segment, nothing more.
89
+ if (typeof transcriptPath !== 'string' || typeof sessionId !== 'string' || !sessionId || path.basename(sessionId) !== sessionId || sessionId.startsWith('.'))
90
+ return undefined;
91
+ try {
92
+ let usage;
93
+ for (const file of await filesWrittenSince(path.join(path.dirname(transcriptPath), sessionId), RE_GEMINI_CHAT_FILE, Date.parse(turn.startedAt))) {
94
+ usage = mergeUsage(usage, await readOnce(file, turn.startedAt, turn.untilIso, excludeMessageIds));
95
+ }
96
+ return usage;
97
+ }
98
+ catch {
99
+ return undefined;
100
+ }
101
+ }
68
102
  /**
69
103
  * The usage one chat-file record carries, when it is a reply with `tokens`.
70
104
  *
@@ -1,4 +1,4 @@
1
- import type { ReadTurnUsageRetry, TranscriptUsageEntry, TurnUsage, WindowedTail } from './types/transcript.types.js';
1
+ import type { ReadTurnUsageRetry, TailSnapshot, TranscriptUsageEntry, TurnUsage, WindowedTail } from './types/transcript.types.js';
2
2
  /** One read pass over a transcript. */
3
3
  type TranscriptPass = () => Promise<TurnUsage | undefined>;
4
4
  /**
@@ -26,6 +26,16 @@ export declare function readUntilSettled(pass: TranscriptPass, retry?: ReadTurnU
26
26
  * @returns The tail text, or undefined when the file cannot be read.
27
27
  */
28
28
  export declare function readTranscriptTail(transcriptPath: string): Promise<string | undefined>;
29
+ /**
30
+ * A transcript's tail as of one size, and the byte offset it starts at.
31
+ *
32
+ * One `stat` for both: a file still being appended to gives the tail and a
33
+ * read of what precedes it the same cut, so nothing falls between them.
34
+ *
35
+ * @param file - Transcript file.
36
+ * @returns The tail (partial first line dropped) and where it starts, or undefined when the file cannot be read.
37
+ */
38
+ export declare function readTailSnapshot(file: string): Promise<TailSnapshot | undefined>;
29
39
  /**
30
40
  * A transcript tail with its turn window parsed: the start of every usage pass.
31
41
  *
@@ -39,6 +49,16 @@ export declare function readTranscriptTail(transcriptPath: string): Promise<stri
39
49
  * @returns The tail and both bounds, or undefined when a bound is not a date or the file cannot be read.
40
50
  */
41
51
  export declare function readWindowedTail(transcriptPath: string, sinceIso: string, untilIso?: string): Promise<WindowedTail | undefined>;
52
+ /**
53
+ * The files in one folder whose names pass a test and that were written at or
54
+ * after a moment: the subagent transcripts a turn may hold usage in.
55
+ *
56
+ * @param dir - The folder.
57
+ * @param name - Test for a file name.
58
+ * @param since - Epoch ms; NaN keeps every file.
59
+ * @returns Absolute paths; empty when the folder cannot be read.
60
+ */
61
+ export declare function filesWrittenSince(dir: string, name: RegExp, since: number): Promise<string[]>;
42
62
  /**
43
63
  * Stable identity for a transcript entry.
44
64
  *
@@ -63,6 +83,16 @@ export declare function messageIdFor(rawId: string | undefined, line: string): s
63
83
  * @returns The turn's usage, or undefined when there is nothing to report.
64
84
  */
65
85
  export declare function accumulateUsage(entries: ReadonlyMap<string, TranscriptUsageEntry>): TurnUsage | undefined;
86
+ /**
87
+ * One turn's usage out of two disjoint reads, summed: the parent's transcript
88
+ * and its subagents'. The model stays the parent's, the agent the developer
89
+ * talked to; a subagent's names the turn only when the parent read named none.
90
+ *
91
+ * @param parent - Usage of the parent transcript.
92
+ * @param subagents - Usage of the subagents' transcripts, none of it in `parent`.
93
+ * @returns The sum, or whichever one exists.
94
+ */
95
+ export declare function mergeUsage(parent: TurnUsage | undefined, subagents: TurnUsage | undefined): TurnUsage | undefined;
66
96
  /**
67
97
  * Decode one JSONL line.
68
98
  *
@@ -1,4 +1,5 @@
1
1
  import fs from 'node:fs/promises';
2
+ import path from 'node:path';
2
3
  import { add, finiteOrZero } from '../core/number.js';
3
4
  import { asRecord } from '../core/object.js';
4
5
  import { sleep } from '../core/async.js';
@@ -54,6 +55,36 @@ export async function readTranscriptTail(transcriptPath) {
54
55
  return undefined;
55
56
  }
56
57
  }
58
+ /**
59
+ * A transcript's tail as of one size, and the byte offset it starts at.
60
+ *
61
+ * One `stat` for both: a file still being appended to gives the tail and a
62
+ * read of what precedes it the same cut, so nothing falls between them.
63
+ *
64
+ * @param file - Transcript file.
65
+ * @returns The tail (partial first line dropped) and where it starts, or undefined when the file cannot be read.
66
+ */
67
+ export async function readTailSnapshot(file) {
68
+ try {
69
+ const { size } = await fs.stat(file);
70
+ const handle = await fs.open(file, 'r');
71
+ try {
72
+ const start = Math.max(0, size - TRANSCRIPT_TAIL_BYTES);
73
+ const buffer = Buffer.allocUnsafe(size - start);
74
+ const { bytesRead } = await handle.read(buffer, 0, size - start, start);
75
+ const bytes = buffer.subarray(0, bytesRead);
76
+ // A cut tail starts mid-line: drop up to the first newline, counted in bytes.
77
+ const skip = start === 0 ? 0 : bytes.indexOf(0x0a) + 1;
78
+ return { raw: bytes.subarray(skip).toString('utf8'), start: start + skip };
79
+ }
80
+ finally {
81
+ await handle.close();
82
+ }
83
+ }
84
+ catch {
85
+ return undefined;
86
+ }
87
+ }
57
88
  /**
58
89
  * A transcript tail with its turn window parsed: the start of every usage pass.
59
90
  *
@@ -76,6 +107,28 @@ export async function readWindowedTail(transcriptPath, sinceIso, untilIso) {
76
107
  return undefined;
77
108
  return { raw, since, until };
78
109
  }
110
+ /**
111
+ * The files in one folder whose names pass a test and that were written at or
112
+ * after a moment: the subagent transcripts a turn may hold usage in.
113
+ *
114
+ * @param dir - The folder.
115
+ * @param name - Test for a file name.
116
+ * @param since - Epoch ms; NaN keeps every file.
117
+ * @returns Absolute paths; empty when the folder cannot be read.
118
+ */
119
+ export async function filesWrittenSince(dir, name, since) {
120
+ const names = await fs.readdir(dir).catch(() => []);
121
+ const files = [];
122
+ for (const entry of names) {
123
+ if (!name.test(entry))
124
+ continue;
125
+ const file = path.join(dir, entry);
126
+ const stat = await fs.stat(file).catch(() => undefined);
127
+ if (stat && !(stat.mtimeMs < since))
128
+ files.push(file);
129
+ }
130
+ return files;
131
+ }
79
132
  /**
80
133
  * Stable identity for a transcript entry.
81
134
  *
@@ -128,6 +181,27 @@ export function accumulateUsage(entries) {
128
181
  messageIds: [...entries.keys()]
129
182
  };
130
183
  }
184
+ /**
185
+ * One turn's usage out of two disjoint reads, summed: the parent's transcript
186
+ * and its subagents'. The model stays the parent's, the agent the developer
187
+ * talked to; a subagent's names the turn only when the parent read named none.
188
+ *
189
+ * @param parent - Usage of the parent transcript.
190
+ * @param subagents - Usage of the subagents' transcripts, none of it in `parent`.
191
+ * @returns The sum, or whichever one exists.
192
+ */
193
+ export function mergeUsage(parent, subagents) {
194
+ if (!parent || !subagents)
195
+ return parent ?? subagents;
196
+ return {
197
+ model: parent.model ?? subagents.model,
198
+ inputTokens: add(parent.inputTokens, subagents.inputTokens),
199
+ outputTokens: add(parent.outputTokens, subagents.outputTokens),
200
+ cachedInputTokens: add(parent.cachedInputTokens, subagents.cachedInputTokens),
201
+ cacheCreationInputTokens: add(parent.cacheCreationInputTokens, subagents.cacheCreationInputTokens),
202
+ messageIds: [...(parent.messageIds ?? []), ...(subagents.messageIds ?? [])]
203
+ };
204
+ }
131
205
  /**
132
206
  * Read the last TRANSCRIPT_TAIL_BYTES of a file, dropping the partial first
133
207
  * line.
@@ -1,5 +1,5 @@
1
1
  import type { SessionTitles } from './types/transcript.types.js';
2
- import type { AgentProcessRecord, InheritedCheckoutMemo, SessionActivity, SessionModeRecord, TurnRecord, TurnStateEntry, WorkCheckoutMemo } from './types/turn-state.types.js';
2
+ import type { AgentProcessRecord, InheritedCheckoutMemo, SentTurn, SessionActivity, SessionModeRecord, TurnRecord, TurnStateEntry, WorkCheckoutMemo } from './types/turn-state.types.js';
3
3
  export type { CheckoutRecord, PromptRecord, ResponseRecord, SessionModelRecord, ToolRecord, TurnRecord, TurnStateEntry } from './types/turn-state.types.js';
4
4
  /**
5
5
  * The well-formed part of a session mode, from the start event's session or
@@ -115,6 +115,23 @@ export declare class TurnStateStore {
115
115
  * @param messageIds - Transcript message ids counted into that turn.
116
116
  */
117
117
  claimUsage(sessionId: string, turnId: string, messageIds: readonly string[]): Promise<void>;
118
+ /**
119
+ * Keep the summary a turn closed with, for a background subagent of that
120
+ * turn finishing later to re-send with its usage added. Cleared with the session.
121
+ *
122
+ * @param sessionId - Provider session id.
123
+ * @param turnId - The turn.
124
+ * @param sent - The summary as built, with the checkout it routed by.
125
+ */
126
+ rememberSentTurn(sessionId: string, turnId: string, sent: SentTurn): Promise<void>;
127
+ /**
128
+ * The summary a turn last went out with.
129
+ *
130
+ * @param sessionId - Provider session id.
131
+ * @param turnId - The turn.
132
+ * @returns It, or undefined when none was kept or it cannot be read.
133
+ */
134
+ readSentTurn(sessionId: string, turnId: string): Promise<SentTurn | undefined>;
118
135
  /**
119
136
  * Every transcript message id already claimed in this session.
120
137
  *
@@ -7,7 +7,7 @@ import { writeFileAtomic } from '../storage/atomic-file.js';
7
7
  import { readJsonFile } from '../storage/json-file.js';
8
8
  import { SECRET_FILE_MODE, SWEEP_MARKER_FILE } from '../storage/constants/storage.constants.js';
9
9
  import { claimSweep } from '../storage/sweep-marker.js';
10
- import { AGENT_PIDS_DIR, AGENT_PROCESS_FILE, BILLING_SENT_FILE, CLOSED_TURN_PREFIX, CLOSING_TURN_PREFIX, DETACHED_CLOSE_MAX_AGE_MS, INHERITED_CHECKOUT_FILE, LIVENESS_IGNORED_FILES, PROMPT_TICKETS_FILE, RE_UNSAFE_NAME_CHARS, SESSION_DIR_HASH_LENGTH, SESSION_ENDED_FILE, SESSION_FILES, SESSION_MODEL_FILE, SESSION_MODE_FILE, SESSION_RESUME_FILES, SESSION_START_FILE, SESSION_TITLE_FILE, TURN_RECORD_KINDS, TURN_STATE_SWEEP_INTERVAL_MS, UNTRACED_MARKER_PREFIX, USAGE_CLAIM_PREFIX, WORK_CHECKOUT_FILE } from './constants/turns.constants.js';
10
+ import { AGENT_PIDS_DIR, AGENT_PROCESS_FILE, BILLING_SENT_FILE, CLOSED_TURN_PREFIX, CLOSING_TURN_PREFIX, DETACHED_CLOSE_MAX_AGE_MS, INHERITED_CHECKOUT_FILE, LIVENESS_IGNORED_FILES, PROMPT_TICKETS_FILE, RE_UNSAFE_NAME_CHARS, SENT_TURN_PREFIX, SESSION_DIR_HASH_LENGTH, SESSION_ENDED_FILE, SESSION_FILES, SESSION_MODEL_FILE, SESSION_MODE_FILE, SESSION_RESUME_FILES, SESSION_START_FILE, SESSION_TITLE_FILE, TURN_RECORD_KINDS, TURN_STATE_SWEEP_INTERVAL_MS, UNTRACED_MARKER_PREFIX, USAGE_CLAIM_PREFIX, WORK_CHECKOUT_FILE } from './constants/turns.constants.js';
11
11
  /**
12
12
  * The well-formed part of a session mode, from the start event's session or
13
13
  * the memo read back: what is written and what is read pass the same check.
@@ -172,7 +172,35 @@ export class TurnStateStore {
172
172
  if (messageIds.length === 0)
173
173
  return;
174
174
  const file = path.join(this.sessionDir(sessionId), `${USAGE_CLAIM_PREFIX}${safeName(turnId)}.json`);
175
- await writeFileAtomic(file, JSON.stringify({ messageIds }), SECRET_FILE_MODE);
175
+ // Added to, never replaced: a background subagent claims onto a turn that already closed.
176
+ const earlier = await idsIn(file);
177
+ await writeFileAtomic(file, JSON.stringify({ messageIds: [...new Set([...earlier, ...messageIds])] }), SECRET_FILE_MODE);
178
+ }
179
+ /**
180
+ * Keep the summary a turn closed with, for a background subagent of that
181
+ * turn finishing later to re-send with its usage added. Cleared with the session.
182
+ *
183
+ * @param sessionId - Provider session id.
184
+ * @param turnId - The turn.
185
+ * @param sent - The summary as built, with the checkout it routed by.
186
+ */
187
+ async rememberSentTurn(sessionId, turnId, sent) {
188
+ await writeFileAtomic(path.join(this.sessionDir(sessionId), `${SENT_TURN_PREFIX}${safeName(turnId)}`), JSON.stringify(sent), SECRET_FILE_MODE);
189
+ }
190
+ /**
191
+ * The summary a turn last went out with.
192
+ *
193
+ * @param sessionId - Provider session id.
194
+ * @param turnId - The turn.
195
+ * @returns It, or undefined when none was kept or it cannot be read.
196
+ */
197
+ async readSentTurn(sessionId, turnId) {
198
+ const read = await readJsonFile(path.join(this.sessionDir(sessionId), `${SENT_TURN_PREFIX}${safeName(turnId)}`));
199
+ const sent = asRecord(read.state === 'ok' ? read.value : undefined);
200
+ const summary = asRecord(sent?.['summary']);
201
+ if (!summary || summary['turn_id'] !== turnId || typeof summary['id'] !== 'string')
202
+ return undefined;
203
+ return { ...sent, summary: summary };
176
204
  }
177
205
  /**
178
206
  * Every transcript message id already claimed in this session.
@@ -187,14 +215,8 @@ export class TurnStateStore {
187
215
  for (const name of names) {
188
216
  if (!name.startsWith(USAGE_CLAIM_PREFIX) || !name.endsWith('.json'))
189
217
  continue;
190
- const read = await readJsonFile(path.join(dir, name));
191
- const ids = asRecord(read.state === 'ok' ? read.value : undefined)?.['messageIds'];
192
- if (!Array.isArray(ids))
193
- continue;
194
- for (const id of ids) {
195
- if (typeof id === 'string')
196
- claimed.add(id);
197
- }
218
+ for (const id of await idsIn(path.join(dir, name)))
219
+ claimed.add(id);
198
220
  }
199
221
  return claimed;
200
222
  }
@@ -608,6 +630,19 @@ export class TurnStateStore {
608
630
  return path.join(this.turnsDir, sha256Hex(sessionId).slice(0, SESSION_DIR_HASH_LENGTH));
609
631
  }
610
632
  }
633
+ /**
634
+ * The message ids one claim file holds.
635
+ *
636
+ * @param file - A usage-claim file.
637
+ * @returns Its ids; empty when it is missing, unreadable or the wrong shape.
638
+ */
639
+ async function idsIn(file) {
640
+ const read = await readJsonFile(file);
641
+ const ids = asRecord(read.state === 'ok' ? read.value : undefined)?.['messageIds'];
642
+ if (!Array.isArray(ids))
643
+ return [];
644
+ return ids.filter((id) => typeof id === 'string');
645
+ }
611
646
  /**
612
647
  * Every turn record in one session directory, oldest first.
613
648
  *