Skip to content

7.4 billion tokens per month. 34 free LLM providers. 635 free model endpoints. All behind one /v1 endpoint, plus any custom OpenAI-compatible endpoint. Smart routing, automatic failover, encrypted keys. Personal experimentation only.

TypeScript

fix: keyed Fusion aliases and Responses API parity (#1088)

Björn Mage616fdd0624cf
diff --git a/server/src/__tests__/db/migrate/unified-key-output.test.ts b/server/src/__tests__/db/migrate/unified-key-output.test.ts
new file mode 100644
index 00000000..73065c18
--- /dev/null
+++ b/server/src/__tests__/db/migrate/unified-key-output.test.ts
@@ -0,0 +1,118 @@
+import Database from 'better-sqlite3';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { up as runLegacyBaseline } from '../../../db/migrations/20260101_000000_legacy_baseline.js';
+
+const ORIGINAL_NODE_ENV = process.env.NODE_ENV;
+const ORIGINAL_CI = process.env.CI;
+const ORIGINAL_ENCRYPTION_KEY = process.env.ENCRYPTION_KEY;
+const ORIGINAL_KUBERNETES_SERVICE_HOST = process.env.KUBERNETES_SERVICE_HOST;
+const ORIGINAL_STDOUT_TTY = Object.getOwnPropertyDescriptor(process.stdout, 'isTTY');
+
+describe('legacy baseline unified API key output', () => {
+ let output: string[];
+
+ beforeEach(() => {
+ output = [];
+ process.env.ENCRYPTION_KEY = '0'.repeat(64);
+ delete process.env.KUBERNETES_SERVICE_HOST;
+ delete process.env.CI;
+
+ vi.spyOn(console, 'log').mockImplementation((...args: unknown[]) => {
+ output.push(args.map(String).join(' '));
+ });
+ vi.spyOn(process.stdout, 'write').mockImplementation((chunk) => {
+ output.push(String(chunk));
+ return true;
+ });
+ });
+
+ afterEach(() => {
+ vi.restoreAllMocks();
+ restoreEnv('NODE_ENV', ORIGINAL_NODE_ENV);
+ restoreEnv('CI', ORIGINAL_CI);
+ restoreEnv('ENCRYPTION_KEY', ORIGINAL_ENCRYPTION_KEY);
+ restoreEnv('KUBERNETES_SERVICE_HOST', ORIGINAL_KUBERNETES_SERVICE_HOST);
+
+ if (ORIGINAL_STDOUT_TTY) {
+ Object.defineProperty(process.stdout, 'isTTY', ORIGINAL_STDOUT_TTY);
+ } else {
+ Reflect.deleteProperty(process.stdout, 'isTTY');
+ }
+ });
+
+ it('does not put a fresh key in production logs, even with an attached TTY', () => {
+ process.env.NODE_ENV = 'production';
+ setStdoutTTY(true);
+
+ const key = runBaselineAndReadKey();
+
+ expect(output.join('')).not.toContain(key);
+ expect(output.join('')).toContain('dashboard');
+ expect(output.join('')).toContain('Keys page');
+ });
+
+ it('does not put a fresh key in non-TTY development logs', () => {
+ process.env.NODE_ENV = 'development';
+ setStdoutTTY(false);
+
+ const key = runBaselineAndReadKey();
+
+ expect(output.join('')).not.toContain(key);
+ expect(output.join('')).toContain('dashboard');
+ expect(output.join('')).toContain('Keys page');
+ });
+
+ it('does not disclose a key from a Kubernetes TTY', () => {
+ process.env.NODE_ENV = 'development';
+ process.env.KUBERNETES_SERVICE_HOST = '10.0.0.1';
+ setStdoutTTY(true);
+
+ const key = runBaselineAndReadKey();
+
+ expect(output.join('')).not.toContain(key);
+ expect(output.join('')).toContain('not printed to logs');
+ });
+
+ it('does not disclose a key in CI even with a development TTY', () => {
+ process.env.NODE_ENV = 'development';
+ process.env.CI = 'true';
+ setStdoutTTY(true);
+
+ const key = runBaselineAndReadKey();
+
+ expect(output.join('')).not.toContain(key);
+ expect(output.join('')).toContain('not printed to logs');
+ });
+
+ it('discloses the full key only for interactive local development', () => {
+ process.env.NODE_ENV = 'development';
+ setStdoutTTY(true);
+
+ const key = runBaselineAndReadKey();
+
+ expect(output.join('')).toContain(`Your unified API key: ${key}`);
+ });
+});
+
+function runBaselineAndReadKey(): string {
+ const db = new Database(':memory:');
+ try {
+ runLegacyBaseline(db);
+ const row = db.prepare("SELECT value FROM settings WHERE key = 'unified_api_key'").get() as { value: string };
+ return row.value;
+ } finally {
+ db.close();
+ }
+}
+
+function setStdoutTTY(value: boolean): void {
+ Object.defineProperty(process.stdout, 'isTTY', {
+ configurable: true,
+ value,
+ });
+}
+
+function restoreEnv(name: string, value: string | undefined): void {
+ if (value === undefined) delete process.env[name];
+ else process.env[name] = value;
+}
diff --git a/server/src/__tests__/routes/fusion.test.ts b/server/src/__tests__/routes/fusion.test.ts
index d3813910..1dada99c 100644
--- a/server/src/__tests__/routes/fusion.test.ts
+++ b/server/src/__tests__/routes/fusion.test.ts
@@ -5,6 +5,7 @@ import { initDb, getDb, getUnifiedApiKey } from '../../db/index.js';
import { mintDashboardToken, isGatedApiPath } from '../helpers/auth.js';
import { isFusionModel, fusionConfigSchema, familyKey, diversifyChain } from '../../services/fusion.js';
import { getOrderedFusionChain, setRoutingStrategy, getRoutingStrategy, type FusionCandidate } from '../../services/router.js';
+import * as router from '../../services/router.js';
import { setCooldown } from '../../services/ratelimit.js';
let dashToken = '';
@@ -293,6 +294,203 @@ describe('fusion route (/v1/chat/completions, model: "fusion")', () => {
expect(groqCall?.body.tool_choice).toBe('required');
expect(groqCall?.body.parallel_tool_calls).toBe(true);
expect(upstream.calls.some(c => c.url.includes('openrouter.ai'))).toBe(false);
+ // Tool actions are not mergeable: once the first capable model returns a
+ // structured call, Fusion must not fan out to a second model that could
+ // propose a duplicate side effect.
+ expect(upstream.calls.some(c => c.url.includes('api.cerebras.ai'))).toBe(false);
+ });
+
+ it('keeps looking for a structured call when tool_choice is auto', async () => {
+ const toolCalls = [{
+ id: 'call_auto_exec',
+ type: 'function',
+ function: { name: 'exec_command', arguments: '{"cmd":"pwd"}' },
+ }];
+ const upstream = mockUpstreams({
+ 'api.groq.com': 'prose-only first candidate',
+ 'api.cerebras.ai': { content: null, tool_calls: toolCalls, finish_reason: 'tool_calls' },
+ 'openrouter.ai': 'JUDGE SHOULD NOT RUN',
+ });
+
+ const { status, body } = await request(app, 'POST', '/v1/chat/completions', {
+ model: 'fusion',
+ messages: [{ role: 'user', content: 'run the command' }],
+ tools: [{
+ type: 'function',
+ function: { name: 'exec_command', parameters: { type: 'object', properties: { cmd: { type: 'string' } } } },
+ }],
+ // Omitted/auto tool choice is the shape Codex commonly sends.
+ fusion: { models: [toolGroqModel, toolCerebrasModel], judge: openrouterModel },
+ }, authHeaders());
+
+ expect(status).toBe(200);
+ expect(body.choices[0].finish_reason).toBe('tool_calls');
+ expect(body.choices[0].message.tool_calls).toEqual(toolCalls);
+ expect(upstream.calls.some(c => c.url.includes('api.groq.com'))).toBe(true);
+ expect(upstream.calls.some(c => c.url.includes('api.cerebras.ai'))).toBe(true);
+ expect(upstream.calls.some(c => c.url.includes('openrouter.ai'))).toBe(false);
+ });
+
+ it('tries overflow after prose when an automatic one-model panel requires a tool call', async () => {
+ const toolCalls = [{ id: 'required-overflow', type: 'function', function: { name: 'get_weather', arguments: '{"city":"Dublin"}' } }];
+ vi.spyOn(router, 'getOrderedFusionChain').mockReturnValue([
+ router.resolveFusionCandidate(toolGroqModel)!, router.resolveFusionCandidate(toolCerebrasModel)!,
+ ]);
+ const upstream = mockUpstreams({
+ 'api.groq.com': 'prose does not satisfy a required tool call',
+ 'api.cerebras.ai': { content: null, tool_calls: toolCalls, finish_reason: 'tool_calls' },
+ });
+ const { status, body } = await request(app, 'POST', '/v1/chat/completions', {
+ model: 'fusion', messages: [{ role: 'user', content: 'Get the weather' }],
+ tools: [{ type: 'function', function: { name: 'get_weather', parameters: { type: 'object', properties: { city: { type: 'string' } } } } }],
+ tool_choice: 'required', fusion: { k: 1 },
+ }, authHeaders());
+ expect(status).toBe(200);
+ expect(body.choices[0].message.tool_calls).toEqual(toolCalls);
+ expect(upstream.calls.some(call => call.url.includes('api.cerebras.ai'))).toBe(true);
+ expect(body.execution_id).toBeTruthy();
+ });
+
+ it('keeps the execution ID and server error type when required tool calls fail', async () => {
+ mockUpstreams({ 'api.groq.com': 'prose only' });
+ const { status, body } = await request(app, 'POST', '/v1/chat/completions', {
+ model: 'fusion', messages: [{ role: 'user', content: 'Get the weather' }],
+ tools: [{ type: 'function', function: { name: 'get_weather', parameters: { type: 'object' } } }],
+ tool_choice: 'required', fusion: { models: [toolGroqModel] },
+ }, authHeaders());
+ expect(status).toBe(502);
+ expect(body.error.type).toBe('server_error');
+ expect(body.execution_id).toBeTruthy();
+ });
+
+ it('does not forward a tool call that violates a named tool_choice', async () => {
+ const wrongCall = [{
+ id: 'call_wrong',
+ type: 'function',
+ function: { name: 'get_weather', arguments: '{"city":"Paris"}' },
+ }];
+ const rightCall = [{
+ id: 'call_right',
+ type: 'function',
+ function: { name: 'exec_command', arguments: '{"cmd":"pwd"}' },
+ }];
+ const upstream = mockUpstreams({
+ 'api.groq.com': { content: null, tool_calls: wrongCall, finish_reason: 'tool_calls' },
+ 'api.cerebras.ai': { content: null, tool_calls: rightCall, finish_reason: 'tool_calls' },
+ 'openrouter.ai': 'JUDGE SHOULD NOT RUN',
+ });
+
+ const { status, body } = await request(app, 'POST', '/v1/chat/completions', {
+ model: 'fusion',
+ messages: [{ role: 'user', content: 'run the command' }],
+ tools: [{
+ type: 'function',
+ function: { name: 'exec_command', parameters: { type: 'object', properties: { cmd: { type: 'string' } } } },
+ }],
+ tool_choice: { type: 'function', function: { name: 'exec_command' } },
+ fusion: { models: [toolGroqModel, toolCerebrasModel], judge: openrouterModel },
+ }, authHeaders());
+
+ expect(status).toBe(200);
+ expect(body.choices[0].finish_reason).toBe('tool_calls');
+ expect(body.choices[0].message.tool_calls).toEqual(rightCall);
+ expect(upstream.calls.some(c => c.url.includes('api.groq.com'))).toBe(true);
+ expect(upstream.calls.some(c => c.url.includes('api.cerebras.ai'))).toBe(true);
+ expect(upstream.calls.some(c => c.url.includes('openrouter.ai'))).toBe(false);
+ });
+
+ it('suppresses a provider tool call when tool_choice is none', async () => {
+ const ignoredCall = [{
+ id: 'call_ignored',
+ type: 'function',
+ function: { name: 'exec_command', arguments: '{"cmd":"rm -rf /"}' },
+ }];
+ const upstream = mockUpstreams({
+ 'api.groq.com': { content: null, tool_calls: ignoredCall, finish_reason: 'tool_calls' },
+ 'api.cerebras.ai': 'safe prose fallback',
+ 'openrouter.ai': 'JUDGE SHOULD NOT RUN',
+ });
+
+ const { status, body } = await request(app, 'POST', '/v1/chat/completions', {
+ model: 'fusion',
+ messages: [{ role: 'user', content: 'answer without tools' }],
+ tools: [{
+ type: 'function',
+ function: { name: 'exec_command', parameters: { type: 'object', properties: { cmd: { type: 'string' } } } },
+ }],
+ tool_choice: 'none',
+ fusion: { models: [toolGroqModel, toolCerebrasModel], judge: openrouterModel },
+ }, authHeaders());
+
+ expect(status).toBe(200);
+ expect(body.choices[0].finish_reason).toBe('stop');
+ expect(body.choices[0].message.content).toBe('safe prose fallback');
+ expect(body.choices[0].message.tool_calls).toBeUndefined();
+ expect(upstream.calls.some(c => c.url.includes('api.groq.com'))).toBe(true);
+ expect(upstream.calls.some(c => c.url.includes('api.cerebras.ai'))).toBe(true);
+ expect(upstream.calls.some(c => c.url.includes('openrouter.ai'))).toBe(false);
+ });
+
+ it('times out a stalled tool candidate before falling back sequentially', async () => {
+ // Keep the unit test fast while exercising the same AbortSignal path used
+ // by the hosted 12s tool deadline. The first provider never answers; the
+ // second returns a valid structured call and must be reached without a
+ // parallel in-flight request.
+ getDb().prepare("INSERT INTO settings (key, value) VALUES ('fusion_tool_timeout_ms', '20') ON CONFLICT(key) DO UPDATE SET value = excluded.value").run();
+ const toolCalls = [{
+ id: 'call_exec',
+ type: 'function',
+ function: { name: 'exec_command', arguments: '{"cmd":"true"}' },
+ }];
+ const calls: string[] = [];
+ const origFetch = global.fetch;
+ vi.spyOn(global, 'fetch').mockImplementation(async (url, init) => {
+ const u = typeof url === 'string' ? url : url.toString();
+ calls.push(u);
+ if (u.includes('api.groq.com')) {
+ return await new Promise((_resolve, reject) => {
+ const signal = (init as any)?.signal as AbortSignal | undefined;
+ const abort = () => reject(signal?.reason ?? new Error('aborted'));
+ if (signal?.aborted) abort();
+ else signal?.addEventListener('abort', abort, { once: true });
+ }) as any;
+ }
+ if (u.includes('api.cerebras.ai')) {
+ return {
+ ok: true,
+ status: 200,
+ json: () => Promise.resolve({
+ id: 'chatcmpl-timeout-fallback', object: 'chat.completion', created: 1, model: 'm',
+ choices: [{ index: 0, message: { role: 'assistant', content: null, tool_calls: toolCalls }, finish_reason: 'tool_calls' }],
+ usage: { prompt_tokens: 1, completion_tokens: 1, total_tokens: 2 },
+ }),
+ } as any;
+ }
+ return origFetch(url as any, init as any);
+ });
+
+ try {
+ const started = Date.now();
+ const { status, body } = await request(app, 'POST', '/v1/chat/completions', {
+ model: 'fusion',
+ messages: [{ role: 'user', content: 'run the command' }],
+ tools: [{
+ type: 'function',
+ function: { name: 'exec_command', parameters: { type: 'object', properties: { cmd: { type: 'string' } } } },
+ }],
+ tool_choice: 'required',
+ fusion: { models: [toolGroqModel, toolCerebrasModel] },
+ }, authHeaders());
+
+ expect(status).toBe(200);
+ expect(body.choices[0].finish_reason).toBe('tool_calls');
+ expect(body.choices[0].message.tool_calls).toEqual(toolCalls);
+ expect(calls.filter(u => u.includes('api.groq.com'))).toHaveLength(1);
+ expect(calls.filter(u => u.includes('api.cerebras.ai'))).toHaveLength(1);
+ expect(Date.now() - started).toBeLessThan(2000);
+ } finally {
+ getDb().prepare("DELETE FROM settings WHERE key = 'fusion_tool_timeout_ms'").run();
+ }
});
it('keeps tool-bearing fusion panels on tool-capable models even with tool_choice none', async () => {
diff --git a/server/src/__tests__/routes/responses-fusion.test.ts b/server/src/__tests__/routes/responses-fusion.test.ts
new file mode 100644
index 00000000..6a8806dd
--- /dev/null
+++ b/server/src/__tests__/routes/responses-fusion.test.ts
@@ -0,0 +1,151 @@
+import { describe, it, expect, beforeAll, beforeEach, vi } from 'vitest';
+
+const { mockRunFusion } = vi.hoisted(() => ({ mockRunFusion: vi.fn() }));
+
+// Keep the real schema/error helpers, but isolate this route test from the
+// catalog and upstream provider implementations. The assertions below verify
+// that the Responses surface accepts the virtual id and faithfully translates
+// the existing Fusion result in both wire modes.
+vi.mock('../../services/fusion.js', async (importOriginal) => {
+ const actual = await importOriginal<typeof import('../../services/fusion.js')>();
+ return { ...actual, runFusion: mockRunFusion };
+});
+
+import type { Express } from 'express';
+import { createApp } from '../../app.js';
+import { initDb, getUnifiedApiKey } from '../../db/index.js';
+
+async function post(app: Express, body: unknown, key: string) {
+ const server = app.listen(0, '127.0.0.1');
+ if (!server.listening) await new Promise<void>(resolve => server.once('listening', () => resolve()));
+ const addr = server.address() as { port: number };
+ const response = await fetch(`http://127.0.0.1:${addr.port}/v1/responses`, {
+ method: 'POST',
+ headers: { 'Content-Type': 'application/json', Authorization: `Bearer ${key}` },
+ body: JSON.stringify(body),
+ });
+ const text = await response.text();
+ server.close();
+ return { status: response.status, text, headers: response.headers };
+}
+
+function eventPayload(text: string, event: string): any {
+ const frame = text.split(`event: ${event}\n`).at(-1)?.split('\n\n')[0];
+ const data = frame?.split('\n').find(line => line.startsWith('data: '));
+ return data ? JSON.parse(data.slice('data: '.length)) : undefined;
+}
+
+function fusionResult(text = 'fused answer') {
+ return {
+ response: {
+ id: 'chat-fusion',
+ object: 'chat.completion' as const,
+ created: 1,
+ model: 'fusion',
+ choices: [{
+ index: 0,
+ message: { role: 'assistant' as const, content: text },
+ finish_reason: 'stop',
+ }],
+ usage: { prompt_tokens: 5, completion_tokens: 7, total_tokens: 12 },
+ _fusion: {
+ panel: [{ platform: 'google', model: 'gemini-3.5-flash-lite' }],
+ judge: null,
+ synthesized: false,
+ },
+ x_fusion: { strategy: 'best_of', synthesized: false },
+ },
+ routedVia: 'fusion(google/gemini-3.5-flash-lite)',
+ };
+}
+
+describe('POST /v1/responses virtual Fusion model', () => {
+ let app: Express;
+ let key: string;
+
+ beforeAll(() => {
+ process.env.ENCRYPTION_KEY = '0'.repeat(64);
+ initDb(':memory:');
+ app = createApp();
+ key = getUnifiedApiKey();
+ });
+
+ beforeEach(() => mockRunFusion.mockReset());
+
+ it('dispatches model=fusion without a catalog row and translates the result', async () => {
+ mockRunFusion.mockResolvedValue(fusionResult());
+
+ const { status, text, headers } = await post(app, {
+ model: 'fusion',
+ input: 'compare these answers',
+ fusion: { strategy: 'best_of', k: 2, expose_panel: true },
+ }, key);
+
+ expect(status).toBe(200);
+ const body = JSON.parse(text);
+ expect(body.object).toBe('response');
+ expect(body.model).toBe('fusion');
+ expect(body.output_text).toBe('fused answer');
+ expect(body.output[0]).toMatchObject({ type: 'message', role: 'assistant' });
+ expect(body.usage).toMatchObject({ input_tokens: 5, output_tokens: 7, total_tokens: 12 });
+ expect(body).not.toHaveProperty('_fusion');
+ expect(body).not.toHaveProperty('x_fusion');
+ expect(body.metadata).toMatchObject({
+ fusion: 'true',
+ fusion_panel: 'google/gemini-3.5-flash-lite',
+ fusion_judge: 'none',
+ fusion_synthesized: 'false',
+ fusion_strategy: 'best_of',
+ });
+ expect(headers.get('x-routed-via')).toBe('fusion(google/gemini-3.5-flash-lite)');
+
+ expect(mockRunFusion).toHaveBeenCalledTimes(1);
+ expect(mockRunFusion.mock.calls[0][0]).toMatchObject({
+ messages: [{ role: 'user', content: 'compare these answers' }],
+ config: { strategy: 'best_of', k: 2, expose_panel: true },
+ vision: false,
+ });
+ });
+
+ it('emits a Responses SSE sequence for a streamed Fusion judge', async () => {
+ mockRunFusion.mockImplementation(async (params: any) => {
+ params?.hooks?.onJudgeDelta?.('fused ');
+ params?.hooks?.onJudgeDelta?.('stream');
+ return fusionResult('fused stream');
+ });
+
+ const { status, text, headers } = await post(app, {
+ model: 'fusion',
+ input: 'stream the synthesis',
+ stream: true,
+ }, key);
+
+ expect(status).toBe(200);
+ expect(headers.get('content-type')).toContain('text/event-stream');
+ for (const event of [
+ 'response.created',
+ 'response.in_progress',
+ 'response.output_item.added',
+ 'response.content_part.added',
+ 'response.output_text.delta',
+ 'response.output_text.done',
+ 'response.content_part.done',
+ 'response.output_item.done',
+ 'response.completed',
+ ]) {
+ expect(text).toContain(`event: ${event}`);
+ }
+ expect(text).toContain('"delta":"fused "');
+ expect(text).toContain('"delta":"stream"');
+ const completed = eventPayload(text, 'response.completed');
+ expect(completed.response.output_text).toBe('fused stream');
+ expect(completed.response).not.toHaveProperty('_fusion');
+ expect(completed.response).not.toHaveProperty('x_fusion');
+ expect(completed.response.metadata).toMatchObject({ fusion: 'true', fusion_synthesized: 'false' });
+ expect(headers.get('x-routed-via')).toBe('fusion');
+ expect(text).not.toContain('"_fusion"');
+ expect(text).not.toContain('"x_fusion"');
+ expect(mockRunFusion).toHaveBeenCalledTimes(1);
+ expect(mockRunFusion.mock.calls[0]?.[0]?.hooks).toBeDefined();
+ });
+});
diff --git a/server/src/__tests__/routes/responses-translate.test.ts b/server/src/__tests__/routes/responses-translate.test.ts
index c19382c4..3e1679f6 100644
--- a/server/src/__tests__/routes/responses-translate.test.ts
+++ b/server/src/__tests__/routes/responses-translate.test.ts
@@ -21,6 +21,16 @@ describe('Responses → chat translation (#96)', () => {
expect(msgs[1]).toEqual({ role: 'user', content: 'hi' });
});
+ it('drops Codex additional_tools metadata without creating an empty turn', () => {
+ const msgs = toChatMessages({
+ input: [
+ { type: 'additional_tools', id: 'at_1', role: 'developer', tools: [{ type: 'shell' }] },
+ { type: 'message', role: 'user', content: [{ type: 'input_text', text: 'hello' }] },
+ ],
+ } as any);
+ expect(msgs).toEqual([{ role: 'user', content: 'hello' }]);
+ });
+
it('flattens message items with content parts and maps the developer role to system', () => {
const msgs = toChatMessages({
input: [
diff --git a/server/src/__tests__/routes/responses.test.ts b/server/src/__tests__/routes/responses.test.ts
index 9af29494..4e82323e 100644
--- a/server/src/__tests__/routes/responses.test.ts
+++ b/server/src/__tests__/routes/responses.test.ts
@@ -51,6 +51,30 @@ describe('POST /v1/responses (#96)', () => {
expect((await post(app, '/v1/responses', { model: 'auto' }, key)).status).toBe(400);
});
+ it('accepts Codex additional_tools metadata items', async () => {
+ mockRouteRequest.mockClear();
+ mockRouteRequest.mockReturnValue(fakeRoute({
+ async chatCompletion() {
+ return {
+ id: 'c', object: 'chat.completion', created: 0, model: 'fake-model',
+ choices: [{ index: 0, message: { role: 'assistant', content: 'ok' }, finish_reason: 'stop' }],
+ usage: { prompt_tokens: 1, completion_tokens: 1, total_tokens: 2 },
+ };
+ },
+ async *streamChatCompletion() { /* unused */ },
+ }));
+
+ const { status, text } = await post(app, '/v1/responses', {
+ input: [
+ { type: 'additional_tools', id: 'at_1', role: 'developer', tools: [{ type: 'shell' }] },
+ { type: 'message', role: 'user', content: [{ type: 'input_text', text: 'hello' }] },
+ ],
+ stream: false,
+ }, key);
+ expect(status).toBe(200);
+ expect(JSON.parse(text).output_text).toBe('ok');
+ });
+
// #118: image parts now translate to image_url content blocks, so an image
// request must be routed with requireVision=true (only vision-capable models
// are candidates; a text-only pinned model is skipped, falling back to a
diff --git a/server/src/__tests__/services/fusion.test.ts b/server/src/__tests__/services/fusion.test.ts
index fc170bca..cc1758f9 100644
--- a/server/src/__tests__/services/fusion.test.ts
+++ b/server/src/__tests__/services/fusion.test.ts
@@ -1,7 +1,7 @@
import { describe, it, expect, beforeAll, beforeEach } from 'vitest';
import { initDb, getDb } from '../../db/index.js';
import { encrypt } from '../../lib/crypto.js';
-import { setRoutingStrategy } from '../../services/router.js';
+import { resolveFusionCandidate, setRoutingStrategy } from '../../services/router.js';
// A fusion unit-test fixture: seed the standard catalog, then add one healthy
// key per platform so the auto-panel chain has servable members (the seed ships
@@ -49,6 +49,28 @@ describe('selectPanel vision filtering', () => {
expect(panel.length).toBeGreaterThan(0);
expect(panel.every((c) => c.supportsVision === 1)).toBe(true);
});
+
+ it('explicit unified aliases prefer a keyed provider over a keyless duplicate', () => {
+ const db = getDb();
+ const insert = db.prepare(`
+ INSERT INTO models (platform, model_id, display_name, intelligence_rank, speed_rank, enabled)
+ VALUES (?, ?, ?, ?, ?, 1)
+ `);
+ // Make the keyless row win the normal deterministic ordering. The fusion
+ // resolver must still choose the configured provider for the same logical
+ // alias rather than spending a panel slot on a dead relay.
+ insert.run('kilo', 'edge-case-model', 'Edge Case Model (Kilo)', 1, 1);
+ insert.run('nvidia', 'edge-case-model', 'Edge Case Model (NVIDIA)', 2, 2);
+ addKey('nvidia');
+
+ try {
+ const candidate = resolveFusionCandidate('edge-case-model');
+ expect(candidate?.platform).toBe('nvidia');
+ expect(candidate?.modelId).toBe('edge-case-model');
+ } finally {
+ db.prepare("DELETE FROM models WHERE model_id = 'edge-case-model'").run();
+ }
+ });
});
describe('fusion vision judge', () => {
diff --git a/server/src/db/migrations/20260101_000000_legacy_baseline.ts b/server/src/db/migrations/20260101_000000_legacy_baseline.ts
index 3cd532a5..80426ab1 100644
--- a/server/src/db/migrations/20260101_000000_legacy_baseline.ts
+++ b/server/src/db/migrations/20260101_000000_legacy_baseline.ts
@@ -2238,14 +2238,29 @@ function ensureUnifiedKey(db: Db) {
if (!existing) {
const key = `freellmapi-${crypto.randomBytes(24).toString('hex')}`;
db.prepare("INSERT INTO settings (key, value) VALUES ('unified_api_key', ?)").run(key);
- // Straight to stdout, deliberately bypassing the console redaction installed
- // in index.ts: this is the one intentional disclosure of the key, and the
- // operator needs to copy it to configure a client. Every other path that
- // echoes a credential is an accident and stays redacted.
- process.stdout.write(`\n Your unified API key: ${key}\n\n`);
+ // A direct stdout write bypasses the process-wide console redaction, so it
+ // is only safe for a deliberate local-development session with an attached
+ // terminal. Production, CI, and container startup must never put this
+ // credential in a log stream; the dashboard is the safe retrieval path.
+ if (isInteractiveLocalDevelopment()) {
+ process.stdout.write(`\n Your unified API key: ${key}\n\n`);
+ } else {
+ console.log(
+ '\n A unified API key was generated. Open the dashboard and retrieve it from the Keys page.\n' +
+ ' The key is intentionally not printed to logs.\n',
+ );
+ }
}
}
+function isInteractiveLocalDevelopment(): boolean {
+ const nodeEnv = process.env.NODE_ENV?.trim().toLowerCase() || 'development';
+ return nodeEnv === 'development'
+ && process.stdout.isTTY === true
+ && !process.env.CI
+ && !process.env.KUBERNETES_SERVICE_HOST;
+}
+
/**
* Migration helper to ensure Default profile exists, legacy profiles converted,
* and fallback_config synced.
diff --git a/server/src/routes/proxy.ts b/server/src/routes/proxy.ts
index 98f29909..6b6aab20 100644
--- a/server/src/routes/proxy.ts
+++ b/server/src/routes/proxy.ts
@@ -1663,6 +1663,24 @@ proxyRouter.post('/chat/completions', async (req: Request, res: Response) => {
}
max_tokens = budgetCheck.maxTokens;
+ // Client-disconnect fan-out: the flag stops the loop before the NEXT
+ // attempt; the AbortController (threaded to the provider as
+ // CompletionOptions.signal) additionally cancels the IN-FLIGHT upstream
+ // fetch and any body/stream read, so tokens stop burning and the in-flight
+ // lease frees immediately. 'close' also fires on normal completion —
+ // writableEnded distinguishes a real disconnect.
+ //
+ // This controller is declared before the Fusion branch because Fusion uses
+ // the same cancellation signal as the ordinary fallback loop below.
+ let clientGone = false;
+ const clientAbort = new AbortController();
+ res.on('close', () => {
+ if (!res.writableEnded) {
+ clientGone = true;
+ clientAbort.abort(newClientAbortError());
+ }
+ });
+
// ── Fusion: multi-model synthesis ──────────────────────────────────────────
// The virtual "fusion" model fans the prompt out to a panel of diverse models
// in parallel, then a judge synthesizes one answer. It routes each panel/judge
@@ -1671,7 +1689,11 @@ proxyRouter.post('/chat/completions', async (req: Request, res: Response) => {
// Image requests run on vision-capable panel members; tool requests run on
// tool-capable members and return the first structured tool call directly.
if (isFusionModel(requestedModel)) {
- const fusionOptions = { temperature, max_tokens, top_p, stop, tools, tool_choice, parallel_tool_calls, ...samplingParams };
+ // Keep Fusion's sequential tool fallback tied to the caller's socket. The
+ // Responses route already threads this signal; the legacy Chat surface
+ // needs the same cancellation so a disconnected client does not leave a
+ // bounded-but-expensive provider call running in the background.
+ const fusionOptions = { temperature, max_tokens, top_p, stop, tools, tool_choice, parallel_tool_calls, ...samplingParams, signal: clientAbort.signal };
const fusionConfig = parsed.data.fusion ?? {};
if (stream) {
@@ -1735,7 +1757,9 @@ proxyRouter.post('/chat/completions', async (req: Request, res: Response) => {
}
} catch (err: any) {
const message = err instanceof FusionError ? err.message : `fusion error: ${sanitizeProviderErrorMessage(err?.message)}`;
- const type = err instanceof FusionError && err.status === 429 ? 'rate_limit_error' : 'server_error';
+ const type = err instanceof FusionError
+ ? (err.status === 429 ? 'rate_limit_error' : err.status >= 500 ? 'server_error' : 'invalid_request_error')
+ : 'server_error';
writeFrame({ error: { message, type } });
}
try { res.write('data: [DONE]\n\n'); res.end(); } catch { /* socket gone */ }
@@ -1772,7 +1796,13 @@ proxyRouter.post('/chat/completions', async (req: Request, res: Response) => {
res.json({ ...response, execution_id: requestGroupId });
} catch (err: any) {
if (err instanceof FusionError) {
- res.status(err.status).json({ error: { message: err.message, type: err.status === 429 ? 'rate_limit_error' : 'invalid_request_error' }, execution_id: requestGroupId });
+ res.status(err.status).json({
+ error: {
+ message: err.message,
+ type: err.status === 429 ? 'rate_limit_error' : err.status >= 500 ? 'server_error' : 'invalid_request_error',
+ },
+ execution_id: requestGroupId,
+ });
} else {
res.status(502).json({ error: { message: `fusion error: ${sanitizeProviderErrorMessage(err?.message)}`, type: 'server_error' }, execution_id: requestGroupId });
}
@@ -2031,24 +2061,10 @@ proxyRouter.post('/chat/completions', async (req: Request, res: Response) => {
// stream turn-integrity framing.
const state = newFallbackState();
const attemptLog: AttemptRecord[] = [];
- // Client-disconnect fan-out: the flag stops the loop before the NEXT
- // attempt; the AbortController (threaded to the provider as
- // CompletionOptions.signal) additionally cancels the IN-FLIGHT upstream
- // fetch and any body/stream read, so tokens stop burning and the in-flight
- // lease frees immediately. 'close' also fires on normal completion —
- // writableEnded distinguishes a real disconnect.
- let clientGone = false;
- const clientAbort = new AbortController();
// Fallback-v2 hedging: the loop aborts this controller (via abortInFlight)
// when the wall-clock retry budget expires mid-attempt, canceling the
// in-flight upstream instead of waiting for a stalled attempt to time out.
const hedgeAbort = new AbortController();
- res.on('close', () => {
- if (!res.writableEnded) {
- clientGone = true;
- clientAbort.abort(newClientAbortError());
- }
- });
await runFallbackLoop({
maxRetries: MAX_RETRIES,
diff --git a/server/src/routes/responses.ts b/server/src/routes/responses.ts
index 615eb619..21ce5e24 100644
--- a/server/src/routes/responses.ts
+++ b/server/src/routes/responses.ts
@@ -30,7 +30,7 @@ import {
logRequest,
} from './proxy.js';
import { runFallbackLoop, newFallbackState, recordUpstreamSuccess, setFallbackHeaders, exhaustionErrorPayload, setExhaustionHeaders, type AttemptRecord } from '../lib/fallback-loop.js';
-import { routedViaValue } from '../lib/header-value.js';
+import { routedViaValue, safeHeaderValue } from '../lib/header-value.js';
import { applyTokenBudget, tokenBudgetMessage } from '../lib/guardrails.js';
import { samplingParamSchemaFields, pickSamplingParams, type ResponseFormat } from '../lib/sampling-params.js';
import { enforceJsonContent } from '../lib/structured-output.js';
@@ -38,6 +38,14 @@ import { sanitizeProviderErrorMessage } from '../lib/error-redaction.js';
import { isClientAbortError, newClientAbortError, newHedgeAbortError } from '../lib/error-classify.js';
import { inferQuotaPoolKey, type QuotaObservationContext } from '../services/provider-quota.js';
import { compressRequest, formatCompressionHeader } from '../services/compression/pipeline.js';
+import {
+ FUSION_MODEL_ID,
+ FusionError,
+ fusionConfigSchema,
+ isFusionModel,
+ runFusion,
+ type FusionResult,
+} from '../services/fusion.js';
export const responsesRouter = Router();
@@ -144,6 +152,19 @@ const localShellCallItemSchema = z.object({
id: z.string().optional(),
}).passthrough();
+// Codex sends its client-side tool inventory as an `additional_tools` input
+// item on every Responses turn. It is metadata for the harness, not a chat
+// message, so the translator deliberately drops it below. Keep the schema
+// permissive because Codex may add fields (or tool shapes) as the inventory
+// evolves; rejecting the whole request here turns an otherwise valid launch
+// into a misleading `input: Invalid input` 400.
+const additionalToolsItemSchema = z.object({
+ type: z.literal('additional_tools'),
+ id: z.string().optional(),
+ role: z.string().optional(),
+ tools: z.array(z.record(z.string(), z.unknown())).optional(),
+}).passthrough();
+
// The rest of the official ResponseInputItemParam union: built-in tool calls
// (web_search, file_search, code interpreter, image generation), MCP items,
// and item references. None has a chat-completions equivalent — validated
@@ -165,6 +186,7 @@ const inputItemSchema = z.union([
computerCallOutputItemSchema,
reasoningItemSchema,
localShellCallItemSchema,
+ additionalToolsItemSchema,
otherKnownItemSchema,
messageItemSchema,
]);
@@ -191,6 +213,10 @@ const responsesRequestSchema = z.object({
top_p: z.number().min(0).max(1).nullable().optional(),
max_output_tokens: z.number().int().positive().nullable().optional(),
tools: z.array(responsesToolSchema).optional(),
+ // The virtual Fusion model fans the translated conversation out to a
+ // diverse panel, then optionally synthesizes the survivors. Keep the
+ // Responses surface in parity with /v1/chat/completions.
+ fusion: fusionConfigSchema.optional(),
tool_choice: z.union([
z.enum(['none', 'auto', 'required']),
z.object({ type: z.literal('function'), name: z.string() }).passthrough(),
@@ -459,6 +485,7 @@ export function buildResponseObject(opts: {
promptTokens: number;
completionTokens: number;
reasoningTokens?: number;
+ metadata?: Record<string, string>;
}) {
const output: any[] = [];
if (opts.text.length > 0) {
@@ -496,7 +523,90 @@ export function buildResponseObject(opts: {
output_tokens_details: { reasoning_tokens: opts.reasoningTokens ?? 0 },
total_tokens: opts.promptTokens + opts.completionTokens,
},
+ ...(opts.metadata ? { metadata: opts.metadata } : {}),
+ };
+}
+
+/**
+ * Translate the chat-shaped result returned by the Fusion service into the
+ * Responses object clients expect. Chat Fusion uses additive `_fusion` and
+ * `x_fusion` fields, but those are not part of the Responses schema and strict
+ * SDKs (including Codex) reject them while decoding `response.completed`.
+ * Preserve the portable routing summary in the standard string-valued
+ * `metadata` map instead; the chat surface keeps its richer fields unchanged.
+ */
+function buildFusionResponseObject(id: string, result: FusionResult): Record<string, unknown> {
+ const fusionResponse = result.response as FusionResult['response'] & {
+ _fusion?: unknown;
+ x_fusion?: unknown;
};
+ const message = fusionResponse.choices?.[0]?.message;
+ const usage = fusionResponse.usage;
+ const response = buildResponseObject({
+ id,
+ model: FUSION_MODEL_ID,
+ text: contentToString(message?.content ?? ''),
+ toolCalls: message?.tool_calls ?? [],
+ promptTokens: usage?.prompt_tokens ?? 0,
+ completionTokens: usage?.completion_tokens ?? 0,
+ reasoningTokens: usage?.completion_tokens_details?.reasoning_tokens,
+ metadata: fusionResponseMetadata(fusionResponse),
+ }) as Record<string, unknown>;
+
+ return response;
+}
+
+function fusionResponseMetadata(result: FusionResult['response'] & { _fusion?: unknown; x_fusion?: unknown }): Record<string, string> {
+ const metadata: Record<string, string> = { fusion: 'true' };
+ const summary = result._fusion && typeof result._fusion === 'object' && !Array.isArray(result._fusion)
+ ? result._fusion as Record<string, unknown>
+ : undefined;
+ const details = result.x_fusion && typeof result.x_fusion === 'object' && !Array.isArray(result.x_fusion)
+ ? result.x_fusion as Record<string, unknown>
+ : undefined;
+
+ if (Array.isArray(summary?.panel)) {
+ const panel = summary.panel
+ .map((entry) => {
+ if (!entry || typeof entry !== 'object') return null;
+ const item = entry as Record<string, unknown>;
+ return typeof item.platform === 'string' && typeof item.model === 'string'
+ ? `${item.platform}/${item.model}`
+ : null;
+ })
+ .filter((entry): entry is string => entry !== null);
+ if (panel.length > 0) metadata.fusion_panel = panel.join(',');
+ }
+
+ if (summary && 'judge' in summary) {
+ const judge = summary.judge;
+ if (judge && typeof judge === 'object') {
+ const item = judge as Record<string, unknown>;
+ if (typeof item.platform === 'string' && typeof item.model === 'string') {
+ metadata.fusion_judge = `${item.platform}/${item.model}`;
+ }
+ } else {
+ metadata.fusion_judge = 'none';
+ }
+ }
+
+ if (typeof summary?.synthesized === 'boolean') metadata.fusion_synthesized = String(summary.synthesized);
+ if (typeof details?.strategy === 'string') metadata.fusion_strategy = details.strategy;
+ return metadata;
+}
+
+/** Apply the same structured-output contract to Fusion as the chat route. */
+function enforceFusionResponseFormat(result: FusionResult, responseFormat: ResponseFormat | undefined): void {
+ if (!responseFormat) return;
+ const message = result.response.choices?.[0]?.message as any;
+ if (!message || message.tool_calls?.length) return;
+ const text = contentToString(message.content ?? '');
+ if (!text) return;
+ const enforced = enforceJsonContent(text);
+ if (!enforced.ok) {
+ throw new Error(`fusion produced non-JSON output despite response_format=${responseFormat.type} — retry, or pin a structured-output-capable model instead of "fusion"`);
+ }
+ if (enforced.healed) message.content = enforced.content;
}
function quotaContextForRoute(route: RouteResult, endpoint: string): QuotaObservationContext {
@@ -674,6 +784,9 @@ responsesRouter.post('/responses', async (req: Request, res: Response) => {
if (isAutoModel(requestedModelLabel)) {
preferredModel = resolveStickyPreference(getStickyModel(messages, sessionIdHeader));
+ } else if (isFusionModel(requestedModelLabel)) {
+ // Fusion is a virtual model, not a row in the catalog. Its panel and
+ // judge each resolve through the normal router inside runFusion below.
} else {
const db = getDb();
const resolved = isUnifyEnabled() ? resolveRequestedIdForDispatch(requestedModelLabel, getModelGroups()) : null;
@@ -754,6 +867,229 @@ responsesRouter.post('/responses', async (req: Request, res: Response) => {
});
const dispatchOpts = { ...completionOpts, signal: AbortSignal.any([clientAbort.signal, hedgeAbort.signal]) };
+ // ── Fusion: Responses-API virtual model ────────────────────────────────
+ // `fusion` is intentionally not a catalog row. The chat route handles this
+ // virtual id before normal model dispatch; do the same here after the common
+ // Responses translation/guardrails so Codex and other Responses clients can
+ // opt into the exact same panel + judge behavior.
+ if (isFusionModel(requestedModelLabel)) {
+ const fusionConfig = reqData.fusion ?? {};
+ const fusionOptions = { ...dispatchOpts };
+
+ if (!stream) {
+ try {
+ const result = await runFusion({
+ messages,
+ config: fusionConfig,
+ options: fusionOptions,
+ estimatedTokens: estimatedTotal,
+ vision: hasImage,
+ });
+ enforceFusionResponseFormat(result, samplingParams.response_format);
+ res.setHeader('X-Routed-Via', safeHeaderValue(result.routedVia));
+ res.json(buildFusionResponseObject(responseId, result));
+ } catch (err: any) {
+ if (err instanceof FusionError) {
+ res.status(err.status).json({
+ error: {
+ message: err.message,
+ type: err.status === 429 ? 'rate_limit_error' : err.status >= 500 ? 'server_error' : 'invalid_request_error',
+ },
+ });
+ } else {
+ res.status(502).json({
+ error: {
+ message: `fusion error: ${sanitizeProviderErrorMessage(err?.message)}`,
+ type: 'server_error',
+ },
+ });
+ }
+ }
+ return;
+ }
+
+ // A streamed Fusion judge can emit deltas through runFusion's hook. Panel
+ // and best-of/single-survivor paths remain valid Responses streams too:
+ // they simply emit the completed answer once the fan-out settles.
+ res.setHeader('Content-Type', 'text/event-stream');
+ res.setHeader('Cache-Control', 'no-cache');
+ res.setHeader('Connection', 'keep-alive');
+ // The detailed panel is only known after runFusion settles, but the
+ // standard header can still identify this stream as Fusion before the
+ // response is committed. The final metadata carries panel/judge details.
+ res.setHeader('X-Routed-Via', FUSION_MODEL_ID);
+ let fusionSequence = 0;
+ const fusionSse = (event: string, payload: Record<string, unknown>) => {
+ if (res.writableEnded) return;
+ try {
+ res.write(`event: ${event}\n`);
+ res.write(`data: ${JSON.stringify({ type: event, sequence_number: fusionSequence++, ...payload })}\n\n`);
+ } catch {
+ // The close listener aborts the provider signal; a late write can still
+ // race the socket teardown and is intentionally ignored.
+ }
+ };
+ const skeleton = {
+ id: responseId,
+ object: 'response',
+ created_at: nowUnix(),
+ status: 'in_progress',
+ model: FUSION_MODEL_ID,
+ output: [],
+ output_text: '',
+ metadata: { fusion: 'true' },
+ };
+ fusionSse('response.created', { response: skeleton });
+ fusionSse('response.in_progress', { response: skeleton });
+
+ // Fusion fans out to several upstream models before the judge can emit a
+ // token. That gap can exceed the ~15s idle timeout used by Codex's
+ // Responses client even though the HTTP connection is healthy. A standard
+ // in-progress event keeps the client-side event watchdog alive; comments
+ // are ignored by Codex's watchdog even though they refresh curl's stream.
+ const fusionHeartbeat = setInterval(() => {
+ if (res.writableEnded || res.destroyed) return;
+ try {
+ fusionSse('response.in_progress', { response: skeleton });
+ } catch {
+ // The close listener aborts the in-flight fan-out; a late heartbeat
+ // racing socket teardown is harmless.
+ }
+ }, 5000);
+ fusionHeartbeat.unref?.();
+
+ let textItemId: string | null = null;
+ const textOutputIndex = 0;
+ let streamedText = '';
+ const openTextItem = (id: string = newId('msg')) => {
+ if (textItemId !== null) return;
+ textItemId = id;
+ fusionSse('response.output_item.added', {
+ output_index: textOutputIndex,
+ item: { id, type: 'message', status: 'in_progress', role: 'assistant', content: [] },
+ });
+ fusionSse('response.content_part.added', {
+ item_id: id,
+ output_index: textOutputIndex,
+ content_index: 0,
+ part: { type: 'output_text', text: '', annotations: [] },
+ });
+ };
+
+ try {
+ const result = await runFusion({
+ messages,
+ config: fusionConfig,
+ options: fusionOptions,
+ estimatedTokens: estimatedTotal,
+ vision: hasImage,
+ hooks: {
+ onJudgeDelta: (delta) => {
+ if (!delta) return;
+ openTextItem();
+ fusionSse('response.output_text.delta', {
+ item_id: textItemId,
+ output_index: textOutputIndex,
+ content_index: 0,
+ delta,
+ });
+ streamedText += delta;
+ },
+ },
+ });
+ // Like the chat route's streamed Fusion branch, do not run a structured
+ // output verdict after judge deltas have already reached the client: a
+ // failed verdict could not retract the partial answer. Non-streaming
+ // Fusion is checked above before the response is committed.
+ const responseObject = buildFusionResponseObject(responseId, result) as any;
+ const outputs = Array.isArray(responseObject.output) ? responseObject.output : [];
+ const messageOutput = outputs.find((item: any) => item?.type === 'message');
+ const finalText = typeof responseObject.output_text === 'string' ? responseObject.output_text : '';
+
+ if (messageOutput) {
+ // Keep the final Response object's message id aligned with any judge
+ // deltas already emitted on the wire.
+ if (textItemId === null) openTextItem(messageOutput.id);
+ else messageOutput.id = textItemId;
+ if (finalText && !streamedText) {
+ fusionSse('response.output_text.delta', {
+ item_id: textItemId,
+ output_index: textOutputIndex,
+ content_index: 0,
+ delta: finalText,
+ });
+ streamedText = finalText;
+ } else if (finalText.length > streamedText.length && finalText.startsWith(streamedText)) {
+ fusionSse('response.output_text.delta', {
+ item_id: textItemId,
+ output_index: textOutputIndex,
+ content_index: 0,
+ delta: finalText.slice(streamedText.length),
+ });
+ streamedText = finalText;
+ }
+ fusionSse('response.output_text.done', {
+ item_id: textItemId,
+ output_index: textOutputIndex,
+ content_index: 0,
+ text: finalText,
+ });
+ fusionSse('response.content_part.done', {
+ item_id: textItemId,
+ output_index: textOutputIndex,
+ content_index: 0,
+ part: { type: 'output_text', text: finalText, annotations: [] },
+ });
+ fusionSse('response.output_item.done', {
+ output_index: textOutputIndex,
+ item: messageOutput,
+ });
+ }
+
+ let outputIndex = messageOutput ? 1 : 0;
+ for (const output of outputs) {
+ if (output?.type !== 'function_call') continue;
+ const item = { ...output, status: 'in_progress', arguments: '' };
+ fusionSse('response.output_item.added', { output_index: outputIndex, item });
+ if (output.arguments) {
+ fusionSse('response.function_call_arguments.delta', {
+ item_id: output.id,
+ output_index: outputIndex,
+ delta: output.arguments,
+ });
+ }
+ fusionSse('response.function_call_arguments.done', {
+ item_id: output.id,
+ output_index: outputIndex,
+ arguments: output.arguments ?? '',
+ });
+ fusionSse('response.output_item.done', { output_index: outputIndex, item: output });
+ outputIndex++;
+ }
+
+ fusionSse('response.completed', { response: responseObject });
+ res.end();
+ } catch (err: any) {
+ const message = err instanceof FusionError
+ ? err.message
+ : `fusion error: ${sanitizeProviderErrorMessage(err?.message)}`;
+ const type = err instanceof FusionError
+ ? (err.status === 429 ? 'rate_limit_error' : err.status >= 500 ? 'server_error' : 'invalid_request_error')
+ : 'server_error';
+ fusionSse('response.failed', {
+ response: {
+ ...skeleton,
+ status: 'failed',
+ error: { message, type },
+ },
+ });
+ res.end();
+ } finally {
+ clearInterval(fusionHeartbeat);
+ }
+ return;
+ }
+
// Stream bookkeeping (used only when stream === true). `streamStarted` is the
// commit flag: true once the response.created/in_progress skeleton has left,
// after which failover is no longer possible. seq/streamStarted span attempts
diff --git a/server/src/services/fusion.ts b/server/src/services/fusion.ts
index de4d33b2..c9afdbd1 100644
--- a/server/src/services/fusion.ts
+++ b/server/src/services/fusion.ts
@@ -48,6 +48,14 @@ const SYNTHESIS_QUORUM = 2;
const MAX_SLOT_ATTEMPTS = 4;
// Judge dispatch walks the normal auto chain; give it room to fail over.
const MAX_JUDGE_ATTEMPTS = 6;
+// Tool calls are actions, not independent prose. Running a whole Fusion panel
+// for them is both unsafe (several models can propose the same side effect)
+// and needlessly slow (one stalled provider holds Promise.allSettled open).
+// Keep each sequential candidate bounded well below the provider's generous
+// cold-start timeout; a slower candidate can still be reached through the
+// normal ordered fallback list after this one is abandoned.
+const DEFAULT_TOOL_CALL_TIMEOUT_MS = 12_000;
+const MAX_TOOL_CALL_TIMEOUT_MS = 120_000;
function intSetting(key: string, fallback: number): number {
const raw = getSetting(key);
@@ -56,6 +64,36 @@ function intSetting(key: string, fallback: number): number {
return Number.isFinite(n) && n > 0 ? n : fallback;
}
+function toolCallTimeoutMs(): number {
+ return Math.min(
+ intSetting('fusion_tool_timeout_ms', DEFAULT_TOOL_CALL_TIMEOUT_MS),
+ MAX_TOOL_CALL_TIMEOUT_MS,
+ );
+}
+
+/**
+ * Give one tool-bearing panel candidate its own deadline while preserving the
+ * caller's disconnect signal. The timer is cancelled as soon as the candidate
+ * settles; aborting a request is deliberately scoped to this candidate so a
+ * later fallback can still run.
+ */
+function withToolCallDeadline(options: CompletionOptions): { options: CompletionOptions; cancel: () => void } {
+ const controller = new AbortController();
+ const timeoutMs = toolCallTimeoutMs();
+ const timer = setTimeout(() => {
+ controller.abort(new Error(`fusion tool call timed out after ${timeoutMs}ms`));
+ }, timeoutMs);
+ timer.unref?.();
+
+ const signal = options.signal
+ ? AbortSignal.any([options.signal, controller.signal])
+ : controller.signal;
+ return {
+ options: { ...options, signal },
+ cancel: () => clearTimeout(timer),
+ };
+}
+
function panelDefaultK(): number {
return Math.min(intSetting('fusion_default_k', DEFAULT_PANEL_K), panelMaxK());
}
@@ -564,6 +602,15 @@ export async function runFusion(params: {
const strategy = config.strategy ?? 'synthesize';
const requireTools = (options.tools?.length ?? 0) > 0;
+ const requiresToolCall = options.tool_choice === 'required'
+ || (typeof options.tool_choice === 'object' && options.tool_choice !== null);
+ const requiredToolName = typeof options.tool_choice === 'object'
+ ? options.tool_choice.function.name
+ : undefined;
+ // `tool_choice=auto` (or an omitted choice) still allows a model to emit a
+ // structured call. Continue past a prose-only candidate so a later capable
+ // model gets a chance; `none` is the explicit opt-out and may stop at prose.
+ const acceptsToolCall = options.tool_choice !== 'none';
const { panel, overflow, dropped } = selectPanel(config, { requireTools, requireVision: vision, estimatedTokens });
if (panel.length === 0) {
const hint = vision
@@ -579,12 +626,17 @@ export async function runFusion(params: {
// model's keys (so a key 429 doesn't collapse the slot onto a duplicate
// backend — issue #326). Returns its answer and fires onPanel the moment it
// settles so a streaming client sees answers arrive one by one.
- const runSlot = (cand: FusionCandidate): Promise<PanelAnswer> =>
+ const runSlot = (cand: FusionCandidate, slotOptions: CompletionOptions = options): Promise<PanelAnswer> =>
runModelCall(
(skipKeys) => routePinnedModel(cand.modelDbId, estimatedTokens, skipKeys),
- messages, options, estimatedTokens, MAX_SLOT_ATTEMPTS,
+ messages, slotOptions, estimatedTokens, MAX_SLOT_ATTEMPTS,
).then((outcome): PanelAnswer => {
- const answer: PanelAnswer = outcome.ok
+ const returnedToolCalls = outcome.toolCalls;
+ const forbiddenToolCall = options.tool_choice === 'none' && !!returnedToolCalls?.length;
+ const wrongNamedTool = !!requiredToolName
+ && !!returnedToolCalls?.length
+ && returnedToolCalls.some(tc => tc.function?.name !== requiredToolName);
+ const answer: PanelAnswer = outcome.ok && !wrongNamedTool && !forbiddenToolCall
? {
modelDbId: cand.modelDbId,
platform: cand.platform,
@@ -596,7 +648,18 @@ export async function runFusion(params: {
rawChoice: outcome.rawChoice,
usage: outcome.usage,
}
- : { modelDbId: cand.modelDbId, platform: cand.platform, modelId: cand.modelId, displayName: cand.displayName, status: 'failed', error: outcome.error };
+ : {
+ modelDbId: cand.modelDbId,
+ platform: cand.platform,
+ modelId: cand.modelId,
+ displayName: cand.displayName,
+ status: 'failed',
+ error: wrongNamedTool
+ ? `provider returned a tool call other than required function '${requiredToolName}'`
+ : forbiddenToolCall
+ ? 'provider returned a tool call despite tool_choice=none'
+ : outcome.error,
+ };
hooks?.onPanel?.({ platform: answer.platform, model: answer.modelId, status: answer.status, content: answer.content, tool_calls: answer.toolCalls, error: answer.error });
return answer;
});
@@ -613,17 +676,45 @@ export async function runFusion(params: {
const answers: PanelAnswer[] = [];
let okCount = 0;
let cursor = 0;
- while (okCount < target && cursor < candidates.length) {
- const wave = candidates.slice(cursor, cursor + (target - okCount));
- cursor += wave.length;
- const settled = await Promise.allSettled(wave.map(runSlot));
- settled.forEach((s, i) => {
- const a: PanelAnswer = s.status === 'fulfilled'
- ? s.value
- : { modelDbId: wave[i].modelDbId, platform: wave[i].platform, modelId: wave[i].modelId, displayName: wave[i].displayName, status: 'failed', error: sanitizeProviderErrorMessage((s as PromiseRejectedResult).reason?.message) };
- answers.push(a);
- if (a.status === 'ok' && (a.content || (a.toolCalls?.length ?? 0) > 0)) okCount++;
- });
+ if (requireTools) {
+ // Tool calls are not safely mergeable: the client may execute the returned
+ // action, so asking several models in parallel can produce duplicate or
+ // contradictory side effects. Walk the ordered candidates one at a time,
+ // stopping at the first structured call (or the target number of prose
+ // survivors when the model declines to call). Each candidate gets a bounded signal so a slow
+ // provider cannot hold the Responses stream open for its full 180s
+ // cold-start budget. This also makes fallback deterministic and releases
+ // the provider lease before the next candidate starts.
+ while (cursor < candidates.length) {
+ const cand = candidates[cursor++];
+ const deadline = withToolCallDeadline(options);
+ let answer: PanelAnswer;
+ try {
+ answer = await runSlot(cand, deadline.options);
+ } finally {
+ deadline.cancel();
+ }
+ answers.push(answer);
+ const usable = answer.status === 'ok' && (answer.content || (answer.toolCalls?.length ?? 0) > 0);
+ if (usable) {
+ okCount++;
+ if (answer.toolCalls?.length && acceptsToolCall) break;
+ if (!acceptsToolCall || (!requiresToolCall && okCount >= target)) break;
+ }
+ }
+ } else {
+ while (okCount < target && cursor < candidates.length) {
+ const wave = candidates.slice(cursor, cursor + (target - okCount));
+ cursor += wave.length;
+ const settled = await Promise.allSettled(wave.map(cand => runSlot(cand)));
+ settled.forEach((s, i) => {
+ const a: PanelAnswer = s.status === 'fulfilled'
+ ? s.value
+ : { modelDbId: wave[i].modelDbId, platform: wave[i].platform, modelId: wave[i].modelId, displayName: wave[i].displayName, status: 'failed', error: sanitizeProviderErrorMessage((s as PromiseRejectedResult).reason?.message) };
+ answers.push(a);
+ if (a.status === 'ok' && (a.content || (a.toolCalls?.length ?? 0) > 0)) okCount++;
+ });
+ }
}
const survivors = answers.filter(a => a.status === 'ok' && (a.content || (a.toolCalls?.length ?? 0) > 0));
@@ -688,6 +779,16 @@ export async function runFusion(params: {
};
}
+ if (requiresToolCall) {
+ // `tool_choice=required` (or a named function choice) is a contract with
+ // the caller. Returning prose after every candidate ignored that contract
+ // would leave an agent waiting for a tool result that can never arrive.
+ throw new FusionError(
+ 'fusion: no panel model returned the required tool call. Try again or pick a tool-capable `fusion.models` entry.',
+ 502,
+ );
+ }
+
const textSurvivors = survivors.filter(a => a.content);
// Decide the final answer.
diff --git a/server/src/services/router.ts b/server/src/services/router.ts
index 95b804e3..ee22bc40 100644
--- a/server/src/services/router.ts
+++ b/server/src/services/router.ts
@@ -1900,18 +1900,23 @@ export function getOrderedFusionChain(estimatedTokens: number, exactOutputReserv
*/
export function resolveFusionCandidate(modelId: string): FusionCandidate | null {
const db = getDb();
- const row = db.prepare(`
+ const rows = db.prepare(`
SELECT m.id as model_db_id, m.platform, m.model_id, m.display_name,
m.size_label, m.supports_vision, m.supports_tools
FROM models m
WHERE m.model_id = ? AND m.enabled = 1
ORDER BY m.intelligence_rank ASC, m.id ASC
- LIMIT 1
- `).get(modelId) as {
+ `).all(modelId) as {
model_db_id: number; platform: string; model_id: string; display_name: string;
size_label: string; supports_vision: number; supports_tools: number;
- } | undefined;
- if (row) {
+ }[];
+ if (rows.length > 0) {
+ // A logical model can have several enabled provider rows. Prefer one with
+ // an enabled, healthy/unknown key before falling back to the deterministic
+ // ranking. Without this check a duplicate alias can pin fusion to a
+ // keyless provider (for example a free relay) while a configured provider
+ // for the same model is available.
+ const row = rows.find(candidate => routableKeyIdsForModel(candidate.model_db_id).length > 0) ?? rows[0];
return {
modelDbId: row.model_db_id,
platform: row.platform,
@@ -1930,7 +1935,11 @@ export function resolveFusionCandidate(modelId: string): FusionCandidate | null
if (isUnifyEnabled()) {
const resolved = resolveRequestedIdForDispatch(modelId, getModelGroups());
if (resolved && resolved.memberDbIds.length > 0) {
- const top = resolveModelGroupCandidates(resolved.memberDbIds, resolved.demotedDbIds)[0];
+ const candidates = resolveModelGroupCandidates(resolved.memberDbIds, resolved.demotedDbIds);
+ // Bare unified aliases may resolve to a provider row that is enabled in
+ // the catalog but has no usable key. Select the first routable member so
+ // an explicit fusion panel does not waste a slot on that dead end.
+ const top = candidates.find(candidate => routableKeyIdsForModel(candidate.model_db_id).length > 0) ?? candidates[0];
if (top) {
return {
modelDbId: top.model_db_id,