symposium 3.3.0 → 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.

package/CLAUDE.md

@@ -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`)
 

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
@@ -453,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.3.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"
-  }
+	"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/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);
+});