Skip to content

armgit / alook

Public Imported from GitHub
0

Multi-Agent Collaboration for Team and Friends

fix: account every settled runtime usage record (#636)

Gustavo Yed91ac7ff80a9
diff --git a/src/daemon/agent-driver/src/adapters/claude/index.ts b/src/daemon/agent-driver/src/adapters/claude/index.ts
index 8efe9fff6..ca229a489 100644
--- a/src/daemon/agent-driver/src/adapters/claude/index.ts
+++ b/src/daemon/agent-driver/src/adapters/claude/index.ts
@@ -43,7 +43,9 @@ export class ClaudeDriver implements BackendAdapter {
private readonly eventNormalizer = new ClaudeEventNormalizer(this.turnProtocol);
beginTurn(): string {
- return this.turnProtocol.beginTurn();
+ const receipt = this.turnProtocol.beginTurn();
+ this.eventNormalizer.beginTurn();
+ return receipt;
}
probe(command?: string): ProbeResult {
diff --git a/src/daemon/agent-driver/src/adapters/claude/normalizer.test.ts b/src/daemon/agent-driver/src/adapters/claude/normalizer.test.ts
index d73fafebb..560e612b9 100644
--- a/src/daemon/agent-driver/src/adapters/claude/normalizer.test.ts
+++ b/src/daemon/agent-driver/src/adapters/claude/normalizer.test.ts
@@ -61,9 +61,9 @@ describe("ClaudeEventNormalizer.normalizeLine", () => {
});
it("result → telemetry + turn_end", () => {
- const out = new ClaudeEventNormalizer().normalizeLine(
- J({ type: "result", subtype: "success", session_id: "s1", user_message_uuid: "root-1", usage: { input_tokens: 3, output_tokens: 5 } }),
- );
+ const n = new ClaudeEventNormalizer();
+ const line = J({ type: "result", subtype: "success", session_id: "s1", user_message_uuid: "root-1", usage: { input_tokens: 3, output_tokens: 5 } });
+ const out = n.normalizeLine(line);
const kinds = out.map((e) => e.kind);
expect(kinds).toContain("turn_end");
expect(kinds).toContain("telemetry");
@@ -78,6 +78,39 @@ describe("ClaudeEventNormalizer.normalizeLine", () => {
cache: null,
},
});
+ expect(n.normalizeLine(line).filter((event) => event.kind === "telemetry")).toEqual([]);
+ n.beginTurn();
+ expect(n.normalizeLine(line).filter((event) => event.kind === "telemetry")).toHaveLength(1);
+ });
+
+ it("does not emit usage without a backend session identity", () => {
+ const out = new ClaudeEventNormalizer().normalizeLine(
+ J({ type: "result", subtype: "success", usage: { input_tokens: 3, output_tokens: 5 } }),
+ );
+ expect(out).toEqual([{ kind: "turn_end", sessionId: undefined }]);
+ });
+
+ it("uses request_id and the invocation fallback when root request identity is absent", () => {
+ const n = new ClaudeEventNormalizer();
+ const withRequestId = J({
+ type: "result",
+ subtype: "success",
+ session_id: "s1",
+ request_id: "request-1",
+ usage: { input_tokens: 2, output_tokens: 1 },
+ });
+ expect(n.normalizeLine(withRequestId).filter((event) => event.kind === "telemetry")).toHaveLength(1);
+ expect(n.normalizeLine(withRequestId).filter((event) => event.kind === "telemetry")).toEqual([]);
+
+ n.beginTurn();
+ const withoutRequestId = J({
+ type: "result",
+ subtype: "success",
+ session_id: "s1",
+ usage: { input_tokens: 3, output_tokens: 2 },
+ });
+ expect(n.normalizeLine(withoutRequestId).filter((event) => event.kind === "telemetry")).toHaveLength(1);
+ expect(n.normalizeLine(withoutRequestId).filter((event) => event.kind === "telemetry")).toEqual([]);
});
it("result with is_error → error + turn_end", () => {
diff --git a/src/daemon/agent-driver/src/adapters/claude/normalizer.ts b/src/daemon/agent-driver/src/adapters/claude/normalizer.ts
index aadfca22b..1f929b399 100644
--- a/src/daemon/agent-driver/src/adapters/claude/normalizer.ts
+++ b/src/daemon/agent-driver/src/adapters/claude/normalizer.ts
@@ -14,6 +14,7 @@
* The `session_id` on any line keeps `currentSessionId` fresh for resume.
*/
import type { AdapterEvent } from "../../internal/adapter.js";
+import { SettledUsageProjector } from "../../internal/token-usage.js";
import { tryParseJsonLine } from "../../internal/utils.js";
import type { ClaudeTurnProtocol } from "./turnProtocol.js";
@@ -21,9 +22,14 @@ const API_ERROR_RE = /API Error:.*(?:Connection error|\b[45]\d{2}\b)/i;
export class ClaudeEventNormalizer {
private currentSession: string | null = null;
+ private readonly usageProjector = new SettledUsageProjector();
constructor(private readonly turnProtocol?: ClaudeTurnProtocol) {}
+ beginTurn(): void {
+ this.usageProjector.reset();
+ }
+
get currentSessionId(): string | null {
return this.currentSession;
}
@@ -114,7 +120,7 @@ export class ClaudeEventNormalizer {
? this.turnProtocol?.claimResult(rawOwner) ?? (this.turnProtocol ? null : `claude:${rawOwner}`)
: null;
if (this.turnProtocol && !turnOwner) return;
- const usage = this.buildUsageTelemetry(event);
+ const usage = this.buildUsageTelemetry(event, rawOwner);
if (usage) out.push(usage);
if (event.is_error || event.subtype === "error_during_execution") {
out.push({ kind: "error", message: String(event.result ?? "Claude runtime error") });
@@ -130,27 +136,24 @@ export class ClaudeEventNormalizer {
return this.turnProtocol?.acceptsTurnWork() ?? true;
}
- private buildUsageTelemetry(event: any): AdapterEvent | null {
+ private buildUsageTelemetry(event: any, rootRequestId: string | null): AdapterEvent | null {
const u = event?.usage;
if (!u) return null;
- const metric = (value: unknown) =>
- typeof value === "number" && Number.isSafeInteger(value) && value >= 0
- ? value
- : null;
- const cacheParts = [u.cache_read_input_tokens, u.cache_creation_input_tokens]
- .filter((value): value is number => typeof value === "number" && Number.isSafeInteger(value) && value >= 0);
- const cache = cacheParts.length > 0 && Number.isSafeInteger(cacheParts.reduce((sum, value) => sum + value, 0))
- ? cacheParts.reduce((sum, value) => sum + value, 0)
- : null;
- return {
- kind: "telemetry",
- name: "token_usage",
+ const backendSessionId = event.session_id ?? this.currentSession;
+ if (typeof backendSessionId !== "string" || !backendSessionId) return null;
+ const providerRecordId = rootRequestId
+ ?? (typeof event.request_id === "string" ? event.request_id : "invocation-result");
+ return this.usageProjector.project({
+ runtime: "claude",
+ backendSessionId,
+ providerRecordId,
source: "claude_result_usage",
- usage: {
- input: metric(u.input_tokens),
- output: metric(u.output_tokens),
- cache,
- },
- };
+ input: u.input_tokens,
+ output: u.output_tokens,
+ cacheRead: u.cache_read_input_tokens,
+ cacheWrite: u.cache_creation_input_tokens,
+ inputIncludesCache: false,
+ outputIncludesReasoning: true,
+ });
}
}
diff --git a/src/daemon/agent-driver/src/adapters/codex/normalizer.test.ts b/src/daemon/agent-driver/src/adapters/codex/normalizer.test.ts
index 7357f6891..2f6bc2384 100644
--- a/src/daemon/agent-driver/src/adapters/codex/normalizer.test.ts
+++ b/src/daemon/agent-driver/src/adapters/codex/normalizer.test.ts
@@ -281,6 +281,109 @@ describe("CodexEventNormalizer — turn id tracking (for turn/steer expectedTurn
expect(n.currentSessionId).toBe("root-thread");
expect(n.currentTurnId).toBe("root-turn");
});
+
+ it("accounts child raw responses without letting child lifecycle change the root turn", () => {
+ const n = new CodexEventNormalizer();
+ adoptRootTurn(n, "root-thread", "shared-turn-id");
+ const childUsage = notify("rawResponse/completed", {
+ threadId: "child-thread",
+ turnId: "shared-turn-id",
+ responseId: "child-response",
+ usage: {
+ inputTokens: 40,
+ cachedInputTokens: 10,
+ cacheWriteInputTokens: 5,
+ outputTokens: 8,
+ },
+ });
+ const rootUsage = notify("rawResponse/completed", {
+ threadId: "root-thread",
+ turnId: "shared-turn-id",
+ responseId: "root-response",
+ usage: {
+ inputTokens: 20,
+ cachedInputTokens: 2,
+ cacheWriteInputTokens: 1,
+ outputTokens: 4,
+ },
+ });
+
+ expect(n.normalizeLine(childUsage)).toEqual([expect.objectContaining({
+ kind: "telemetry",
+ usage: { input: 25, output: 8, cache: 15 },
+ })]);
+ expect(n.normalizeLine(rootUsage)).toEqual([expect.objectContaining({
+ kind: "telemetry",
+ usage: { input: 17, output: 4, cache: 3 },
+ })]);
+ expect(n.normalizeLine(childUsage)).toEqual([]);
+ expect(n.normalizeLine(rootUsage)).toEqual([]);
+
+ expect(n.normalizeLine(notify("turn/completed", {
+ threadId: "child-thread",
+ turn: { id: "shared-turn-id", status: "completed" },
+ }))).toEqual([]);
+ expect(n.currentSessionId).toBe("root-thread");
+ expect(n.currentTurnId).toBe("shared-turn-id");
+ expect(n.normalizeLine(rootUsage)).toEqual([]);
+
+ expect(n.normalizeLine(notify("turn/completed", {
+ threadId: "root-thread",
+ turn: { id: "shared-turn-id", status: "completed" },
+ }))).toEqual([
+ { kind: "turn_end", sessionId: "root-thread", turnOwner: "codex:root-thread:shared-turn-id" },
+ ]);
+ });
+
+ it("releases child usage at a child compaction completion", () => {
+ const n = new CodexEventNormalizer();
+ adoptRootTurn(n, "root-thread", "root-turn");
+ const childUsage = notify("rawResponse/completed", {
+ threadId: "child-thread",
+ turnId: "child-turn",
+ responseId: "child-response",
+ usage: { inputTokens: 9, cachedInputTokens: 4, outputTokens: 2 },
+ });
+
+ expect(n.normalizeLine(childUsage)).toHaveLength(1);
+ expect(n.normalizeLine(childUsage)).toEqual([]);
+ expect(n.normalizeLine(notify("item/completed", {
+ threadId: "child-thread",
+ turnId: "child-turn",
+ item: { type: "contextCompaction" },
+ }))).toEqual([]);
+ expect(n.normalizeLine(childUsage)).toHaveLength(1);
+ });
+
+ it("rejects incomplete settlements and releases late root compaction usage", () => {
+ const n = new CodexEventNormalizer();
+ adoptRootTurn(n, "root-thread", "root-turn");
+ expect(n.normalizeLine(notify("rawResponse/completed", {
+ threadId: "root-thread",
+ turnId: "root-turn",
+ responseId: "missing-usage",
+ }))).toEqual([]);
+ expect(n.normalizeLine(notify("rawResponse/completed", {
+ threadId: "root-thread",
+ turnId: "root-turn",
+ usage: { inputTokens: 1, outputTokens: 1 },
+ }))).toEqual([]);
+ expect(n.normalizeLine(notify("rawResponse/completed", {
+ threadId: "root-thread",
+ responseId: "missing-turn",
+ usage: { inputTokens: 1, outputTokens: 1 },
+ }))).toEqual([]);
+
+ expect(n.normalizeLine(notify("turn/completed", {
+ threadId: "root-thread",
+ turn: { id: "root-turn", status: "completed" },
+ }))).toHaveLength(1);
+ expect(n.normalizeLine(notify("item/completed", {
+ threadId: "root-thread",
+ turnId: "root-turn",
+ item: { type: "contextCompaction" },
+ }))).toEqual([{ kind: "compaction_finished" }]);
+ });
});
describe("CodexEventNormalizer — session_init dedup (result + thread/started notification)", () => {
@@ -353,7 +456,7 @@ describe("CodexEventNormalizer — complete owned event family", () => {
]);
});
- it("emits only the latest current-turn usage at terminal and maps Spark quota windows", () => {
+ it("emits every settled raw response once, ignores the legacy snapshot, and maps Spark quota windows", () => {
const n = new CodexEventNormalizer();
adoptRootTurn(n, "root", "turn");
expect(n.normalizeLine(notify("thread/tokenUsage/updated", {
@@ -363,29 +466,53 @@ describe("CodexEventNormalizer — complete owned event family", () => {
total: { inputTokens: 9_999, cachedInputTokens: 8_888, outputTokens: 7_777 },
},
}))).toEqual([]);
- expect(n.normalizeLine(notify("thread/tokenUsage/updated", {
+ const first = notify("rawResponse/completed", {
threadId: "root",
- tokenUsage: {
- last: { inputTokens: 120, cachedInputTokens: 50, outputTokens: 14 },
+ turnId: "turn",
+ responseId: "response-1",
+ usage: {
+ inputTokens: 120,
+ cachedInputTokens: 50,
+ cacheWriteInputTokens: 10,
+ outputTokens: 14,
},
- }))).toEqual([]);
+ });
+ expect(n.normalizeLine(first)).toEqual([{
+ kind: "telemetry",
+ name: "token_usage",
+ source: "codex_raw_response_completed",
+ usage: { input: 60, output: 14, cache: 60 },
+ }]);
+ expect(n.normalizeLine(first)).toEqual([]);
+ expect(n.normalizeLine(notify("rawResponse/completed", {
+ threadId: "root",
+ turnId: "turn",
+ responseId: "response-2",
+ usage: { inputTokens: 30, cachedInputTokens: 5, cacheWriteInputTokens: 0, outputTokens: 7 },
+ }))).toEqual([expect.objectContaining({
+ kind: "telemetry",
+ usage: { input: 25, output: 7, cache: 5 },
+ })]);
const terminal = n.normalizeLine(notify("turn/completed", {
threadId: "root",
turn: { id: "turn", status: "completed" },
}));
expect(terminal).toEqual([
- {
- kind: "telemetry",
- name: "token_usage",
- source: "codex_thread_token_usage_updated",
- usage: {
- input: 70,
- output: 14,
- cache: 50,
- },
- },
{ kind: "turn_end", sessionId: "root", turnOwner: "codex:root:turn" },
]);
+ expect(n.normalizeLine(first)).toEqual([]);
+
+ adoptRootTurn(n, "root", "turn-2");
+ expect(n.normalizeLine(notify("rawResponse/completed", {
+ threadId: "root",
+ turnId: "turn-2",
+ responseId: "response-1",
+ usage: { inputTokens: 2, cachedInputTokens: 0, cacheWriteInputTokens: 0, outputTokens: 1 },
+ }))).toHaveLength(1);
+ n.normalizeLine(notify("turn/completed", {
+ threadId: "root",
+ turn: { id: "turn-2", status: "completed" },
+ }));
n.registerQuotaReadRequest(99);
const quota = n.normalizeLine(JSON.stringify({
diff --git a/src/daemon/agent-driver/src/adapters/codex/normalizer.ts b/src/daemon/agent-driver/src/adapters/codex/normalizer.ts
index 94aa43413..2168016f7 100644
--- a/src/daemon/agent-driver/src/adapters/codex/normalizer.ts
+++ b/src/daemon/agent-driver/src/adapters/codex/normalizer.ts
@@ -1,5 +1,6 @@
import type { AdapterEvent } from "../../internal/adapter.js";
-import { mapCodexQuotaSnapshots, mapCodexTelemetry } from "./telemetry.js";
+import { mapCodexQuotaSnapshots, mapCodexSettledUsage } from "./telemetry.js";
+import { SettledUsageProjector } from "../../internal/token-usage.js";
import { tryParseJsonLine } from "../../internal/utils.js";
import { randomBytes } from "node:crypto";
@@ -54,7 +55,8 @@ export class CodexEventNormalizer {
private readonly rateLimitSnapshots = new Map<string, Record<string, unknown>>();
private quotaSnapshotInitialized = false;
private quotaSourceGeneration = codexQuotaSourceGeneration;
- private pendingTurnUsage: AdapterEvent | null = null;
+ private readonly usageProjector = new SettledUsageProjector();
+ private readonly usageRecordsBySessionAndTurn = new Map<string, Map<string, Set<string>>>();
private threadId: string | null = null;
private turnId: string | null = null;
/**
@@ -149,7 +151,8 @@ export class CodexEventNormalizer {
if (threadId !== this.threadId) {
this.turnId = null;
this.terminalTurn = null;
- this.pendingTurnUsage = null;
+ this.usageProjector.reset();
+ this.usageRecordsBySessionAndTurn.clear();
}
this.threadId = threadId;
}
@@ -202,6 +205,28 @@ export class CodexEventNormalizer {
private handleNotification(method: string, params: any): AdapterEvent[] {
const notificationThreadId = typeof params?.threadId === "string" ? params.threadId : null;
+ if (method === "rawResponse/completed") return this.handleSettledUsage(params);
+ if (
+ method === "turn/completed"
+ && notificationThreadId !== null
+ && notificationThreadId !== this.threadId
+ ) {
+ const turnId = this.notificationTurnId(params);
+ if (turnId) this.releaseUsageForTurn(notificationThreadId, turnId);
+ return [];
+ }
+ if (
+ method === "item/completed"
+ && notificationThreadId !== null
+ && notificationThreadId !== this.threadId
+ ) {
+ const turnId = this.notificationTurnId(params);
+ const itemType = params?.item?.type ?? params?.type;
+ if (turnId && itemType === "contextCompaction") {
+ this.releaseUsageForTurn(notificationThreadId, turnId);
+ }
+ return [];
+ }
if (
this.threadId !== null &&
notificationThreadId !== null &&
@@ -221,7 +246,6 @@ export class CodexEventNormalizer {
) return [];
this.turnId = params.turn.id;
this.terminalTurn = null;
- this.pendingTurnUsage = null;
return [
{
kind: "turn_owner",
@@ -241,7 +265,7 @@ export class CodexEventNormalizer {
return this.handleItemStarted(params);
case "item/completed":
- return this.handleItemCompleted(params);
+ return this.handleItemCompletedAndReleaseUsage(params);
case "rawResponseItem/completed":
return [{ kind: "internal_progress", source: "codex_raw_item", itemType: "rawResponseItem" }];
@@ -256,19 +280,17 @@ export class CodexEventNormalizer {
case "turn/completed":
if (!this.acceptRootTerminal(params)) return [];
- const usage = this.pendingTurnUsage;
- this.pendingTurnUsage = null;
+ this.releaseUsageForTurn(params.threadId, params.turn.id);
if (params.turn.status === "failed") {
return [
- ...(usage ? [usage] : []),
{ kind: "error", message: "Codex turn failed" },
{ kind: "turn_end", sessionId: this.threadId ?? undefined, turnOwner: this.turnReceipt(params.threadId, params.turn.id) },
];
}
if (params.turn.status === "interrupted") {
- return [...(usage ? [usage] : []), { kind: "error", message: "Codex turn interrupted" }, { kind: "turn_end", sessionId: this.threadId ?? undefined, turnOwner: this.turnReceipt(params.threadId, params.turn.id) }];
+ return [{ kind: "error", message: "Codex turn interrupted" }, { kind: "turn_end", sessionId: this.threadId ?? undefined, turnOwner: this.turnReceipt(params.threadId, params.turn.id) }];
}
- return [...(usage ? [usage] : []), { kind: "turn_end", sessionId: this.threadId ?? undefined, turnOwner: this.turnReceipt(params.threadId, params.turn.id) }];
+ return [{ kind: "turn_end", sessionId: this.threadId ?? undefined, turnOwner: this.turnReceipt(params.threadId, params.turn.id) }];
case "error":
if (params?.willRetry === true) {
@@ -276,11 +298,8 @@ export class CodexEventNormalizer {
}
return [{ kind: "error", message: params?.error?.message ?? params?.message ?? "Codex error" }];
- case "thread/tokenUsage/updated": {
- const usage = mapCodexTelemetry(method, params, codexQuotaSourceEpoch)[0];
- if (usage) this.pendingTurnUsage = usage;
+ case "thread/tokenUsage/updated":
return [];
- }
case "account/rateLimits/updated":
return this.mergeQuotaSnapshots(params);
case "account/updated":
@@ -293,6 +312,55 @@ export class CodexEventNormalizer {
}
}
+ private handleSettledUsage(params: any): AdapterEvent[] {
+ const notificationTurnId = this.notificationTurnId(params);
+ if (
+ this.turnId === null
+ && this.terminalTurn?.state === "closed"
+ && notificationTurnId === this.terminalTurn.turnId
+ && params?.threadId === this.terminalTurn.threadId
+ ) return [];
+ const backendSessionId = params?.threadId ?? params?.thread_id;
+ const providerRecordId = params?.responseId ?? params?.response_id;
+ if (
+ !notificationTurnId
+ || typeof backendSessionId !== "string"
+ || typeof providerRecordId !== "string"
+ ) return [];
+ const usage = mapCodexSettledUsage(params, this.usageProjector);
+ if (!usage) return [];
+ const recordsByTurn = this.usageRecordsBySessionAndTurn.get(backendSessionId) ?? new Map<string, Set<string>>();
+ const recordIds = recordsByTurn.get(notificationTurnId) ?? new Set<string>();
+ recordIds.add(providerRecordId);
+ recordsByTurn.set(notificationTurnId, recordIds);
+ this.usageRecordsBySessionAndTurn.set(backendSessionId, recordsByTurn);
+ return [usage];
+ }
+
+ private releaseUsageForTurn(backendSessionId: string, turnId: string): void {
+ const recordsByTurn = this.usageRecordsBySessionAndTurn.get(backendSessionId);
+ for (const providerRecordId of recordsByTurn?.get(turnId) ?? []) {
+ this.usageProjector.release({ runtime: "codex", backendSessionId, providerRecordId });
+ }
+ recordsByTurn?.delete(turnId);
+ if (recordsByTurn?.size === 0) this.usageRecordsBySessionAndTurn.delete(backendSessionId);
+ }
+
+ private handleItemCompletedAndReleaseUsage(params: any): AdapterEvent[] {
+ const events = this.handleItemCompleted(params);
+ const turnId = this.notificationTurnId(params);
+ const itemType = params?.item?.type ?? params?.type;
+ if (
+ turnId
+ && itemType === "contextCompaction"
+ && turnId !== this.turnId
+ && typeof params?.threadId === "string"
+ ) {
+ this.releaseUsageForTurn(params.threadId, turnId);
+ }
+ return events;
+ }
+
private isRootWorkNotification(method: string): boolean {
return method === "item/reasoning/textDelta"
|| method === "item/reasoning/summaryTextDelta"
diff --git a/src/daemon/agent-driver/src/adapters/codex/telemetry.ts b/src/daemon/agent-driver/src/adapters/codex/telemetry.ts
index f3f66faac..b14ed1115 100644
--- a/src/daemon/agent-driver/src/adapters/codex/telemetry.ts
+++ b/src/daemon/agent-driver/src/adapters/codex/telemetry.ts
@@ -1,24 +1,6 @@
import type { AdapterEvent } from "../../internal/adapter.js";
-import type { QuotaLimit, QuotaWindowIdentity, TokenMetricDelta } from "../../contract.js";
-
-function metric(value: unknown): TokenMetricDelta {
- return typeof value === "number" && Number.isSafeInteger(value) && value >= 0
- ? value
- : null;
-}
-
-function nonCachedInput(input: unknown, cached: unknown): TokenMetricDelta {
- if (
- typeof input !== "number"
- || !Number.isSafeInteger(input)
- || input < 0
- || typeof cached !== "number"
- || !Number.isSafeInteger(cached)
- || cached < 0
- || cached > input
- ) return null;
- return input - cached;
-}
+import type { QuotaLimit, QuotaWindowIdentity } from "../../contract.js";
+import type { SettledUsageProjector } from "../../internal/token-usage.js";
function canonicalId(value: unknown, fallback: string): string {
return typeof value === "string" && value.length > 0 && new TextEncoder().encode(value).length <= 64
@@ -113,25 +95,28 @@ export function mapCodexQuotaSnapshots(snapshots: any[], sourceEpoch: string): A
};
}
-export function mapCodexTelemetry(method: string, params: any, sourceEpoch: string): AdapterEvent[] {
- if (method === "thread/tokenUsage/updated") {
- const u = params?.tokenUsage?.last ?? params?.token_usage?.last;
- if (!u) return [];
- const input = u.inputTokens ?? u.input_tokens;
- const cached = u.cachedInputTokens ?? u.cached_input_tokens;
- return [{
- kind: "telemetry",
- name: "token_usage",
- source: "codex_thread_token_usage_updated",
- usage: {
- input: nonCachedInput(input, cached),
- output: metric(u.outputTokens ?? u.output_tokens),
- cache: metric(cached),
- },
- }];
- }
- if (method === "account/rateLimits/updated") {
- return [mapCodexQuotaSnapshots([params?.rateLimits ?? params ?? {}], sourceEpoch)];
- }
- return [];
+export function mapCodexSettledUsage(
+ params: any,
+ projector: SettledUsageProjector,
+): AdapterEvent | null {
+ const backendSessionId = params?.threadId ?? params?.thread_id;
+ const providerRecordId = params?.responseId ?? params?.response_id;
+ const usage = params?.usage;
+ if (
+ typeof backendSessionId !== "string"
+ || typeof providerRecordId !== "string"
+ || !usage
+ ) return null;
+ return projector.project({
+ runtime: "codex",
+ backendSessionId,
+ providerRecordId,
+ source: "codex_raw_response_completed",
+ input: usage.inputTokens ?? usage.input_tokens,
+ output: usage.outputTokens ?? usage.output_tokens,
+ cacheRead: usage.cachedInputTokens ?? usage.cached_input_tokens,
+ cacheWrite: usage.cacheWriteInputTokens ?? usage.cache_write_input_tokens,
+ inputIncludesCache: true,
+ outputIncludesReasoning: true,
+ });
}
diff --git a/src/daemon/agent-driver/src/adapters/opencode/service-lane.test.ts b/src/daemon/agent-driver/src/adapters/opencode/service-lane.test.ts
index 2b6ecabcb..7c2a5e778 100644
--- a/src/daemon/agent-driver/src/adapters/opencode/service-lane.test.ts
+++ b/src/daemon/agent-driver/src/adapters/opencode/service-lane.test.ts
@@ -1362,6 +1362,46 @@ describe("OpenCodeServiceLane authenticated persistent protocol", () => {
await lane.stop({ reason: "test", forceAfterMs: 0 });
});
+ it("accounts tool-call and terminal durable steps once across frontier replay", async () => {
+ const lane = makeLane();
+ const { runtime } = collectEvents(lane);
+ await lane.start({ text: "root", terminalOwner: "msg_root" });
+ const service = factories.at(-1)!.service!;
+ const toolStep = service.appendHistoryOnly("session.next.step.ended", {
+ assistantMessageID: "msg_tool",
+ finish: "tool-calls",
+ cost: 0,
+ tokens: { input: 10, output: 2, reasoning: 1, cache: { read: 3, write: 4 } },
+ });
+ service.replayDurable(toolStep);
+ const finalStep = service.appendHistoryOnly("session.next.step.ended", {
+ assistantMessageID: "msg_final",
+ finish: "stop",
+ cost: 0,
+ tokens: { input: 5, output: 6, reasoning: 1, cache: { read: 0, write: 0 } },
+ });
+ service.replayDurable(finalStep);
+ service.replayDurable(finalStep);
+ service.active = false;
+
+ await waitForTurn(runtime, 1);
+ expect(runtime.filter((event) => event.kind === "telemetry")).toEqual([
+ {
+ kind: "telemetry",
+ name: "token_usage",
+ source: "opencode.v2",
+ usage: { input: 10, output: 3, cache: 7 },
+ },
+ {
+ kind: "telemetry",
+ name: "token_usage",
+ source: "opencode.v2",
+ usage: { input: 5, output: 7, cache: 0 },
+ },
+ ]);
+ await lane.stop({ reason: "test", forceAfterMs: 0 });
+ });
+
it("fails closed on malformed admission and active-barrier responses", async () => {
const admissionLane = makeLane();
const admissionEvents = collectEvents(admissionLane);
diff --git a/src/daemon/agent-driver/src/adapters/opencode/service-lane.ts b/src/daemon/agent-driver/src/adapters/opencode/service-lane.ts
index 8e1dd0515..024638fbd 100644
--- a/src/daemon/agent-driver/src/adapters/opencode/service-lane.ts
+++ b/src/daemon/agent-driver/src/adapters/opencode/service-lane.ts
@@ -14,6 +14,7 @@ import type {
SpawnedProcess,
SpawnedProcessHandle,
} from "../../internal/adapter.js";
+import { SettledUsageProjector } from "../../internal/token-usage.js";
import { resolveLaunchFieldsOrDefault } from "../../internal/config.js";
import { killProcessTree, SESSION_STOP_GRACE_MS } from "../../internal/killTree.js";
@@ -185,6 +186,7 @@ export class OpenCodeServiceLane implements RuntimeLane {
private lastDurableSeq = 0;
private readonly durableSeqById = new Map<string, number>();
private readonly durableIdBySeq = new Map<number, string>();
+ private readonly usageProjector = new SettledUsageProjector();
private readonly toolNames = new Map<string, string>();
private readonly handledPermissions = new Set<string>();
private readonly permissionFlights = new Map<string, Promise<void>>();
@@ -750,8 +752,10 @@ export class OpenCodeServiceLane implements RuntimeLane {
const event = record(value);
const durable = record(event?.durable);
const data = record(event?.data);
+ const backendSessionId = this.sessionId;
if (
!event
+ || !backendSessionId
|| typeof event.id !== "string"
|| typeof event.type !== "string"
|| !durable
@@ -848,27 +852,26 @@ export class OpenCodeServiceLane implements RuntimeLane {
});
}
const tokens = record(data.tokens);
- if (tokens && data.finish !== "tool-calls") {
+ if (tokens) {
const cache = record(tokens.cache);
- const metric = (value: unknown) =>
- typeof value === "number" && Number.isSafeInteger(value) && value >= 0
- ? value
- : null;
- const cacheParts = [cache?.read, cache?.write]
- .filter((value): value is number => typeof value === "number" && Number.isSafeInteger(value) && value >= 0);
- const cacheTotal = cacheParts.reduce((sum, value) => sum + value, 0);
- this.events.emit("runtime_event", {
- kind: "telemetry",
- name: "token_usage",
+ const identity = {
+ runtime: "opencode",
+ backendSessionId,
+ providerRecordId: event.id,
+ } as const;
+ const usage = this.usageProjector.project({
+ ...identity,
source: "opencode.v2",
- usage: {
- input: metric(tokens.input),
- output: metric(tokens.output),
- cache: cacheParts.length > 0 && Number.isSafeInteger(cacheTotal)
- ? cacheTotal
- : null,
- },
- } satisfies AdapterEvent);
+ input: tokens.input,
+ output: tokens.output,
+ reasoning: tokens.reasoning,
+ cacheRead: cache?.read,
+ cacheWrite: cache?.write,
+ inputIncludesCache: false,
+ outputIncludesReasoning: false,
+ });
+ if (usage) this.events.emit("runtime_event", usage);
+ this.usageProjector.release(identity);
}
break;
}
diff --git a/src/daemon/agent-driver/src/adapters/pi/index.test.ts b/src/daemon/agent-driver/src/adapters/pi/index.test.ts
index c23bd20fd..f6222aae7 100644
--- a/src/daemon/agent-driver/src/adapters/pi/index.test.ts
+++ b/src/daemon/agent-driver/src/adapters/pi/index.test.ts
@@ -118,6 +118,52 @@ describe("PiDriver.openLane — AGENTS.md packing", () => {
expect(PI_IGNORED_EVENT_TYPES).not.toContain("auto_retry_end");
});
+ it("accounts each assistant message_end once and releases it at the ordered turn_end", () => {
+ const state = { sawTextDelta: false };
+ const messageEnd = {
+ type: "message_end",
+ message: {
+ role: "assistant",
+ responseId: "resp-1",
+ usage: { input: 11, output: 7, cacheRead: 3, cacheWrite: 2 },
+ },
+ };
+ expect(mapPiSdkEvent(messageEnd, "sess_1", state)).toEqual([{
+ kind: "telemetry",
+ name: "token_usage",
+ source: "pi_message_end",
+ usage: { input: 11, output: 7, cache: 5 },
+ }]);
+ expect(mapPiSdkEvent(messageEnd, "sess_1", state)).toEqual([]);
+ expect(mapPiSdkEvent({ type: "message_end", message: { role: "toolResult" } }, "sess_1", state)).toEqual([]);
+ expect(mapPiSdkEvent({ type: "turn_end", message: messageEnd.message }, "sess_1", state)).toEqual([]);
+ expect(PI_IGNORED_EVENT_TYPES).not.toContain("message_end");
+ expect(PI_IGNORED_EVENT_TYPES).not.toContain("turn_end");
+
+ expect(mapPiSdkEvent({
+ ...messageEnd,
+ message: { ...messageEnd.message, responseId: "resp-2", usage: { input: 1, output: 2, cacheRead: 0, cacheWrite: 0 } },
+ }, "sess_1", state)).toHaveLength(1);
+ });
+
+ it("uses a lane-local completion id when the SDK omits responseId", () => {
+ const state = { sawTextDelta: false };
+ expect(mapPiSdkEvent({
+ type: "message_end",
+ message: {
+ role: "assistant",
+ timestamp: 123,
+ usage: { input: 4, output: 3, cacheRead: 2, cacheWrite: 1 },
+ },
+ }, "sess_1", state)).toEqual([{
+ kind: "telemetry",
+ name: "token_usage",
+ source: "pi_message_end",
+ usage: { input: 4, output: 3, cache: 3 },
+ }]);
+ expect(mapPiSdkEvent({ type: "turn_end" }, "sess_1", state)).toEqual([]);
+ });
+
it("exposes SDK-only parser and encoder no-ops", () => {
const driver = new PiDriver(() => fakeDeps());
expect(driver.normalizeLine()).toEqual([]);
diff --git a/src/daemon/agent-driver/src/adapters/pi/index.ts b/src/daemon/agent-driver/src/adapters/pi/index.ts
index 5457e47b4..2d904232b 100644
--- a/src/daemon/agent-driver/src/adapters/pi/index.ts
+++ b/src/daemon/agent-driver/src/adapters/pi/index.ts
@@ -8,6 +8,7 @@ import type {
} from "../../internal/adapter.js";
import { SdkLane } from "../../controller/sdk-host.js";
import { resolveLaunchFieldsOrDefault } from "../../internal/config.js";
+import { SettledUsageProjector } from "../../internal/token-usage.js";
import { resolveCommandOnPath, type ProbeDeps } from "../../internal/probe.js";
import { parsePiModelCatalog } from "../../internal/modelCatalog.js";
import {
@@ -153,8 +154,6 @@ function readPiSdkVersion(): string | undefined {
export const PI_IGNORED_EVENT_TYPES = [
"agent_start",
"turn_start",
- "turn_end",
- "message_end",
"tool_execution_update",
"queue_update",
"session_info_changed",
@@ -162,8 +161,21 @@ export const PI_IGNORED_EVENT_TYPES = [
"agent_end",
] as const;
+interface PiEventState {
+ sawTextDelta: boolean;
+ usageProjector?: SettledUsageProjector;
+ pendingUsageRecordIds?: Set<string>;
+ usageRecordSequence?: number;
+}
+
+function piUsageState(state: PiEventState) {
+ state.usageProjector ??= new SettledUsageProjector();
+ state.pendingUsageRecordIds ??= new Set<string>();
+ return { projector: state.usageProjector, pending: state.pendingUsageRecordIds };
+}
+
/** Map a Pi SDK event to zero or more normalized events. */
-export function mapPiSdkEvent(event: any, sessionId: string, state: { sawTextDelta: boolean }): AdapterEvent[] {
+export function mapPiSdkEvent(event: any, sessionId: string, state: PiEventState): AdapterEvent[] {
if (event?.type === "message_update") {
const d = event.assistantMessageEvent ?? {};
switch (d.type) {
@@ -183,6 +195,36 @@ export function mapPiSdkEvent(event: any, sessionId: string, state: { sawTextDel
}
}
switch (event?.type) {
+ case "message_end": {
+ const message = event.message;
+ if (message?.role !== "assistant" || !message.usage) return [];
+ state.usageRecordSequence = (state.usageRecordSequence ?? 0) + 1;
+ const providerRecordId = typeof message.responseId === "string" && message.responseId
+ ? message.responseId
+ : `live:${message.timestamp ?? "unknown"}:${state.usageRecordSequence}`;
+ const { projector, pending } = piUsageState(state);
+ const identity = { runtime: "pi", backendSessionId: sessionId, providerRecordId } as const;
+ const usage = projector.project({
+ ...identity,
+ source: "pi_message_end",
+ input: message.usage.input,
+ output: message.usage.output,
+ cacheRead: message.usage.cacheRead,
+ cacheWrite: message.usage.cacheWrite,
+ inputIncludesCache: false,
+ outputIncludesReasoning: true,
+ });
+ pending.add(providerRecordId);
+ return usage ? [usage] : [];
+ }
+ case "turn_end": {
+ const { projector, pending } = piUsageState(state);
+ for (const providerRecordId of pending) {
+ projector.release({ runtime: "pi", backendSessionId: sessionId, providerRecordId });
+ }
+ pending.clear();
+ return [];
+ }
case "auto_retry_start":
return [{ kind: "runtime_recovery", stage: "retrying", source: "pi_auto_retry" }];
case "auto_retry_end":
diff --git a/src/daemon/agent-driver/src/internal/token-usage.test.ts b/src/daemon/agent-driver/src/internal/token-usage.test.ts
new file mode 100644
index 000000000..cd227d009
--- /dev/null
+++ b/src/daemon/agent-driver/src/internal/token-usage.test.ts
@@ -0,0 +1,124 @@
+import { describe, expect, it } from "vitest";
+import { SettledUsageProjector } from "./token-usage.js";
+
+const identity = {
+ runtime: "codex",
+ backendSessionId: "thread-1",
+ providerRecordId: "response-1",
+};
+
+describe("SettledUsageProjector", () => {
+ it("normalizes an inclusive input and cache read/write exactly once", () => {
+ const projector = new SettledUsageProjector();
+ const record = {
+ ...identity,
+ source: "fixture",
+ input: 100,
+ output: 7,
+ cacheRead: 30,
+ cacheWrite: 10,
+ inputIncludesCache: true,
+ outputIncludesReasoning: true,
+ } as const;
+
+ expect(projector.project(record)).toEqual({
+ kind: "telemetry",
+ name: "token_usage",
+ source: "fixture",
+ usage: { input: 60, output: 7, cache: 40 },
+ });
+ expect(projector.project(record)).toBeNull();
+ expect(projector.activeCount).toBe(1);
+ });
+
+ it("keeps exclusive input separate from cache and preserves reported zero", () => {
+ const projector = new SettledUsageProjector();
+ expect(projector.project({
+ ...identity,
+ source: "fixture",
+ input: 0,
+ output: 0,
+ cacheRead: 0,
+ cacheWrite: 0,
+ inputIncludesCache: false,
+ outputIncludesReasoning: true,
+ })).toMatchObject({ usage: { input: 0, output: 0, cache: 0 } });
+ });
+
+ it("maps missing, malformed, inconsistent, and overflowing metrics to null", () => {
+ const projector = new SettledUsageProjector();
+ expect(projector.project({
+ ...identity,
+ source: "fixture",
+ input: 3,
+ output: -1,
+ cacheRead: 4,
+ cacheWrite: 0,
+ inputIncludesCache: true,
+ outputIncludesReasoning: true,
+ })).toMatchObject({ usage: { input: null, output: null, cache: 4 } });
+ expect(projector.project({
+ ...identity,
+ providerRecordId: "overflow",
+ source: "fixture",
+ input: undefined,
+ output: undefined,
+ cacheRead: Number.MAX_SAFE_INTEGER,
+ cacheWrite: 1,
+ inputIncludesCache: false,
+ outputIncludesReasoning: true,
+ })).toBeNull();
+ expect(projector.activeCount).toBe(1);
+ expect(projector.project({
+ ...identity,
+ providerRecordId: "overflow",
+ source: "fixture",
+ input: 1,
+ output: 2,
+ inputIncludesCache: false,
+ outputIncludesReasoning: true,
+ })).not.toBeNull();
+ });
+
+ it("adds provider-exclusive reasoning to output without guessing invalid totals", () => {
+ const projector = new SettledUsageProjector();
+ expect(projector.project({
+ ...identity,
+ source: "fixture",
+ input: 1,
+ output: 7,
+ reasoning: 3,
+ inputIncludesCache: false,
+ outputIncludesReasoning: false,
+ })).toMatchObject({ usage: { input: 1, output: 10, cache: null } });
+ expect(projector.project({
+ ...identity,
+ providerRecordId: "missing-reasoning",
+ source: "fixture",
+ input: undefined,
+ output: 7,
+ reasoning: undefined,
+ inputIncludesCache: false,
+ outputIncludesReasoning: false,
+ })).toBeNull();
+ });
+
+ it("requires the full runtime/session/provider identity and scopes equal ids by session", () => {
+ const projector = new SettledUsageProjector();
+ const base = { source: "fixture", input: 1, output: 1, inputIncludesCache: false, outputIncludesReasoning: true } as const;
+ expect(projector.project({ ...base, ...identity, backendSessionId: "" })).toBeNull();
+ expect(projector.project({ ...base, ...identity })).not.toBeNull();
+ expect(projector.project({ ...base, ...identity, backendSessionId: "thread-2" })).not.toBeNull();
+ });
+
+ it("releases identities only when the adapter reaches its no-replay frontier", () => {
+ const projector = new SettledUsageProjector();
+ const record = { ...identity, source: "fixture", input: 1, output: 1, inputIncludesCache: false, outputIncludesReasoning: true } as const;
+ expect(projector.project(record)).not.toBeNull();
+ projector.release(identity);
+ expect(projector.activeCount).toBe(0);
+ expect(projector.project(record)).not.toBeNull();
+ projector.reset();
+ expect(projector.activeCount).toBe(0);
+ });
+});
diff --git a/src/daemon/agent-driver/src/internal/token-usage.ts b/src/daemon/agent-driver/src/internal/token-usage.ts
new file mode 100644
index 000000000..b860848dd
--- /dev/null
+++ b/src/daemon/agent-driver/src/internal/token-usage.ts
@@ -0,0 +1,92 @@
+import type { AdapterEvent } from "./adapter.js";
+
+interface SettledUsageIdentity {
+ readonly runtime: string;
+ readonly backendSessionId: string;
+ readonly providerRecordId: string;
+}
+
+interface SettledUsageRecord extends SettledUsageIdentity {
+ readonly source: string;
+ readonly input: unknown;
+ readonly output: unknown;
+ readonly reasoning?: unknown;
+ readonly cacheRead?: unknown;
+ readonly cacheWrite?: unknown;
+ readonly inputIncludesCache: boolean;
+ readonly outputIncludesReasoning: boolean;
+}
+
+function validIdentityPart(value: string): boolean {
+ return value.trim().length > 0 && Buffer.byteLength(value, "utf8") <= 512;
+}
+
+function identityKey(identity: SettledUsageIdentity): string | null {
+ if (
+ !validIdentityPart(identity.runtime)
+ || !validIdentityPart(identity.backendSessionId)
+ || !validIdentityPart(identity.providerRecordId)
+ ) return null;
+ return JSON.stringify([identity.runtime, identity.backendSessionId, identity.providerRecordId]);
+}
+
+function metric(value: unknown): number | null {
+ return typeof value === "number" && Number.isSafeInteger(value) && value >= 0 ? value : null;
+}
+
+function cacheMetric(read: unknown, write: unknown): number | null {
+ const present = [read, write].filter((value) => value !== undefined);
+ if (present.length === 0) return null;
+ const metrics = present.map(metric);
+ if (metrics.some((value) => value === null)) return null;
+ const total = (metrics as number[]).reduce((sum, value) => sum + value, 0);
+ return Number.isSafeInteger(total) ? total : null;
+}
+
+export class SettledUsageProjector {
+ private readonly active = new Set<string>();
+
+ project(record: SettledUsageRecord): AdapterEvent | null {
+ const key = identityKey(record);
+ if (!key || this.active.has(key)) return null;
+ this.active.add(key);
+
+ const cache = cacheMetric(record.cacheRead, record.cacheWrite);
+ const rawInput = metric(record.input);
+ const input = record.inputIncludesCache
+ ? rawInput !== null && cache !== null && cache <= rawInput
+ ? rawInput - cache
+ : null
+ : rawInput;
+ const rawOutput = metric(record.output);
+ const reasoning = metric(record.reasoning);
+ const output = record.outputIncludesReasoning
+ ? rawOutput
+ : rawOutput !== null && reasoning !== null && Number.isSafeInteger(rawOutput + reasoning)
+ ? rawOutput + reasoning
+ : null;
+ if (input === null && output === null && cache === null) {
+ this.active.delete(key);
+ return null;
+ }
+ return {
+ kind: "telemetry",
+ name: "token_usage",
+ source: record.source,
+ usage: { input, output, cache },
+ };
+ }
+
+ release(identity: SettledUsageIdentity): void {
+ const key = identityKey(identity);
+ if (key) this.active.delete(key);
+ }
+
+ reset(): void {
+ this.active.clear();
+ }
+
+ get activeCount(): number {
+ return this.active.size;
+ }
+}