Skip to content

armgit / cindy

Public Imported from GitHub
0

Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。

fix(claude): pair completed speed with normalized turn usage

zqchris55d1177f886c
diff --git a/apps/desktop/src/main/__tests__/makerEventHotPathOrdering.test.ts b/apps/desktop/src/main/__tests__/makerEventHotPathOrdering.test.ts
index 762d65ce5d..a6916667a0 100644
--- a/apps/desktop/src/main/__tests__/makerEventHotPathOrdering.test.ts
+++ b/apps/desktop/src/main/__tests__/makerEventHotPathOrdering.test.ts
@@ -1023,8 +1023,8 @@ describe('maker:event hot path ordering', () => {
const claudeCostFallback = claudeDoneSource.slice(
claudeDoneSource.indexOf("} else if (typeof cumulative === 'number' && cumulative >= 0)"),
);
- expect(claudeCostFallback).toMatch(
- /buildClaudeTurnUsageDetails\(\s*undefined,\s*undefined,\s*resolvedModel,/,
+ expect(claudeCostFallback).not.toMatch(
+ /buildClaudeTurnUsageDetails\(\s*doneData\??\.usage/,
);
expect(claudeCostFallback).toContain(
"if (route !== 'provider-api' || turnContext.accessKind === 'managed')",
diff --git a/apps/desktop/src/main/maker-ipc/__tests__/sessionClaudeTurnUsage.test.ts b/apps/desktop/src/main/maker-ipc/__tests__/sessionClaudeTurnUsage.test.ts
new file mode 100644
index 0000000000..87b0ded265
--- /dev/null
+++ b/apps/desktop/src/main/maker-ipc/__tests__/sessionClaudeTurnUsage.test.ts
@@ -0,0 +1,107 @@
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { createSourceFile, isFunctionDeclaration, ScriptKind, ScriptTarget, transpileModule } from 'typescript';
+import { describe, expect, it, vi } from 'vitest';
+import { calibratedResponseDuration } from '@cindy/maker-shared/usage-format';
+import type { AgentEvent, Session } from '@cindy/maker-core';
+import type { RecordSessionClaudeTurnUsageDeps } from '../sessionClaudeTurnUsage.js';
+import { buildClaudeTurnUsageDetails, normalizeTurnUsageSegments } from '../../usage/turnCostCalculator.js';
+import { ClaudeOutputLagTimingGuard, computeModelUsageDeltas } from '../../usage/modelUsageDelta.js';
+
+// Execute the production sink with database/network effects isolated, retaining
+// real usage normalization, timing validation and message-detail construction.
+const source = readFileSync(resolve(__dirname, '../sessionClaudeTurnUsage.ts'), 'utf8').replace(/\r\n?/g, '\n');
+const ast = createSourceFile('sessionClaudeTurnUsage.ts', source, ScriptTarget.Latest, true, ScriptKind.TS);
+const declaration = ast.statements.find(node => isFunctionDeclaration(node) && node.name?.text === 'recordSessionClaudeTurnUsage');
+if (!declaration) throw new Error('recordSessionClaudeTurnUsage not found');
+const compiled = transpileModule(declaration.getText(ast), {
+ compilerOptions: { target: ScriptTarget.ES2022 },
+}).outputText.replace('export function ', 'function ');
+
+function harness() {
+ const record = vi.fn<(value: { turnUsageDetails: unknown }) => Promise<void>>().mockResolvedValue(undefined);
+ const guard = new ClaudeOutputLagTimingGuard();
+ const recordSpend = vi.fn();
+ const runtime = {
+ calibratedResponseDuration, normalizeTurnUsageSegments, buildClaudeTurnUsageDetails, computeModelUsageDeltas,
+ captureTurnUsageContext: () => ({ providerId: null }),
+ recordTurnUsageOnMessage: record,
+ triggerClaudeAccountUsageRefresh: vi.fn(), triggerClaudeSubscriptionUsageRefresh: vi.fn(),
+ getSessionProvider: () => undefined,
+ CHATGPT_MODEL_PREFIX: 'chatgpt/', isExclusiveXaiModelId: () => false,
+ detectClaudeModelMismatch: () => null,
+ billingRouteForExplicitProvider: () => null, readClaudeSessionRoute: () => 'subscription',
+ readClaudeApiKey: () => undefined, getReferenceModelPricing: () => null,
+ CURRENT_CINDY_REGION: 'global',
+ resolveClaudeTurnCostSinks: () => ({ turnMoney: null, estimatedTurnMoney: null, perModel: [] }),
+ recordTurnSpend: recordSpend,
+ };
+ const wire = new Function('runtime', `const {${Object.keys(runtime).join(',')}} = runtime; ${compiled}; return recordSessionClaudeTurnUsage;`)(runtime) as
+ typeof import('../sessionClaudeTurnUsage.js').recordSessionClaudeTurnUsage;
+ const deps: RecordSessionClaudeTurnUsageDeps = {
+ turnUsageContextBySession: new Map(), turnModelPromiseBySession: new Map(),
+ readSessionModelForUsage: async () => 'claude-sonnet-4.5',
+ lastReportedModelUsageBySession: new Map(), claudeOutputLagTimingGuard: guard,
+ lastReportedCostUsdBySession: new Map(), log: { warn: vi.fn() },
+ unpricedSubscriptionValueMarker: () => ({ amount: 0, currency: 'USD', kind: 'value-estimate', approximate: true }),
+ };
+ const send = (data: unknown) => wire(deps, { id: 'task' } as Session,
+ { type: 'done', source: 'claude-code', data } as AgentEvent, 'assistant', 9_000, false);
+ return { send, record, guard, deps, recordSpend };
+}
+
+function done(output = 60, cumulative = 160, durationMs = 3_000) {
+ return {
+ total_cost_usd: 0, usage: { input_tokens: 500, output_tokens: cumulative, cache_read_input_tokens: 200 },
+ turnUsage: { input_tokens: 15, output_tokens: output, cache_read_input_tokens: 5, cache_creation_input_tokens: 2 },
+ responseSpeed: { phase: 'complete', waitOrigin: 'stream', firstResponseMs: 1000, waitingMs: 0,
+ durationMs, outputTokens: output, estimated: false, averageRate: output * 1000 / durationMs,
+ recentRate: output * 1000 / durationMs, samples: [], sampledAt: 10_000 },
+ };
+}
+
+describe('Claude completed usage without modelUsage', () => {
+ it('persists current-turn TPS across cumulative results without charging or copying aggregate tokens', async () => {
+ const h = harness();
+ h.send(done(100, 100, 2_000));
+ await vi.waitFor(() => expect(h.record).toHaveBeenCalledTimes(1));
+ h.send(done());
+ await vi.waitFor(() => expect(h.record).toHaveBeenCalledTimes(2));
+ const first = h.record.mock.calls[0][0].turnUsageDetails;
+ const second = h.record.mock.calls[1][0].turnUsageDetails;
+ expect(first).toMatchObject({ outputTokens: 100, durationMs: 2_000 });
+ expect(second).toMatchObject({ inputTokens: 15, outputTokens: 60, cacheReadTokens: 5,
+ cacheCreateTokens: 2, durationMs: 3_000, turnDurationMs: 9_000 });
+ expect(h.deps.lastReportedCostUsdBySession.get('task')).toBe(0);
+ expect(h.recordSpend).not.toHaveBeenCalled();
+ });
+
+ it('uses the normalized delta when partial request metadata has no priced model rows', async () => {
+ const h = harness();
+ h.send({ ...done(), usageSegments: [{ model: 'claude-sonnet-4.5', inputTokens: 5, outputTokens: 10 }],
+ usageSegmentsComplete: false });
+ await vi.waitFor(() => expect(h.record).toHaveBeenCalledTimes(1));
+ expect(h.record.mock.calls[0][0].turnUsageDetails).toMatchObject({ inputTokens: 15,
+ outputTokens: 60, cacheReadTokens: 5, cacheCreateTokens: 2, durationMs: 3_000 });
+ expect(h.recordSpend).not.toHaveBeenCalled();
+ });
+
+ it.each([undefined, { output_tokens: 160 }, { output_tokens: Number.NaN }, { output_tokens: -1 }])(
+ 'omits timing when the normalized provider count is unavailable or mismatched (%j)', async (turnUsage) => {
+ const h = harness(); h.send({ ...done(), turnUsage });
+ await vi.waitFor(() => expect(h.record).toHaveBeenCalledTimes(1));
+ expect(h.record.mock.calls[0][0].turnUsageDetails).toMatchObject({ outputTokens: 0 });
+ expect(h.record.mock.calls[0][0].turnUsageDetails).not.toHaveProperty('durationMs');
+ },
+ );
+
+ it('keeps a real zero and respects output-lag suppression', async () => {
+ const h = harness(); h.send(done(0, 160));
+ await vi.waitFor(() => expect(h.record).toHaveBeenCalledTimes(1));
+ expect(h.record.mock.calls[0][0].turnUsageDetails).toMatchObject({ outputTokens: 0, durationMs: 3_000 });
+ vi.spyOn(h.guard, 'evaluate').mockReturnValue({ detected: false, suppressTiming: true });
+ h.send(done());
+ await vi.waitFor(() => expect(h.record).toHaveBeenCalledTimes(2));
+ expect(h.record.mock.calls[1][0].turnUsageDetails).not.toHaveProperty('durationMs');
+ });
+});
diff --git a/apps/desktop/src/main/maker-ipc/sessionClaudeTurnUsage.ts b/apps/desktop/src/main/maker-ipc/sessionClaudeTurnUsage.ts
index bc9ca96b55..af54783afa 100644
--- a/apps/desktop/src/main/maker-ipc/sessionClaudeTurnUsage.ts
+++ b/apps/desktop/src/main/maker-ipc/sessionClaudeTurnUsage.ts
@@ -101,6 +101,12 @@ export function recordSessionClaudeTurnUsage(
duration_ms?: unknown;
duration_api_ms?: unknown;
responseSpeed?: unknown;
+ turnUsage?: {
+ input_tokens?: number;
+ output_tokens?: number;
+ cache_read_input_tokens?: number;
+ cache_creation_input_tokens?: number;
+ };
usage?: {
input_tokens?: number;
output_tokens?: number;
@@ -169,12 +175,15 @@ export function recordSessionClaudeTurnUsage(
: undefined,
doneData?.is_error !== true,
);
+ const claudeTurnOutputTokens = modelUsageDeltas?.length
+ ? modelUsageDeltas.reduce((sum, delta) => sum + delta.outputTokensDelta, 0)
+ : typeof doneData?.turnUsage?.output_tokens === 'number' ? doneData.turnUsage.output_tokens : undefined;
const claudeGenerationDurationMs = outputLagTiming.suppressTiming
? undefined
: doneData?.responseSpeed !== undefined
- ? calibratedResponseDuration(doneData.responseSpeed, modelUsageDeltas?.length
- ? modelUsageDeltas.reduce((sum, delta) => sum + delta.outputTokensDelta, 0)
- : doneData?.usage?.output_tokens ?? 0)
+ ? claudeTurnOutputTokens !== undefined
+ ? calibratedResponseDuration(doneData.responseSpeed, claudeTurnOutputTokens)
+ : undefined
: typeof doneData?.duration_api_ms === 'number'
? doneData.duration_api_ms
: undefined;
@@ -335,7 +344,7 @@ export function recordSessionClaudeTurnUsage(
// deltas 非空 → buildClaudeTurnUsageDetails 用 deltas 里的 model, fallbackModel 不取用。
// 传 perModel → 落「按模型成本明细」(含 subagent 跑的模型, 如 Haiku)。
const turnUsageDetails = buildClaudeTurnUsageDetails(
- doneData?.usage,
+ doneData?.turnUsage ?? doneData?.usage,
resolvedUsageDeltas,
'unknown',
perModel,
@@ -369,7 +378,7 @@ export function recordSessionClaudeTurnUsage(
const turnEstimatedValue =
estimatedValues.length > 0 ? addRegionalMoney(estimatedValues) : null;
const turnUsageDetails = buildClaudeTurnUsageDetails(
- doneData?.usage,
+ doneData?.turnUsage ?? doneData?.usage,
resolvedUsageDeltas,
'unknown',
perModel,
@@ -414,9 +423,11 @@ export function recordSessionClaudeTurnUsage(
}
// `doneData.usage` can be the same process-lifetime cumulative snapshot as
// `total_cost_usd`. Without model deltas or request segments it is not a reliable
- // per-turn token fact, so retain only model/timing metadata in this fallback.
+ // per-turn token fact. Persist the normalized provider delta only when
+ // its output matches the calibrated measurement; never the aggregate.
const turnUsageDetails = buildClaudeTurnUsageDetails(
- undefined,
+ claudeGenerationDurationMs !== undefined && claudeTurnOutputTokens !== undefined
+ ? doneData?.turnUsage : undefined,
undefined,
resolvedModel,
undefined,
@@ -424,7 +435,7 @@ export function recordSessionClaudeTurnUsage(
claudeTurnDurationMs,
);
// 本分支有三个"记不了钱"的出口(本轮 cost 未增长 / 订阅直连 / 非明确
- // provider-api 路由)。只保留可证明的模型与时长;进程累计 usage 不能冒充本轮 token。
+ // provider-api 路由)。只保留可证明的模型、输出与时长;进程累计 usage 不能冒充本轮 token。
const recordUsageOnly = async () => {
if (!turnAssistantPersistId) return;
await recordTurnUsageOnMessage({
diff --git a/docs/dev-rules/protocol-compatibility.md b/docs/dev-rules/protocol-compatibility.md
index 679ca0eeb3..0216067086 100644
--- a/docs/dev-rules/protocol-compatibility.md
+++ b/docs/dev-rules/protocol-compatibility.md
@@ -18,6 +18,9 @@
沿用原 usage 路径,旧客户端忽略新增字段。无需服务端更新、新通道、权限或数据库 migration。
终态真实 output 与生成 duration 的匹配沿现有消息用量记录处理。详见
[`response-speed.md`](response-speed.md)。
+Claude 的既有 done payload 可选携带 `turnUsage`,来自 SDK result 用量的本轮增量,
+供历史速度与消息用量配对。原 `usage` 保持会话累计口径;旧端忽略新字段,新端缺字段且无模型增量时
+省略该速度,不将累计用量当本轮输出。费用与上下文仍走原计量路径。
## 任务列表提前同步聊天正文
diff --git a/docs/dev-rules/response-speed.md b/docs/dev-rules/response-speed.md
index 736ed7b1af..f5c2136975 100644
--- a/docs/dev-rules/response-speed.md
+++ b/docs/dev-rules/response-speed.md
@@ -40,6 +40,8 @@ Pi 重试关闭失败片段,下一请求重新等待;每轮重新清空测
应用/Renderer 重载后首响应和曲线不恢复。已有消息用量记录继续保存真实 output 与经过
计数匹配检查的生成 duration,支持历史最终平均 TPS;缺失或计数不匹配时省略 TPS。
不增加数据库 schema、migration 或首响应持久字段。
+Claude result 的原始 `usage` 是会话累计值;历史速度与消息详情使用同一份真实本轮
+`turnUsage` 增量(或模型增量),不能把累计输出与本轮生成时间配对。它不来自流式估算。
## 兼容与验证
diff --git a/packages/maker-core/src/agents/claude-code/generation-timing.test.ts b/packages/maker-core/src/agents/claude-code/generation-timing.test.ts
index 95b02b92a6..3a5fbf5135 100644
--- a/packages/maker-core/src/agents/claude-code/generation-timing.test.ts
+++ b/packages/maker-core/src/agents/claude-code/generation-timing.test.ts
@@ -2011,3 +2011,42 @@ describe('claude generation pause boundaries', () => {
vi.useRealTimers();
});
});
+
+describe('Claude normalized completed-turn output', () => {
+ afterEach(() => { vi.useRealTimers(); vi.restoreAllMocks(); });
+
+ it('preserves raw SDK aggregates while exposing real turn output across success, zero and reset', () => {
+ vi.useFakeTimers();
+ const ctx = createTranslatorCtx();
+ const events: AgentEvent[] = [];
+ const queue = { push: (event: AgentEvent) => events.push(event) } as unknown as Parameters<typeof translateSdkMessage>[1];
+ const counts = [100, 60, 0, 30];
+ const aggregates = [100, 160, 160, 30];
+ for (const [index, output] of counts.entries()) {
+ const start = 1_000 + index * 10_000;
+ vi.setSystemTime(start);
+ resetClaudeGenerationTiming(ctx.rt.generation);
+ ctx.tracker.beginTurn();
+ ctx.turn = createTurnState();
+ translateSdkMessage({ type: 'stream_event', event: { type: 'message_start',
+ message: { id: `m-${index}`, model: 'claude-sonnet-4.5', usage: { input_tokens: 0 } } } }, queue, ctx);
+ vi.setSystemTime(start + 1_000);
+ translateSdkMessage({ type: 'stream_event', event: { type: 'content_block_start',
+ content_block: { type: 'text', text: '' } } }, queue, ctx);
+ translateSdkMessage({ type: 'stream_event', event: { type: 'content_block_delta',
+ delta: { type: 'text_delta', text: 'answer' } } }, queue, ctx);
+ vi.setSystemTime(start + 3_000);
+ translateSdkMessage({ type: 'stream_event', event: { type: 'message_delta',
+ usage: { output_tokens: output } } }, queue, ctx);
+ vi.setSystemTime(start + 5_000);
+ translateSdkMessage({ type: 'result', subtype: 'success', result: 'answer', total_cost_usd: 0,
+ usage: { input_tokens: 0, output_tokens: aggregates[index] } }, queue, ctx);
+ const done = events.filter(event => event.type === 'done').at(-1);
+ expect(done?.data).toMatchObject({ usage: { output_tokens: aggregates[index] }, turnUsage: { output_tokens: output },
+ responseSpeed: { phase: 'complete', outputTokens: output, durationMs: 2_000,
+ averageRate: output / 2, estimated: false } });
+ expect(done?.data).not.toHaveProperty('modelUsage');
+ expect(ctx.rt.lastResultUsageAggregate?.outputTokens).toBe(aggregates[index]);
+ }
+ });
+});
diff --git a/packages/maker-core/src/agents/claude-code/translator.ts b/packages/maker-core/src/agents/claude-code/translator.ts
index 17e73a72d9..2aa2532735 100644
--- a/packages/maker-core/src/agents/claude-code/translator.ts
+++ b/packages/maker-core/src/agents/claude-code/translator.ts
@@ -2515,6 +2515,14 @@ function handleResult(
const resultWithUsageSegments = {
...safeResult,
responseSpeed: liveGeneration.responseSpeed.snapshot(),
+ // Keep SDK usage intact; the normalized provider delta can pair
+ // with the current turn's response-speed denominator.
+ turnUsage: resultUsage ? {
+ input_tokens: resultUsage.inputTokens,
+ output_tokens: resultUsage.outputTokens,
+ cache_read_input_tokens: resultUsage.cacheReadTokens,
+ cache_creation_input_tokens: resultUsage.cacheCreateTokens,
+ } : undefined,
usageSegments: turnUsageSegments,
usageSegmentsComplete,
modelUsageCumulativeStartsAtZero: ctx.modelUsageCumulativeStartsAtZero?.() === true,