Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。
TypeScript agentai-agentai-assistantandroidclaude-codecodexelectroniosllmmacosreact-nativetypescriptwindows
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.tsindex 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.tsnew file mode 100644index 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.tsindex 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-primport { 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/preflimport { 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.tsnew file mode 100644index 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();+}