@zvada/agent-server 0.3.7-replay.1 → 0.3.8

package/CHANGELOG.md

@@ -1,6 +1,17 @@
 # Changelog
 
-## 0.3.7-replay.1
+## 0.3.8
+
+- Report each Claude turn's cost as the increase in the SDK's cumulative query cost. Preserve the native total in raw diagnostics, reset the baseline with a fresh query or conversation reset, and keep unknown cost distinct from reported zero.
+
+## 0.3.7
+
+- 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.
+
+- Preserve per-turn harness, configured model and thinking level in lifecycle events, run summaries and the canonical conversation fold.
+- Keep primary model reports separate from requested aliases; collect Claude message models and Codex routing targets without attributing subagent models to the main run.
+- Execution metadata is an explicit allowlist and contains no credentials, environment variables or working-directory paths.
 
 - Add `AgentServerClient.onEventGap` for consumers using `startTurn` and `onEvent`.
   Missing replay data and server restarts are reported before surviving events.

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-replay.1",
+	"version": "0.3.8",
 	"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;
@@ -79,7 +83,7 @@ type ClaudeMessage =
 	| { type: "turn_interrupted" }
 	| {
 			type: "assistant";
-			message?: { content?: ContentBlock[]; usage?: RawUsage };
+			message?: { content?: ContentBlock[]; usage?: RawUsage; model?: string };
 			parent_tool_use_id?: string | null;
 	  }
 	| { type: "user"; message?: { content?: ContentBlock[] | string } }
@@ -89,6 +93,8 @@ type ClaudeMessage =
 			usage?: RawUsage;
 			modelUsage?: Record<string, { contextWindow?: number }>;
 			total_cost_usd?: number;
+			/** Per-turn delta from the generator tap; null means unreported. */
+			turn_cost_usd?: number | null;
 			stop_reason?: string | null;
 			is_error?: boolean;
 	  };
@@ -227,6 +233,7 @@ export class ClaudeCodeTransformer implements EventTransformer<unknown> {
 	private hasStreamed = false;
 
 	private usage: TokenUsage = { ...DEFAULT_TOKEN_USAGE };
+	private readonly reportedModels = new Set<string>();
 	private stopReason?: StopReason;
 	private finishReason?: string;
 	private cost?: number;
@@ -287,6 +294,7 @@ export class ClaudeCodeTransformer implements EventTransformer<unknown> {
 				: undefined);
 		return {
 			usage: this.usage,
+			...(this.reportedModels.size && { reportedModels: [...this.reportedModels] }),
 			stopReason: this.stopReason,
 			finishReason: this.finishReason,
 			cost: this.cost,
@@ -308,6 +316,7 @@ export class ClaudeCodeTransformer implements EventTransformer<unknown> {
 	 * skip the duplicate. Otherwise emit its content blocks as finalized parts.
 	 */
 	private handleAssistant(msg: Extract<ClaudeMessage, { type: "assistant" }>): AdapterEvent[] {
+		if (!msg.parent_tool_use_id && msg.message?.model) this.reportedModels.add(msg.message.model);
 		// Context gauge: every top-level model message carries fresh usage (the
 		// sub-agent's context is its own and would misreport the session's).
 		const gauge: AdapterEvent[] =
@@ -496,16 +505,23 @@ 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,
+					}),
 				},
 			};
 		}
-		if (typeof msg.total_cost_usd === "number") this.cost = msg.total_cost_usd;
+		this.cost = "turn_cost_usd" in msg ? (msg.turn_cost_usd ?? undefined) : msg.total_cost_usd;
 		this.finishReason = msg.stop_reason ?? msg.subtype ?? this.finishReason;
 		this.stopReason = mapClaudeStopReason(msg.stop_reason, msg.subtype);
 		if (msg.subtype && msg.subtype !== "success") {

package/src/core/agents/claude-code/generator-session.ts

@@ -100,6 +100,8 @@ export class ClaudeGeneratorSession {
 	/** Resolved once at spawn; re-merged into every hot-swap. */
 	private sdkServers?: SdkMcpServers;
 	private nativeSessionId: string | null = null;
+	/** SDK cost is cumulative within this query; token usage is already per turn. */
+	private cumulativeCost: number | undefined = 0;
 
 	private currentTap: AsyncQueue<SDKMessage> | null = null;
 	private readonly idleWaiters: Array<() => void> = [];
@@ -284,8 +286,26 @@ export class ClaudeGeneratorSession {
 				if (event.type === "system" && event.subtype === "init" && event.session_id) {
 					this.nativeSessionId = event.session_id;
 				}
-				this.currentTap?.push(event);
-				if (event.type === "result") this.onTurnComplete();
+				if (event.type === "conversation_reset") this.cumulativeCost = 0;
+				if (event.type === "result") {
+					// Keep the native total intact for raw diagnostics. A crash can
+					// report a zeroed total; that does not establish this turn's cost.
+					const result = {
+						...event,
+						turn_cost_usd:
+							this.cumulativeCost !== undefined && event.total_cost_usd >= this.cumulativeCost
+								? event.total_cost_usd - this.cumulativeCost
+								: null,
+					};
+					this.cumulativeCost =
+						this.cumulativeCost !== undefined && event.total_cost_usd < this.cumulativeCost
+							? undefined
+							: event.total_cost_usd;
+					this.currentTap?.push(result);
+					this.onTurnComplete();
+				} else {
+					this.currentTap?.push(event);
+				}
 			}
 		} catch (err) {
 			this.currentTap?.fail(err);

package/src/core/agents/codex-app-server/adapter.ts

@@ -47,6 +47,7 @@ interface Notification {
 		error?: { message?: string; additionalDetails?: string | null };
 		willRetry?: boolean;
 		message?: string;
+		toModel?: string;
 	};
 }
 
@@ -55,6 +56,7 @@ export class CodexAppServerTransformer implements EventTransformer<unknown> {
 	private readonly partByItem = new Map<string, Part>();
 
 	private usage: TokenUsage = { ...DEFAULT_TOKEN_USAGE };
+	private readonly reportedModels = new Set<string>();
 	private stopReason?: StopReason;
 	private finishReason?: string;
 	private error?: string;
@@ -66,6 +68,9 @@ export class CodexAppServerTransformer implements EventTransformer<unknown> {
 	process(raw: unknown): AdapterEvent[] {
 		const { method, params } = raw as Notification;
 		switch (method) {
+			case "model/rerouted":
+				if (params.toModel) this.reportedModels.add(params.toModel);
+				return [];
 			case "item/started":
 				return params.item ? this.openItem(params.item) : [];
 			case "item/completed":
@@ -105,6 +110,7 @@ export class CodexAppServerTransformer implements EventTransformer<unknown> {
 	finish(): TransformResult {
 		return {
 			usage: this.usage,
+			...(this.reportedModels.size && { reportedModels: [...this.reportedModels] }),
 			stopReason: this.stopReason,
 			finishReason: this.finishReason,
 			error: this.error,

package/src/core/agents/types.ts

@@ -32,6 +32,8 @@ export type AdapterEvent =
 /** Terminal result of a turn, surfaced on `turn.ended`. */
 export interface TransformResult {
 	usage: TokenUsage;
+	/** Models observed on the primary run, excluding subagents and configured defaults. */
+	reportedModels?: string[];
 	/** Normalized terminal status, when the harness reported one. The engine
 	 * overrides with `cancelled`/`error` based on what it observed. */
 	stopReason?: StopReason;

package/src/core/runtime/agent-runtime.ts

@@ -14,6 +14,7 @@ import type {
 	RunRequest,
 	StopReason,
 	TokenUsage,
+	TurnExecution,
 } from "../../protocol/index.ts";
 import { DEFAULT_TOKEN_USAGE, generateUUIDv7 } from "../../protocol/index.ts";
 import type { AgentExecuteOptions, CancelResult, PermissionDecision } from "../agents/base.ts";
@@ -28,6 +29,7 @@ export interface RunSummary {
 	sessionId: string;
 	turnId: string;
 	harness: AgentHarness;
+	execution: TurnExecution;
 	/** Native session/thread id to persist for a future resume. */
 	nativeSessionId?: string;
 	/** When the turn requested a resume: whether the harness honored it. */
@@ -239,7 +241,12 @@ export class AgentRuntime {
 		const { sessionId, turnId, input, config } = request;
 		const agent = this.registry.getAgent(config.harness);
 		const transformer = this.registry.getAdapter(config.harness)({ sessionId });
-		const processor = new EventProcessor(sessionId, turnId, { model: config.model });
+		const execution: TurnExecution = {
+			harness: config.harness,
+			...(config.model !== undefined && { model: config.model }),
+			...(config.thinkingLevel !== undefined && { thinkingLevel: config.thinkingLevel }),
+		};
+		const processor = new EventProcessor(sessionId, turnId, execution);
 
 		// Isolate sink failures: a misbehaving transport must never break the
 		// turn's lifecycle bracketing (turn.started ... turn.ended).
@@ -374,7 +381,7 @@ export class AgentRuntime {
 			await Promise.all([...settles, ...settleEmits]);
 		};
 
-		await emit({ type: "turn.started", turnId, sessionId, timestamp: Date.now() });
+		await emit({ type: "turn.started", turnId, sessionId, execution, timestamp: Date.now() });
 
 		// The user echo (spec §7.2): the submitted input goes back onto the stream
 		// as a complete user message (outputIndex 0) before any harness output, so
@@ -474,6 +481,10 @@ export class AgentRuntime {
 			nativeSessionId,
 			...(resumed !== undefined && { resumed }),
 			usage: result.usage ?? DEFAULT_TOKEN_USAGE,
+			execution: {
+				...execution,
+				...(result.reportedModels && { reportedModels: result.reportedModels }),
+			},
 			stopReason,
 			finishReason: result.finishReason,
 			cost: result.cost,

package/src/core/runtime/event-processor.ts

@@ -4,7 +4,14 @@ import {
 	echoMessageId,
 	generateUUIDv7,
 } from "../../protocol/index.ts";
-import type { AgentInput, Delta, LifecycleEvent, Part, StopReason } from "../../protocol/index.ts";
+import type {
+	AgentInput,
+	Delta,
+	LifecycleEvent,
+	Part,
+	StopReason,
+	TurnExecution,
+} from "../../protocol/index.ts";
 import type { AdapterEvent, TransformResult } from "../agents/types.ts";
 
 /** Where a part lives on the wire — fixed at first emission for the whole turn. */
@@ -36,7 +43,7 @@ export class EventProcessor {
 	constructor(
 		private readonly sessionId: string,
 		private readonly turnId: string,
-		private readonly meta: { model?: string } = {},
+		private readonly execution?: TurnExecution,
 	) {}
 
 	/**
@@ -125,6 +132,12 @@ export class EventProcessor {
 			finishReason: result.finishReason,
 			tokens: result.usage,
 			cost: result.cost,
+			...(this.execution && {
+				execution: {
+					...this.execution,
+					...(result.reportedModels && { reportedModels: result.reportedModels }),
+				},
+			}),
 			error:
 				result.error && !result.cancelled
 					? { category: classifyError(result.error), message: result.error }
@@ -160,7 +173,7 @@ export class EventProcessor {
 			// user-authored. Gating here keeps it off every user message; every
 			// assistant message (top-level AND parented sub-agent output) keeps it,
 			// since `config.model` is the only per-turn model signal available.
-			...(role === "assistant" && this.meta.model && { model: this.meta.model }),
+			...(role === "assistant" && this.execution?.model && { model: this.execution?.model }),
 			timestamp: Date.now(),
 		};
 	}

package/src/protocol/execution.ts

@@ -0,0 +1,16 @@
+import { z } from "zod";
+import { AgentHarnessSchema } from "./harness.ts";
+import { ThinkingLevelSchema } from "./thinking.ts";
+
+/** Safe, per-turn execution metadata. Never serialize the full RunConfig here. */
+export const TurnExecutionSchema = z.object({
+	harness: AgentHarnessSchema,
+	/** Model id/alias passed to the harness. Absent means the harness chose its default. */
+	model: z.string().optional(),
+	/** Requested setting, not a measurement of the model's internal reasoning. */
+	thinkingLevel: ThinkingLevelSchema.optional(),
+	/** Distinct models reported by the primary harness during this turn, in observation order.
+	 * Excludes subagents. Absence means unreported, never a fallback to the requested alias. */
+	reportedModels: z.array(z.string()).optional(),
+});
+export type TurnExecution = z.infer<typeof TurnExecutionSchema>;

package/src/protocol/index.ts

@@ -17,6 +17,7 @@ export * from "./harness.ts";
 export * from "./thinking.ts";
 export * from "./models.ts";
 export * from "./config.ts";
+export * from "./execution.ts";
 export * from "./lifecycle.ts";
 export * from "./stop-reasons.ts";
 export * from "./seq-cursor.ts";

package/src/protocol/lifecycle.ts

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import { ErrorCategorySchema, ErrorInfoSchema } from "./errors.ts";
+import { TurnExecutionSchema } from "./execution.ts";
 import { isKnownLifecycleEventType } from "./guards.ts";
 import { AgentHarnessSchema } from "./harness.ts";
 import { MetaSchema } from "./meta.ts";
@@ -168,6 +169,7 @@ export const TurnStartedEventSchema = z.object({
 	type: z.literal("turn.started"),
 	sessionId: z.string(),
 	turnId: z.string(),
+	execution: TurnExecutionSchema.optional(),
 	timestamp: EpochMsSchema,
 	_meta: MetaSchema,
 });
@@ -177,6 +179,7 @@ export const TurnEndedEventSchema = z.object({
 	type: z.literal("turn.ended"),
 	sessionId: z.string(),
 	turnId: z.string(),
+	execution: TurnExecutionSchema.optional(),
 	/** Normalized terminal status — `cancelled` and `error` are first-class. */
 	stopReason: StopReasonSchema,
 	/** Raw provider finish string (`end_turn`, `completed`, …), always preserved when reported. */

package/src/protocol/reduce.ts

@@ -2,6 +2,7 @@ import { z } from "zod";
 // The package ships raw .ts — keep imports exactly-used, or every consumer
 // compiling with noUnusedLocals inherits the noise as build errors.
 import { ErrorCategorySchema, ErrorInfoSchema } from "./errors.ts";
+import { TurnExecutionSchema } from "./execution.ts";
 import { isUnknownEvent } from "./guards.ts";
 import { AgentHarnessSchema } from "./harness.ts";
 import {
@@ -115,6 +116,7 @@ export type TimelineEntry = z.infer<typeof TimelineEntrySchema>;
 
 export const ConversationTurnSchema = z.object({
 	turnId: z.string(),
+	execution: TurnExecutionSchema.optional(),
 	/** Derived view state, not wire vocabulary. */
 	status: z.enum(["active", "ended"]),
 	stopReason: StopReasonSchema.optional(),
@@ -496,6 +498,7 @@ function reduceWith(
 			if (existing !== -1) return state; // replay overlap — the turn is known
 			const turn: ConversationTurn = {
 				turnId: event.turnId,
+				...(event.execution !== undefined && { execution: event.execution }),
 				status: "active",
 				errors: [],
 				startedAt: event.timestamp,
@@ -603,6 +606,7 @@ function reduceWith(
 				...base,
 				status: "ended",
 				stopReason: event.stopReason,
+				...(event.execution !== undefined && { execution: event.execution }),
 				...(event.finishReason !== undefined && { finishReason: event.finishReason }),
 				...(event.tokens !== undefined && { tokens: event.tokens }),
 				...(event.cost !== undefined && { cost: event.cost }),