fix(cli): backfill zero-usage assistant messages from the transcript

Some gateways report all-zero usage in stream-json while the Claude
transcript carries the real sample ~100 ms later. Delay those assistant
messages briefly and patch usage from the main transcript so context and
usage meters stay truthful.

via [HAPI](https://hapi.run)

Co-Authored-By: HAPI <noreply@hapi.run>
Co-Authored-By: Claude Code <noreply@anthropic.com>
This commit is contained in:
2026-11-08 20:24:29 +08:00
co-authored by HAPI Claude Code
parent 4be290073e
commit f2c43f2eb2
3 changed files with 281 additions and 2 deletions
+13 -2
View File
@@ -18,6 +18,8 @@ import { RPC_METHODS } from "@hapi/protocol/rpcMethods";
import { parseSpecialCommand } from "@/parsers/specialCommands";
import { ClaudeToolResultImages } from './utils/toolResultImages';
import { applySessionTitleFallback, readNativeSessionTitle, stripAttachmentReferences } from './utils/sessionTitleFallback';
import { getProjectPath } from './utils/path';
import { hasUsageSignal, TranscriptUsageIndex } from './utils/transcriptUsage';
import {
RemoteLauncherBase,
type RemoteLauncherDisplayContext,
@@ -144,8 +146,14 @@ class ClaudeRemoteLauncher extends RemoteLauncherBase {
this.permissionHandler = permissionHandler;
const toolResultImages = new ClaudeToolResultImages();
// Stream-json assistant messages report all-zero usage for some
// gateways; the transcript carries the real sample a beat later.
const transcriptUsage = new TranscriptUsageIndex(getProjectPath(session.path), session.sessionId);
const messageQueue = new OutgoingMessageQueue(
(logMessage) => toolResultImages.send(session.client, logMessage)
(logMessage) => {
transcriptUsage.patch(logMessage);
return toolResultImages.send(session.client, logMessage);
}
);
permissionHandler.setOnPermissionRequest((toolCallId: string) => {
@@ -261,6 +269,7 @@ class ClaudeRemoteLauncher extends RemoteLauncherBase {
const handleSessionFound = (sessionId: string) => {
sdkToLogConverter.updateSessionId(sessionId);
transcriptUsage.updateSessionId(sessionId);
};
this.handleSessionFound = handleSessionFound;
session.addSessionFoundCallback(handleSessionFound);
@@ -399,7 +408,9 @@ class ClaudeRemoteLauncher extends RemoteLauncherBase {
}
}
messageQueue.enqueue(logMessage);
const needsUsagePatch = logMessage.type === 'assistant'
&& !hasUsageSignal((logMessage as { message?: { usage?: Record<string, unknown> } }).message?.usage);
messageQueue.enqueue(logMessage, needsUsagePatch ? { delay: 200 } : undefined);
}
if (message.type === 'assistant') {
@@ -0,0 +1,121 @@
import { appendFileSync, mkdtempSync, writeFileSync } from 'node:fs'
import { tmpdir } from 'node:os'
import { join } from 'node:path'
import { describe, expect, it } from 'vitest'
import { OutgoingMessageQueue } from './OutgoingMessageQueue'
import { hasUsageSignal, TranscriptUsageIndex } from './transcriptUsage'
function assistantLine(id: string, usage: Record<string, number>): string {
return JSON.stringify({
type: 'assistant',
message: { id, role: 'assistant', usage }
}) + '\n'
}
function assistantLog(id: string, usage?: Record<string, number>) {
return { type: 'assistant' as const, message: { id, usage } }
}
describe('TranscriptUsageIndex', () => {
it('patches an all-zero stream-json usage from the transcript sample', () => {
const dir = mkdtempSync(join(tmpdir(), 'hapi-usage-'))
const index = new TranscriptUsageIndex(dir, 'session-1')
const path = join(dir, 'session-1.jsonl')
appendFileSync(path, assistantLine('msg-1', {
input_tokens: 1200,
output_tokens: 30,
cache_read_input_tokens: 170000,
cache_creation_input_tokens: 0
}))
const log = assistantLog('msg-1', {
input_tokens: 0,
output_tokens: 0,
cache_read_input_tokens: 0,
cache_creation_input_tokens: 0,
context_window: 800000
})
expect(index.patch(log)).toBe(true)
expect(log.message.usage).toMatchObject({
input_tokens: 1200,
output_tokens: 30,
cache_read_input_tokens: 170000,
context_window: 800000
})
})
it('leaves an authoritative usage sample untouched', () => {
const dir = mkdtempSync(join(tmpdir(), 'hapi-usage-'))
const index = new TranscriptUsageIndex(dir, 'session-1')
appendFileSync(join(dir, 'session-1.jsonl'), assistantLine('msg-1', { input_tokens: 9 }))
const log = assistantLog('msg-1', { input_tokens: 42, output_tokens: 7 })
expect(index.patch(log)).toBe(false)
expect(log.message.usage?.input_tokens).toBe(42)
})
it('waits for a partially flushed transcript line', () => {
const dir = mkdtempSync(join(tmpdir(), 'hapi-usage-'))
const index = new TranscriptUsageIndex(dir, 'session-1')
const path = join(dir, 'session-1.jsonl')
const line = assistantLine('msg-1', { input_tokens: 5 })
appendFileSync(path, line.slice(0, line.length - 10))
const log = assistantLog('msg-1', { input_tokens: 0 })
expect(index.patch(log)).toBe(false)
appendFileSync(path, line.slice(line.length - 10))
expect(index.patch(log)).toBe(true)
expect(log.message.usage?.input_tokens).toBe(5)
})
it('switches to a resumed session transcript without replaying history', () => {
const dir = mkdtempSync(join(tmpdir(), 'hapi-usage-'))
writeFileSync(join(dir, 'session-2.jsonl'), assistantLine('old-msg', { input_tokens: 7 }))
const index = new TranscriptUsageIndex(dir, 'session-2')
appendFileSync(join(dir, 'session-2.jsonl'), assistantLine('new-msg', { input_tokens: 11 }))
expect(index.patch(assistantLog('old-msg', { input_tokens: 0 }))).toBe(false)
expect(index.patch(assistantLog('new-msg', { input_tokens: 0 }))).toBe(true)
})
it('patches before the delayed outgoing queue sends', async () => {
const dir = mkdtempSync(join(tmpdir(), 'hapi-usage-'))
const index = new TranscriptUsageIndex(dir, 'session-1')
const sent: ReturnType<typeof assistantLog>[] = []
const queue = new OutgoingMessageQueue((logMessage) => {
index.patch(logMessage)
sent.push(logMessage as ReturnType<typeof assistantLog>)
})
const log = {
...assistantLog('msg-1', { input_tokens: 0, output_tokens: 0 }),
message: {
...assistantLog('msg-1').message,
content: [{ type: 'text', text: 'hello' }],
usage: { input_tokens: 0, output_tokens: 0 }
}
}
queue.enqueue(log, { delay: 200 })
setTimeout(() => {
appendFileSync(join(dir, 'session-1.jsonl'), assistantLine('msg-1', {
input_tokens: 120,
cache_read_input_tokens: 8000
}))
}, 60)
await new Promise((resolve) => setTimeout(resolve, 350))
expect(sent).toHaveLength(1)
expect(sent[0]!.message.usage).toMatchObject({ input_tokens: 120, cache_read_input_tokens: 8000 })
})
})
describe('hasUsageSignal', () => {
it('treats only positive token counts as real samples', () => {
expect(hasUsageSignal(undefined)).toBe(false)
expect(hasUsageSignal({ input_tokens: 0, output_tokens: 0 })).toBe(false)
expect(hasUsageSignal({ cache_read_input_tokens: 1 })).toBe(true)
expect(hasUsageSignal({ output_tokens: 3 })).toBe(true)
})
})
+147
View File
@@ -0,0 +1,147 @@
import { existsSync, openSync, closeSync, readSync, statSync } from 'node:fs'
import { join } from 'node:path'
type UsageRecord = Record<string, unknown>
/** Any non-zero token field makes a usage sample authoritative. */
export function hasUsageSignal(usage: UsageRecord | null | undefined): boolean {
if (!usage) return false
for (const key of ['input_tokens', 'output_tokens', 'cache_read_input_tokens', 'cache_creation_input_tokens']) {
const value = usage[key]
if (typeof value === 'number' && value > 0) return true
}
return false
}
function isAssistantLogMessage(value: unknown): value is {
type: string
message?: { id?: unknown; usage?: UsageRecord }
} {
return typeof value === 'object' && value !== null
&& (value as { type?: unknown }).type === 'assistant'
}
/**
* Claude Code 2.1.3xx writes real per-call `usage` to its transcript but the
* stream-json `assistant` messages HAPI relays carry all-zero usage (verified
* with the OpenCode Go gateway: transcript has input/cache tokens, the SDK
* message has zeros). The transcript entry lands ~100 ms later, so the remote
* launcher delays zero-usage assistant messages and patches the usage in right
* before sending.
*
* Only the main transcript is read: sidechain usage must not drive the parent
* context meter, and the reducer already ignores sidechain rows.
*/
export class TranscriptUsageIndex {
private sessionId: string | null
/** Bytes already consumed; starts at EOF so resumed history is not re-parsed. */
private offset: number
/** Trailing partial line (Claude Code has not flushed the newline yet). */
private carry = ''
private usageByMessageId = new Map<string, UsageRecord>()
constructor(private readonly projectDir: string, sessionId: string | null) {
this.sessionId = sessionId
this.offset = this.currentFileSize()
}
get path(): string | null {
return this.sessionId ? join(this.projectDir, `${this.sessionId}.jsonl`) : null
}
updateSessionId(sessionId: string | null): void {
if (sessionId === this.sessionId) return
this.sessionId = sessionId
this.offset = this.currentFileSize()
this.carry = ''
this.usageByMessageId.clear()
}
/**
* Replace an all-zero assistant usage with the transcript's real sample.
* Returns true when the message was patched.
*/
patch(logMessage: unknown): boolean {
if (!isAssistantLogMessage(logMessage)) return false
const message = logMessage.message
if (!message || typeof message.id !== 'string') return false
const current = message.usage
if (hasUsageSignal(current)) return false
const found = this.lookup(message.id)
if (!found) return false
message.usage = { ...(current ?? {}), ...found }
return true
}
private lookup(messageId: string): UsageRecord | null {
const cached = this.usageByMessageId.get(messageId)
if (cached) return cached
this.readNewLines()
return this.usageByMessageId.get(messageId) ?? null
}
private currentFileSize(): number {
const path = this.path
if (!path) return 0
try {
return existsSync(path) ? statSync(path).size : 0
} catch {
return 0
}
}
private readNewLines(): void {
const path = this.path
if (!path) return
let size: number
try {
size = statSync(path).size
} catch {
return
}
if (size < this.offset) {
// Truncated/replaced transcript: start over rather than seeking past EOF.
this.offset = 0
this.carry = ''
this.usageByMessageId.clear()
}
if (size === this.offset) return
const length = size - this.offset
const buffer = Buffer.allocUnsafe(length)
let fd: number | null = null
try {
fd = openSync(path, 'r')
const read = readSync(fd, buffer, 0, length, this.offset)
this.offset += read
this.consume(buffer.subarray(0, read).toString('utf8'))
} catch {
// A transient read error must not break message delivery.
} finally {
if (fd !== null) closeSync(fd)
}
}
private consume(chunk: string): void {
const text = this.carry + chunk
const lines = text.split('\n')
this.carry = lines.pop() ?? ''
for (const line of lines) {
if (!line.includes('"usage"')) continue
let entry: any
try {
entry = JSON.parse(line)
} catch {
continue
}
if (entry?.type !== 'assistant') continue
const message = entry.message
const id = message?.id
const usage = message?.usage
if (typeof id === 'string' && hasUsageSignal(usage)) {
this.usageByMessageId.set(id, usage)
}
}
}
}