Skip to content

Commit 0ae1353

Browse files
fix: tell a fork from its session_meta when reading its usage
thread/list answers forkedFromId null, so list rows of forks were counted with their inherited history: an end-to-end run against a mock Responses API showed 6000 input tokens for a fork whose own turn used 2000. A rollout whose session_meta names forked_from_id is now a fork, whatever the listed thread says; the result is read once per thread. Co-Authored-By: Claude Opus 5.5 <[email protected]>
1 parent 13156a4 commit 0ae1353

4 files changed

Lines changed: 62 additions & 21 deletions

File tree

‎docs/air-extensions.md‎

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1066,9 +1066,10 @@ The adapter sends no `cost`: Codex reports none.
10661066
`PromptResponse.usage` counts it. `cachedReadTokens` and `cachedWriteTokens` are the cache reads and writes.
10671067
`outputTokens` includes `reasoningTokens`.
10681068
- `model` is `Thread.model`, the thread's latest model.
1069-
- A fork counts only its own work. The first record of a fork carries the total of the history it inherited
1070-
plus the usage of its own first request, so the adapter subtracts that first total minus its
1071-
`last_token_usage`. A fork whose first record is not in the first 8 MB of its rollout gets no `usage`.
1069+
- A fork counts only its own work. A rollout whose first line, `session_meta`, names a `forked_from_id` is a
1070+
fork; `Thread.forkedFromId` does not tell, as `thread/list` leaves it out. The first record of a fork carries
1071+
the total of the history it inherited plus the usage of its own first request, so the adapter subtracts that
1072+
first total minus its `last_token_usage`. A fork whose first record is not in the first 8 MB of its rollout gets no `usage`.
10721073
- `subagents` lists the threads that the thread spawned, in the order it spawned them, each with its own counts
10731074
and `model`; they are not part of the thread's counts. The adapter finds them in the thread's own records in
10741075
its rollout: a `SubAgentActivity` item of kind `started` names the child in `agent_thread_id`, and in older

‎src/RolloutUsage.ts‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -130,6 +130,37 @@ export async function readLastTokenTotal(file: string): Promise<RawTokens | null
130130
}
131131
}
132132

133+
export const ZERO_TOKENS: Readonly<RawTokens> = Object.freeze({input: 0, cached: 0, cacheWrite: 0, output: 0, reasoning: 0});
134+
135+
/** How much of the start of a rollout is read for its `session_meta` line. */
136+
const SESSION_META_LIMIT = 1024 * 1024;
137+
138+
/**
139+
* `"notForked"` for a rollout whose `session_meta`, its first line, has no `forked_from_id`; otherwise the
140+
* first `token_count` of the fork, see {@link readFirstTokenCount}.
141+
*/
142+
export async function readForkStart(file: string): Promise<{total: RawTokens, last: RawTokens | null} | "notForked" | null> {
143+
const handle = await fs.open(file, "r");
144+
let firstLine: string;
145+
try {
146+
const buffer = Buffer.alloc(SESSION_META_LIMIT);
147+
const {bytesRead} = await handle.read(buffer, 0, SESSION_META_LIMIT, 0);
148+
const end = buffer.subarray(0, bytesRead).indexOf(NEWLINE);
149+
firstLine = buffer.toString("utf8", 0, end < 0 ? bytesRead : end);
150+
} finally {
151+
await handle.close();
152+
}
153+
let meta: unknown;
154+
try {
155+
meta = JSON.parse(firstLine);
156+
} catch {
157+
return "notForked";
158+
}
159+
const forkedFrom = field(field(meta, "payload"), "forked_from_id");
160+
if (field(meta, "type") !== "session_meta" || typeof forkedFrom !== "string" || forkedFrom === "") return "notForked";
161+
return await readFirstTokenCount(file);
162+
}
163+
133164
/** The first `token_count` of the rollout, read from its start, or `null` within {@link HEAD_LIMIT}. */
134165
export async function readFirstTokenCount(file: string): Promise<{total: RawTokens, last: RawTokens | null} | null> {
135166
const handle = await fs.open(file, "r");

‎src/SessionUsage.ts‎

Lines changed: 13 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -16,13 +16,14 @@ import type {Thread} from "./app-server/v2";
1616
import {logger} from "./Logger";
1717
import {
1818
minus,
19-
readFirstTokenCount,
19+
readForkStart,
2020
readLastTokenTotal,
2121
scanSpawnedThreads,
2222
type RawTokens,
2323
type SessionUsageTokens,
2424
type SpawnScan,
2525
usageTokens,
26+
ZERO_TOKENS,
2627
} from "./RolloutUsage";
2728

2829
export type {SessionUsageTokens} from "./RolloutUsage";
@@ -82,7 +83,6 @@ interface CachedFileTokens {
8283
interface Subagent {
8384
path: string;
8485
model: string | null;
85-
forked: boolean;
8686
/** The stamp of the rollout when the thread was read: a subagent whose rollout changed is read again. */
8787
stamp: string | null;
8888
}
@@ -241,7 +241,7 @@ export class SessionUsageIndex {
241241
let usage: SessionUsage | null = null;
242242
if (thread.path !== null) {
243243
try {
244-
const own = await this.tokensOf(thread.id, thread.path, thread.forkedFromId !== null);
244+
const own = await this.tokensOf(thread.id, thread.path);
245245
if (own !== null) {
246246
usage = {...own, model: thread.model, subagents: await this.subagentUsages(subject, thread.path)};
247247
}
@@ -301,7 +301,7 @@ export class SessionUsageIndex {
301301
child = {...child, stamp};
302302
remember(this.subagents, childId, child);
303303
}
304-
const tokens = await this.tokensOf(childId, child.path, child.forked);
304+
const tokens = await this.tokensOf(childId, child.path);
305305
return tokens === null ? null : {sessionId: childId, model: child.model, ...tokens};
306306
}
307307

@@ -312,7 +312,7 @@ export class SessionUsageIndex {
312312
this.subagents.delete(threadId);
313313
return null;
314314
}
315-
const subagent: Subagent = {path: thread.path, model: thread.model, forked: thread.forkedFromId !== null, stamp: null};
315+
const subagent: Subagent = {path: thread.path, model: thread.model, stamp: null};
316316
remember(this.subagents, threadId, subagent);
317317
return subagent;
318318
}
@@ -321,26 +321,28 @@ export class SessionUsageIndex {
321321
* The own usage of a thread from its rollout, or `null` when it has no `token_count`. The rollout is read
322322
* again only when its path, size or modification time changed.
323323
*/
324-
private async tokensOf(threadId: string, file: string, forked: boolean): Promise<SessionUsageTokens | null> {
324+
private async tokensOf(threadId: string, file: string): Promise<SessionUsageTokens | null> {
325325
const stamp = await stampOf(file);
326326
const cached = this.fileTokens.get(threadId);
327327
if (cached !== undefined && cached.stamp === stamp) {
328328
remember(this.fileTokens, threadId, cached);
329329
return cached.tokens;
330330
}
331-
const tokens = await this.readTokens(threadId, file, forked);
331+
const tokens = await this.readTokens(threadId, file);
332332
remember(this.fileTokens, threadId, {stamp, tokens});
333333
return tokens;
334334
}
335335

336-
private async readTokens(threadId: string, file: string, forked: boolean): Promise<SessionUsageTokens | null> {
336+
private async readTokens(threadId: string, file: string): Promise<SessionUsageTokens | null> {
337337
const total = await readLastTokenTotal(file);
338338
if (total === null) return null;
339-
if (!forked) return usageTokens(total);
340339
let inherited = this.inherited.get(threadId);
341340
if (inherited === undefined) {
342-
const first = await readFirstTokenCount(file);
343-
inherited = first === null ? null : first.last === null ? first.total : minus(first.total, first.last);
341+
// A fork tells from its own session_meta: `thread/list` leaves out `Thread.forkedFromId`.
342+
const start = await readForkStart(file);
343+
inherited = start === "notForked"
344+
? ZERO_TOKENS
345+
: start === null ? null : start.last === null ? start.total : minus(start.total, start.last);
344346
remember(this.inherited, threadId, inherited);
345347
}
346348
// A fork whose first record is beyond the read start of its rollout: its own part is unknown.

‎src/__tests__/SessionUsage.test.ts‎

Lines changed: 14 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -214,25 +214,32 @@ describe("SessionUsageIndex", () => {
214214
});
215215
});
216216

217-
it("counts only the own work of a fork", async () => {
218-
const file = write("fork.jsonl", [
217+
it("counts only the own work of a fork, which its session_meta names, whatever the listed thread says", async () => {
218+
const meta = (forkedFrom: string | null) => JSON.stringify({type: "session_meta", payload: {id: PARENT, forked_from_id: forkedFrom}});
219+
const lines = [
219220
// The first total is the inherited 1000/100 plus the fork's first request of 50/5.
220221
tokenCount({input: 1050, cached: 800, output: 105}, {input: 50, output: 5}),
221222
tokenCount({input: 1200, cached: 900, output: 130}),
222-
]);
223+
];
224+
const fork = write("fork.jsonl", [meta(OTHER), ...lines]);
225+
const plain = write("plain.jsonl", [meta(null), ...lines]);
223226
const {index} = createIndex(new Map());
224-
const subject = {thread: thread(PARENT, file, {forkedFromId: OTHER}), archived: false};
225-
index.usageOf(subject);
227+
// `thread/list` gives no forkedFromId.
228+
const forkSubject = {thread: thread(PARENT, fork), archived: false};
229+
const plainSubject = {thread: thread(CHILD, plain), archived: false};
230+
index.usageOf(forkSubject);
231+
index.usageOf(plainSubject);
226232
await settle(index);
227233

228-
expect(index.usageOf(subject)).toMatchObject({inputTokens: 100, cachedReadTokens: 100, outputTokens: 30});
234+
expect(index.usageOf(forkSubject)).toMatchObject({inputTokens: 100, cachedReadTokens: 100, outputTokens: 30});
235+
expect(index.usageOf(plainSubject)).toMatchObject({inputTokens: 300, cachedReadTokens: 900, outputTokens: 130});
229236
});
230237

231238
it("lists the subagents apart, each with its own usage and model, and leaves out a thread without usage", async () => {
232239
const childFile = write("child.jsonl", [tokenCount({input: 40, output: 4})]);
233240
const parentFile = write("parent.jsonl", [spawn(PARENT, CHILD), spawn(PARENT, OTHER), tokenCount({input: 10, output: 1})]);
234241
const threads = new Map([
235-
[CHILD, thread(CHILD, childFile, {model: "gpt-5-mini", forkedFromId: PARENT})],
242+
[CHILD, thread(CHILD, childFile, {model: "gpt-5-mini"})],
236243
[OTHER, thread(OTHER, null)],
237244
]);
238245
const {index} = createIndex(threads);

0 commit comments

Comments
 (0)