symposium 3.0.7 → 3.1.0

package/Agent.js

@@ -502,23 +502,39 @@ ${context_string}
 		const completion_options = {};
 		if (this.response_schema) {
 			const schema = this.response_schema;
-			const converted = (schema.type === 'object' && model.structured_output)
-				? this.convertFunctionToResponseFormat(JSON.parse(JSON.stringify(schema)))
-				: null;
 
-			if (converted && converted.count <= 100) { // OpenAI does not support structured output if there are more than 100 parameters
-				completion_options.response_format = {
-					type: 'json_schema',
-					name: 'response',
-					schema: converted.obj,
-					strict: true,
-				};
-			} else {
-				completion_options.tools = [{
+			// When the agent also exposes toolkit tools, the structured answer cannot be
+			// forced up-front (that would prevent the model from calling its tools first).
+			// Instead we offer an extra `response` tool, alongside the real ones, that the
+			// model calls once it is ready to answer. handleCompletion() treats a `response`
+			// call as terminal and every other call as a normal tool invocation.
+			const has_tools = (await this.getTools()).length > 0;
+
+			if (has_tools) {
+				completion_options.append_tools = [{
 					name: 'response',
+					description: 'Call this tool with your final answer, conforming to the required schema, only once you have gathered everything you need. Do not call it before you are ready to give the definitive answer.',
 					parameters: schema,
 				}];
-				completion_options.force_tool = 'response';
+			} else {
+				const converted = (schema.type === 'object' && model.structured_output)
+					? this.convertFunctionToResponseFormat(JSON.parse(JSON.stringify(schema)))
+					: null;
+
+				if (converted && converted.count <= 100) { // OpenAI does not support structured output if there are more than 100 parameters
+					completion_options.response_format = {
+						type: 'json_schema',
+						name: 'response',
+						schema: converted.obj,
+						strict: true,
+					};
+				} else {
+					completion_options.tools = [{
+						name: 'response',
+						parameters: schema,
+					}];
+					completion_options.force_tool = 'response';
+				}
 			}
 		}
 
@@ -733,10 +749,18 @@ ${context_string}
 		}
 
 		if (tool_calls.length) {
-			if (this.response_schema)
+			// With response_schema set, a call to the synthetic `response` tool is the
+			// terminal answer; any other call is a real toolkit tool to be executed.
+			const response_call = this.response_schema ? tool_calls.find(t => t.name === 'response') : null;
+			if (response_call)
+				return {type: 'response', value: await this.afterHandle(thread, completion, response_call.arguments)};
+
+			// response_schema with no toolkit tools: legacy forced-`response` path — the lone
+			// tool call carries the answer even if the model named it unexpectedly.
+			if (this.response_schema && (await this.getTools()).length === 0)
 				return {type: 'response', value: await this.afterHandle(thread, completion, tool_calls[0].arguments)};
 
-			return yield* this.callTools(thread, completion, tool_calls);
+			return yield* this.callTools(thread, completion, tool_calls.filter(t => t.name !== 'response'));
 		} else {
 			await thread.storeState();
 			await this.afterHandle(thread, completion);

package/CLAUDE.md

@@ -29,6 +29,8 @@ The execution core. After Phase 6, `agent.message()` is a non-generator dispatch
 - `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).
 - `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).
+
 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.

package/Model.js

@@ -32,6 +32,11 @@ export default class Model {
 		if (options.tools !== null)
 			tools = options.tools;
 
+		// Additive tools (e.g. the synthetic `response` tool for schema output) ride
+		// alongside the toolkit tools instead of replacing them.
+		if (options.append_tools)
+			tools = [...tools, ...options.append_tools];
+
 		if (options.force_tool && !tools.find(t => t.name === options.force_tool))
 			throw new Error('Tool ' + options.force_tool + ' not found.');
 

package/README.md

@@ -343,6 +343,8 @@ for await (const ev of agent.message('Look up the weather and reply in JSON')) {
 
 Internally, structured-output-capable OpenAI models use `response_format: json_schema`; otherwise the agent falls back to a forced function call and parses its arguments.
 
+**Combining `response_schema` with toolkits.** If the agent also has toolkit tools, the schema is not forced up-front (that would stop the model from calling its tools). Instead an extra `response` tool is offered alongside the real ones: the model calls its tools across turns and, when ready, calls `response` with the final schema-conforming answer, which surfaces as the `{type:'result', value}` event. This lets a chat agent search/act on its own and still return a validated object. `response` is a reserved tool name while `response_schema` is set, so don't expose a toolkit tool by that name.
+
 ### Real-time Voice and Transcription
 
 Symposium has built-in support for audio transcription and real-time voice sessions, currently powered by OpenAI.

package/package.json

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

package/test/agent.test.js

@@ -284,6 +284,80 @@ test('chat agent with response_schema yields normal events plus final result eve
 	assert.deepEqual(events[2].value, {city: 'Rome'});
 });
 
+// ────────────────────────────────────────────────────────────────────────────────
+// response_schema + toolkit: the model may call its real tools across turns and then
+// deliver the structured answer through the synthetic `response` tool. Verifies the
+// two are NOT mutually exclusive (regression guard for the schema-vs-tools fix).
+// ────────────────────────────────────────────────────────────────────────────────
+test('chat agent with response_schema + toolkit: runs a tool then `response` yields the result', async () => {
+	const label = 'fake-chat-schema-tools';
+	await Symposium.loadModel(new ScriptedModel(label, [
+		{
+			deltas: [],
+			messages: [new Message('assistant', [
+				{type: 'tool_call', content: [{id: 'call_s', name: 'search', arguments: {q: 'Rome'}}]},
+			])],
+		},
+		{
+			deltas: [],
+			messages: [new Message('assistant', [
+				{type: 'tool_call', content: [{id: 'call_r', name: 'response', arguments: {unique_code: 'IT-05-087', confidence: 0.9}}]},
+			])],
+		},
+	]));
+
+	let searched = null;
+	class SearchTool extends Toolkit {
+		name = 'search';
+		async getTools() {
+			return [{name: 'search', description: 'search the master tree', parameters: {type: 'object', properties: {q: {type: 'string'}}}}];
+		}
+		async callTool(_thread, _name, payload) {
+			searched = payload.q;
+			return {results: [{unique_code: 'IT-05-087'}]};
+		}
+	}
+
+	const agent = new Agent();
+	agent.default_model = label;
+	agent.response_schema = {
+		type: 'object',
+		properties: {unique_code: {type: 'string'}, confidence: {type: 'number'}},
+		required: ['unique_code', 'confidence'],
+	};
+	await agent.addToolkit(new SearchTool());
+	await agent.init();
+
+	const thread = await makeThread(agent, label);
+
+	const events = [];
+	for await (const ev of agent.message('match Rome', thread))
+		events.push(ev);
+
+	const types = events.map(e => e.type);
+	// the real `search` tool ran (tool + tool_response), THEN `response` carried the answer
+	assert.deepEqual(types, ['start', 'tool', 'tool_response', 'result', 'end']);
+	assert.equal(searched, 'Rome');
+	assert.equal(events[1].name, 'search');
+	assert.deepEqual(events.find(e => e.type === 'result').value, {unique_code: 'IT-05-087', confidence: 0.9});
+});
+
+// ────────────────────────────────────────────────────────────────────────────────
+// parseOptions: append_tools augments the toolkit tools rather than replacing them,
+// so the synthetic `response` tool coexists with the real ones.
+// ────────────────────────────────────────────────────────────────────────────────
+test('Model.parseOptions merges append_tools alongside the toolkit tools', () => {
+	const model = new Model();
+	const toolkitTools = [{name: 'search'}, {name: 'get_chain'}];
+
+	const {tools} = model.parseOptions({append_tools: [{name: 'response'}]}, toolkitTools);
+	assert.deepEqual(tools.map(t => t.name), ['search', 'get_chain', 'response']);
+
+	// force_tool validation still sees the appended tool
+	const {tools: forced} = model.parseOptions({append_tools: [{name: 'response'}], force_tool: 'response'}, toolkitTools);
+	assert.ok(forced.find(t => t.name === 'response'));
+});
+
 // ────────────────────────────────────────────────────────────────────────────────
 // Tool authorization: tool.authorize() returns false, generator suspends until an
 // {type:'auth'} control message arrives on the input channel.