Skip to content

armgit / cindy

Public Imported from GitHub
0

Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。

fix(utility-model): use the least thinking each model allows in auxiliary requests

fmfsaisai916dc719821a
diff --git a/apps/desktop/src/main/utility-model/__tests__/oneShotCandidates.test.ts b/apps/desktop/src/main/utility-model/__tests__/oneShotCandidates.test.ts
index cbab2907e7..6f6a0b9658 100644
--- a/apps/desktop/src/main/utility-model/__tests__/oneShotCandidates.test.ts
+++ b/apps/desktop/src/main/utility-model/__tests__/oneShotCandidates.test.ts
@@ -124,6 +124,8 @@ import {
requestUtilityText,
toAnthropicApiModelId,
} from '../oneShotCandidates.js';
+import { resetUtilityReasoningMemory } from '../utilityReasoningPlan.js';
+import { AUTO_AUXILIARY_MODEL_CHAIN } from '../../../shared/auxiliaryModelChain.js';
const getProfiles = vi.mocked(getUtilityModelChainProfiles);
const appCapabilities = vi.mocked(getAppCapabilities);
@@ -151,6 +153,7 @@ describe('utility one-shot candidates', () => {
beforeEach(() => {
vi.clearAllMocks();
fetchMock.mockReset();
+ resetUtilityReasoningMemory();
chainState.source = 'auto';
chainState.refs = ['codex-gpt-5.4-mini', 'litellm-gpt-5.4-mini'];
ownerState.key = 'owner-a';
@@ -3174,4 +3177,639 @@ describe('utility one-shot candidates', () => {
expect(reportKeyRejected).toHaveBeenCalledWith('review-key-sent');
});
});
+
+ describe('least-thinking reasoning plan', () => {
+ const GATEWAY = 'https://gateway.test.invalid';
+ const rejected = (status: number) => ({
+ ok: false,
+ status,
+ body: { cancel: vi.fn(async () => undefined) },
+ });
+ const chatOk = (content: string) => ({
+ ok: true,
+ text: async () => JSON.stringify({ choices: [{ message: { content } }] }),
+ });
+ const responsesOk = (text: string) => ({
+ ok: true,
+ text: async () => `data: {"type":"response.output_text.delta","delta":"${text}"}\ndata: [DONE]\n`,
+ });
+ const messagesOk = (text: string) => ({
+ ok: true,
+ text: async () => JSON.stringify({ content: [{ type: 'text', text }] }),
+ });
+ const urlOf = (index: number) => fetchMock.mock.calls[index]?.[0];
+ const bodyOf = (index: number) =>
+ JSON.parse(String(fetchMock.mock.calls[index]?.[1]?.body)) as Record<string, unknown>;
+
+ function xdCatalog(agent: 'codex' | 'claude-code', models: Array<Record<string, unknown>>) {
+ return {
+ providers: [{
+ id: 'xd',
+ name: 'XD Gateway',
+ source: 'builtin',
+ agents: [agent],
+ auth: { method: 'managed' },
+ routing: { [agent]: { upstream: 'https://ignored.invalid', authStrategy: 'gateway-key' } },
+ models: { [agent]: models.map((model) => ({ name: String(model.id), contextWindow: 200_000, ...model })) },
+ }],
+ };
+ }
+
+ function customChatCatalog(input: { upstream: string; model: Record<string, unknown> }) {
+ return {
+ providers: [{
+ id: 'custom-chat',
+ name: 'Custom Chat',
+ source: 'user',
+ agents: ['codex'],
+ auth: { method: 'apiKey' },
+ routing: {
+ codex: { upstream: input.upstream, wireProtocol: 'openai-chat', authStrategy: 'api-key-header' },
+ },
+ models: { codex: [{ name: 'Custom', contextWindow: 100_000, ...input.model }] },
+ }],
+ };
+ }
+
+ const GPT_SOL = {
+ id: 'gpt-6.1-sol',
+ nativeApi: 'openai-responses',
+ efforts: ['low', 'medium', 'high', 'xhigh', 'max', 'ultra'],
+ defaultEffort: 'medium',
+ };
+
+ it('sends a Cindy AI GPT model to /v1/responses with the lowest catalog effort', async () => {
+ activeCatalog.mockReturnValue(xdCatalog('codex', [GPT_SOL]) as never);
+ readKey.mockReturnValue('xd-key');
+ fetchMock.mockResolvedValueOnce(responsesOk('done') as never);
+
+ const result = await requestExplicitUtilityText('summarize', {
+ providerId: 'xd',
+ agentKind: 'codex',
+ model: 'gpt-6.1-sol',
+ maxTokens: 256,
+ disableReasoning: true,
+ });
+
+ expect(result).toMatchObject({ ok: true, text: 'done', providerId: 'xd', model: 'gpt-6.1-sol' });
+ expect(fetchMock).toHaveBeenCalledTimes(1);
+ expect(urlOf(0)).toBe(`${GATEWAY}/v1/responses`);
+ expect(fetchMock.mock.calls[0]?.[1]?.headers).toMatchObject({ Authorization: 'Bearer xd-key' });
+ expect(bodyOf(0)).toEqual({
+ model: 'gpt-6.1-sol',
+ input: [{ type: 'message', role: 'user', content: [{ type: 'input_text', text: 'summarize' }] }],
+ store: false,
+ stream: true,
+ max_output_tokens: 256,
+ reasoning: { effort: 'low' },
+ });
+ });
+
+ it('sends a Cindy AI Claude model to /v1/messages with thinking turned off', async () => {
+ activeCatalog.mockReturnValue(xdCatalog('claude-code', [{
+ id: 'claude-sonnet-4-6',
+ nativeApi: 'anthropic-messages',
+ efforts: ['low', 'medium', 'high', 'max'],
+ defaultEffort: 'medium',
+ }]) as never);
+ readKey.mockReturnValue('xd-key');
+ fetchMock.mockResolvedValueOnce(messagesOk('title') as never);
+
+ const result = await requestExplicitUtilityText('name it', {
+ providerId: 'xd',
+ agentKind: 'claude-code',
+ model: 'claude-sonnet-4-6',
+ maxTokens: 64,
+ systemPrompt: 'SYSTEM',
+ disableReasoning: true,
+ });
+
+ expect(result).toMatchObject({ ok: true, text: 'title' });
+ expect(fetchMock).toHaveBeenCalledTimes(1);
+ expect(urlOf(0)).toBe(`${GATEWAY}/v1/messages`);
+ expect(fetchMock.mock.calls[0]?.[1]?.headers).toMatchObject({
+ Authorization: 'Bearer xd-key',
+ 'anthropic-version': '2023-06-01',
+ });
+ expect(bodyOf(0)).toEqual({
+ model: 'claude-sonnet-4-6',
+ max_tokens: 64,
+ system: 'SYSTEM',
+ thinking: { type: 'disabled' },
+ messages: [{ role: 'user', content: 'name it' }],
+ });
+ });
+
+ // The automatic chain's first request must stay byte-identical to the
+ // pre-plan Chat body, whether or not the Gateway declared efforts.
+ it.each([
+ { id: 'deepseek/deepseek-v4-flash', efforts: ['low', 'high', 'max'] },
+ { id: 'tencent/hy3', efforts: ['low', 'medium', 'high'] },
+ { id: 'qwen/qwen3.8-flash', efforts: ['low', 'medium', 'xhigh'] },
+ { id: 'deepseek/deepseek-v4-flash', efforts: [] },
+ ])('keeps the automatic chain first Chat request unchanged for $id (efforts: $efforts)', async ({ id, efforts }) => {
+ const autoRef = AUTO_AUXILIARY_MODEL_CHAIN.find((ref) => ref.endsWith(`:${id}`));
+ expect(autoRef).toBeDefined();
+ chainState.source = 'auto';
+ chainState.refs = [autoRef!];
+ activeCatalog.mockReturnValue(xdCatalog('codex', [{
+ id,
+ nativeApi: 'openai-completions',
+ efforts,
+ // Gateway omitted efforts: the catalog projects `[]` without a discovered declaration.
+ ...(efforts.length > 0 ? { discoveredMetadata: { efforts } } : {}),
+ }]) as never);
+ readKey.mockReturnValue('xd-key');
+ fetchMock.mockResolvedValueOnce(chatOk('ok') as never);
+
+ const result = await requestUtilityText(makerMock(false), 'hello', {
+ maxTokens: 32,
+ systemPrompt: 'SYSTEM',
+ });
+
+ expect(result).toMatchObject({ ok: true, providerId: 'xd', model: id });
+ expect(fetchMock).toHaveBeenCalledTimes(1);
+ expect(urlOf(0)).toBe(`${GATEWAY}/v1/chat/completions`);
+ expect(bodyOf(0)).toEqual({
+ model: id,
+ max_tokens: 32,
+ thinking: { type: 'disabled' },
+ reasoning_effort: 'minimal',
+ messages: [
+ { role: 'system', content: 'SYSTEM' },
+ { role: 'user', content: 'hello' },
+ ],
+ });
+ });
+
+ it('falls back from a missing native endpoint to Chat and keeps the effort', async () => {
+ activeCatalog.mockReturnValue(xdCatalog('codex', [GPT_SOL]) as never);
+ readKey.mockReturnValue('xd-key');
+ fetchMock
+ .mockResolvedValueOnce(rejected(404) as never)
+ .mockResolvedValueOnce(chatOk('chat text') as never);
+
+ const result = await requestExplicitUtilityText('summarize', {
+ providerId: 'xd',
+ agentKind: 'codex',
+ model: 'gpt-6.1-sol',
+ maxTokens: 128,
+ disableReasoning: true,
+ });
+
+ expect(result).toMatchObject({ ok: true, text: 'chat text' });
+ expect(fetchMock).toHaveBeenCalledTimes(2);
+ expect(urlOf(0)).toBe(`${GATEWAY}/v1/responses`);
+ expect(urlOf(1)).toBe(`${GATEWAY}/v1/chat/completions`);
+ // Carries the Responses effort instead of Chat's "off" pair, which the
+ // Gateway translated into the rejected `none` for this model.
+ expect(bodyOf(1)).toEqual({
+ model: 'gpt-6.1-sol',
+ max_tokens: 128,
+ reasoning_effort: 'low',
+ messages: [{ role: 'user', content: 'summarize' }],
+ });
+ });
+
+ it('falls back from a rejected Messages request to Chat with thinking still off', async () => {
+ activeCatalog.mockReturnValue(xdCatalog('claude-code', [{
+ id: 'claude-sonnet-4-6',
+ nativeApi: 'anthropic-messages',
+ efforts: ['low', 'medium'],
+ defaultEffort: 'medium',
+ }]) as never);
+ readKey.mockReturnValue('xd-key');
+ fetchMock
+ .mockResolvedValueOnce(rejected(404) as never)
+ .mockResolvedValueOnce(chatOk('chat text') as never);
+
+ const result = await requestExplicitUtilityText('name it', {
+ providerId: 'xd',
+ agentKind: 'claude-code',
+ model: 'claude-sonnet-4-6',
+ maxTokens: 64,
+ disableReasoning: true,
+ });
+
+ expect(result).toMatchObject({ ok: true, text: 'chat text' });
+ expect(urlOf(1)).toBe(`${GATEWAY}/v1/chat/completions`);
+ expect(bodyOf(1)).toMatchObject({ thinking: { type: 'disabled' }, reasoning_effort: 'minimal' });
+ });
+
+ it('climbs a declared native ladder before falling back to Chat at the lowest effort', async () => {
+ activeCatalog.mockReturnValue(xdCatalog('codex', [GPT_SOL]) as never);
+ readKey.mockReturnValue('xd-key');
+ fetchMock
+ .mockResolvedValueOnce(rejected(400) as never)
+ .mockResolvedValueOnce(rejected(400) as never)
+ .mockResolvedValueOnce(chatOk('chat text') as never);
+
+ const result = await requestExplicitUtilityText('summarize', {
+ providerId: 'xd',
+ agentKind: 'codex',
+ model: 'gpt-6.1-sol',
+ disableReasoning: true,
+ });
+
+ expect(result).toMatchObject({ ok: true, text: 'chat text' });
+ expect(fetchMock.mock.calls.map((call) => call[0])).toEqual([
+ `${GATEWAY}/v1/responses`,
+ `${GATEWAY}/v1/responses`,
+ `${GATEWAY}/v1/chat/completions`,
+ ]);
+ expect(bodyOf(0)).toMatchObject({ reasoning: { effort: 'low' } });
+ expect(bodyOf(1)).toMatchObject({ reasoning: { effort: 'medium' } });
+ expect(bodyOf(2)).toMatchObject({ reasoning_effort: 'low' });
+ expect(bodyOf(2)).not.toHaveProperty('thinking');
+ });
+
+ it('caps the number of requests a single call can spend on parameter errors', async () => {
+ activeCatalog.mockReturnValue(xdCatalog('claude-code', [{
+ id: 'claude-sonnet-4-6',
+ nativeApi: 'anthropic-messages',
+ efforts: ['low', 'medium', 'high', 'max'],
+ }]) as never);
+ readKey.mockReturnValue('xd-key');
+ fetchMock.mockResolvedValue(rejected(400) as never);
+
+ const result = await requestExplicitUtilityText('hello', {
+ providerId: 'xd',
+ agentKind: 'claude-code',
+ model: 'claude-sonnet-4-6',
+ disableReasoning: true,
+ });
+
+ expect(result).toMatchObject({ ok: false });
+ // Messages off / low / medium, then Chat off: four requests, not the full six-step plan.
+ expect(fetchMock).toHaveBeenCalledTimes(4);
+ expect(urlOf(3)).toBe(`${GATEWAY}/v1/chat/completions`);
+ });
+
+ it('climbs a declared Chat ladder and never sends a request without reasoning parameters', async () => {
+ activeCatalog.mockReturnValue(customChatCatalog({
+ upstream: 'https://custom.example/v1',
+ model: { id: 'custom-thinker', efforts: ['high', 'low', 'medium'] },
+ }) as never);
+ readCustomKey.mockReturnValue('custom-secret');
+ fetchMock.mockResolvedValue(rejected(400) as never);
+
+ const result = await requestExplicitUtilityText('hello', {
+ providerId: 'custom-chat',
+ agentKind: 'codex',
+ model: 'custom-thinker',
+ maxTokens: 64,
+ disableReasoning: true,
+ });
+
+ expect(result).toMatchObject({
+ ok: false,
+ attempts: [expect.objectContaining({ reason: 'http_error', httpStatus: 400 })],
+ });
+ expect(fetchMock).toHaveBeenCalledTimes(3);
+ expect(bodyOf(0)).toMatchObject({ thinking: { type: 'disabled' }, reasoning_effort: 'minimal' });
+ expect(bodyOf(1)).toMatchObject({ reasoning_effort: 'low' });
+ expect(bodyOf(1)).not.toHaveProperty('thinking');
+ expect(bodyOf(2)).toMatchObject({ reasoning_effort: 'medium' });
+ for (let index = 0; index < 3; index += 1) {
+ expect(bodyOf(index)).toHaveProperty('reasoning_effort');
+ expect(bodyOf(index)).toHaveProperty('max_tokens', 64);
+ }
+ });
+
+ it('sends no reasoning parameters and does not retry when the catalog declares none', async () => {
+ activeCatalog.mockReturnValue(xdCatalog('codex', [{
+ id: 'plain-chat',
+ nativeApi: 'openai-completions',
+ efforts: [],
+ discoveredMetadata: { efforts: [] },
+ }]) as never);
+ readKey.mockReturnValue('xd-key');
+ fetchMock.mockResolvedValueOnce(rejected(400) as never);
+
+ const result = await requestExplicitUtilityText('hello', {
+ providerId: 'xd',
+ agentKind: 'codex',
+ model: 'plain-chat',
+ disableReasoning: true,
+ });
+
+ expect(result).toMatchObject({ ok: false });
+ expect(fetchMock).toHaveBeenCalledTimes(1);
+ expect(bodyOf(0)).toEqual({ model: 'plain-chat', messages: [{ role: 'user', content: 'hello' }] });
+ });
+
+ it('sends no reasoning parameters to a model the vendor profile marks as non-reasoning', async () => {
+ activeCatalog.mockReturnValue(customChatCatalog({
+ upstream: 'https://api.moonshot.ai/v1',
+ model: { id: 'kimi-k2.6', efforts: ['low', 'high'] },
+ }) as never);
+ readCustomKey.mockReturnValue('custom-secret');
+ fetchMock.mockResolvedValueOnce(chatOk('ok') as never);
+
+ await requestExplicitUtilityText('hello', {
+ providerId: 'custom-chat',
+ agentKind: 'codex',
+ model: 'kimi-k2.6',
+ disableReasoning: true,
+ });
+
+ expect(bodyOf(0)).not.toHaveProperty('thinking');
+ expect(bodyOf(0)).not.toHaveProperty('reasoning_effort');
+ });
+
+ it('walks an undeclared custom model from off to low to the minimal body', async () => {
+ activeCatalog.mockReturnValue(customChatCatalog({
+ upstream: 'https://custom.example/v1',
+ model: { id: 'mystery', efforts: [], effortsUnknown: true },
+ }) as never);
+ readCustomKey.mockReturnValue('custom-secret');
+ fetchMock
+ .mockResolvedValueOnce(rejected(400) as never)
+ .mockResolvedValueOnce(rejected(422) as never)
+ .mockResolvedValueOnce(chatOk('ok') as never);
+
+ const result = await requestExplicitUtilityText('hello', {
+ providerId: 'custom-chat',
+ agentKind: 'codex',
+ model: 'mystery',
+ maxTokens: 48,
+ disableReasoning: true,
+ });
+
+ expect(result).toMatchObject({ ok: true, text: 'ok' });
+ expect(fetchMock).toHaveBeenCalledTimes(3);
+ expect(bodyOf(0)).toMatchObject({ max_tokens: 48, thinking: { type: 'disabled' }, reasoning_effort: 'minimal' });
+ expect(bodyOf(1)).toMatchObject({ max_tokens: 48, reasoning_effort: 'low' });
+ expect(bodyOf(1)).not.toHaveProperty('thinking');
+ expect(bodyOf(2)).toEqual({ model: 'mystery', messages: [{ role: 'user', content: 'hello' }] });
+ });
+
+ it('remembers the accepted step and continues down when it is later rejected', async () => {
+ activeCatalog.mockReturnValue(customChatCatalog({
+ upstream: 'https://custom.example/v1',
+ model: { id: 'custom-thinker', efforts: ['low', 'medium', 'high'] },
+ }) as never);
+ readCustomKey.mockReturnValue('custom-secret');
+ const request = () => requestExplicitUtilityText('hello', {
+ providerId: 'custom-chat',
+ agentKind: 'codex',
+ model: 'custom-thinker',
+ disableReasoning: true,
+ });
+
+ fetchMock
+ .mockResolvedValueOnce(rejected(400) as never)
+ .mockResolvedValueOnce(chatOk('first') as never);
+ await expect(request()).resolves.toMatchObject({ ok: true, text: 'first' });
+ expect(fetchMock).toHaveBeenCalledTimes(2);
+
+ fetchMock.mockClear();
+ fetchMock.mockResolvedValueOnce(chatOk('second') as never);
+ await expect(request()).resolves.toMatchObject({ ok: true, text: 'second' });
+ expect(fetchMock).toHaveBeenCalledTimes(1);
+ expect(bodyOf(0)).toMatchObject({ reasoning_effort: 'low' });
+ expect(bodyOf(0)).not.toHaveProperty('thinking');
+
+ fetchMock.mockClear();
+ fetchMock
+ .mockResolvedValueOnce(rejected(400) as never)
+ .mockResolvedValueOnce(chatOk('third') as never);
+ await expect(request()).resolves.toMatchObject({ ok: true, text: 'third' });
+ expect(fetchMock).toHaveBeenCalledTimes(2);
+ expect(bodyOf(0)).toMatchObject({ reasoning_effort: 'low' });
+ expect(bodyOf(1)).toMatchObject({ reasoning_effort: 'medium' });
+ });
+
+ it.each([401, 403, 429, 500, 503])('does not walk the plan after HTTP %i', async (status) => {
+ activeCatalog.mockReturnValue(xdCatalog('codex', [GPT_SOL]) as never);
+ readKey.mockReturnValue('xd-key');
+ fetchMock.mockResolvedValue(rejected(status) as never);
+
+ const result = await requestExplicitUtilityText('hello', {
+ providerId: 'xd',
+ agentKind: 'codex',
+ model: 'gpt-6.1-sol',
+ disableReasoning: true,
+ });
+
+ expect(result).toMatchObject({
+ ok: false,
+ attempts: [expect.objectContaining({ reason: 'http_error', httpStatus: status })],
+ });
+ expect(fetchMock).toHaveBeenCalledTimes(1);
+ expect(reportKeyRejected).toHaveBeenCalledTimes(status === 401 ? 1 : 0);
+ });
+
+ it('does not walk the plan after a timeout', async () => {
+ activeCatalog.mockReturnValue(customChatCatalog({
+ upstream: 'https://custom.example/v1',
+ model: { id: 'custom-thinker', efforts: ['low', 'medium'] },
+ }) as never);
+ readCustomKey.mockReturnValue('custom-secret');
+ fetchMock.mockRejectedValue(Object.assign(new Error('aborted'), { name: 'AbortError' }));
+
+ const result = await requestExplicitUtilityText('hello', {
+ providerId: 'custom-chat',
+ agentKind: 'codex',
+ model: 'custom-thinker',
+ disableReasoning: true,
+ });
+
+ expect(result).toMatchObject({ ok: false, reason: 'timeout' });
+ expect(fetchMock).toHaveBeenCalledTimes(1);
+ });
+
+ it('keeps the output-budget retry on the accepted native step', async () => {
+ activeCatalog.mockReturnValue(xdCatalog('codex', [GPT_SOL]) as never);
+ readKey.mockReturnValue('xd-key');
+ const truncated = {
+ ok: true,
+ text: async () => 'data: {"type":"response.incomplete","response":{"incomplete_details":{"reason":"max_output_tokens"},"output":[]}}\n',
+ };
+ fetchMock
+ .mockResolvedValueOnce(truncated as never)
+ .mockResolvedValueOnce(responsesOk('full answer') as never);
+
+ const result = await requestExplicitUtilityText('summarize', {
+ providerId: 'xd',
+ agentKind: 'codex',
+ model: 'gpt-6.1-sol',
+ maxTokens: 200,
+ disableReasoning: true,
+ });
+
+ expect(result).toMatchObject({ ok: true, text: 'full answer' });
+ expect(fetchMock).toHaveBeenCalledTimes(2);
+ expect(urlOf(1)).toBe(`${GATEWAY}/v1/responses`);
+ expect(bodyOf(1)).toMatchObject({ reasoning: { effort: 'low' } });
+ expect(Number(bodyOf(1).max_output_tokens)).toBeGreaterThan(200);
+ });
+
+ it('reports the Cindy AI key when a Chat fallback or budget retry is rejected with 401', async () => {
+ activeCatalog.mockReturnValue(xdCatalog('codex', [GPT_SOL]) as never);
+ readKey.mockReturnValue('xd-key-sent');
+ fetchMock
+ .mockResolvedValueOnce(rejected(404) as never)
+ .mockResolvedValueOnce(rejected(401) as never);
+
+ await requestExplicitUtilityText('summarize', {
+ providerId: 'xd',
+ agentKind: 'codex',
+ model: 'gpt-6.1-sol',
+ disableReasoning: true,
+ });
+ expect(reportKeyRejected).toHaveBeenCalledTimes(1);
+ expect(reportKeyRejected).toHaveBeenCalledWith('xd-key-sent');
+
+ reportKeyRejected.mockClear();
+ fetchMock.mockReset();
+ resetUtilityReasoningMemory();
+ fetchMock
+ .mockResolvedValueOnce({
+ ok: true,
+ text: async () => 'data: {"type":"response.incomplete","response":{"incomplete_details":{"reason":"max_output_tokens"},"output":[]}}\n',
+ } as never)
+ .mockResolvedValueOnce(rejected(401) as never);
+ await requestExplicitUtilityText('summarize', {
+ providerId: 'xd',
+ agentKind: 'codex',
+ model: 'gpt-6.1-sol',
+ maxTokens: 200,
+ disableReasoning: true,
+ });
+ expect(fetchMock).toHaveBeenCalledTimes(2);
+ expect(reportKeyRejected).toHaveBeenCalledTimes(1);
+ expect(reportKeyRejected).toHaveBeenCalledWith('xd-key-sent');
+ });
+
+ it('lets model-compat translate the off request for a thinking-toggle vendor', async () => {
+ activeCatalog.mockReturnValue(customChatCatalog({
+ upstream: 'https://open.bigmodel.cn/api/paas/v4',
+ model: { id: 'glm-5', efforts: ['low', 'medium', 'high'] },
+ }) as never);
+ readCustomKey.mockReturnValue('custom-secret');
+ fetchMock
+ .mockResolvedValueOnce(rejected(400) as never)
+ .mockResolvedValueOnce(chatOk('ok') as never);
+
+ await requestExplicitUtilityText('hello', {
+ providerId: 'custom-chat',
+ agentKind: 'codex',
+ model: 'glm-5',
+ disableReasoning: true,
+ });
+
+ // Zhipu maps both "off" and `low` to `thinking: disabled`; the identical
+ // `low` request is skipped and the next distinct step is `medium`.
+ expect(bodyOf(0)).toMatchObject({ thinking: { type: 'disabled' } });
+ expect(bodyOf(0)).not.toHaveProperty('reasoning_effort');
+ expect(bodyOf(1)).toMatchObject({ thinking: { type: 'enabled' } });
+ expect(bodyOf(1)).not.toHaveProperty('reasoning_effort');
+ });
+
+ it('keeps the off pair untranslated when the vendor profile has no off spelling', async () => {
+ activeCatalog.mockReturnValue(customChatCatalog({
+ upstream: 'https://api.deepseek.com',
+ model: { id: 'deepseek-v4-flash', efforts: ['low', 'high', 'max'] },
+ }) as never);
+ readCustomKey.mockReturnValue('custom-secret');
+ fetchMock.mockResolvedValueOnce(chatOk('ok') as never);
+
+ await requestExplicitUtilityText('hello', {
+ providerId: 'custom-chat',
+ agentKind: 'codex',
+ model: 'deepseek-v4-flash',
+ disableReasoning: true,
+ });
+
+ // Effort mapping would turn `minimal` into `low`, i.e. ask for some thinking.
+ expect(bodyOf(0)).toEqual({
+ model: 'deepseek-v4-flash',
+ thinking: { type: 'disabled' },
+ reasoning_effort: 'minimal',
+ messages: [{ role: 'user', content: 'hello' }],
+ });
+ });
+
+ it('uses the vendor off spelling when the profile maps `none`', async () => {
+ activeCatalog.mockReturnValue(customChatCatalog({
+ upstream: 'https://inference.baseten.co/v1',
+ model: { id: 'openai/gpt-oss-120b', efforts: ['low', 'medium', 'high'] },
+ }) as never);
+ readCustomKey.mockReturnValue('custom-secret');
+ fetchMock.mockResolvedValueOnce(chatOk('ok') as never);
+
+ await requestExplicitUtilityText('hello', {
+ providerId: 'custom-chat',
+ agentKind: 'codex',
+ model: 'openai/gpt-oss-120b',
+ disableReasoning: true,
+ });
+
+ expect(bodyOf(0)).toMatchObject({ thinking: { type: 'disabled' }, reasoning_effort: 'none' });
+ });
+
+ it('caps a Cindy AI Messages request without a caller budget at the model output limit', async () => {
+ activeCatalog.mockReturnValue(xdCatalog('claude-code', [{
+ id: 'claude-sonnet-4-6',
+ nativeApi: 'anthropic-messages',
+ efforts: ['low', 'medium'],
+ maxOutput: 64_000,
+ }]) as never);
+ readKey.mockReturnValue('xd-key');
+ fetchMock.mockResolvedValueOnce(messagesOk('answer') as never);
+
+ await requestExplicitUtilityText('question', {
+ providerId: 'xd',
+ agentKind: 'claude-code',
+ model: 'claude-sonnet-4-6',
+ disableReasoning: true,
+ });
+
+ expect(bodyOf(0)).toMatchObject({ max_tokens: 64_000 });
+ });
+
+ it('raises a tiny Responses output budget to the protocol minimum', async () => {
+ activeCatalog.mockReturnValue(xdCatalog('codex', [GPT_SOL]) as never);
+ readKey.mockReturnValue('xd-key');
+ fetchMock.mockResolvedValueOnce(responsesOk('yes') as never);
+
+ await requestExplicitUtilityText('page?', {
+ providerId: 'xd',
+ agentKind: 'codex',
+ model: 'gpt-6.1-sol',
+ maxTokens: 8,
+ disableReasoning: true,
+ });
+
+ expect(bodyOf(0)).toMatchObject({ max_output_tokens: 16 });
+ });
+
+ it('still turns thinking off first for a custom Pi model with a placeholder effort list', async () => {
+ activeCatalog.mockReturnValue({
+ providers: [{
+ id: 'custom-pi',
+ name: 'Custom Pi',
+ source: 'user',
+ agents: ['pi'],
+ auth: { method: 'apiKey' },
+ routing: {
+ pi: { upstream: 'https://custom.example/v1', wireProtocol: 'openai-chat', authStrategy: 'api-key-header' },
+ },
+ models: { pi: [{ id: 'pi-model', name: 'Pi Model', contextWindow: 100_000, efforts: [] }] },
+ }],
+ } as never);
+ readCustomKey.mockReturnValue('custom-secret');
+ fetchMock.mockResolvedValueOnce(chatOk('ok') as never);
+
+ await requestExplicitUtilityText('hello', {
+ providerId: 'custom-pi',
+ agentKind: 'pi',
+ model: 'pi-model',
+ disableReasoning: true,
+ });
+
+ expect(bodyOf(0)).toMatchObject({ thinking: { type: 'disabled' }, reasoning_effort: 'minimal' });
+ });
+ });
});
diff --git a/apps/desktop/src/main/utility-model/__tests__/utilityReasoningPlan.test.ts b/apps/desktop/src/main/utility-model/__tests__/utilityReasoningPlan.test.ts
new file mode 100644
index 0000000000..c16aef14d2
--- /dev/null
+++ b/apps/desktop/src/main/utility-model/__tests__/utilityReasoningPlan.test.ts
@@ -0,0 +1,183 @@
+import { beforeEach, describe, expect, it } from 'vitest';
+
+import {
+ buildUtilityRequestPlan,
+ compatHasReasoningOff,
+ compatMarksNoReasoning,
+ nextUtilityRequestStep,
+ rememberUtilityStep,
+ rememberedUtilityStepIndex,
+ resetUtilityReasoningMemory,
+ utilityReasoningDeclaration,
+ utilityRequestStepKey,
+} from '../utilityReasoningPlan.js';
+
+const keys = (steps: ReturnType<typeof buildUtilityRequestPlan>) => steps.map(utilityRequestStepKey);
+
+describe('utilityReasoningDeclaration', () => {
+ it('sorts declared efforts from least to most thinking', () => {
+ expect(utilityReasoningDeclaration('custom', 'codex', { efforts: ['max', 'low', 'high'] })).toEqual({
+ kind: 'declared',
+ efforts: ['low', 'high', 'max'],
+ });
+ });
+
+ it('treats an explicit empty list as declared-empty and a missing one as unknown', () => {
+ expect(utilityReasoningDeclaration('anthropic', 'claude-code', { efforts: [] })).toEqual({ kind: 'empty' });
+ expect(utilityReasoningDeclaration('custom', 'codex', { efforts: [], effortsUnknown: true })).toEqual({ kind: 'unknown' });
+ expect(utilityReasoningDeclaration('custom', 'codex', undefined)).toEqual({ kind: 'unknown' });
+ });
+
+ it('only trusts an empty Cindy AI list that the Gateway actually sent', () => {
+ expect(utilityReasoningDeclaration('xd', 'codex', { efforts: [] })).toEqual({ kind: 'unknown' });
+ expect(utilityReasoningDeclaration('xd', 'codex', { efforts: [], discoveredMetadata: { efforts: [] } }))
+ .toEqual({ kind: 'empty' });
+ });
+
+ it('does not read a custom Pi placeholder list as declared-empty', () => {
+ expect(utilityReasoningDeclaration('custom-pi', 'pi', { efforts: [] })).toEqual({ kind: 'unknown' });
+ expect(utilityReasoningDeclaration('custom-pi', 'pi', { efforts: [], reasoning: false })).toEqual({ kind: 'empty' });
+ });
+});
+
+describe('buildUtilityRequestPlan', () => {
+ const declared = { kind: 'declared' as const, efforts: ['low', 'medium', 'high'] };
+
+ it('starts Responses at the lowest effort because it has no off value', () => {
+ expect(keys(buildUtilityRequestPlan({ wire: 'responses', mode: { kind: 'ladder', declaration: declared } })))
+ .toEqual(['responses|effort:low', 'responses|effort:medium']);
+ });
+
+ it('tries off first on Chat and Messages', () => {
+ expect(keys(buildUtilityRequestPlan({ wire: 'chat-completions', mode: { kind: 'ladder', declaration: declared } })))
+ .toEqual(['chat-completions|off', 'chat-completions|effort:low', 'chat-completions|effort:medium']);
+ expect(keys(buildUtilityRequestPlan({ wire: 'anthropic-messages', mode: { kind: 'ladder', declaration: declared } })))
+ .toEqual(['anthropic-messages|off', 'anthropic-messages|effort:low', 'anthropic-messages|effort:medium']);
+ });
+
+ it('continues a native Responses plan on Chat from the same effort, skipping Chat off', () => {
+ expect(keys(buildUtilityRequestPlan({
+ wire: 'responses',
+ mode: { kind: 'ladder', declaration: declared },
+ chatFallback: true,
+ }))).toEqual([
+ 'responses|effort:low',
+ 'responses|effort:medium',
+ 'chat-completions|effort:low',
+ 'chat-completions|effort:medium',
+ ]);
+ });
+
+ it('never adds the minimal body to a declared ladder', () => {
+ expect(keys(buildUtilityRequestPlan({
+ wire: 'chat-completions',
+ mode: { kind: 'ladder', declaration: declared },
+ minimalBodyFallback: true,
+ }))).not.toContain('chat-completions|omit|minimal');
+ });
+
+ it('walks an unknown model from off to low to the minimal body', () => {
+ expect(keys(buildUtilityRequestPlan({
+ wire: 'chat-completions',
+ mode: { kind: 'ladder', declaration: { kind: 'unknown' } },
+ minimalBodyFallback: true,
+ }))).toEqual(['chat-completions|off', 'chat-completions|effort:low', 'chat-completions|omit|minimal']);
+ });
+
+ it('sends nothing for a declared-empty model', () => {
+ expect(keys(buildUtilityRequestPlan({
+ wire: 'responses',
+ mode: { kind: 'ladder', declaration: { kind: 'empty' } },
+ chatFallback: true,
+ }))).toEqual(['responses|omit', 'chat-completions|omit']);
+ });
+
+ it('keeps an explicit caller effort and carries it to the Chat fallback', () => {
+ expect(keys(buildUtilityRequestPlan({
+ wire: 'anthropic-messages',
+ mode: { kind: 'fixed', rung: { kind: 'effort', effort: 'low' } },
+ chatFallback: true,
+ }))).toEqual(['anthropic-messages|omit', 'chat-completions|effort:low']);
+ });
+});
+
+describe('nextUtilityRequestStep', () => {
+ const steps = buildUtilityRequestPlan({
+ wire: 'anthropic-messages',
+ mode: { kind: 'ladder', declaration: { kind: 'declared', efforts: ['low', 'medium'] } },
+ chatFallback: true,
+ });
+
+ it('jumps from a missing native endpoint to Chat with the same reasoning step', () => {
+ expect(utilityRequestStepKey(steps[nextUtilityRequestStep(steps, 1, 404)!]!))
+ .toBe('chat-completions|effort:low');
+ });
+
+ it('only treats 404 as a parameter error on Cindy AI native steps', () => {
+ const chat = steps.findIndex((step) => step.wire === 'chat-completions');
+ expect(nextUtilityRequestStep(steps, chat, 404)).toBeNull();
+ });
+
+ it.each([401, 403, 429, 500, 502])('does not advance on HTTP %i', (status) => {
+ expect(nextUtilityRequestStep(steps, 0, status)).toBeNull();
+ });
+
+ it('advances on 400 and 422 until the plan ends', () => {
+ expect(nextUtilityRequestStep(steps, 0, 400)).toBe(1);
+ expect(nextUtilityRequestStep(steps, 0, 422)).toBe(1);
+ expect(nextUtilityRequestStep(steps, steps.length - 1, 400)).toBeNull();
+ });
+});
+
+describe('remembered steps', () => {
+ beforeEach(() => resetUtilityReasoningMemory());
+
+ it('starts from the remembered step and ignores one that is no longer in the plan', () => {
+ const steps = buildUtilityRequestPlan({
+ wire: 'chat-completions',
+ mode: { kind: 'ladder', declaration: { kind: 'declared', efforts: ['low', 'medium'] } },
+ });
+ rememberUtilityStep('route', steps[1]!);
+ expect(rememberedUtilityStepIndex('route', steps)).toBe(1);
+ expect(rememberedUtilityStepIndex('other-route', steps)).toBe(0);
+ rememberUtilityStep('route', { wire: 'responses', rung: { kind: 'effort', effort: 'xhigh' } });
+ expect(rememberedUtilityStepIndex('route', steps)).toBe(0);
+ });
+
+ it('never remembers the minimal body', () => {
+ const steps = buildUtilityRequestPlan({
+ wire: 'chat-completions',
+ mode: { kind: 'ladder', declaration: { kind: 'unknown' } },
+ minimalBodyFallback: true,
+ });
+ rememberUtilityStep('route', steps.at(-1)!);
+ expect(rememberedUtilityStepIndex('route', steps)).toBe(0);
+ });
+});
+
+describe('compatHasReasoningOff', () => {
+ it('is true only for vendor profiles with their own off spelling', () => {
+ const route = (upstreamBase: string, model: string) => ({ harness: 'codex' as const, upstreamBase, model });
+ expect(compatHasReasoningOff(route('https://open.bigmodel.cn/api/paas/v4', 'glm-5'))).toBe(true);
+ expect(compatHasReasoningOff(route('https://inference.baseten.co/v1', 'openai/gpt-oss-120b'))).toBe(true);
+ expect(compatHasReasoningOff(route('https://api.deepseek.com', 'deepseek-v4-flash'))).toBe(false);
+ expect(compatHasReasoningOff(route('https://gateway.test.invalid', 'deepseek/deepseek-v4-flash'))).toBe(false);
+ });
+});
+
+describe('compatMarksNoReasoning', () => {
+ it('follows the vendor profile and ignores unknown endpoints', () => {
+ expect(compatMarksNoReasoning({
+ wire: 'chat-completions',
+ harness: 'codex',
+ upstreamBase: 'https://api.moonshot.ai/v1',
+ model: 'kimi-k2.6',
+ })).toBe(true);
+ expect(compatMarksNoReasoning({
+ wire: 'chat-completions',
+ harness: 'codex',
+ upstreamBase: 'https://gateway.test.invalid',
+ model: 'kimi-k2.6',
+ })).toBe(false);
+ });
+});
diff --git a/apps/desktop/src/main/utility-model/oneShotCandidates.ts b/apps/desktop/src/main/utility-model/oneShotCandidates.ts
index 032ea90697..b682e159e5 100644
--- a/apps/desktop/src/main/utility-model/oneShotCandidates.ts
+++ b/apps/desktop/src/main/utility-model/oneShotCandidates.ts
@@ -2,10 +2,12 @@ import { isOpenAiSubscriptionProvider, providerCatalogId } from '@cindy/model-pr
import { randomUUID } from 'node:crypto';
import { type AgentKind, type Maker } from '@cindy/maker-core';
+import { normalizeProviderRequest, type CompatibilityHarness } from '@cindy/model-compat';
import {
appendProviderRequestPath,
isModelSelectableForNewRoute,
storedCustomProviderId,
+ type CatalogModel,
} from '@cindy/model-providers';
import { createLogger } from '../logger.js';
@@ -34,6 +36,21 @@ import { ensureManagedOllamaReadyForSession } from '../local-model-runtime/prefl
import { parseAuxiliaryModelRef, type ParsedAuxiliaryModelRef } from '../../shared/auxiliaryModelChain.js';
import { getUtilityModelChainProfiles } from './UtilityModelSelection.js';
import { getEffectiveAuxiliaryModelChain } from './resolveAuxiliaryModelChain.js';
+import {
+ MAX_REASONING_REQUESTS,
+ buildUtilityRequestPlan,
+ compatHasReasoningOff,
+ compatMarksNoReasoning,
+ nextUtilityRequestStep,
+ rememberUtilityStep,
+ rememberedUtilityStepIndex,
+ utilityReasoningDeclaration,
+ utilityReasoningMemoryKey,
+ utilityRequestStepKey,
+ type UtilityReasoningDeclaration,
+ type UtilityReasoningMode,
+ type UtilityRequestStep,
+} from './utilityReasoningPlan.js';
import { getUtilityModelProfile, isUtilityModelProviderKind } from '../../shared/utilityModelProfiles.js';
import type { UtilityModelProfile, UtilityModelTransport } from '../../shared/utilityModelProfiles.js';
import type {
@@ -107,9 +124,10 @@ export type UtilityTextRequestOptions = {
/** Optional lightweight reasoning hint for short internal classifiers. */
reasoningEffort?: 'minimal' | 'low' | 'medium' | 'high';
/**
- * Disable provider-native thinking for strict short-output budgets. Messages
- * and chat routes send `thinking.type=disabled`; Responses routes use the
- * lowest supported effort because that protocol has no off value.
+ * Use the least thinking the model allows, for strict short-output budgets.
+ * Messages and chat routes first try turning thinking off; Responses routes
+ * start at the lowest catalog effort because that protocol has no off value.
+ * See utilityReasoningPlan.ts for the fallback rules.
*/
disableReasoning?: boolean;
/** Abort an in-flight direct HTTP request when the owning workflow ends. */
@@ -462,11 +480,17 @@ export async function requestDedicatedAutoReviewCandidateText(
model: candidate.model,
transport: candidate.transport,
profile,
+ // The Gateway alias is not a catalog model: keep its fixed Chat request
+ // with no reasoning fields and let the Gateway apply the alias policy.
execute: (text, requestOpts) => requestProviderHttpText({
- wire: 'chat-completions',
- endpoint: joinProxyPath(baseUrl, '/v1/chat/completions'),
- headers: { Authorization: `Bearer ${apiKey}` },
- model: candidate.model,
+ targets: {
+ 'chat-completions': {
+ endpoint: joinProxyPath(baseUrl, '/v1/chat/completions'),
+ headers: { Authorization: `Bearer ${apiKey}` },
+ model: candidate.model,
+ },
+ },
+ steps: [{ wire: 'chat-completions', rung: { kind: 'omit' } }],
prompt: text,
systemPrompt,
maxTokens: DEDICATED_AUTO_REVIEW_MAX_TOKENS,
@@ -963,7 +987,9 @@ async function requestExplicitProviderText(
requestOpts?.signal?.throwIfAborted();
}
return requestCustomProviderText({
+ providerId: provider.id,
agentKind,
+ catalogModel,
baseUrl: routing.upstream,
requestPath: routing.requestPath,
wireProtocol,
@@ -1101,21 +1127,55 @@ async function requestBuiltinProviderText(
const baseUrl = effectiveXdGatewayBaseUrl().trim();
if (!apiKey) return { ok: false, reason: 'no_candidate', attempts: [skippedAttempt(profile, 'api_key_missing')] };
if (!baseUrl) return { ok: false, reason: 'no_candidate', attempts: [skippedAttempt(profile, 'endpoint_missing')] };
+ // Cindy AI serves every model on all three request formats; send each model
+ // in its native format so the Gateway does not have to translate reasoning
+ // parameters, and fall back to Chat on parameter / format errors.
+ const nativeWire: ProviderWire = catalogModel?.nativeApi === 'openai-responses'
+ ? 'responses'
+ : catalogModel?.nativeApi === 'anthropic-messages'
+ ? 'anthropic-messages'
+ : 'chat-completions';
+ const authorization = { Authorization: `Bearer ${apiKey}` };
return executeCandidates([{
providerId: input.provider.id,
model: input.model,
transport: 'litellm-chat-completions',
profile,
execute: (text, requestOpts) => requestProviderHttpText({
- wire: 'chat-completions',
- endpoint: joinProxyPath(baseUrl, '/v1/chat/completions'),
- headers: { Authorization: `Bearer ${apiKey}` },
- model: input.model,
+ targets: {
+ 'chat-completions': {
+ endpoint: joinProxyPath(baseUrl, '/v1/chat/completions'),
+ headers: authorization,
+ model: input.model,
+ },
+ responses: {
+ endpoint: joinProxyPath(baseUrl, '/v1/responses'),
+ headers: authorization,
+ model: input.model,
+ },
+ 'anthropic-messages': {
+ endpoint: joinProxyPath(baseUrl, '/v1/messages'),
+ headers: { ...authorization, 'anthropic-version': '2023-06-01' },
+ model: toAnthropicApiModelId(input.model),
+ // Chat sent no output limit when the caller set none; keep Messages'
+ // required max_tokens within the model's own limit.
+ ...(catalogModel?.maxOutput !== undefined ? { defaultMaxTokens: catalogModel.maxOutput } : {}),
+ },
+ },
+ ...utilityRequestPlan({
+ providerId: input.provider.id,
+ agentKind: input.agentKind,
+ model: input.model,
+ catalogModel,
+ wire: nativeWire,
+ upstreamBase: baseUrl,
+ chatFallback: true,
+ disableReasoning: requestOpts?.disableReasoning ?? input.disableReasoning,
+ reasoningEffort: requestOpts?.reasoningEffort ?? input.reasoningEffort,
+ }),
prompt: text,
maxTokens: requestOpts?.maxTokens ?? input.maxTokens,
timeoutMs: requestOpts?.timeoutMs ?? input.timeoutMs,
- reasoningEffort: requestOpts?.reasoningEffort ?? input.reasoningEffort,
- disableReasoning: requestOpts?.disableReasoning ?? input.disableReasoning,
signal: requestOpts?.signal ?? input.signal,
systemPrompt: requestOpts?.systemPrompt,
responseInstructions: requestOpts?.responseInstructions,
@@ -1159,22 +1219,33 @@ async function requestBuiltinProviderText(
transport: 'codex-responses',
profile,
execute: (text, requestOpts) => requestProviderHttpText({
- wire: 'responses',
- endpoint: joinProxyPath(routing.upstream, '/responses'),
- headers: {
- Authorization: `Bearer ${creds.accessToken}`,
- 'chatgpt-account-id': accountId,
- 'OpenAI-Beta': 'responses=experimental',
- originator: 'codex_cli_rs',
- session_id: randomUUID(),
- accept: 'text/event-stream',
+ targets: {
+ responses: {
+ endpoint: joinProxyPath(routing.upstream, '/responses'),
+ headers: {
+ Authorization: `Bearer ${creds.accessToken}`,
+ 'chatgpt-account-id': accountId,
+ 'OpenAI-Beta': 'responses=experimental',
+ originator: 'codex_cli_rs',
+ session_id: randomUUID(),
+ accept: 'text/event-stream',
+ },
+ model: input.model.replace(/^chatgpt\//, ''),
+ },
},
- model: input.model.replace(/^chatgpt\//, ''),
+ ...utilityRequestPlan({
+ providerId: input.provider.id,
+ agentKind: input.agentKind,
+ model: input.model.replace(/^chatgpt\//, ''),
+ catalogModel,
+ wire: 'responses',
+ upstreamBase: routing.upstream,
+ disableReasoning: requestOpts?.disableReasoning ?? input.disableReasoning,
+ reasoningEffort: requestOpts?.reasoningEffort ?? input.reasoningEffort,
+ }),
prompt: text,
maxTokens: requestOpts?.maxTokens ?? input.maxTokens,
timeoutMs: requestOpts?.timeoutMs ?? input.timeoutMs,
- reasoningEffort: requestOpts?.reasoningEffort ?? input.reasoningEffort,
- disableReasoning: requestOpts?.disableReasoning ?? input.disableReasoning,
// ChatGPT's private Codex Responses endpoint rejects this public API
// parameter with HTTP 400. The Auto reviewer enforces its own compact
// output ceiling after the response instead.
@@ -1218,16 +1289,27 @@ async function requestBuiltinProviderText(
transport: 'codex-responses',
profile,
execute: (text, requestOpts) => requestProviderHttpText({
- wire: 'responses',
- endpoint: joinProxyPath(routing.upstream, '/responses'),
- headers: { Authorization: `Bearer ${accessToken}` },
- model: input.model.replace(/^xai\//, ''),
+ targets: {
+ responses: {
+ endpoint: joinProxyPath(routing.upstream, '/responses'),
+ headers: { Authorization: `Bearer ${accessToken}` },
+ model: input.model.replace(/^xai\//, ''),
+ },
+ },
+ ...utilityRequestPlan({
+ providerId: input.provider.id,
+ agentKind: input.agentKind,
+ model: input.model.replace(/^xai\//, ''),
+ catalogModel,
+ wire: 'responses',
+ upstreamBase: routing.upstream,
+ disableReasoning: requestOpts?.disableReasoning ?? input.disableReasoning,
+ reasoningEffort: requestOpts?.reasoningEffort ?? input.reasoningEffort,
+ supportsReasoning: supportsXaiReasoning(input.model),
+ }),
prompt: text,
maxTokens: requestOpts?.maxTokens ?? input.maxTokens,
timeoutMs: requestOpts?.timeoutMs ?? input.timeoutMs,
- reasoningEffort: requestOpts?.reasoningEffort ?? input.reasoningEffort,
- disableReasoning: requestOpts?.disableReasoning ?? input.disableReasoning,
- supportsReasoning: supportsXaiReasoning(input.model),
signal: requestOpts?.signal ?? input.signal,
systemPrompt: requestOpts?.systemPrompt,
responseInstructions: requestOpts?.responseInstructions,
@@ -1560,27 +1642,40 @@ function joinAnthropicMessagesPath(baseUrl: string): string {
return url.toString();
}
-/**
- * Execute one provider-native request and classify failures without retaining
- * arbitrary upstream response bodies. The wire controls both request shape and
- * response parser; callers remain responsible for provider fallback semantics.
- */
-async function requestProviderHttpText(input: {
- wire: ProviderWire;
+/** Endpoint, headers and model id for one request format of the selected route. */
+type ProviderWireTarget = {
endpoint: string;
headers?: Record<string, string>;
model: string;
+ /** Messages requires max_tokens; the model's declared output limit when the caller sets none. */
+ defaultMaxTokens?: number;
+};
+
+/** OpenAI Responses rejects `max_output_tokens` below this value. */
+const RESPONSES_MIN_OUTPUT_TOKENS = 16;
+
+/**
+ * Execute one provider-native request plan and classify failures without
+ * retaining arbitrary upstream response bodies. Each plan step picks the wire
+ * (request shape and response parser) and the reasoning parameters; only
+ * parameter-class rejections advance the plan (see utilityReasoningPlan.ts).
+ * Callers remain responsible for provider fallback semantics.
+ */
+async function requestProviderHttpText(input: {
+ targets: Partial<Record<ProviderWire, ProviderWireTarget>>;
+ steps: readonly UtilityRequestStep[];
+ /** Remembers the step that succeeded for this route; omitted when there is no choice. */
+ memoryKey?: string;
+ /**
+ * model-compat route facts for Chat / Responses bodies. `chatOffViaCompat`
+ * means the vendor profile has its own spelling for "thinking off".
+ */
+ compat?: { harness: CompatibilityHarness; upstreamBase: string; chatOffViaCompat: boolean };
prompt: string;
maxTokens?: number;
timeoutMs?: number;
- reasoningEffort?: 'minimal' | 'low' | 'medium' | 'high';
- disableReasoning?: boolean;
/** Ollama's OpenAI-compatible chat wire uses `reasoning_effort: "none"` to disable thinking. */
isOllama?: boolean;
- /** Some coding-specialized models reject their wire's reasoning field. */
- supportsReasoning?: boolean;
- /** Unknown custom routes may reject optional fields from an otherwise compatible wire. */
- retryWithMinimalBodyOnInvalidRequest?: boolean;
/** Some private Responses-compatible endpoints reject max_output_tokens. */
supportsMaxOutputTokens?: boolean;
/** Owning workflow cancellation; linked with the candidate timeout below. */
@@ -1596,7 +1691,7 @@ async function requestProviderHttpText(input: {
/** Synchronous catalog/override snapshot guard. */
routeStillCurrent?: () => boolean;
/**
- * Called when the final response is HTTP 401. Only the Cindy AI (xd) gateway branches
+ * Called when a response is HTTP 401. Only the Cindy AI (xd) gateway branches
* pass it, so a stale Cindy AI key can be re-synced; other providers keep plain 401s.
*/
onUnauthorized?: () => void;
@@ -1611,68 +1706,79 @@ async function requestProviderHttpText(input: {
const instructions = [input.systemPrompt, input.responseInstructions]
.filter((value): value is string => typeof value === 'string' && value.trim().length > 0)
.join('\n');
- // Responses-compatible routes do not have a reasoning "off" value. The
- // lowest common supported effort for the subscribed GPT models is `low`;
- // sending `minimal` to GPT-5.4 mini is rejected by ChatGPT with HTTP 400.
- const reasoningEffort = input.disableReasoning
- ? input.wire === 'responses' ? 'low' : 'minimal'
- : input.reasoningEffort;
- const supportsRequestedReasoning = Boolean(
- input.wire !== 'anthropic-messages'
- && reasoningEffort
- && input.supportsReasoning !== false,
- );
- const hasOptionalRequestFields = input.wire === 'responses'
- || input.maxTokens !== undefined
- || input.disableReasoning === true
- || supportsRequestedReasoning;
- const ollamaReasoningOff = input.wire === 'chat-completions'
- && input.isOllama === true
- && input.disableReasoning === true;
- const buildBody = (minimal: boolean) => input.wire === 'responses'
- ? {
- model: input.model,
- input: [{ type: 'message', role: 'user', content: [{ type: 'input_text', text: input.prompt }] }],
- ...(instructions ? { instructions } : {}),
- ...(!minimal ? {
- store: false,
- stream: true,
- } : {}),
- ...(!minimal && maxTokens !== undefined && input.supportsMaxOutputTokens !== false
- ? { max_output_tokens: maxTokens }
- : {}),
- ...(!minimal && supportsRequestedReasoning
- ? { reasoning: { effort: reasoningEffort } }
- : {}),
- }
- : input.wire === 'anthropic-messages'
- ? {
- model: input.model,
+ const targetFor = (step: UtilityRequestStep): ProviderWireTarget => {
+ const target = input.targets[step.wire];
+ if (!target) throw new UtilityTextExecutionError({ reason: 'request_failed' });
+ return target;
+ };
+ const buildBody = (step: UtilityRequestStep, raisedBudget?: number): Record<string, unknown> => {
+ const { model, defaultMaxTokens } = targetFor(step);
+ const minimal = step.minimalBody === true;
+ const rung = step.rung;
+ const effort = rung.kind === 'effort' ? rung.effort : undefined;
+ const maxTokens = raisedBudget ?? (minimal ? undefined : input.maxTokens);
+ if (step.wire === 'anthropic-messages') {
+ return {
+ model,
// Anthropic API 协议必填 max_tokens。缺省由调用方以模型目录声明的
// maxOutput 兜底(模型自身输出能力);81920 只是模型不在目录时的最后
// 回退,不是宿主承诺的输出上限。
- max_tokens: maxTokens ?? 81_920,
+ max_tokens: maxTokens ?? defaultMaxTokens ?? 81_920,
...(instructions ? { system: instructions } : {}),
- ...(!minimal && input.disableReasoning ? { thinking: { type: 'disabled' } } : {}),
+ ...(rung.kind === 'off' ? { thinking: { type: 'disabled' } } : {}),
+ ...(effort ? { output_config: { effort } } : {}),
messages: [{ role: 'user', content: input.prompt }],
+ };
+ }
+ const chatOffViaCompat = step.wire === 'chat-completions'
+ && rung.kind === 'off'
+ && input.isOllama !== true
+ && input.compat?.chatOffViaCompat === true;
+ const body: Record<string, unknown> = step.wire === 'responses'
+ ? {
+ model,
+ input: [{ type: 'message', role: 'user', content: [{ type: 'input_text', text: input.prompt }] }],
+ ...(instructions ? { instructions } : {}),
+ ...(!minimal ? { store: false, stream: true } : {}),
+ ...(maxTokens !== undefined && input.supportsMaxOutputTokens !== false
+ ? { max_output_tokens: Math.max(maxTokens, RESPONSES_MIN_OUTPUT_TOKENS) }
+ : {}),
+ // Responses has no reasoning "off" value; the plan never asks for one here.
+ ...(effort ? { reasoning: { effort } } : {}),
}
: {
- model: input.model,
- ...(!minimal && maxTokens !== undefined ? { max_tokens: maxTokens } : {}),
- ...(!minimal && input.disableReasoning
- ? ollamaReasoningOff
+ model,
+ ...(maxTokens !== undefined ? { max_tokens: maxTokens } : {}),
+ // Keep both off signals: OpenAI-compatible gateways honour one or the
+ // other, and Cindy AI's chat-native models have always received this pair.
+ // A vendor profile with its own "off" spelling translates `none` instead.
+ ...(rung.kind === 'off'
+ ? input.isOllama === true
? { reasoning_effort: 'none' }
- : { thinking: { type: 'disabled' } }
- : {}),
- ...(!minimal && supportsRequestedReasoning && !ollamaReasoningOff
- ? { reasoning_effort: reasoningEffort }
+ : { thinking: { type: 'disabled' }, reasoning_effort: chatOffViaCompat ? 'none' : 'minimal' }
: {}),
+ ...(effort ? { reasoning_effort: effort } : {}),
messages: [
...(instructions ? [{ role: 'system', content: instructions }] : []),
{ role: 'user', content: input.prompt },
],
};
- let maxTokens = input.maxTokens;
+ // The minimal body exists to drop fields an endpoint rejected; vendor
+ // normalisation could add some back (for example `store`). Without a
+ // vendor "off" spelling, the off pair is sent as is: effort mapping would
+ // read `minimal` as a request for some thinking (low / budget / enabled).
+ if (minimal || !input.compat) return body;
+ if (step.wire === 'chat-completions' && rung.kind === 'off' && !chatOffViaCompat) return body;
+ const normalized = normalizeProviderRequest(body, {
+ harness: input.compat.harness,
+ protocol: step.wire === 'responses' ? 'openai-responses' : 'openai-chat',
+ upstreamBase: input.compat.upstreamBase,
+ model,
+ });
+ return normalized && typeof normalized === 'object' && !Array.isArray(normalized)
+ ? normalized as Record<string, unknown>
+ : body;
+ };
const canDispatch = async (): Promise<boolean> => {
if (input.routeStillCurrent && !input.routeStillCurrent()) return false;
if (input.beforeDispatch && !(await input.beforeDispatch())) return false;
@@ -1681,39 +1787,54 @@ async function requestProviderHttpText(input: {
if (input.beforeDispatch && !(await input.beforeDispatch())) return false;
return !input.routeStillCurrent || input.routeStillCurrent();
};
- const send = async (minimal: boolean, raisedBudget?: number) => {
+ const send = async (step: UtilityRequestStep, body: Record<string, unknown>) => {
if (!(await canDispatch())) {
throw new UtilityTextExecutionError({ reason: 'request_failed' });
}
- // 预算重试要带着放大后的预算, 又不能把已知不兼容的可选字段加回去 —— 最小体
- // 把 max_tokens 一起丢了, 直接 send(true) 等于没放大。buildBody 每次返回新
- // 对象, 在这一个字段上覆盖即可。
- const body = buildBody(minimal) as Record<string, unknown>;
- if (raisedBudget !== undefined) {
- body[input.wire === 'responses' ? 'max_output_tokens' : 'max_tokens'] = raisedBudget;
- }
- return undiciFetch(input.endpoint, {
+ const target = targetFor(step);
+ return undiciFetch(target.endpoint, {
method: 'POST',
signal: controller.signal,
headers: {
- ...(input.headers ?? {}),
+ ...(target.headers ?? {}),
'Content-Type': 'application/json',
},
body: JSON.stringify(body),
});
};
- let response = await send(false);
- let minimalBody = false;
- if (
- !response.ok
- && (response.status === 400 || response.status === 422)
- && input.wire !== 'anthropic-messages'
- && hasOptionalRequestFields
- && input.retryWithMinimalBodyOnInvalidRequest
- ) {
+
+ let index = rememberedUtilityStepIndex(input.memoryKey, input.steps);
+ let step = input.steps[index];
+ if (!step) throw new UtilityTextExecutionError({ reason: 'request_failed' });
+ let body = buildBody(step);
+ let response = await send(step, body);
+ let requests = 1;
+ while (!response.ok) {
+ // Only parameter-class rejections advance the plan. Bodies identical to
+ // the rejected one (for example a minimal body with nothing to strip)
+ // would only be rejected again.
+ let next: number | null = requests < MAX_REASONING_REQUESTS
+ ? nextUtilityRequestStep(input.steps, index, response.status)
+ : null;
+ let nextBody: Record<string, unknown> | undefined;
+ while (next !== null) {
+ const candidate = input.steps[next]!;
+ nextBody = buildBody(candidate);
+ if (candidate.wire !== step.wire || stableSnapshot(nextBody) !== stableSnapshot(body)) break;
+ next = nextUtilityRequestStep(input.steps, next, response.status);
+ }
+ if (next === null || !nextBody) break;
await response.body?.cancel().catch(() => undefined);
- response = await send(true);
- minimalBody = true;
+ log.debug('utility text request rejected, trying the next reasoning step', {
+ status: response.status,
+ from: utilityRequestStepKey(step),
+ to: utilityRequestStepKey(input.steps[next]!),
+ });
+ index = next;
+ step = input.steps[index]!;
+ body = nextBody;
+ response = await send(step, body);
+ requests += 1;
}
if (!response.ok) {
if (response.status === 401) input.onUnauthorized?.();
@@ -1722,37 +1843,40 @@ async function requestProviderHttpText(input: {
}
let raw = await response.text();
- const parsed = responseStructure(input.wire, raw);
- let text = wireResponseText(input.wire, raw);
+ const parsed = responseStructure(step.wire, raw);
+ let text = wireResponseText(step.wire, raw);
// thinking:disabled 只是请求侧建议,BYOM 网关可以无视;max_tokens 是含思考的
// 总预算,思考吃光就只剩空正文。放大预算重发一次,而不是直接丢掉这个候选。
- const budgetIsSent = input.wire !== 'responses' || input.supportsMaxOutputTokens !== false;
+ const budgetIsSent = step.wire !== 'responses' || input.supportsMaxOutputTokens !== false;
const retryBudget = !text
&& input.maxTokens !== undefined
&& budgetIsSent
- && outputBudgetExhausted(input.wire, parsed)
+ && outputBudgetExhausted(step.wire, parsed)
? reasoningRetryBudget(parsed, input.maxTokens)
: 0;
if (retryBudget > 0) {
- maxTokens = retryBudget;
log.warn('utility text reasoning burned the output budget, retrying larger', {
- wire: input.wire,
- model: input.model,
+ wire: step.wire,
+ model: targetFor(step).model,
from: input.maxTokens,
to: retryBudget,
});
- // 已被网关拒过的可选字段不重新加回去(原样重来只会再被拒一次)。
- const budgeted = await send(minimalBody, retryBudget);
+ // 预算重试沿用刚才成功的那一步(写法与档位都不变),只放大预算;已被网关拒过
+ // 的可选字段不重新加回去(原样重来只会再被拒一次)。
+ const budgeted = await send(step, buildBody(step, retryBudget));
if (budgeted.ok) {
raw = await budgeted.text();
- text = wireResponseText(input.wire, raw);
+ text = wireResponseText(step.wire, raw);
} else {
if (budgeted.status === 401) input.onUnauthorized?.();
await budgeted.body?.cancel().catch(() => undefined);
}
}
+ // The step was accepted by the provider; remember it even when the model
+ // produced no usable text, because the wording itself was not rejected.
+ if (input.steps.length > 1) rememberUtilityStep(input.memoryKey, step);
if (!text) {
- if (input.wire === 'chat-completions') {
+ if (step.wire === 'chat-completions') {
log.warn('utility text chat-completions empty content', chatCompletionEmptyFingerprint(parsed));
}
throw new UtilityTextExecutionError({ reason: 'empty_response' });
@@ -1770,6 +1894,73 @@ async function requestProviderHttpText(input: {
}
}
+/**
+ * Build the request plan for one route: entry wire from the caller, reasoning
+ * values from the model catalog (see utilityReasoningPlan.ts for the rules).
+ */
+function utilityRequestPlan(input: {
+ providerId: string;
+ agentKind: AgentKind;
+ model: string;
+ catalogModel: CatalogModel | undefined;
+ wire: ProviderWire;
+ upstreamBase: string;
+ /** Cindy AI native wires fall back to Chat on parameter / format errors. */
+ chatFallback?: boolean;
+ /** Custom routes keep the legacy "drop every optional field" last resort. */
+ minimalBodyFallback?: boolean;
+ disableReasoning?: boolean;
+ reasoningEffort?: string;
+ /** Some coding-specialized models reject their wire's reasoning field. */
+ supportsReasoning?: boolean;
+}): Pick<Parameters<typeof requestProviderHttpText>[0], 'steps' | 'memoryKey' | 'compat'> {
+ const harness: CompatibilityHarness = input.agentKind;
+ let mode: UtilityReasoningMode;
+ if (input.disableReasoning) {
+ const declaration: UtilityReasoningDeclaration =
+ input.supportsReasoning === false
+ || compatMarksNoReasoning({
+ wire: input.wire,
+ harness,
+ upstreamBase: input.upstreamBase,
+ model: input.model,
+ })
+ ? { kind: 'empty' }
+ : utilityReasoningDeclaration(input.providerId, input.agentKind, input.catalogModel);
+ mode = { kind: 'ladder', declaration };
+ } else {
+ mode = {
+ kind: 'fixed',
+ rung: input.reasoningEffort && input.supportsReasoning !== false
+ ? { kind: 'effort', effort: input.reasoningEffort }
+ : { kind: 'omit' },
+ };
+ }
+ const steps = buildUtilityRequestPlan({
+ wire: input.wire,
+ mode,
+ chatFallback: input.chatFallback,
+ minimalBodyFallback: input.minimalBodyFallback,
+ });
+ return {
+ steps,
+ memoryKey: steps.length > 1
+ ? utilityReasoningMemoryKey({
+ providerId: input.providerId,
+ agentKind: input.agentKind,
+ model: input.model,
+ wire: input.wire,
+ mode,
+ })
+ : undefined,
+ compat: {
+ harness,
+ upstreamBase: input.upstreamBase,
+ chatOffViaCompat: compatHasReasoningOff({ harness, upstreamBase: input.upstreamBase, model: input.model }),
+ },
+ };
+}
+
type ChatCompletionBody = { choices?: Array<{ message?: { content?: unknown } }> };
/**
@@ -1916,7 +2107,9 @@ function chatCompletionEmptyFingerprint(parsed: unknown): Record<string, unknown
/** Direct request for a user provider runtime selected by the schedule. */
async function requestCustomProviderText(input: {
+ providerId: string;
agentKind: AgentKind;
+ catalogModel: CatalogModel | undefined;
baseUrl: string;
requestPath?: string;
wireProtocol?: 'anthropic-messages' | 'openai-responses' | 'openai-chat';
@@ -1967,23 +2160,35 @@ async function requestCustomProviderText(input: {
headers['anthropic-version'] = headers['anthropic-version'] ?? '2023-06-01';
}
return requestProviderHttpText({
- wire,
- endpoint: input.requestPath
- ? appendProviderRequestPath(input.baseUrl, input.requestPath)
- : wire === 'responses'
- ? joinProxyPath(input.baseUrl, '/responses')
- : wire === 'chat-completions'
- ? joinProxyPath(input.baseUrl, '/chat/completions')
- : joinAnthropicMessagesPath(input.baseUrl),
- headers,
- model: input.model,
+ targets: {
+ [wire]: {
+ endpoint: input.requestPath
+ ? appendProviderRequestPath(input.baseUrl, input.requestPath)
+ : wire === 'responses'
+ ? joinProxyPath(input.baseUrl, '/responses')
+ : wire === 'chat-completions'
+ ? joinProxyPath(input.baseUrl, '/chat/completions')
+ : joinAnthropicMessagesPath(input.baseUrl),
+ headers,
+ model: input.model,
+ },
+ },
+ ...utilityRequestPlan({
+ providerId: input.providerId,
+ agentKind: input.agentKind,
+ model: input.model,
+ catalogModel: input.catalogModel,
+ wire,
+ upstreamBase: input.baseUrl,
+ // Unknown custom routes may reject optional fields from an otherwise compatible wire.
+ minimalBodyFallback: true,
+ disableReasoning: input.disableReasoning,
+ reasoningEffort: input.reasoningEffort,
+ }),
prompt: input.prompt,
maxTokens: input.maxTokens,
timeoutMs: input.timeoutMs,
- reasoningEffort: input.reasoningEffort,
- disableReasoning: input.disableReasoning,
isOllama: input.isOllama,
- retryWithMinimalBodyOnInvalidRequest: true,
signal: input.signal,
systemPrompt: input.systemPrompt,
responseInstructions: input.responseInstructions,
diff --git a/apps/desktop/src/main/utility-model/utilityReasoningPlan.ts b/apps/desktop/src/main/utility-model/utilityReasoningPlan.ts
new file mode 100644
index 0000000000..608e52322d
--- /dev/null
+++ b/apps/desktop/src/main/utility-model/utilityReasoningPlan.ts
@@ -0,0 +1,257 @@
+/**
+ * 辅助模型直连请求的思考参数取值规则。
+ *
+ * 目标是「使用该模型允许的最少思考」:
+ * - 用哪一档由模型目录决定(声明档位里的最低档);
+ * - 能不能关掉思考由请求协议决定(Messages / Chat 先试关掉,Responses 没有关掉的写法);
+ * - 各厂商写法差异交给 model-compat(调用方在组装好 Chat / Responses 请求体后归一一次);
+ * - 只有参数类错误(400 / 422,以及 Cindy AI 原生接口的 404)才沿着计划往下退,
+ * 成功的那一步按「供应商 + 模型 + 请求格式」记在内存里,下次直接从它开始。
+ *
+ * 这里只看状态码,不解析报错文案;也只记成功,不记失败。
+ */
+import {
+ profileModelListed,
+ profileModelValue,
+ resolveProviderCompatibilityProfile,
+ type CompatibilityHarness,
+} from '@cindy/model-compat';
+import { effortRank, type CatalogModel, type Effort } from '@cindy/model-providers';
+
+export type UtilityProviderWire = 'chat-completions' | 'anthropic-messages' | 'responses';
+
+/** 一次请求要带的思考参数:关掉 / 某一档 / 完全不带。 */
+export type UtilityReasoningRung =
+ | { kind: 'off' }
+ | { kind: 'effort'; effort: string }
+ | { kind: 'omit' };
+
+/**
+ * 目录对该模型思考档位的说法:
+ * - declared:声明了档位(按强弱升序);
+ * - empty:明确声明没有档位(或厂商档案标为不思考);
+ * - unknown:没有任何来源声明过。
+ */
+export type UtilityReasoningDeclaration =
+ | { kind: 'declared'; efforts: readonly string[] }
+ | { kind: 'empty' }
+ | { kind: 'unknown' };
+
+export type UtilityRequestStep = {
+ wire: UtilityProviderWire;
+ rung: UtilityReasoningRung;
+ /** 去掉所有可选字段的兜底请求体(仅自定义供应商沿用的旧行为)。 */
+ minimalBody?: boolean;
+ /** Cindy AI 原生接口:404 视为「该格式不可用」,直接退回 Chat。 */
+ gatewayNative?: boolean;
+};
+
+/** 写死的档位兜底只用于目录没声明的模型,与改动前 Responses 的取值一致。 */
+const UNKNOWN_MODEL_EFFORT = 'low';
+
+/** 每次辅助请求因参数类错误而发出的请求总数上限(不含 #6098 的预算重试)。 */
+export const MAX_REASONING_REQUESTS = 4;
+
+/**
+ * Cindy AI 网关的模型档位由网关下发;下发里缺了 efforts 时目录会落成 `[]`,
+ * 与「明确声明为空」不可区分。网关的原始声明保留在 discoveredMetadata 里,
+ * 据此把「没下发」识别为未声明,而不是当成「这个模型不思考」。
+ */
+export function utilityReasoningDeclaration(
+ providerId: string,
+ agentKind: string,
+ model: Pick<CatalogModel, 'efforts' | 'effortsUnknown' | 'discoveredMetadata' | 'reasoning'> | undefined,
+): UtilityReasoningDeclaration {
+ if (!model || model.effortsUnknown || !Array.isArray(model.efforts)) return { kind: 'unknown' };
+ if (model.efforts.length === 0) {
+ if (providerId === 'xd') {
+ return Array.isArray(model.discoveredMetadata?.efforts) ? { kind: 'empty' } : { kind: 'unknown' };
+ }
+ // 自定义 Pi 模型从不打「未声明」标记,`[]` 只是 Pi 运行时的占位(见
+ // model-providers user-provider.ts);只有显式 reasoning:false 才算声明为空。
+ if (agentKind === 'pi' && model.reasoning !== false) return { kind: 'unknown' };
+ return { kind: 'empty' };
+ }
+ const efforts = [...new Set(model.efforts)].sort(
+ (a, b) => effortRank(a as Effort) - effortRank(b as Effort),
+ );
+ return { kind: 'declared', efforts };
+}
+
+/** 厂商档案把该模型标成不思考时,一开始就不带思考参数。只对 Chat / Responses 生效。 */
+export function compatMarksNoReasoning(input: {
+ wire: UtilityProviderWire;
+ harness: CompatibilityHarness;
+ upstreamBase: string;
+ model: string;
+}): boolean {
+ if (input.wire === 'anthropic-messages') return false;
+ const profile = resolveProviderCompatibilityProfile({
+ harness: input.harness,
+ protocol: input.wire === 'responses' ? 'openai-responses' : 'openai-chat',
+ upstreamBase: input.upstreamBase,
+ model: input.model,
+ });
+ return Boolean(profile && profileModelListed(profile.noReasoningModels, input.model));
+}
+
+/**
+ * 厂商档案是否给出了「关掉思考」的专门写法(网关对象格式,或档位映射里有 `none`)。
+ * 有时 Chat 的「关掉」交给 model-compat 翻译 `reasoning_effort: 'none'`;没有时保持
+ * 原来的 `thinking: disabled` + `reasoning_effort: 'minimal'` 且不经档位映射——
+ * 否则 `minimal` 会被当成「要一档思考」映射成 low / 思考预算 / enabled。
+ */
+export function compatHasReasoningOff(input: {
+ harness: CompatibilityHarness;
+ upstreamBase: string;
+ model: string;
+}): boolean {
+ const profile = resolveProviderCompatibilityProfile({
+ harness: input.harness,
+ protocol: 'openai-chat',
+ upstreamBase: input.upstreamBase,
+ model: input.model,
+ });
+ if (!profile) return false;
+ if (profile.reasoningWireFormat === 'gateway-object') return true;
+ const wireMap = profileModelValue(profile.modelReasoningEffortMap, input.model) ?? profile.reasoningEffortMap;
+ return typeof wireMap === 'object' && wireMap !== null && Object.hasOwn(wireMap, 'none');
+}
+
+/** 同一声明在某个请求格式上的退让顺序:关掉(协议支持时)→ 最低档 → 高一档。 */
+export function utilityReasoningRungs(
+ wire: UtilityProviderWire,
+ declaration: UtilityReasoningDeclaration,
+): UtilityReasoningRung[] {
+ if (declaration.kind === 'empty') return [{ kind: 'omit' }];
+ const off: UtilityReasoningRung[] = wire === 'responses' ? [] : [{ kind: 'off' }];
+ const efforts = declaration.kind === 'declared'
+ ? declaration.efforts.slice(0, 2)
+ : [UNKNOWN_MODEL_EFFORT];
+ return [...off, ...efforts.map((effort) => ({ kind: 'effort' as const, effort }))];
+}
+
+export function utilityReasoningRungKey(rung: UtilityReasoningRung): string {
+ return rung.kind === 'effort' ? `effort:${rung.effort}` : rung.kind;
+}
+
+export function utilityRequestStepKey(step: UtilityRequestStep): string {
+ return `${step.wire}|${utilityReasoningRungKey(step.rung)}${step.minimalBody ? '|minimal' : ''}`;
+}
+
+export type UtilityReasoningMode =
+ /** 默认:按目录声明逐级退让。 */
+ | { kind: 'ladder'; declaration: UtilityReasoningDeclaration }
+ /** 调用方显式要求的单一取值(重新打开思考、或指定档位),不做档位退让。 */
+ | { kind: 'fixed'; rung: UtilityReasoningRung };
+
+/**
+ * 生成一次请求的完整计划。
+ *
+ * - `chatFallback`:Cindy AI 按模型原生格式发,原生格式出参数 / 格式类错误时退回 Chat,
+ * Chat 从原生格式起步的那一档接着往下退(思考档位照常带上,不会丢)。
+ * - `minimalBodyFallback`:自定义供应商沿用的「去掉所有可选参数」兜底;档位模式下
+ * 只给目录没声明档位(或声明为空)的模型,声明了档位的绝不退到不带思考参数。
+ */
+export function buildUtilityRequestPlan(input: {
+ wire: UtilityProviderWire;
+ mode: UtilityReasoningMode;
+ chatFallback?: boolean;
+ minimalBodyFallback?: boolean;
+}): UtilityRequestStep[] {
+ const { wire, mode } = input;
+ const withChatFallback = input.chatFallback === true && wire !== 'chat-completions';
+ const steps: UtilityRequestStep[] = [];
+ if (mode.kind === 'fixed') {
+ // Messages 从未表达过调用方指定的档位,保持原样;退回 Chat 时照常带上。
+ const nativeRung: UtilityReasoningRung =
+ wire === 'anthropic-messages' && mode.rung.kind === 'effort' ? { kind: 'omit' } : mode.rung;
+ steps.push({ wire, rung: nativeRung, ...(withChatFallback ? { gatewayNative: true } : {}) });
+ if (withChatFallback) steps.push({ wire: 'chat-completions', rung: mode.rung });
+ } else {
+ const nativeRungs = utilityReasoningRungs(wire, mode.declaration);
+ for (const rung of nativeRungs) {
+ steps.push({ wire, rung, ...(withChatFallback ? { gatewayNative: true } : {}) });
+ }
+ if (withChatFallback) {
+ const chatRungs = utilityReasoningRungs('chat-completions', mode.declaration);
+ const startKey = utilityReasoningRungKey(nativeRungs[0]!);
+ const start = Math.max(0, chatRungs.findIndex((rung) => utilityReasoningRungKey(rung) === startKey));
+ for (const rung of chatRungs.slice(start)) steps.push({ wire: 'chat-completions', rung });
+ }
+ }
+ const minimalAllowed = mode.kind === 'fixed' || mode.declaration.kind !== 'declared';
+ if (input.minimalBodyFallback && minimalAllowed && wire !== 'anthropic-messages') {
+ steps.push({ wire, rung: { kind: 'omit' }, minimalBody: true });
+ }
+ return steps;
+}
+
+/**
+ * 参数类错误时计划的下一步;返回 null 表示不再退让。
+ * 401 / 403 / 429 / 5xx 一律不退让:换写法解决不了鉴权、限流和服务端故障。
+ */
+export function nextUtilityRequestStep(
+ steps: readonly UtilityRequestStep[],
+ index: number,
+ status: number,
+): number | null {
+ const step = steps[index];
+ if (!step) return null;
+ if (status === 404) {
+ if (!step.gatewayNative) return null;
+ // 原生接口不存在:原生格式的其它档位同样不可用,带着当前档位直接退回 Chat。
+ const chat = steps.findIndex((candidate, i) => i > index && candidate.wire === 'chat-completions');
+ if (chat < 0) return null;
+ const sameRung = steps.findIndex((candidate, i) =>
+ i >= chat
+ && candidate.wire === 'chat-completions'
+ && utilityReasoningRungKey(candidate.rung) === utilityReasoningRungKey(step.rung));
+ return sameRung >= 0 ? sameRung : chat;
+ }
+ if (status !== 400 && status !== 422) return null;
+ return index + 1 < steps.length ? index + 1 : null;
+}
+
+/** 只记成功的写法,进程内有效;重启后清空。 */
+const rememberedSteps = new Map<string, string>();
+const REMEMBERED_STEP_LIMIT = 256;
+
+export function utilityReasoningMemoryKey(parts: {
+ providerId: string;
+ agentKind: string;
+ model: string;
+ wire: UtilityProviderWire;
+ mode: UtilityReasoningMode;
+}): string {
+ const mode = parts.mode.kind === 'ladder' ? 'ladder' : `fixed:${utilityReasoningRungKey(parts.mode.rung)}`;
+ return JSON.stringify([parts.providerId, parts.agentKind, parts.model, parts.wire, mode]);
+}
+
+/** 记住的写法若仍在本次计划里,就从它开始;它后来被拒时照常往下退。 */
+export function rememberedUtilityStepIndex(
+ memoryKey: string | undefined,
+ steps: readonly UtilityRequestStep[],
+): number {
+ if (!memoryKey) return 0;
+ const remembered = rememberedSteps.get(memoryKey);
+ if (!remembered) return 0;
+ return Math.max(0, steps.findIndex((step) => utilityRequestStepKey(step) === remembered));
+}
+
+export function rememberUtilityStep(memoryKey: string | undefined, step: UtilityRequestStep): void {
+ // 最小请求体同时丢掉了输出上限和思考参数;记住它会让之后所有调用方
+ // (不同的 maxTokens)都从这里起步、再也回不到带参数的写法。
+ if (!memoryKey || step.minimalBody) return;
+ rememberedSteps.delete(memoryKey);
+ if (rememberedSteps.size >= REMEMBERED_STEP_LIMIT) {
+ const oldest = rememberedSteps.keys().next().value;
+ if (oldest !== undefined) rememberedSteps.delete(oldest);
+ }
+ rememberedSteps.set(memoryKey, utilityRequestStepKey(step));
+}
+
+/** 测试用:清空进程内记住的写法。 */
+export function resetUtilityReasoningMemory(): void {
+ rememberedSteps.clear();
+}