symposium 3.2.0 → 3.3.0

package/Agent.js

@@ -672,8 +672,14 @@ ${context_string}
 			let step = await it.next();
 			while (!step.done) {
 				const delta = step.value;
-				if (delta && delta.type === 'text_delta')
+				if (delta && delta.type === 'text_delta') {
 					yield {type: 'chunk', content: delta.content};
+				} else if (delta && delta.type === 'usage') {
+					// Last reported usage rides on thread state too, so it survives
+					// storeState and is readable at turn_end / after a reload.
+					thread.state.usage = delta.content;
+					yield {type: 'usage', content: delta.content};
+				}
 				step = await it.next();
 			}
 			messages = step.value;

package/CLAUDE.md

@@ -26,7 +26,7 @@ The execution core. After Phase 6, `agent.message()` is a non-generator dispatch
 
 `message(content, thread)` accepts three input shapes (Phase 3): a plain `string`, a `ContentBlock[]`, or an `AsyncIterable<string | ContentBlock | ContentBlock[] | ControlMessage>`. The first two behave as they always have — one user turn, one model loop, done. An async iterable enables streaming input: the agent drains the iterable into the initial user message (stopping on a `{type:'submit'}` control message, on iterable close, or once at least one content piece has arrived and the next read would block), kicks off the loop, then keeps reading concurrently. New content items pushed during a turn are queued and inserted as a user message at the next inter-turn boundary. A `{type:'cancel'}` control message terminates the loop gracefully after the in-flight turn. `{type:'auth', id, decision}` control messages carry tool-authorization responses — see the tool-authorization paragraph below. Use `createInputChannel()` (exported from `index.js`) for a simple promise-queue-backed `AsyncIterable` with `send(item)` / `close()` methods; under the hood it's implemented in `InputChannel.js`. For streaming input, the chat agent does NOT terminate after a no-tool-call turn — it waits for the next message; the run ends only when the iterable closes (or cancel is received).
 
-- `chat` — yields the full event set (`start`, `chunk`, `output`, `reasoning`, `tool`, `tool_response`, `tools_auth`, `retry`, `turn_end`, `end`). `turn_end` fires after each completed turn (after the LLM finishes a response with no more tool calls), regardless of streaming vs single-shot mode — consumers use it to detect turn boundaries within a streaming run, where `start`/`end` only bracket the whole run. If `response_schema` is set, the final assistant message is parsed against it and a `{type:'result', value}` event is yielded before `end`; the run terminates after the schema-conforming answer (no further turns).
+- `chat` — yields the full event set (`start`, `chunk`, `output`, `reasoning`, `tool`, `tool_response`, `tools_auth`, `retry`, `usage`, `turn_end`, `end`). `turn_end` fires after each completed turn (after the LLM finishes a response with no more tool calls), regardless of streaming vs single-shot mode — consumers use it to detect turn boundaries within a streaming run, where `start`/`end` only bracket the whole run. If `response_schema` is set, the final assistant message is parsed against it and a `{type:'result', value}` event is yielded before `end`; the run terminates after the schema-conforming answer (no further turns).
 - `utility` — `await agent.message(...)` resolves to the parsed value. With no `response_schema`, the value is the raw assistant text. With `response_schema` set, the value is the parsed JSON object: structured-output-capable models with ≤100 properties use `response_format: json_schema`; otherwise the agent falls back to a forced tool call (synthetic name `'response'`) and parses its arguments. See `convertFunctionToResponseFormat()` for the OpenAI-specific schema constraints (all properties forced to required, `additionalProperties: false`). The legacy `agent.utility = {type, function, parameters}` shape was removed in Phase 6 — use `response_schema` (a raw JSON schema) instead. `response_schema` is independent of `type` and works on chat agents too.
 
 **`response_schema` + toolkits (tool use *then* structured output).** When an agent has BOTH `response_schema` and toolkit tools, the schema is NOT forced up-front (forcing would block the model from calling its tools first). Instead `execute()` advertises an extra `response` tool *alongside* the real ones via `completion_options.append_tools` (merged by `Model.parseOptions` — additive, unlike `options.tools` which replaces). The model uses its real tools across turns and, when ready, calls `response` with the final schema-conforming answer; `handleCompletion` treats a `response` call as terminal (→ `afterHandle` → `{type:'result', value}`) and every other call as a normal tool invocation (`response` is a **reserved tool name** when `response_schema` is set). The forced-tool / `response_format` paths above apply only when the agent has **no** toolkits, so existing tool-less utility agents are unchanged. This is what lets a `chat` agent self-search and still return a validated object (consume it by draining for the `result` event).
@@ -40,8 +40,8 @@ Within a single LLM turn, tools are executed **sequentially** (in `tools_to_call
 ### Models (`Models/*.js`, base in `Model.js`)
 
 Every provider extends `Model` and implements:
-- `getModels()` — returns `Map<label, definition>` where definition flags capabilities: `tools`, `structured_output`, `audio`, `image_generation`, `tokens` (context window), `tiktoken` (encoding name).
-- `generate(model, thread, tools, options)` — **async generator** (Phase 1 of v3 refactor). Yields streaming deltas during generation and `return`s the final assembled `Message[]`. Delta union: `{type: 'text_delta', content}`, `{type: 'reasoning_delta', content}`, `{type: 'tool_call', content: {id?, name, arguments}}` (emitted complete), `{type: 'image', content, meta}`. `Agent.generateCompletion()` (Phase 2) is itself an async generator: it forwards `text_delta` to consumers as `{type:'chunk', content}` events and returns the assembled `Message[]`. Other delta types are not forwarded yet and only contribute to the final assembly. Tool-call deltas from chat-completions-style APIs (OpenAI legacy, Groq) are accumulated per `index` and yielded once at end-of-stream.
+- `getModels()` — returns `Map<label, definition>` where definition flags capabilities: `tools`, `structured_output`, `audio`, `image_generation`, `reasoning` (the OpenAI Responses adapter only sends `include: ['reasoning.encrypted_content']` + `reasoning: {summary}` when set — non-reasoning models like `gpt-4o` reject them), `tokens` (context window), `tiktoken` (encoding name).
+- `generate(model, thread, tools, options)` — **async generator** (Phase 1 of v3 refactor). Yields streaming deltas during generation and `return`s the final assembled `Message[]`. Delta union: `{type: 'text_delta', content}`, `{type: 'reasoning_delta', content}`, `{type: 'tool_call', content: {id?, name, arguments}}` (emitted complete), `{type: 'image', content, meta}`, `{type: 'usage', content: {input, output, cached, context}}` (once at end-of-stream, via `Model.usageDelta()`, only when the provider reported usage — `input` includes `cached`; `context` = `input + output`; Anthropic's cache read/creation tokens are folded back into `input` since the API reports them outside `input_tokens`). `Agent.generateCompletion()` (Phase 2) is itself an async generator: it forwards `text_delta` to consumers as `{type:'chunk', content}` events, forwards `usage` as `{type:'usage', content}` (also stamping `thread.state.usage`, last call wins), and returns the assembled `Message[]`. Other delta types are not forwarded yet and only contribute to the final assembly. Tool-call deltas from chat-completions-style APIs (OpenAI legacy, Groq) are accumulated per `index` and yielded once at end-of-stream; on those APIs the usage chunk arrives last with empty `choices` (OpenAI/DeepSeek need `stream_options: {include_usage: true}`, sent by `LegacyOpenAIModel`; Groq ships it natively under `x_groq.usage`).
 - Optionally `countTokens(thread)` (used by `Summarizer`).
 
 A model definition's `tools: true` means the provider supports native tool calling. When false, `Agent.parseTools()` falls back to parsing `\`\`\`\nCALL <name>\n<json>\n\`\`\`` blocks out of plain text — the prompt for this is built by `Model.promptFromTools()` (in Italian; do not translate without verifying the existing parser still matches).
@@ -79,6 +79,7 @@ Two distinct concepts share the word "context":
 | `{type:'tool_response', id, name, toolkit, success, response?, error?}` | tool result | After tool returns or throws. `id` matches the `tool` event's id; `name` is the tool name (same as the `tool` event); `toolkit` is the owning toolkit's name. |
 | `{type:'tools_auth', id, tools}` | uuid + pending tool calls | When `tool.authorize()` returns false; resume by sending `{type:'auth', id, decision}` on the input channel |
 | `{type:'retry', attempt, reason}` | 1-indexed retry number + error message | Yielded only when an error occurs AFTER at least one `chunk` has been streamed for the current turn (hybrid retry, Phase 5). Errors before any output are retried silently. |
+| `{type:'usage', content}` | `{input, output, cached, context}` | Provider-reported token usage, one per LLM call (so several per turn when tools run). `context` = `input + output` — tokens occupying the model context after the call. Mirrored on `thread.state.usage` (last call wins, persisted with the thread). Absent when the provider reports no usage. |
 | `{type:'result', value}` | parsed value | Utility agents only |
 | `{type:'turn_end', thread}` | thread object | Yielded after a turn completes (the LLM finished a response with no more tool calls). Fires once per turn whether the run continues (streaming, awaiting next user message) or ends. Use this — not `end` — to detect per-turn boundaries in a streaming session. |
 | `{type:'end', thread}` | thread object | Always yielded, even on throw (yielded from a `finally`) |

package/Model.js

@@ -15,9 +15,22 @@ export default class Model {
 		//   {type: 'reasoning_delta', content: string}
 		//   {type: 'tool_call',       content: {id?, name, arguments}}
 		//   {type: 'image',           content: <image-block-content>, meta}
+		//   {type: 'usage',           content: {input, output, cached, context}}
+		// The usage delta is yielded once at end of stream (via usageDelta()),
+		// only when the provider reported token usage for the call.
 		return null;
 	}
 
+	// Normalized token usage for one LLM call. `input` is the full prompt size
+	// (cache included), `cached` the portion of it served from cache, `context`
+	// the tokens occupying the model context after the call (input + output).
+	usageDelta(input, output, cached = 0) {
+		input = input || 0;
+		output = output || 0;
+		cached = cached || 0;
+		return {type: 'usage', content: {input, output, cached, context: input + output}};
+	}
+
 	async countTokens(thread) {
 		throw new Error('countTokens not implemented in this model');
 	}

package/Models/AnthropicModel.js

@@ -153,6 +153,14 @@ export default class AnthropicModel extends Model {
 
 			const message = await stream.finalMessage();
 
+			if (message.usage) {
+				// Anthropic reports cached tokens OUTSIDE input_tokens: the real
+				// prompt size is input + cache reads + cache writes.
+				const cached = message.usage.cache_read_input_tokens || 0;
+				const input = (message.usage.input_tokens || 0) + cached + (message.usage.cache_creation_input_tokens || 0);
+				yield this.usageDelta(input, message.usage.output_tokens, cached);
+			}
+
 			const message_content = [];
 			if (message.content) {
 				for (let m of message.content) {

package/Models/GrokModel.js

@@ -7,21 +7,31 @@ export default class GrokModel extends OpenAIModel {
 			['grok-4-1-fast-reasoning', {
 				name: 'grok-4-1-fast-reasoning',
 				tokens: 2000000,
+				reasoning: true,
 				tools: true,
 			}],
 			['grok-4-1-fast-non-reasoning', {
 				name: 'grok-4-1-fast-non-reasoning',
 				tokens: 2000000,
+				reasoning: true,
 				tools: true,
 			}],
 			['grok-4-20-fast-reasoning', {
 				name: 'grok-4.20-beta-0309-reasoning',
 				tokens: 2000000,
+				reasoning: true,
 				tools: true,
 			}],
 			['grok-4-20-fast-non-reasoning', {
 				name: 'grok-4.20-beta-0309-non-reasoning',
 				tokens: 2000000,
+				reasoning: true,
+				tools: true,
+			}],
+			['grok-4.5', {
+				name: 'grok-4.5',
+				tokens: 5000000,
+				reasoning: true,
 				tools: true,
 			}],
 		]);
@@ -38,7 +48,7 @@ export default class GrokModel extends OpenAIModel {
 		return this.openai;
 	}
 
-	async generate(model, thread, tools = [], options = {}) {
+	async *generate(model, thread, tools = [], options = {}) {
 		if (options.image_generation) {
 			tools.push({
 				name: 'generate_image',
@@ -56,7 +66,7 @@ export default class GrokModel extends OpenAIModel {
 			});
 		}
 
-		const response = await super.generate(model, thread, tools, options);
+		const response = yield* super.generate(model, thread, tools, options);
 
 		// Check for image generation response
 		if (options.image_generation) {

package/Models/GroqModel.js

@@ -79,10 +79,14 @@ export default class GroqModel extends Model {
 
 		const stream = await this.getGroq().chat.completions.create({...completion_payload, stream: true});
 
-		let fullText = '';
+		let fullText = '', usage = null;
 		const toolBuffer = new Map();
 
 		for await (const chunk of stream) {
+			// Groq ships usage on the final chunk under x_groq — grab it before the delta guard.
+			if (chunk.x_groq?.usage || chunk.usage)
+				usage = chunk.x_groq?.usage || chunk.usage;
+
 			const delta = chunk.choices?.[0]?.delta;
 			if (!delta)
 				continue;
@@ -119,6 +123,9 @@ export default class GroqModel extends Model {
 			yield {type: 'tool_call', content: tc};
 		}
 
+		if (usage)
+			yield this.usageDelta(usage.prompt_tokens, usage.completion_tokens, usage.prompt_tokens_details?.cached_tokens);
+
 		const message_content = [];
 		if (fullText)
 			message_content.push({type: 'text', content: fullText});

package/Models/LegacyOpenAIModel.js

@@ -70,12 +70,16 @@ export default class LegacyOpenAIModel extends Model {
 		if (!completion_payload.tools.length)
 			delete completion_payload.tools;
 
-		const stream = await this.getOpenAi().chat.completions.create({...completion_payload, stream: true});
+		const stream = await this.getOpenAi().chat.completions.create({...completion_payload, stream: true, stream_options: {include_usage: true}});
 
-		let fullText = '';
+		let fullText = '', usage = null;
 		const toolBuffer = new Map();
 
 		for await (const chunk of stream) {
+			// The usage chunk arrives last with empty choices — grab it before the delta guard.
+			if (chunk.usage)
+				usage = chunk.usage;
+
 			const delta = chunk.choices?.[0]?.delta;
 			if (!delta)
 				continue;
@@ -112,6 +116,9 @@ export default class LegacyOpenAIModel extends Model {
 			yield {type: 'tool_call', content: tc};
 		}
 
+		if (usage)
+			yield this.usageDelta(usage.prompt_tokens, usage.completion_tokens, usage.prompt_tokens_details?.cached_tokens ?? usage.prompt_cache_hit_tokens);
+
 		const message_content = [];
 		if (fullText)
 			message_content.push({type: 'text', content: fullText});

package/Models/OllamaModel.js

@@ -90,9 +90,14 @@ export default class OllamaModel extends Model {
 
 		let fullText = '';
 		let fullThinking = '';
+		let usage = null;
 		const toolCalls = [];
 
 		for await (const chunk of stream) {
+			// The final done chunk carries the token counts — grab them before the message guard.
+			if (chunk.prompt_eval_count != null || chunk.eval_count != null)
+				usage = {input: chunk.prompt_eval_count, output: chunk.eval_count};
+
 			const m = chunk.message;
 			if (!m)
 				continue;
@@ -122,6 +127,9 @@ export default class OllamaModel extends Model {
 			}
 		}
 
+		if (usage)
+			yield this.usageDelta(usage.input, usage.output);
+
 		const message_content = [];
 		if (fullThinking)
 			message_content.push({type: 'reasoning', content: fullThinking});

package/Models/OpenAIModel.js

@@ -19,6 +19,7 @@ export default class OpenAIModel extends Model {
 				name: 'gpt-5',
 				tiktoken: 'gpt-4',
 				tokens: 400000,
+				reasoning: true,
 				tools: true,
 				structured_output: true,
 				audio: true,
@@ -28,6 +29,7 @@ export default class OpenAIModel extends Model {
 				name: 'gpt-5-mini',
 				tiktoken: 'gpt-4',
 				tokens: 400000,
+				reasoning: true,
 				tools: true,
 				structured_output: true,
 			}],
@@ -35,6 +37,7 @@ export default class OpenAIModel extends Model {
 				name: 'gpt-5.1',
 				tiktoken: 'gpt-4',
 				tokens: 400000,
+				reasoning: true,
 				tools: true,
 				structured_output: true,
 				audio: true,
@@ -44,6 +47,7 @@ export default class OpenAIModel extends Model {
 				name: 'gpt-5.2',
 				tiktoken: 'gpt-4',
 				tokens: 400000,
+				reasoning: true,
 				tools: true,
 				structured_output: true,
 				audio: true,
@@ -53,6 +57,7 @@ export default class OpenAIModel extends Model {
 				name: 'gpt-5.2-codex',
 				tiktoken: 'gpt-4',
 				tokens: 400000,
+				reasoning: true,
 				tools: true,
 				structured_output: true,
 				audio: false,
@@ -62,6 +67,7 @@ export default class OpenAIModel extends Model {
 				name: 'gpt-5.4',
 				tiktoken: 'gpt-4',
 				tokens: 1000000,
+				reasoning: true,
 				tools: true,
 				structured_output: true,
 				audio: false,
@@ -71,6 +77,7 @@ export default class OpenAIModel extends Model {
 				name: 'gpt-5.5',
 				tiktoken: 'gpt-5',
 				tokens: 1000000,
+				reasoning: true,
 				tools: true,
 				structured_output: true,
 				audio: false,
@@ -80,6 +87,7 @@ export default class OpenAIModel extends Model {
 				name: 'gpt-5.6-luna',
 				tiktoken: 'gpt-5',
 				tokens: 1000000,
+				reasoning: true,
 				tools: true,
 				structured_output: true,
 				audio: false,
@@ -89,6 +97,7 @@ export default class OpenAIModel extends Model {
 				name: 'gpt-5.6-terra',
 				tiktoken: 'gpt-5',
 				tokens: 1000000,
+				reasoning: true,
 				tools: true,
 				structured_output: true,
 				audio: false,
@@ -98,6 +107,7 @@ export default class OpenAIModel extends Model {
 				name: 'gpt-5.6-sol',
 				tiktoken: 'gpt-5',
 				tokens: 1000000,
+				reasoning: true,
 				tools: true,
 				structured_output: true,
 				audio: false,
@@ -156,13 +166,17 @@ export default class OpenAIModel extends Model {
 			model: model.name,
 			input: convertedMessages,
 			store: false,
-			include: ['reasoning.encrypted_content'],
 			tools: apiTools,
-			reasoning: {
-				summary: 'auto',
-			},
 		};
 
+		// Reasoning options are rejected by non-reasoning models (e.g. gpt-4o)
+		if (model.reasoning) {
+			completion_payload.include = ['reasoning.encrypted_content'];
+			completion_payload.reasoning = {
+				summary: 'auto',
+			};
+		}
+
 		if (options.force_tool) {
 			completion_payload.tool_choice = {
 				type: 'function',
@@ -223,6 +237,9 @@ export default class OpenAIModel extends Model {
 
 		const completion = await stream.finalResponse();
 
+		if (completion.usage)
+			yield this.usageDelta(completion.usage.input_tokens, completion.usage.output_tokens, completion.usage.input_tokens_details?.cached_tokens);
+
 		const message_content = [];
 		for (let output of completion.output) {
 			switch (output.type) {

package/README.md

@@ -161,6 +161,7 @@ All events yielded from the generator:
 | `tool_response` | `{id, name, toolkit, success, response?, error?}` | Emitted after the tool returns or throws. `id` matches the `tool` event's id; `name` is the tool name; `toolkit` is the owning toolkit's name. |
 | `tools_auth` | `{id, tools}` | Yielded when authorization is required — see below. |
 | `retry` | `{attempt, reason}` | Only when an error occurs *after* at least one chunk has already streamed for the current turn. |
+| `usage` | `{content: {input, output, cached, context}}` | Token usage reported by the provider after each LLM call (one per call, so several per turn when tools run). `input` is the full prompt size (cache included), `cached` the portion served from cache, `context` = `input + output` — the tokens occupying the model context after the call. Also stored on `thread.state.usage` (last call wins), so it survives persistence and is readable at `turn_end`. Omitted when the provider does not report usage. |
 | `result` | `{value}` | Only when `response_schema` is set — parsed structured answer. |
 | `turn_end` | `{thread}` | After each completed turn (LLM done with no more tool calls). Fires per-turn whether the run continues or ends — use it (not `end`) to detect turn boundaries inside a streaming run. |
 | `end` | `{thread}` | Always yielded last, even on throw. |

package/package.json

@@ -1,7 +1,7 @@
 {
   "type": "module",
   "name": "symposium",
-  "version": "3.2.0",
+  "version": "3.3.0",
   "description": "Agents",
   "main": "index.js",
   "author": "Domenico Giambra",

package/test/agent.test.js

@@ -84,6 +84,32 @@ test('Agent.generateCompletion forwards text_delta as chunks and returns Message
 	assert.deepEqual(value[0].content, [{type: 'text', content: 'Hello world'}]);
 });
 
+test('Agent.generateCompletion forwards usage deltas and stamps thread.state.usage', async () => {
+	const label = 'fake-gen-usage';
+	const usage = {input: 550, output: 30, cached: 400, context: 580};
+	await Symposium.loadModel(new ScriptedModel(label, [{
+		deltas: [
+			{type: 'text_delta', content: 'Hi'},
+			{type: 'usage', content: usage},
+		],
+		messages: [new Message('assistant', [{type: 'text', content: 'Hi'}])],
+	}]));
+
+	const agent = new Agent();
+	agent.default_model = label;
+	await agent.init();
+
+	const thread = await makeThread(agent, label);
+
+	const {deltas} = await drain(agent.generateCompletion(thread));
+
+	assert.deepEqual(deltas, [
+		{type: 'chunk', content: 'Hi'},
+		{type: 'usage', content: usage},
+	]);
+	assert.deepEqual(thread.state.usage, usage);
+});
+
 // ────────────────────────────────────────────────────────────────────────────────
 // Chat happy path
 // ────────────────────────────────────────────────────────────────────────────────

package/test/models/anthropic.test.js

@@ -98,6 +98,35 @@ test('AnthropicModel buffers input_json_delta and yields a complete tool_call',
 	]);
 });
 
+test('AnthropicModel yields a normalized usage delta folding cache tokens into input', async () => {
+	const m = new AnthropicModel();
+	const finalMessage = {
+		content: [{type: 'text', text: 'Hi'}],
+		usage: {
+			input_tokens: 100,
+			cache_read_input_tokens: 400,
+			cache_creation_input_tokens: 50,
+			output_tokens: 30,
+		},
+	};
+	const stream = anthropicMessagesStream(
+		[
+			{type: 'content_block_start', index: 0, content_block: {type: 'text'}},
+			{type: 'content_block_delta', index: 0, delta: {type: 'text_delta', text: 'Hi'}},
+			{type: 'content_block_stop', index: 0},
+		],
+		finalMessage,
+	);
+	installFakeAnthropic(m, stream);
+
+	const {deltas} = await drain(m.generate(buildModelDef(), fakeThread()));
+
+	assert.deepEqual(deltas[deltas.length - 1], {
+		type: 'usage',
+		content: {input: 550, output: 30, cached: 400, context: 580},
+	});
+});
+
 test('AnthropicModel emits reasoning_delta from thinking_delta', async () => {
 	const m = new AnthropicModel();
 	const thinkingBlock = {type: 'thinking', thinking: 'reasoning text'};

package/test/models/groq.test.js

@@ -69,3 +69,18 @@ test('GroqModel accumulates tool_call deltas across chunks', async () => {
 		},
 	]);
 });
+
+test('GroqModel yields a normalized usage delta from the x_groq final chunk', async () => {
+	const m = new GroqModel();
+	installFakeGroq(m, [
+		{choices: [{delta: {content: 'Hi'}}]},
+		{choices: [{delta: {}, finish_reason: 'stop'}], x_groq: {usage: {prompt_tokens: 80, completion_tokens: 20}}},
+	]);
+
+	const {deltas} = await drain(m.generate(buildModelDef(), fakeThread()));
+
+	assert.deepEqual(deltas[deltas.length - 1], {
+		type: 'usage',
+		content: {input: 80, output: 20, cached: 0, context: 100},
+	});
+});

package/test/models/legacyOpenai.test.js

@@ -85,3 +85,45 @@ test('LegacyOpenAIModel combines text + tool_calls in one Message', async () =>
 	assert.equal(value[0].content[1].type, 'tool_call');
 	assert.equal(value[0].content[1].content[0].name, 'f');
 });
+
+test('LegacyOpenAIModel requests include_usage and yields a normalized usage delta', async () => {
+	const m = new LegacyOpenAIModel();
+	let capturedPayload = null;
+	m.getOpenAi = () => ({
+		chat: {
+			completions: {
+				async create(payload) {
+					capturedPayload = payload;
+					return asyncIterable([
+						{choices: [{delta: {content: 'Hi'}}]},
+						{choices: [{delta: {}, finish_reason: 'stop'}]},
+						{choices: [], usage: {prompt_tokens: 500, completion_tokens: 25, prompt_tokens_details: {cached_tokens: 300}}},
+					]);
+				},
+			},
+		},
+	});
+
+	const {deltas} = await drain(m.generate(buildModelDef(), fakeThread()));
+
+	assert.deepEqual(capturedPayload.stream_options, {include_usage: true});
+	assert.deepEqual(deltas[deltas.length - 1], {
+		type: 'usage',
+		content: {input: 500, output: 25, cached: 300, context: 525},
+	});
+});
+
+test('LegacyOpenAIModel maps DeepSeek prompt_cache_hit_tokens to cached', async () => {
+	const m = new LegacyOpenAIModel();
+	installFakeOpenAi(m, [
+		{choices: [{delta: {content: 'Hi'}}]},
+		{choices: [], usage: {prompt_tokens: 500, completion_tokens: 25, prompt_cache_hit_tokens: 200}},
+	]);
+
+	const {deltas} = await drain(m.generate(buildModelDef(), fakeThread()));
+
+	assert.deepEqual(deltas[deltas.length - 1], {
+		type: 'usage',
+		content: {input: 500, output: 25, cached: 200, context: 525},
+	});
+});

package/test/models/ollama.test.js

@@ -88,3 +88,18 @@ test('OllamaModel emulates streaming when only a single full chunk arrives', asy
 	]);
 	assert.deepEqual(value[0].content, [{type: 'text', content: 'One shot response'}]);
 });
+
+test('OllamaModel yields a normalized usage delta from the final done chunk', async () => {
+	const m = new OllamaModel();
+	installFakeOllama(m, [
+		{message: {content: 'Hello'}},
+		{message: {content: ''}, done: true, prompt_eval_count: 60, eval_count: 15},
+	]);
+
+	const {deltas} = await drain(m.generate(buildModelDef(), fakeThread()));
+
+	assert.deepEqual(deltas[deltas.length - 1], {
+		type: 'usage',
+		content: {input: 60, output: 15, cached: 0, context: 75},
+	});
+});

package/test/models/openai.test.js

@@ -138,6 +138,30 @@ test('OpenAIModel emits reasoning_delta and final reasoning block', async () =>
 	assert.deepEqual(value[0].content[1], {type: 'text', content: 'done'});
 });
 
+test('OpenAIModel yields a normalized usage delta from the final response', async () => {
+	const m = new OpenAIModel();
+	const stream = openAiResponsesStream(
+		[{type: 'response.output_text.delta', delta: 'Hi'}],
+		{
+			output: [{type: 'message', content: [{text: 'Hi'}]}],
+			usage: {
+				input_tokens: 1200,
+				input_tokens_details: {cached_tokens: 1000},
+				output_tokens: 40,
+				total_tokens: 1240,
+			},
+		},
+	);
+	installFakeOpenAi(m, stream);
+
+	const {deltas} = await drain(m.generate(buildModelDef(), fakeThread()));
+
+	assert.deepEqual(deltas[deltas.length - 1], {
+		type: 'usage',
+		content: {input: 1200, output: 40, cached: 1000, context: 1240},
+	});
+});
+
 test('OpenAIModel emits image delta and final image block', async () => {
 	const m = new OpenAIModel();
 	const imageItem = {