symposium 3.2.1 → 3.4.0

package/Agent.js

@@ -489,14 +489,20 @@ ${context_string}
 	}
 
 	async beforeExecute(thread) {
-		if (this.options.memory_handler)
-			thread = await this.options.memory_handler.handle(thread);
+		if (this.options.memory_handler) {
+			const handled = await this.options.memory_handler.handle(thread);
+			if (handled && handled !== thread) {
+				// The handler returned a transformed clone (e.g. Summarizer):
+				// re-register it so getThread() doesn't keep serving the stale
+				// original while storage holds the transformed version.
+				thread = handled;
+				this.threads.set(thread.id, thread);
+			}
+		}
 		return thread;
 	}
 
 	async *execute(thread) {
-		thread = await this.beforeExecute(thread);
-
 		const model = Symposium.getModel(thread.state.model);
 
 		const completion_options = {};
@@ -550,6 +556,12 @@ ${context_string}
 					return;
 			}
 
+			// Per-iteration, not once per run: in streaming mode a single
+			// execute() spans the whole session, and the memory handler
+			// (Summarizer, Scrubber) must get a chance before every LLM call,
+			// not just the first one.
+			thread = await this.beforeExecute(thread);
+
 			try {
 				// Inline drain of generateCompletion so we can observe `chunk`
 				// events and flip output_yielded for the hybrid retry strategy.
@@ -672,8 +684,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).
@@ -54,12 +54,14 @@ A `Thread` owns the message history and a free-form `state` object (which always
 
 `thread.unique` (`<agent_name>-<id>`) is the storage key — never reuse the same thread id across agents with different names without realizing they share namespace.
 
-### Context system (`Context.js`, `Contexts/*.js`, `ContextHandler.js`, `Summarizer.js`, `GetContextToolkit.js`)
+### Context system (`Context.js`, `Contexts/*.js`, `ContextHandler.js`, `Summarizer.js`, `Scrubber.js`, `GetContextToolkit.js`)
 
 Two distinct concepts share the word "context":
 
 1. **`Context` / `Contexts/*`** — static reference material attached to an agent via `agent.addContext(text_or_context, {type: 'always' | 'on_request'})`. `always` contexts are inlined into the system message at thread init; `on_request` contexts are advertised by title/description and fetched lazily through the auto-injected `GetContextToolkit`. Mixing both is supported.
-2. **`ContextHandler`** — pre-execute hook (set as `options.memory_handler` on the agent) that can transform the thread before each LLM call. `Summarizer` extends this: when token count crosses `threshold * model.tokens`, it summarizes earlier messages down to `summary_length * model.tokens`, preserving the system prompt.
+2. **`ContextHandler`** — pre-execute hook (set as `options.memory_handler` on the agent) that can transform the thread before each LLM call. Since 3.4 `beforeExecute` runs inside the `execute()` turn loop, so the handler fires before **every** LLM call — including every later turn of a streaming run (previously it ran once per `execute()`, i.e. once per session in streaming mode). If the handler returns a different object than it was given (a transformed clone, as `Summarizer` does), `beforeExecute` re-registers it in `agent.threads`, so `getThread()` and storage stay coherent. Two shipped handlers:
+	- `Summarizer` — when token count crosses `threshold * model.tokens`, it summarizes earlier messages down to `summary_length * model.tokens`, preserving the system prompt. Returns a clone.
+	- `Scrubber` — surgical auto-forget: in messages older than the last `keep_last` (default 3) user messages, replaces `image`/`audio` blocks with short text stubs (carrying the block's optional `content.path` so the model can re-read the file, and the audio transcription when present) and trims `text` (user role only) / `tool_result` contents longer than `max_text_length` chars down to `keep_chars` + a marker. Mutates in place (no clone), never touches `system` messages, keeps tool_call/tool_result pairing intact, idempotent. The persisted thread is scrubbed too — this is deliberate destructive forgetting, whose point is freeing context permanently. Note the prompt-cache tradeoff: each scrub invalidates the provider prefix cache from the edit point, so it trades a one-time cache re-write for permanent window headroom.
 
 ### MCP servers (`MCPServer.js`, `Contexts/MCPResource.js`)
 
@@ -79,6 +81,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,26 +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,
 			}],
 		]);
@@ -43,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',
@@ -61,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

@@ -42,7 +42,7 @@ Symposium uses environment variables to configure access to various services. Yo
 -	**`Thread`**: A single conversation with an agent. Maintains message history and per-conversation state.
 -	**`Toolkit`**: Base class for toolkits — groupings of one or more tools that an `Agent` can call.
 -	**`Message`**: A typed message inside a `Thread`.
--	**`ContextHandler`** / **`Summarizer`**: Pre-execute hooks for managing long-context strategies.
+-	**`ContextHandler`** / **`Summarizer`** / **`Scrubber`**: Pre-execute hooks for managing long-context strategies.
 -	**`createInputChannel`**: Helper that creates an `AsyncIterable` with `send(item)` / `close()` for streaming input into an agent.
 
 ## Getting Started
@@ -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. |
@@ -452,8 +453,9 @@ Returns `{ send(item), close(), [Symbol.asyncIterator]() }`. Push strings, conte
 
 ### Other Classes
 
--	**`ContextHandler`**: Base for managing long-term context.
+-	**`ContextHandler`**: Base for managing long-term context. Set as `options.memory_handler` on the agent; since 3.4 it runs before **every** LLM call (previously once per run, which skipped every later turn of a streaming session). A handler returning a transformed clone is re-registered in the agent's thread cache.
 -	**`Summarizer`**: Utility agent that compresses old messages once a thread crosses a token threshold.
+-	**`Scrubber`**: Surgical auto-forget of heavy content: replaces images/audio blocks and trims oversized texts and tool results in messages older than the last `keep_last` user turns, leaving short text stubs (mentioning the on-disk `path` when the block carries one, so an agent with filesystem tools can re-read the original). Mutates the thread in place so the scrub persists with it; message structure and tool pairing stay intact; system messages are never touched. Options: `keep_last` (3), `max_text_length` (20000 chars), `keep_chars` (1000), plus `images`/`audio`/`texts`/`tool_results` toggles.
 -	**`Logger`**: Simple per-agent logger.
 
 ## License

package/Scrubber.js

@@ -0,0 +1,142 @@
+import ContextHandler from "./ContextHandler.js";
+
+/**
+ * Context handler that retroactively removes heavy content from old messages,
+ * once the conversation has moved past them. Unlike Summarizer (which rewrites
+ * whole spans of history into a summary), Scrubber is surgical: it replaces
+ * individual heavy blocks — images, audio, oversized texts and tool results —
+ * with short text stubs, keeping the message structure (roles, tool pairing)
+ * intact. Mutates the thread in place, so the scrub persists with the normal
+ * thread storeState at turn end.
+ *
+ * Messages belonging to the last `keep_last` user turns are never touched, so
+ * the model always has the recent originals while it is still working on them.
+ * System messages are never touched.
+ *
+ * An image or audio block may carry a `path` in its content (where the source
+ * file lives on disk); the stub then mentions it, so an agent with filesystem
+ * tools can re-read the original if it turns out to still be needed.
+ */
+export default class Scrubber extends ContextHandler {
+	constructor(options = {}) {
+		super();
+		this.options = {
+			keep_last: 3, // most recent user messages whose turns are fully protected
+			max_text_length: 20000, // chars; longer text/tool_result contents get trimmed
+			keep_chars: 1000, // head kept when trimming an oversized text
+			images: true,
+			audio: true,
+			texts: true, // oversized text blocks in user messages
+			tool_results: true, // oversized tool responses
+			...options,
+		};
+	}
+
+	async handle(thread) {
+		const boundary = this.protectedBoundary(thread.messages);
+
+		let scrubbed = 0;
+		for (let i = 0; i < boundary; i++)
+			scrubbed += this.scrubMessage(thread.messages[i]);
+
+		// Exposed for consumers that scrub on demand (e.g. a model-invoked
+		// "forget" tool) and want to report how much was removed.
+		this.last_scrubbed = scrubbed;
+
+		if (scrubbed && this.agent)
+			await this.agent.log('scrub', {thread: thread.id, blocks: scrubbed});
+
+		return thread;
+	}
+
+	// Index of the keep_last-th user message counting from the end; everything
+	// before it is old enough to scrub. 0 (nothing to scrub) when the thread
+	// doesn't have that many user messages yet.
+	protectedBoundary(messages) {
+		let seen = 0;
+		for (let i = messages.length - 1; i >= 0; i--) {
+			if (messages[i].role === 'user') {
+				seen++;
+				if (seen >= this.options.keep_last)
+					return i;
+			}
+		}
+		return 0;
+	}
+
+	// Returns the number of blocks replaced or trimmed. Idempotent: stubs and
+	// already-trimmed blocks are always below the thresholds.
+	scrubMessage(message) {
+		if (message.role === 'system')
+			return 0;
+
+		let scrubbed = 0;
+		message.content = message.content.map(block => {
+			const replacement = this.scrubBlock(block, message.role);
+			if (replacement !== block)
+				scrubbed++;
+			return replacement;
+		});
+		return scrubbed;
+	}
+
+	scrubBlock(block, role) {
+		switch (block?.type) {
+			case 'image':
+				if (this.options.images)
+					return this.stub('image', block.content?.path);
+				break;
+
+			case 'audio':
+				if (this.options.audio) {
+					const transcription = block.content?.transcription;
+					const stub = this.stub('audio recording', block.content?.path);
+					return transcription
+						? {type: 'text', content: stub.content + "\nTranscription: " + transcription}
+						: stub;
+				}
+				break;
+
+			case 'text':
+				if (this.options.texts && role === 'user' && typeof block.content === 'string' && block.content.length > this.options.max_text_length) {
+					const removed = block.content.length - this.options.keep_chars;
+					return {
+						type: 'text',
+						content: block.content.slice(0, this.options.keep_chars)
+							+ "\n[... " + removed + " characters removed from context to save space]",
+					};
+				}
+				break;
+
+			case 'tool_result': {
+				if (!this.options.tool_results)
+					break;
+				const response = block.content?.response;
+				const serialized = typeof response === 'string' ? response : JSON.stringify(response);
+				if (typeof serialized === 'string' && serialized.length > this.options.max_text_length) {
+					const removed = serialized.length - this.options.keep_chars;
+					return {
+						...block,
+						content: {
+							...block.content,
+							response: serialized.slice(0, this.options.keep_chars)
+								+ "\n[... " + removed + " characters removed from context to save space]",
+						},
+					};
+				}
+				break;
+			}
+		}
+
+		return block;
+	}
+
+	stub(what, path) {
+		return {
+			type: 'text',
+			content: path
+				? "[" + what + " removed from context to save space — the original file is still available at " + path + ", read it again only if actually needed]"
+				: "[" + what + " removed from context to save space — ask the user to send it again if actually needed]",
+		};
+	}
+}

package/index.js

@@ -8,6 +8,7 @@ import Logger from "./Logger.js";
 
 import ContextHandler from "./ContextHandler.js";
 import Summarizer from "./Summarizer.js";
+import Scrubber from "./Scrubber.js";
 
 import Context from "./Context.js";
 import File from "./Contexts/File.js";
@@ -26,6 +27,7 @@ export {
 	Logger,
 	ContextHandler,
 	Summarizer,
+	Scrubber,
 	Context,
 	File,
 	Text,

package/package.json

@@ -1,21 +1,21 @@
 {
-  "type": "module",
-  "name": "symposium",
-  "version": "3.2.1",
-  "description": "Agents",
-  "main": "index.js",
-  "author": "Domenico Giambra",
-  "license": "ISC",
-  "scripts": {
-    "test": "node --test \"test/**/*.test.js\""
-  },
-  "dependencies": {
-    "@anthropic-ai/sdk": "^0.110.0",
-    "@modelcontextprotocol/sdk": "^1.29.0",
-    "groq-sdk": "^1.0.0",
-    "ollama": "^0.6.0",
-    "openai": "^6.0.0",
-    "tiktoken": "^1.0.10",
-    "uuid": "^14.0.0"
-  }
+	"type": "module",
+	"name": "symposium",
+	"version": "3.4.0",
+	"description": "Agents",
+	"main": "index.js",
+	"author": "Domenico Giambra",
+	"license": "ISC",
+	"scripts": {
+		"test": "node --test \"test/**/*.test.js\""
+	},
+	"dependencies": {
+		"@anthropic-ai/sdk": "^0.110.0",
+		"@modelcontextprotocol/sdk": "^1.29.0",
+		"groq-sdk": "^1.0.0",
+		"ollama": "^0.6.0",
+		"openai": "^6.0.0",
+		"tiktoken": "^1.0.10",
+		"uuid": "^14.0.0"
+	}
 }

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 = {

package/test/scrubber.test.js

@@ -0,0 +1,216 @@
+import {test} from 'node:test';
+import assert from 'node:assert/strict';
+
+import Agent from '../Agent.js';
+import Symposium from '../Symposium.js';
+import Model from '../Model.js';
+import Message from '../Message.js';
+import Thread from '../Thread.js';
+import ContextHandler from '../ContextHandler.js';
+import Scrubber from '../Scrubber.js';
+
+import {createInputChannel} from '../InputChannel.js';
+
+class ScriptedModel extends Model {
+	constructor(label, script) {
+		super();
+		this.label = label;
+		this.script = script;
+		this.calls = 0;
+	}
+
+	async getModels() {
+		return new Map([
+			[this.label, {
+				name: this.label,
+				tokens: 1000,
+				tools: true,
+				structured_output: false,
+			}],
+		]);
+	}
+
+	async *generate(_model, _thread, _functions, _options) {
+		const turn = this.script[this.calls++];
+		if (!turn)
+			throw new Error('No more scripted turns for model ' + this.label);
+		return turn.messages;
+	}
+}
+
+function imageBlock(path = undefined) {
+	return {type: 'image', content: {type: 'base64', mime: 'image/png', data: 'AAAA', path}};
+}
+
+function makeScrubbableThread() {
+	const thread = new Thread('scrub-test', {name: 'TestAgent'});
+	thread.addMessage('system', 'You are a test agent');
+	thread.addMessage('user', [{type: 'text', content: 'look at this'}, imageBlock()]);
+	thread.addMessage('assistant', 'I see a cat');
+	thread.addMessage('user', 'second message');
+	thread.addMessage('assistant', 'ok');
+	thread.addMessage('user', 'third message');
+	thread.addMessage('assistant', 'ok');
+	thread.addMessage('user', 'fourth message');
+	return thread;
+}
+
+test('Scrubber replaces old image blocks with a stub, keeps recent turns intact', async () => {
+	const thread = makeScrubbableThread();
+	const scrubber = new Scrubber({keep_last: 3});
+
+	await scrubber.handle(thread);
+
+	const first_user = thread.messages[1];
+	assert.equal(first_user.content[0].content, 'look at this');
+	assert.equal(first_user.content[1].type, 'text');
+	assert.match(first_user.content[1].content, /image removed from context/);
+	// Recent messages untouched
+	assert.equal(thread.messages[7].content[0].content, 'fourth message');
+});
+
+test('Scrubber leaves images inside the protected window alone', async () => {
+	const thread = new Thread('scrub-window', {name: 'TestAgent'});
+	thread.addMessage('user', [imageBlock()]);
+	thread.addMessage('assistant', 'ok');
+	thread.addMessage('user', 'follow-up');
+
+	// Only 2 user messages, keep_last 3 → nothing is old enough
+	await new Scrubber({keep_last: 3}).handle(thread);
+	assert.equal(thread.messages[0].content[0].type, 'image');
+});
+
+test('Scrubber stub mentions the on-disk path when the block carries one', async () => {
+	const thread = makeScrubbableThread();
+	thread.messages[1].content[1] = imageBlock('/tmp/photo.png');
+
+	await new Scrubber({keep_last: 3}).handle(thread);
+	assert.match(thread.messages[1].content[1].content, /\/tmp\/photo\.png/);
+});
+
+test('Scrubber trims oversized user texts but not assistant ones', async () => {
+	const long = 'x'.repeat(500);
+	const thread = new Thread('scrub-text', {name: 'TestAgent'});
+	thread.addMessage('user', long);
+	thread.addMessage('assistant', long);
+	thread.addMessage('user', 'a');
+	thread.addMessage('user', 'b');
+	thread.addMessage('user', 'c');
+
+	await new Scrubber({keep_last: 3, max_text_length: 100, keep_chars: 10}).handle(thread);
+
+	assert.match(thread.messages[0].content[0].content, /^x{10}\n\[\.\.\. 490 characters removed/);
+	assert.equal(thread.messages[1].content[0].content, long);
+});
+
+test('Scrubber trims oversized tool results preserving name and id', async () => {
+	const thread = new Thread('scrub-tool', {name: 'TestAgent'});
+	thread.addMessage('tool', [{
+		type: 'tool_result',
+		content: {name: 'WebFetch', id: 'call_1', response: 'y'.repeat(500)},
+	}], 'WebFetch');
+	thread.addMessage('user', 'a');
+	thread.addMessage('user', 'b');
+	thread.addMessage('user', 'c');
+
+	await new Scrubber({keep_last: 3, max_text_length: 100, keep_chars: 10}).handle(thread);
+
+	const block = thread.messages[0].content[0];
+	assert.equal(block.type, 'tool_result');
+	assert.equal(block.content.name, 'WebFetch');
+	assert.equal(block.content.id, 'call_1');
+	assert.match(block.content.response, /characters removed from context/);
+});
+
+test('Scrubber never touches system messages and is idempotent', async () => {
+	const long_system = 's'.repeat(500);
+	const thread = new Thread('scrub-sys', {name: 'TestAgent'});
+	thread.addMessage('system', long_system);
+	thread.addMessage('user', [imageBlock()]);
+	thread.addMessage('user', 'a');
+	thread.addMessage('user', 'b');
+	thread.addMessage('user', 'c');
+
+	const scrubber = new Scrubber({keep_last: 3, max_text_length: 100, keep_chars: 10});
+	await scrubber.handle(thread);
+	assert.equal(thread.messages[0].content[0].content, long_system);
+
+	const after_first = JSON.stringify(thread.messages);
+	await scrubber.handle(thread);
+	assert.equal(JSON.stringify(thread.messages), after_first);
+});
+
+// ────────────────────────────────────────────────────────────────────────────────
+// Agent integration: the memory handler must run before EVERY LLM call in a
+// streaming run, not just once at the start of execute().
+// ────────────────────────────────────────────────────────────────────────────────
+test('memory_handler runs per turn in a streaming run', async () => {
+	const label = 'fake-scrub-streaming';
+	await Symposium.loadModel(new ScriptedModel(label, [
+		{messages: [new Message('assistant', [{type: 'text', content: 'first'}])]},
+		{messages: [new Message('assistant', [{type: 'text', content: 'second'}])]},
+	]));
+
+	class CountingHandler extends ContextHandler {
+		calls = 0;
+
+		async handle(thread) {
+			this.calls++;
+			return thread;
+		}
+	}
+
+	const handler = new CountingHandler();
+	const agent = new Agent({memory_handler: handler});
+	agent.default_model = label;
+	await agent.init();
+
+	const thread = new Thread('scrub-streaming', agent);
+	thread.state = {model: label};
+
+	const channel = createInputChannel();
+	channel.send('first message');
+	channel.send({type: 'submit'});
+
+	let turns = 0;
+	for await (const ev of agent.message(channel, thread)) {
+		if (ev.type === 'turn_end') {
+			turns++;
+			if (turns === 1)
+				channel.send('second message');
+			else
+				channel.close();
+		}
+	}
+
+	assert.equal(turns, 2);
+	assert.equal(handler.calls, 2);
+});
+
+test('a memory_handler returning a clone gets re-registered in agent.threads', async () => {
+	const label = 'fake-scrub-clone';
+	await Symposium.loadModel(new ScriptedModel(label, [
+		{messages: [new Message('assistant', [{type: 'text', content: 'done'}])]},
+	]));
+
+	class CloningHandler extends ContextHandler {
+		async handle(thread) {
+			this.last_clone = thread.clone(true);
+			return this.last_clone;
+		}
+	}
+
+	const handler = new CloningHandler();
+	const agent = new Agent({memory_handler: handler});
+	agent.default_model = label;
+	await agent.init();
+
+	const thread = new Thread('scrub-clone', agent);
+	thread.state = {model: label};
+
+	for await (const ev of agent.trigger(thread)) {
+		void ev;
+	}
+
+	assert.equal(agent.threads.get('scrub-clone'), handler.last_clone);
+});