@zvada/agent-server 0.3.7-attribution.1 → 0.3.7-attribution.2

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 0.3.7-attribution.2
+
+- Retain Claude's reported 5-minute and 1-hour cache-creation token counts in the existing token usage contract. Missing durations stay absent and reported zeroes are preserved.
+- Document the shared cache accounting contract for custom harness adapters, including totals versus subsets and reported cost.
+
 ## 0.3.7-attribution.1
 
 - Preserve per-turn harness, configured model and thinking level in lifecycle events, run summaries and the canonical conversation fold.

package/docs/harnesses.md

@@ -82,6 +82,38 @@ The protocol was checked against Codex CLI 0.153.4 and the
   harness's unparsed event, for migration/debugging/fixture-recording. `data`
   has **no stability guarantees** and is off by default.
 
+## Token and cache accounting
+
+Every adapter uses the same `TokenUsage` on `turn.ended.tokens`. A custom
+adapter maps its provider's counts into this contract; storage and consumers
+do not need a new schema for each harness.
+
+| Field | Meaning |
+| --- | --- |
+| `input` | Uncached input tokens |
+| `output` | Output tokens, including any reasoning tokens |
+| `reasoning` | Reported reasoning portion of output, when available |
+| `cache.read` | Input tokens reused from the provider's cache |
+| `cache.write` | Input tokens written to the provider's cache |
+| `cache.writeEphemeral5m` | Reported 5-minute portion of cache writes |
+| `cache.writeEphemeral1h` | Reported 1-hour portion of cache writes |
+| `turn.ended.cost` | Harness-reported USD cost, when available |
+
+Input, cache reads and cache writes are disjoint. If the native input total
+already includes cached tokens, subtract them once in the adapter. Reasoning
+is part of output and duration buckets are parts of cache writes; do not add
+those subsets to the totals again. Use the shipped `addTokenUsage` helper.
+
+Cache values count tokens, not cache entries. Duration buckets describe creation
+usage reported for that turn, not whether a cache entry is still alive. Leave
+unreported duration buckets and cost absent; a reported zero stays zero. Do not
+infer cache durations, savings or prices from the harness name. Final native
+turn totals take precedence over intermediate message usage.
+
+`session.usage` describes context occupancy and is not a source for per-turn
+cache accounting. An ACP/custom agent that exposes only this gauge cannot
+provide the cache breakdown without an additional native usage report.
+
 ## Known limitations (roadmap)
 
 - **MCP servers** are wired for Claude only; Codex MCP passthrough is pending

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@zvada/agent-server",
-	"version": "0.3.7-attribution.1",
+	"version": "0.3.7-attribution.2",
 	"description": "Harness-agnostic agent execution engine: run Claude Code, Codex (SDK/CLI + app-server), and any ACP agent behind one interface with a normalized event stream, multi-turn sessions, and resume. Root export is the wire contract; /core, /server, /client are the seats.",
 	"license": "MIT",
 	"type": "module",

package/src/core/agents/claude-code/adapter.ts

@@ -55,6 +55,10 @@ interface RawUsage {
 	output_tokens?: number;
 	cache_read_input_tokens?: number;
 	cache_creation_input_tokens?: number;
+	cache_creation?: {
+		ephemeral_5m_input_tokens?: number;
+		ephemeral_1h_input_tokens?: number;
+	};
 }
 interface ContentBlock {
 	type: string;
@@ -499,12 +503,19 @@ export class ClaudeCodeTransformer implements EventTransformer<unknown> {
 	private captureResult(msg: Extract<ClaudeMessage, { type: "result" }>): AdapterEvent[] {
 		this.sawResult = true;
 		if (msg.usage) {
+			const creation = msg.usage.cache_creation;
 			this.usage = {
 				input: msg.usage.input_tokens ?? 0,
 				output: msg.usage.output_tokens ?? this.usage.output,
 				cache: {
 					read: msg.usage.cache_read_input_tokens ?? 0,
 					write: msg.usage.cache_creation_input_tokens ?? 0,
+					...(creation?.ephemeral_5m_input_tokens !== undefined && {
+						writeEphemeral5m: creation.ephemeral_5m_input_tokens,
+					}),
+					...(creation?.ephemeral_1h_input_tokens !== undefined && {
+						writeEphemeral1h: creation.ephemeral_1h_input_tokens,
+					}),
 				},
 			};
 		}