Skip to content

Commit 01c2901

Browse files
fix: find every spawned subagent and bound the background usage reads
Review findings on the token usage of list rows: - Count only the spawns of the thread itself: SubAgentActivity items of kind started under its thread_id (a subagent records "interacted" items that name its parent), and the spawn_agent CollabAgentToolCall records of older rollouts, which named 19 of 657 subagents in real data. - Scan a rollout for spawns at most 8 MB per read and go on 250 ms later, so a first scan of large rollouts does not hold up the other rows. - Read at most 8 subagents at a time. - Keep no subagent that has no rollout yet, treat a missing rollout as no usage instead of failing the parent, and read a subagent again when its rollout changed, which can come with another model. - Read a thread once more 2 s after its updatedAt: a token_count of the same second moves no updatedAt. Co-Authored-By: Claude Opus 5.5 <[email protected]>
1 parent 22e2cc9 commit 01c2901

4 files changed

Lines changed: 273 additions & 61 deletions

File tree

‎docs/air-extensions.md‎

Lines changed: 11 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1070,14 +1070,21 @@ The adapter sends no `cost`: Codex reports none.
10701070
plus the usage of its own first request, so the adapter subtracts that first total minus its
10711071
`last_token_usage`. A fork whose first record is not in the first 8 MB of its rollout gets no `usage`.
10721072
- `subagents` lists the threads that the thread spawned, in the order it spawned them, each with its own counts
1073-
and `model`; they are not part of the thread's counts. The adapter finds them in the thread's rollout, from the
1074-
`agent_thread_id` of its `SubAgentActivity` items, and reads each one with `thread/read` for its rollout and
1075-
model. A subagent without a token count is left out; a thread that spawned none has `subagents: []`.
1073+
and `model`; they are not part of the thread's counts. The adapter finds them in the thread's own records in
1074+
its rollout: a `SubAgentActivity` item of kind `started` names the child in `agent_thread_id`, and in older
1075+
rollouts a `spawn_agent` `CollabAgentToolCall` names it in `receiver_thread_ids`. `thread/list` would miss about
1076+
half of them: it leaves out threads without a user message of their own. The adapter reads each subagent with
1077+
`thread/read` for its rollout and model, again when its rollout changed. A subagent without a token count, or
1078+
without a rollout yet, is left out; a thread that spawned none has `subagents: []`.
1079+
- The adapter scans a rollout for subagents once per process, at most 8 MB per read, and goes on with the rest a
1080+
moment later, so a large rollout does not hold up the other rows. Until the scan is done, `subagents` lists the
1081+
subagents found so far, and the row is sent again when it finds more.
10761082
- The adapter reads usage in the background, so a list never waits for it. A row carries the usage read for its
10771083
thread; the first list of a thread has none, and a thread that changed keeps the usage of the last read until
10781084
the new one is done. A subscription gets the row again when its usage was read, see
10791085
[Session list subscription](#session-list-subscription). A thread whose `updatedAt` and rollout did not change is
1080-
not read again, and a rollout is read again only when its size or time changed.
1086+
not read again, and a rollout is read again only when its size or time changed. A thread read within 2 s of its
1087+
`updatedAt` is read once more after that, since `updatedAt` has whole seconds.
10811088
- The usage of a subagent is read again when its parent thread changes: a subagent that works while its parent
10821089
waits shows its new counts once the parent writes again.
10831090

‎src/RolloutUsage.ts‎

Lines changed: 55 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,8 @@
33
*
44
* Codex writes `event_msg` `token_count` records into the rollout of a thread; `info.total_token_usage` of the
55
* last one is the running total of the thread, `info.last_token_usage` the usage of the request it follows.
6-
* A thread that spawns a subagent records a `SubAgentActivity` item with the `agent_thread_id` of the child.
6+
* A thread that spawns a subagent records an item that names the child: `SubAgentActivity` with its
7+
* `agent_thread_id`, or, in older rollouts, a `spawn_agent` `CollabAgentToolCall` with its `receiver_thread_ids`.
78
*/
89

910
import fs from "node:fs/promises";
@@ -175,7 +176,8 @@ export async function readFirstTokenCount(file: string): Promise<{total: RawToke
175176
}
176177
}
177178

178-
const SPAWN_MARKER = Buffer.from("\"agent_thread_id\":\"");
179+
/** Markers of the records that name a spawned thread: a `SubAgentActivity` item and a `spawn_agent` tool call. */
180+
const SPAWN_MARKERS = [Buffer.from("\"SubAgentActivity\""), Buffer.from("\"spawn_agent\"")];
179181
const THREAD_ID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
180182
const SCAN_CHUNK = 1024 * 1024;
181183

@@ -185,24 +187,32 @@ export interface SpawnScan {
185187
offset: number;
186188
/** The spawned thread ids, in the order of their first record. */
187189
threadIds: string[];
190+
/** The scan reached the end of the file. */
191+
done: boolean;
188192
}
189193

190194
/**
191-
* The threads that a thread spawned, from the `agent_thread_id` of the `SubAgentActivity` items that it records
192-
* under its own `thread_id`: a fork can carry such items of the thread it was forked from. A rollout only grows,
193-
* so a scan goes on from where the last one stopped; one of a file that is shorter now starts over.
195+
* The threads that a thread spawned, from its own records: an `item` of type `SubAgentActivity` with kind
196+
* `started` under the thread's `thread_id`, or of type `CollabAgentToolCall` with tool `spawn_agent` and the
197+
* thread as `sender_thread_id`. A rollout only grows, so a scan goes on from where the last one stopped, and
198+
* reads at most `maxBytes`; one of a file that is shorter now starts over.
194199
*/
195-
export async function scanSpawnedThreads(file: string, threadId: string, previous: SpawnScan | null): Promise<SpawnScan> {
196-
const ownRecord = `"thread_id":"${threadId}"`;
200+
export async function scanSpawnedThreads(
201+
file: string,
202+
threadId: string,
203+
previous: SpawnScan | null,
204+
maxBytes: number,
205+
): Promise<SpawnScan> {
197206
const handle = await fs.open(file, "r");
198207
try {
199208
const size = (await handle.stat()).size;
200209
const scan: SpawnScan = previous !== null && previous.offset <= size
201-
? {offset: previous.offset, threadIds: [...previous.threadIds]}
202-
: {offset: 0, threadIds: []};
210+
? {offset: previous.offset, threadIds: [...previous.threadIds], done: false}
211+
: {offset: 0, threadIds: [], done: false};
203212
const seen = new Set(scan.threadIds);
213+
const limit = Math.min(size, scan.offset + maxBytes);
204214
let position = scan.offset;
205-
while (position < size) {
215+
while (position < limit) {
206216
const length = Math.min(SCAN_CHUNK, size - position);
207217
const buffer = Buffer.alloc(length);
208218
const {bytesRead} = await handle.read(buffer, 0, length, position);
@@ -218,19 +228,47 @@ export async function scanSpawnedThreads(file: string, threadId: string, previou
218228
}
219229
// Only complete lines: the rest is read with the next chunk.
220230
const view = buffer.subarray(0, lastNewline + 1);
221-
for (let at = view.indexOf(SPAWN_MARKER); at >= 0; at = view.indexOf(SPAWN_MARKER, at + SPAWN_MARKER.length)) {
222-
const id = view.toString("latin1", at + SPAWN_MARKER.length, at + SPAWN_MARKER.length + 36).toLowerCase();
223-
if (!THREAD_ID_PATTERN.test(id) || seen.has(id)) continue;
224-
const line = view.toString("utf8", view.lastIndexOf(NEWLINE, at) + 1, view.indexOf(NEWLINE, at));
225-
if (!line.includes(ownRecord) || !line.includes("\"SubAgentActivity\"")) continue;
226-
seen.add(id);
227-
scan.threadIds.push(id);
231+
for (const marker of SPAWN_MARKERS) {
232+
let at = view.indexOf(marker);
233+
while (at >= 0) {
234+
const lineEnd = view.indexOf(NEWLINE, at);
235+
const line = view.toString("utf8", view.lastIndexOf(NEWLINE, at) + 1, lineEnd);
236+
for (const id of spawnedBy(line, threadId)) {
237+
if (seen.has(id)) continue;
238+
seen.add(id);
239+
scan.threadIds.push(id);
240+
}
241+
at = view.indexOf(marker, lineEnd + 1);
242+
}
228243
}
229244
position += view.length;
230245
scan.offset = position;
231246
}
247+
scan.done = scan.offset >= size;
232248
return scan;
233249
} finally {
234250
await handle.close();
235251
}
236252
}
253+
254+
/** The threads that one rollout record says the thread spawned. */
255+
function spawnedBy(line: string, threadId: string): string[] {
256+
let record: unknown;
257+
try {
258+
record = JSON.parse(line);
259+
} catch {
260+
return [];
261+
}
262+
const payload = field(record, "payload");
263+
const item = field(payload, "item");
264+
const ids: unknown[] = [];
265+
if (field(item, "type") === "SubAgentActivity" && field(item, "kind") === "started"
266+
&& field(payload, "thread_id") === threadId) {
267+
ids.push(field(item, "agent_thread_id"));
268+
} else if (field(item, "type") === "CollabAgentToolCall" && field(item, "tool") === "spawn_agent"
269+
&& field(item, "sender_thread_id") === threadId) {
270+
const receivers = field(item, "receiver_thread_ids");
271+
if (Array.isArray(receivers)) ids.push(...receivers);
272+
}
273+
return ids.filter((id): id is string => typeof id === "string" && THREAD_ID_PATTERN.test(id));
274+
}

0 commit comments

Comments
 (0)