symposium 2.4.2 → 3.0.0

package/CLAUDE.md

@@ -0,0 +1,101 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project
+
+Symposium is a Node.js framework (ES modules, Node ≥18) for building LLM-powered agents. Published as the `symposium` npm package; consumed as a library, not a runnable app. No build or lint tooling. Test suite uses the built-in `node:test` runner — run with `npm test` (script: `node --test "test/**/*.test.js"`). Tests live under `test/` and mock provider SDKs to validate the model layer's streaming behavior without network access.
+
+The codebase was refactored to its current shape in the 3.0 release (async-generator API, streaming input channel, real model streaming, hybrid retry, `response_schema`). See `MIGRATION.md` for 2.x → 3.0 side-by-side patterns and `README.md` for consumer-facing docs.
+
+## Architecture
+
+The framework is organized around a small set of cooperating classes at the repo root. Understanding the data flow between them is the fastest way to be productive.
+
+### Bootstrapping (`Symposium.js`)
+
+`Symposium` is a static registry, not an instance. `Symposium.init(storage?)` dynamically imports every file in `Models/` and calls `loadModel()` on each. Each model class returns a `Map` of model definitions (one provider class can register many model labels — see `Models/OpenAIModel.js` registering `gpt-4o`, `gpt-5`, `gpt-5.x`, etc.). Definitions are keyed by label and stored with `{...modelDef, type, class}` where `class` is the provider instance used for actual API calls.
+
+Storage is optional; when present it must implement `init()`, `get(key)`, `set(key, value)`. Threads serialize themselves under `thread-<agent_name>-<thread_id>`.
+
+`Symposium.prompt(system, prompt, options)` is a shortcut: it instantiates a bare `Agent`, marks it as `utility`, drains the agent's event generator, and returns the value carried by the final `{type:'result', value}` event.
+
+### Agents (`Agent.js`)
+
+The execution core. After Phase 6, `agent.message()` is a non-generator dispatcher: for `chat` agents it returns an async generator (`_messageAsStream`); for `utility` agents it returns a `Promise<value>` (`_messageAsValue` drains the generator internally). `trigger()` and `execute()` remain async generators. Callers do `for await (const ev of agent.message(...))` for chat, and `const value = await agent.message(...)` for utility.
+
+`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`, `end`). 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.
+
+The `execute()` loop is a `while (true)` inside an async generator with a `max_retries` (default 5) safety net wrapped around the entire turn: generate completion (forwarding `text_delta` deltas as `{type:'chunk'}` events and flipping a per-turn `output_yielded` flag) → `afterExecute` hook → yield reasoning → `handleCompletion` → if the assistant called tools, run them via `callTools` and loop; otherwise return. On error, the loop retries up to `max_retries` times per turn (hybrid strategy, Phase 5): silent if no chunk has been yielded yet, otherwise it emits `{type:'retry', attempt, reason}` so the consumer knows. A 1-second backoff is preserved for transport-level 5xx errors. Tool-execution errors are NOT retried — they're caught in `callTool()` and surfaced as `{type:'tool_response', success:false, error}`. Errors throw out of the generator naturally — there is no `error` event. Subclasses customize via `doInitThread`, `getDefaultState`, `beforeExecute(thread)`, `afterExecute(thread, completion)`, `afterHandle(thread, completion, value?)` (note: hooks no longer receive an emitter; the parameter was dropped in v3 Phase 2).
+
+Tool authorization is two-phase (Phase 4): `Toolkit.authorize()` runs before the call; if it returns false for any tool in the pending batch, a `{type:'tools_auth', id, tools}` event is yielded and the generator suspends. The consumer resumes by sending `{type:'auth', id, decision}` through the streaming input channel, where `decision ∈ {'approve', 'approve_always', 'reject'}` (`approve_always` calls `toolkit.authorizeAlways()` on each tool in the batch to persist the decision). The background reader routes the auth message into `inputState.pendingAuthResponses` and signals the notifier, so `_awaitAuthDecision(thread, id)` (the notifier-loop helper) wakes and resumes the run. Two implicit-reject rules close the loophole: if the input iterable closes (`readerFinished`) before a decision arrives, the decision is treated as `'reject'` and the agent loop is cancelled; and if `agent.message()` was called with a plain `string` / `ContentBlock[]` (no channel), any auth request auto-rejects since there's no way to deliver a decision.
+
+Within a single LLM turn, tools are executed **sequentially** (in `tools_to_call` order), so event ordering is deterministic. The previous parallel `Promise.all` invocation was dropped in Phase 2 to keep the event stream coherent.
+
+### 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.
+- 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).
+
+`Model.type` is `'llm'` by default but can also be `'stt'` (transcription, see `OpenAITranscribe.js`) or `'embedding'` (see `OpenAIEmbedding.js`). `Symposium.transcribe()` and `Symposium.embed()` route to whichever model is named in `process.env.TRANSCRIPTION_MODEL` / `EMBEDDING_MODEL`.
+
+### Threads & Messages (`Thread.js`, `Message.js`)
+
+A `Thread` owns the message history and a free-form `state` object (which always includes `model`). Messages are `{role, content[], name?, tags[]}`; `content` is always an array of typed parts (`text`, `image`, `audio`, `tool_call`, `tool_result`, `reasoning`). Use `addMessage()` for normal flow and `addPlannedMessage()` + `flushPlannedMessages()` to stage messages that should only land after a tool batch completes.
+
+`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`)
+
+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.
+
+### MCP servers (`MCPServer.js`, `Contexts/MCPResource.js`)
+
+`agent.addMCPServer(config)` is a third population path for tools + on_request contexts. It constructs an `MCPServer` (a `Toolkit` subclass wrapping `@modelcontextprotocol/sdk`'s `Client`), connects via the configured transport (`'stdio' | 'sse' | 'http'`), calls `listTools()`, and exposes each remote tool to the LLM under the **prefixed name** `<server>__<tool>` (always — no opt-out — so multiple MCP servers can coexist without tool-name collisions). When `config.resources: true`, it also calls `listResources()` and registers each as an `on_request` `Context` (`MCPResource`), which lazily reads via `client.readResource(uri)` when the LLM asks for it through `get_context`. Returns the `MCPServer` instance; consumers running long-lived chat agents must call `await server.close()` to tear down the stdio child process or HTTP/SSE connection — there is no global `agent.dispose()`. MCP `prompts` and `sampling` are out of scope for v1. Connection is lazy: `MCPServer.init(agent)` (the normal Toolkit init hook) is what triggers `_connect()`, so the SDK is only imported when an MCP server is actually added.
+
+### Event flow (async generator)
+
+`Agent.message()` / `trigger()` / `execute()` are async generators. The caller iterates with `for await (const ev of agent.message(...))`. There is no emitter, no listener-attach race, and no `BufferedEventEmitter` (removed in Phase 2). Each event is a discriminated union:
+
+| Event | Payload | Notes |
+|---|---|---|
+| `{type:'start', thread}` | thread object | First yield |
+| `{type:'chunk', content}` | text delta string | Streamed during model generation |
+| `{type:'output', content}` | text/image content block | Yielded once the model finishes a message |
+| `{type:'reasoning', content}` | reasoning text | Yielded after assembly, per reasoning block |
+| `{type:'tool', id, name, arguments}` | flattened tool call | Before invoking a tool |
+| `{type:'tool_response', name, success, response?, error?}` | tool result | After tool returns or throws |
+| `{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:'result', value}` | parsed value | Utility agents only |
+| `{type:'end', thread}` | thread object | Always yielded, even on throw (yielded from a `finally`) |
+
+Errors throw out of the generator. There is no `error` event anymore.
+
+## Conventions specific to this repo
+
+- ES modules everywhere (`"type": "module"`); always use `import`/`export` and include the `.js` extension in relative imports.
+- Tabs for indentation; trailing commas in multi-line literals.
+- The fallback tool-call prompt in `Model.promptFromTools()` and the realtime session preamble in `Agent.createRealtimeSession()` are written in Italian by design — keep them that way unless explicitly changing the language contract.
+- When adding a new provider, drop the file in `Models/` and `Symposium.init()` will pick it up automatically — there is no registry to update. The class must `extends Model` and `export default`.
+- MCP server lifecycle is owned by the consumer: `addMCPServer()` returns the `MCPServer` and callers must `await server.close()` when done (no global agent teardown in v1).
+- When adding new public exports, update `index.js` (the package entry point).
+- Bump `package.json` version on releases (see recent commits — `add support for gpt-5.4 model in OpenAIModel.js`, `bump version to 2.4.0`).
+
+## Required environment
+
+Set in a `.env` file at the consumer's project root (the framework reads `process.env` directly, no dotenv loader is bundled):
+
+- `OPENAI_API_KEY` — also required for realtime voice sessions
+- `ANTHROPIC_API_KEY`, `GROQ_API_KEY`, `DEEPSEEK_API_KEY` — per-provider
+- `TRANSCRIPTION_MODEL`, `EMBEDDING_MODEL` — model labels routed to STT/embedding providers

package/Contexts/MCPResource.js

@@ -0,0 +1,19 @@
+import Context from "../Context.js";
+
+export default class MCPResource extends Context {
+	constructor(server, resource) {
+		super();
+		this.server = server;
+		this.resource = resource;
+		this.uri = resource.uri;
+		this.title = resource.name || resource.uri;
+	}
+
+	async getTitle() {
+		return this.title;
+	}
+
+	async getText() {
+		return this.server.readResource(this.uri);
+	}
+}

package/{GetContextTool.js → GetContextToolkit.js}

@@ -1,6 +1,6 @@
-import Tool from "./Tool.js";
+import Toolkit from "./Toolkit.js";
 
-export default class GetContextTool extends Tool {
+export default class GetContextToolkit extends Toolkit {
 	name = 'get_context';
 
 	constructor(agent) {
@@ -8,7 +8,7 @@ export default class GetContextTool extends Tool {
 		this.agent = agent;
 	}
 
-	async getFunctions() {
+	async getTools() {
 		return [
 			{
 				name: 'get_context',
@@ -26,9 +26,9 @@ export default class GetContextTool extends Tool {
 		];
 	}
 
-	async callFunction(thread, name, payload) {
+	async callTool(thread, name, payload) {
 		if (name !== 'get_context')
-			return {error: `Function ${name} not found`};
+			return {error: `Tool ${name} not found`};
 
 		const title = payload.title;
 		const context = this.agent.context.find(c => c.title === title && c.options.type === 'on_request');

package/InputChannel.js

@@ -0,0 +1,42 @@
+export function createInputChannel() {
+	const queue = [];
+	const waiters = [];
+	let closed = false;
+
+	const channel = {
+		send(item) {
+			if (closed)
+				return;
+			if (waiters.length)
+				waiters.shift().resolve({value: item, done: false});
+			else
+				queue.push(item);
+		},
+		close() {
+			if (closed)
+				return;
+			closed = true;
+			while (waiters.length)
+				waiters.shift().resolve({value: undefined, done: true});
+		},
+		[Symbol.asyncIterator]() {
+			return channel;
+		},
+		async next() {
+			if (queue.length)
+				return {value: queue.shift(), done: false};
+			if (closed)
+				return {value: undefined, done: true};
+			return new Promise(resolve => waiters.push({resolve}));
+		},
+		async return() {
+			if (!closed) {
+				closed = true;
+				while (waiters.length)
+					waiters.shift().resolve({value: undefined, done: true});
+			}
+			return {value: undefined, done: true};
+		},
+	};
+	return channel;
+}

package/MCPServer.js

@@ -0,0 +1,160 @@
+import Toolkit from "./Toolkit.js";
+
+const PREFIX_SEPARATOR = '__';
+
+export default class MCPServer extends Toolkit {
+	constructor(config = {}) {
+		super();
+
+		if (!config || typeof config !== 'object')
+			throw new Error('MCPServer config must be an object');
+		if (!config.name || typeof config.name !== 'string')
+			throw new Error('MCPServer config.name is required');
+
+		this.config = config;
+		this.serverName = config.name;
+		this.name = 'mcp:' + this.serverName;
+
+		this.client = null;
+		this.transport = null;
+		this._toolsByPrefixed = new Map();
+	}
+
+	async init(agent) {
+		if (this.client)
+			return;
+
+		this.client = await this._connect();
+
+		const list = await this.client.listTools();
+		const tools = (list && list.tools) || [];
+		for (const t of tools) {
+			const prefixed = this.serverName + PREFIX_SEPARATOR + t.name;
+			this._toolsByPrefixed.set(prefixed, {
+				rawName: t.name,
+				description: t.description || '',
+				inputSchema: t.inputSchema || {type: 'object', properties: {}},
+			});
+		}
+	}
+
+	async _connect() {
+		const {Client} = await import('@modelcontextprotocol/sdk/client/index.js');
+		this.transport = await this._createTransport();
+
+		const client = new Client({
+			name: 'symposium',
+			version: '3.1.0',
+		});
+
+		await client.connect(this.transport);
+		return client;
+	}
+
+	async _createTransport() {
+		const transport = this.config.transport || 'stdio';
+
+		if (transport === 'stdio') {
+			const {StdioClientTransport} = await import('@modelcontextprotocol/sdk/client/stdio.js');
+			if (!this.config.command)
+				throw new Error('MCPServer stdio transport requires a command');
+			return new StdioClientTransport({
+				command: this.config.command,
+				args: this.config.args || [],
+				env: this.config.env,
+				cwd: this.config.cwd,
+			});
+		}
+
+		if (transport === 'sse') {
+			const {SSEClientTransport} = await import('@modelcontextprotocol/sdk/client/sse.js');
+			if (!this.config.url)
+				throw new Error('MCPServer sse transport requires a url');
+			return new SSEClientTransport(new URL(this.config.url), {
+				requestInit: this.config.headers ? {headers: this.config.headers} : undefined,
+			});
+		}
+
+		if (transport === 'http') {
+			const {StreamableHTTPClientTransport} = await import('@modelcontextprotocol/sdk/client/streamableHttp.js');
+			if (!this.config.url)
+				throw new Error('MCPServer http transport requires a url');
+			return new StreamableHTTPClientTransport(new URL(this.config.url), {
+				requestInit: this.config.headers ? {headers: this.config.headers} : undefined,
+			});
+		}
+
+		if (transport && typeof transport === 'object' && typeof transport.connect === 'function')
+			return transport;
+
+		throw new Error('Unknown MCPServer transport: ' + transport);
+	}
+
+	async getTools() {
+		const out = [];
+		for (const [prefixed, entry] of this._toolsByPrefixed) {
+			out.push({
+				name: prefixed,
+				description: entry.description,
+				parameters: entry.inputSchema,
+			});
+		}
+		return out;
+	}
+
+	async callTool(thread, name, payload) {
+		const entry = this._toolsByPrefixed.get(name);
+		if (!entry)
+			return {error: `MCP tool ${name} not found on server ${this.serverName}`};
+
+		const result = await this.client.callTool({
+			name: entry.rawName,
+			arguments: payload || {},
+		});
+
+		if (result && result.isError)
+			throw new Error(MCPServer._renderContent(result.content) || 'MCP tool returned an error');
+
+		return {content: result.content};
+	}
+
+	async listResources() {
+		const list = await this.client.listResources();
+		return (list && list.resources) || [];
+	}
+
+	async readResource(uri) {
+		const result = await this.client.readResource({uri});
+		const contents = (result && result.contents) || [];
+		const parts = [];
+		for (const c of contents) {
+			if (typeof c.text === 'string')
+				parts.push(c.text);
+			else if (typeof c.blob === 'string')
+				parts.push(c.blob);
+		}
+		return parts.join('\n');
+	}
+
+	async close() {
+		if (this.client) {
+			try {
+				await this.client.close();
+			} catch {}
+			this.client = null;
+		}
+		this.transport = null;
+		this._toolsByPrefixed.clear();
+	}
+
+	static _renderContent(content) {
+		if (!Array.isArray(content))
+			return '';
+		const parts = [];
+		for (const c of content) {
+			if (c && typeof c.text === 'string')
+				parts.push(c.text);
+		}
+		return parts.join('\n');
+	}
+}