@theia/ai-openai 1.76.0-next.7 → 1.76.0

package/src/browser/openai-frontend-application-contribution.ts

@@ -14,89 +14,95 @@
 // SPDX-License-Identifier: EPL-2.0 OR GPL-2.0-only WITH Classpath-exception-2.0
 // *****************************************************************************
 
-import { FrontendApplicationContribution } from '@theia/core/lib/browser';
 import { inject, injectable } from '@theia/core/shared/inversify';
-import { ReasoningSupport, resolveCompactionDefault, resolveCompactionTokenThresholdDefault, ServerSideCompactionSetting } from '@theia/ai-core';
+import {
+    ReasoningSupport, resolveCompactionDefault, resolveCompactionTokenThresholdDefault, resolveCustomModelHeaders, ServerSideCompactionSetting
+} from '@theia/ai-core';
+import { DiscoveringProviderContribution, ModelDiscoveryMessages } from '@theia/ai-core/lib/browser';
+import { DiscoveredModel } from '@theia/ai-core/lib/common';
 import { OpenAiLanguageModelsManager, OpenAiModelDescription, OPENAI_PROVIDER_ID } from '../common';
 import {
-    API_KEY_PREF, CUSTOM_ENDPOINTS_PREF, MODELS_PREF, SERVER_SIDE_COMPACTION_PREF, SERVER_SIDE_COMPACTION_TOKEN_THRESHOLD_PREF, USE_RESPONSE_API_PREF
+    ALLOW_ENV_API_KEY_PREF, API_KEY_PREF, CUSTOM_ENDPOINTS_PREF, MODEL_OVERRIDES_PREF, SERVER_SIDE_COMPACTION_PREF, SERVER_SIDE_COMPACTION_TOKEN_THRESHOLD_PREF,
+    USE_RESPONSE_API_PREF
 } from '../common/openai-preferences';
 import {
-    AICorePreferences, PREFERENCE_NAME_MAX_RETRIES, PREFERENCE_NAME_SERVER_SIDE_COMPACTION, PREFERENCE_NAME_SERVER_SIDE_COMPACTION_TOKEN_THRESHOLD
+    AICorePreferences, PREFERENCE_NAME_MAX_RETRIES, PREFERENCE_NAME_SERVER_SIDE_COMPACTION,
+    PREFERENCE_NAME_SERVER_SIDE_COMPACTION_TOKEN_THRESHOLD
 } from '@theia/ai-core/lib/common/ai-core-preferences';
-import { PreferenceService } from '@theia/core';
+import { nls, PreferenceChange } from '@theia/core';
 
-@injectable()
-export class OpenAiFrontendApplicationContribution implements FrontendApplicationContribution {
+/** Provider node id (matches the `ai-features.openAiOfficial.*` configuration segment). */
+const OPENAI_OFFICIAL_PROVIDER_ID = 'openAiOfficial';
 
-    @inject(PreferenceService)
-    protected preferenceService: PreferenceService;
+@injectable()
+export class OpenAiFrontendApplicationContribution extends DiscoveringProviderContribution<OpenAiModelDescription> {
 
     @inject(OpenAiLanguageModelsManager)
-    protected manager: OpenAiLanguageModelsManager;
+    protected readonly manager: OpenAiLanguageModelsManager;
 
     @inject(AICorePreferences)
     protected aiCorePreferences: AICorePreferences;
 
-    protected prevModels: string[] = [];
-    protected prevCustomModels: Partial<OpenAiModelDescription>[] = [];
+    protected readonly providerId = OPENAI_OFFICIAL_PROVIDER_ID;
+    protected readonly providerLabel = 'OpenAI';
+    protected readonly modelOverridesPreference = MODEL_OVERRIDES_PREF;
+    protected readonly allowEnvironmentApiKeyPreference = ALLOW_ENV_API_KEY_PREF;
 
-    onStart(): void {
-        this.preferenceService.ready.then(() => {
-            const apiKey = this.preferenceService.get<string>(API_KEY_PREF, undefined);
-            this.manager.setApiKey(apiKey);
-
-            const proxyUri = this.preferenceService.get<string>('http.proxy', undefined);
-            this.manager.setProxyUrl(proxyUri);
-
-            const models = this.preferenceService.get<string[]>(MODELS_PREF, []);
-            this.manager.createOrUpdateLanguageModels(...models.map(modelId => this.createOpenAIModelDescription(modelId)));
-            this.prevModels = [...models];
-
-            const customModels = this.preferenceService.get<Partial<OpenAiModelDescription>[]>(CUSTOM_ENDPOINTS_PREF, []);
-            this.manager.createOrUpdateLanguageModels(...this.createCustomModelDescriptionsFromPreferences(customModels));
-            this.prevCustomModels = [...customModels];
-
-            this.preferenceService.onPreferenceChanged(event => {
-                if (event.preferenceName === API_KEY_PREF) {
-                    this.manager.setApiKey(this.preferenceService.get<string>(API_KEY_PREF, undefined));
-                    this.updateAllModels();
-                } else if (event.preferenceName === MODELS_PREF) {
-                    this.handleModelChanges(this.preferenceService.get<string[]>(MODELS_PREF, []));
-                } else if (event.preferenceName === CUSTOM_ENDPOINTS_PREF) {
-                    this.handleCustomModelChanges(this.preferenceService.get<Partial<OpenAiModelDescription>[]>(CUSTOM_ENDPOINTS_PREF, []));
-                } else if (event.preferenceName === USE_RESPONSE_API_PREF) {
-                    this.updateAllModels();
-                } else if (event.preferenceName === SERVER_SIDE_COMPACTION_PREF) {
-                    this.updateAllModels();
-                } else if (event.preferenceName === PREFERENCE_NAME_SERVER_SIDE_COMPACTION ||
-                    event.preferenceName === SERVER_SIDE_COMPACTION_TOKEN_THRESHOLD_PREF ||
-                    event.preferenceName === PREFERENCE_NAME_SERVER_SIDE_COMPACTION_TOKEN_THRESHOLD) {
-                    this.updateAllModels();
-                } else if (event.preferenceName === 'http.proxy') {
-                    this.manager.setProxyUrl(this.preferenceService.get<string>('http.proxy', undefined));
-                    this.updateAllModels();
-                }
-            });
+    /** The registered ids carry the `openai/` prefix, while the provider node is `openAiOfficial`. */
+    protected override get modelIdPrefix(): string {
+        return OPENAI_PROVIDER_ID;
+    }
 
-            this.aiCorePreferences.onPreferenceChanged(event => {
-                if (event.preferenceName === PREFERENCE_NAME_MAX_RETRIES) {
-                    this.updateAllModels();
-                }
-            });
-        });
+    protected prevCustomModels: Partial<OpenAiModelDescription>[] = [];
+
+    protected get discoveryMessages(): ModelDiscoveryMessages {
+        return {
+            noCredentials: nls.localize('theia/ai/openai/discovery/noKey', 'No OpenAI API key set. Add a key to discover models.'),
+            consentRequired: nls.localize('theia/ai/openai/discovery/consentRequired',
+                'An OpenAI API key was found in the environment. Confirm its use to discover models.'),
+            consentPrompt: nls.localize('theia/ai/openai/discovery/consentPrompt',
+                'An OpenAI API key was found in the environment (OPENAI_API_KEY). Allow Theia to use it to discover and call OpenAI models?'),
+            useEnvironmentKey: nls.localize('theia/ai/openai/discovery/useEnvKey', 'Use key'),
+            overridden: nls.localize('theia/ai/openai/discovery/overridden',
+                'The model list is configured manually. Clear the model overrides to discover the models from the provider again.'),
+            cached: error => nls.localize('theia/ai/openai/discovery/cached', 'Showing cached models; last refresh failed: {0}', error)
+        };
     }
 
-    protected handleModelChanges(newModels: string[]): void {
-        const oldModels = new Set(this.prevModels);
-        const updatedModels = new Set(newModels);
+    protected override initializeProvider(): void {
+        this.manager.setApiKey(this.preferenceService.get<string>(API_KEY_PREF, undefined));
+        this.manager.setProxyUrl(this.preferenceService.get<string>('http.proxy', undefined));
 
-        const modelsToRemove = [...oldModels].filter(model => !updatedModels.has(model));
-        const modelsToAdd = [...updatedModels].filter(model => !oldModels.has(model));
+        const customModels = this.preferenceService.get<Partial<OpenAiModelDescription>[]>(CUSTOM_ENDPOINTS_PREF, []);
+        this.manager.createOrUpdateLanguageModels(...this.createCustomModelDescriptionsFromPreferences(customModels));
+        this.prevCustomModels = [...customModels];
 
-        this.manager.removeLanguageModels(...modelsToRemove.map(model => `openai/${model}`));
-        this.manager.createOrUpdateLanguageModels(...modelsToAdd.map(modelId => this.createOpenAIModelDescription(modelId)));
-        this.prevModels = newModels;
+        this.aiCorePreferences.onPreferenceChanged(event => {
+            if (event.preferenceName === PREFERENCE_NAME_MAX_RETRIES) {
+                this.updateDiscoveredModels();
+            }
+        });
+    }
+
+    protected override handlePreferenceChange(event: PreferenceChange): void {
+        if (event.preferenceName === API_KEY_PREF) {
+            this.manager.setApiKey(this.preferenceService.get<string>(API_KEY_PREF, undefined));
+            this.discoverAndRegisterModels();
+        } else if (event.preferenceName === CUSTOM_ENDPOINTS_PREF) {
+            this.handleCustomModelChanges(this.preferenceService.get<Partial<OpenAiModelDescription>[]>(CUSTOM_ENDPOINTS_PREF, []));
+        } else if (event.preferenceName === USE_RESPONSE_API_PREF ||
+            event.preferenceName === SERVER_SIDE_COMPACTION_PREF ||
+            event.preferenceName === PREFERENCE_NAME_SERVER_SIDE_COMPACTION ||
+            event.preferenceName === SERVER_SIDE_COMPACTION_TOKEN_THRESHOLD_PREF ||
+            event.preferenceName === PREFERENCE_NAME_SERVER_SIDE_COMPACTION_TOKEN_THRESHOLD) {
+            this.updateDiscoveredModels();
+        } else if (event.preferenceName === 'http.proxy') {
+            this.manager.setProxyUrl(this.preferenceService.get<string>('http.proxy', undefined));
+            // A model keeps the proxy it was registered with, so the custom endpoints have to be
+            // re-registered as well: discovery only covers the models it registers itself.
+            this.updateCustomModels();
+            this.discoverAndRegisterModels();
+        }
     }
 
     protected handleCustomModelChanges(newCustomModels: Partial<OpenAiModelDescription>[]): void {
@@ -118,23 +124,28 @@ export class OpenAiFrontendApplicationContribution implements FrontendApplicatio
                 model.useResponseApi === newModel.useResponseApi &&
                 model.serverSideCompactionEnabledByDefault === newModel.serverSideCompactionEnabledByDefault &&
                 model.serverSideCompactionTokenThresholdByDefault === newModel.serverSideCompactionTokenThresholdByDefault &&
-                reasoningSupportEquals(model.reasoningSupport, newModel.reasoningSupport)));
+                reasoningSupportEquals(model.reasoningSupport, newModel.reasoningSupport) &&
+                JSON.stringify(model.headers) === JSON.stringify(newModel.headers)));
 
         this.manager.removeLanguageModels(...modelsToRemove.map(model => model.id));
         this.manager.createOrUpdateLanguageModels(...modelsToAddOrUpdate);
         this.prevCustomModels = [...newCustomModels];
     }
 
-    protected updateAllModels(): void {
-        const models = this.preferenceService.get<string[]>(MODELS_PREF, []);
-        this.manager.createOrUpdateLanguageModels(...models.map(modelId => this.createOpenAIModelDescription(modelId)));
+    protected override updateDiscoveredModels(): void {
+        super.updateDiscoveredModels();
+        this.updateCustomModels();
+    }
 
+    /** Re-applies the model descriptions of the configured custom endpoints. */
+    protected updateCustomModels(): void {
         const customModels = this.preferenceService.get<Partial<OpenAiModelDescription>[]>(CUSTOM_ENDPOINTS_PREF, []);
         this.manager.createOrUpdateLanguageModels(...this.createCustomModelDescriptionsFromPreferences(customModels));
     }
 
     /** Per-model capabilities are resolved by the backend from the model id; see `openai-model-defaults.ts`. */
-    protected createOpenAIModelDescription(modelId: string): OpenAiModelDescription {
+    protected createModelDescription(model: DiscoveredModel): OpenAiModelDescription {
+        const modelId = model.id;
         const id = `${OPENAI_PROVIDER_ID}/${modelId}`;
         const maxRetries = this.aiCorePreferences.get(PREFERENCE_NAME_MAX_RETRIES) ?? 3;
         const useResponseApi = this.preferenceService.get<boolean>(USE_RESPONSE_API_PREF, false);
@@ -152,7 +163,8 @@ export class OpenAiFrontendApplicationContribution implements FrontendApplicatio
             maxRetries: maxRetries,
             useResponseApi: useResponseApi,
             serverSideCompactionEnabledByDefault,
-            serverSideCompactionTokenThresholdByDefault
+            serverSideCompactionTokenThresholdByDefault,
+            released: model.released
         };
     }
 
@@ -184,6 +196,7 @@ export class OpenAiFrontendApplicationContribution implements FrontendApplicatio
                     enableStreaming: pref.enableStreaming,
                     maxRetries: pref.maxRetries ?? maxRetries,
                     useResponseApi: pref.useResponseApi ?? false,
+                    headers: resolveCustomModelHeaders(pref.headers),
                     reasoningSupport: isReasoningSupport(pref.reasoningSupport) ? pref.reasoningSupport : undefined,
                     serverSideCompactionEnabledByDefault,
                     serverSideCompactionTokenThresholdByDefault

package/src/common/openai-language-models-manager.ts

@@ -13,7 +13,7 @@
 //
 // SPDX-License-Identifier: EPL-2.0 OR GPL-2.0-only WITH Classpath-exception-2.0
 // *****************************************************************************
-import { ReasoningSupport } from '@theia/ai-core';
+import { ApiKeySource, ModelDiscoveryResult, ReasoningSupport } from '@theia/ai-core';
 
 export const OPENAI_LANGUAGE_MODELS_MANAGER_PATH = '/services/open-ai/language-model-manager';
 export const OpenAiLanguageModelsManager = Symbol('OpenAiLanguageModelsManager');
@@ -35,6 +35,8 @@ export interface OpenAiModelDescription {
     deployment?: string;
     /** Maximum number of retry attempts when a request fails. Default is 3. */
     maxRetries: number;
+    /** Additional HTTP headers sent with every request to the endpoint, e.g. headers required by a gateway in front of the API. */
+    headers?: Record<string, string>;
     /** Use the newer OpenAI Response API instead of the Chat Completion API. Default is `false`. */
     useResponseApi?: boolean;
     /** Indicate whether the streaming API shall be used. Defaults from the model id when unset. */
@@ -54,12 +56,29 @@ export interface OpenAiModelDescription {
     serverSideCompactionEnabledByDefault?: boolean;
     /** Resolved default input-token threshold for server-side compaction. `undefined` preserves the provider default. */
     serverSideCompactionTokenThresholdByDefault?: number;
+    /** Release date (ms since epoch) reported by discovery, surfaced as {@link LanguageModelMetaData.released}. */
+    released?: number;
 }
 export interface OpenAiLanguageModelsManager {
     apiKey: string | undefined;
     setApiKey(key: string | undefined): void;
+    /**
+     * Allows or refuses the use of an API key found in the environment. Refused by default: an
+     * environment key is only used once the user has confirmed it, and setting this back to `false`
+     * stops it being used immediately, wherever it would have been used.
+     */
+    setAllowEnvironmentApiKey(allowed: boolean): void;
     setApiVersion(version: string | undefined): void;
     setProxyUrl(proxyUrl: string | undefined): void;
     createOrUpdateLanguageModels(...models: OpenAiModelDescription[]): Promise<void>;
-    removeLanguageModels(...modelIds: string[]): void
+    removeLanguageModels(...modelIds: string[]): void;
+    /**
+     * Fetches the ids of the text-chat models OpenAI currently offers from its `/v1/models` endpoint,
+     * retrying transient connection failures and caching a snapshot for offline use. The endpoint
+     * exposes no capability metadata, so non-chat models are filtered out heuristically. Returns an
+     * empty result when no key is configured; falls back to the cached snapshot on failure.
+     */
+    fetchAvailableModels(): Promise<ModelDiscoveryResult>;
+    /** Reports where the effective API key comes from (preference, environment, or none). */
+    getApiKeySource(): Promise<ApiKeySource>;
 }

package/src/common/openai-preferences.ts

@@ -21,7 +21,8 @@ import { SERVER_SIDE_COMPACTION_TOKEN_THRESHOLD_MINIMUM } from '@theia/ai-core/l
 import { LINUX_ENV_HINT, nls, PreferenceSchema } from '@theia/core';
 
 export const API_KEY_PREF = 'ai-features.openAiOfficial.openAiApiKey';
-export const MODELS_PREF = 'ai-features.openAiOfficial.officialOpenAiModels';
+export const ALLOW_ENV_API_KEY_PREF = 'ai-features.openAiOfficial.allowEnvironmentApiKey';
+export const MODEL_OVERRIDES_PREF = 'ai-features.openAiOfficial.modelOverrides';
 export const USE_RESPONSE_API_PREF = 'ai-features.openAiOfficial.useResponseApi';
 export const SERVER_SIDE_COMPACTION_PREF = 'ai-features.openAiOfficial.serverSideCompaction';
 export const SERVER_SIDE_COMPACTION_TOKEN_THRESHOLD_PREF = 'ai-features.openAiOfficial.serverSideCompactionTokenThreshold';
@@ -37,20 +38,24 @@ export const OpenAiPreferencesSchema: PreferenceSchema = {
 on the machine running Theia. Use the environment variable `OPENAI_API_KEY` to set the key securely.') + LINUX_ENV_HINT,
             title: AI_CORE_PREFERENCES_TITLE,
         },
-        [MODELS_PREF]: {
-            type: 'array',
-            description: nls.localize('theia/ai/openai/models/description', 'Official OpenAI models to use'),
+        [ALLOW_ENV_API_KEY_PREF]: {
+            type: 'boolean',
+            default: false,
             title: AI_CORE_PREFERENCES_TITLE,
-            default: [
-                'gpt-5.6-sol',
-                'gpt-5.6-terra',
-                'gpt-5.6-luna',
-                'gpt-5.5',
-                'gpt-5.5-pro'
-            ],
+            markdownDescription: nls.localize('theia/ai/openai/allowEnvApiKey/description',
+                'Allow Theia to use an OpenAI API key found in the environment (`OPENAI_API_KEY`). '
+                + 'You are asked to confirm this once before the key is used; set it back to `false` to revoke consent.'),
+        },
+        [MODEL_OVERRIDES_PREF]: {
+            type: 'array',
+            default: [],
             items: {
                 type: 'string'
-            }
+            },
+            title: AI_CORE_PREFERENCES_TITLE,
+            markdownDescription: nls.localize('theia/ai/openai/modelOverrides/description',
+                'Override the models discovered from OpenAI. When empty (default), the available models are discovered from the provider. '
+                + 'Set explicit model ids to use exactly those instead; discovery is then not used at all.')
         },
         [USE_RESPONSE_API_PREF]: {
             type: 'boolean',
@@ -117,6 +122,8 @@ on the machine running Theia. Use the environment variable `OPENAI_API_KEY` to s
             - specify `reasoningSupport` to opt in to the chat reasoning selector. Provide an object with\
             `supportedLevels` (e.g. `["off", "low", "medium", "high", "auto"]`) and an optional `defaultLevel`.\
             \n\
+            - specify `headers` to send additional HTTP headers with every request to the endpoint, e.g. headers required by a gateway in front of the API.\
+            \n\
             Refer to [our documentation](https://theia-ide.org/docs/user_ai/#openai-compatible-models-eg-via-vllm) for more information.'),
             default: [],
             items: {
@@ -191,6 +198,12 @@ on the machine running Theia. Use the environment variable `OPENAI_API_KEY` to s
                                 enum: ['off', 'minimal', 'low', 'medium', 'high', 'auto']
                             }
                         }
+                    },
+                    headers: {
+                        type: 'object',
+                        additionalProperties: { type: 'string' },
+                        title: nls.localize('theia/ai/openai/customEndpoints/headers/title',
+                            'Additional HTTP headers sent with every request to the endpoint'),
                     }
                 }
             }

package/src/node/openai-language-model.spec.ts

@@ -17,9 +17,10 @@
 import { expect } from 'chai';
 import { LanguageModelMessage, LanguageModelRequest, LanguageModelResponse, ReasoningSupport, UserRequest } from '@theia/ai-core';
 import { OpenAI } from 'openai';
-import { OpenAiModel, OpenAiModelUtils } from './openai-language-model';
+import { MistralFixedOpenAI, OpenAiModel, OpenAiModelUtils } from './openai-language-model';
 import { OpenAiResponseApiUtils } from './openai-response-api-utils';
 import { OPENAI_WEB_SEARCH } from './openai-server-tools';
+import type { FinalRequestOptions } from 'openai/internal/request-options';
 
 const GPT5_REASONING_SUPPORT: ReasoningSupport = {
     supportedLevels: ['off', 'minimal', 'low', 'medium', 'high', 'auto'],
@@ -80,35 +81,47 @@ describe('OpenAiModel reasoning translation', () => {
         it('maps level=minimal to reasoning.effort=minimal', () => {
             const model = createModel('gpt-5', GPT5_REASONING_SUPPORT);
             const result = model.callGetSettings({ messages: [], reasoning: { level: 'minimal' } }, true);
-            expect(result.reasoning).to.deep.equal({ effort: 'minimal' });
+            expect(result.reasoning).to.deep.equal({ effort: 'minimal', summary: 'auto' });
         });
         it('maps level=high to reasoning.effort=high', () => {
             const model = createModel('gpt-5', GPT5_REASONING_SUPPORT);
             const result = model.callGetSettings({ messages: [], reasoning: { level: 'high' } }, true);
-            expect(result.reasoning).to.deep.equal({ effort: 'high' });
+            expect(result.reasoning).to.deep.equal({ effort: 'high', summary: 'auto' });
         });
         it('omits reasoning entirely when level=off', () => {
             const model = createModel('gpt-5', GPT5_REASONING_SUPPORT);
             const result = model.callGetSettings({ messages: [], reasoning: { level: 'off' } }, true);
             expect(result.reasoning).to.equal(undefined);
         });
-        it('omits reasoning when level=auto (provider default applies)', () => {
+        it('requests reasoning summaries for level=auto without constraining effort', () => {
             const model = createModel('gpt-5', GPT5_REASONING_SUPPORT);
             const result = model.callGetSettings({ messages: [], reasoning: { level: 'auto' } }, true);
-            expect(result.reasoning).to.equal(undefined);
+            expect(result.reasoning).to.deep.equal({ summary: 'auto' });
+        });
+        it('keeps user-configured reasoning fields but lets the selected level decide effort', () => {
+            const model = createModel('gpt-5', GPT5_REASONING_SUPPORT);
+            const result = model.callGetSettings({
+                messages: [], reasoning: { level: 'high' }, settings: { reasoning: { effort: 'low', summary: 'concise' } }
+            }, true);
+            expect(result.reasoning).to.deep.equal({ effort: 'high', summary: 'concise' });
+        });
+        it('keeps a user-configured reasoning.summary for level=auto', () => {
+            const model = createModel('gpt-5', GPT5_REASONING_SUPPORT);
+            const result = model.callGetSettings({ messages: [], reasoning: { level: 'auto' }, settings: { reasoning: { summary: 'detailed' } } }, true);
+            expect(result.reasoning).to.deep.equal({ summary: 'detailed' });
         });
     });
 
-    describe('Chat Completions API (o-series)', () => {
+    describe('Chat Completions API', () => {
         it('maps level=medium to reasoning_effort=medium', () => {
             const model = createModel('o3-mini', O_SERIES_REASONING_SUPPORT);
             const result = model.callGetSettings({ messages: [], reasoning: { level: 'medium' } }, false);
             expect(result.reasoning_effort).to.equal('medium');
         });
-        it('buckets minimal to low (o-series does not accept minimal)', () => {
-            const model = createModel('o3-mini', O_SERIES_REASONING_SUPPORT);
+        it('passes minimal through (GPT-5 accepts it; models that do not exclude it from their supportedLevels)', () => {
+            const model = createModel('gpt-5', GPT5_REASONING_SUPPORT);
             const result = model.callGetSettings({ messages: [], reasoning: { level: 'minimal' } }, false);
-            expect(result.reasoning_effort).to.equal('low');
+            expect(result.reasoning_effort).to.equal('minimal');
         });
         it('omits reasoning_effort for level=off', () => {
             const model = createModel('o3-mini', O_SERIES_REASONING_SUPPORT);
@@ -179,6 +192,47 @@ describe('OpenAiModel Response API fallback', () => {
     });
 });
 
+class TestableMistralFixedOpenAI extends MistralFixedOpenAI {
+    callPrepareOptions(options: FinalRequestOptions): Promise<void> {
+        return this.prepareOptions(options);
+    }
+}
+
+describe('MistralFixedOpenAI request preparation', () => {
+
+    const client = new TestableMistralFixedOpenAI({ apiKey: 'test-key' });
+
+    it('leaves a request without a body alone', async () => {
+        // `GET /models`, which model discovery issues, carries no body at all.
+        const options = { method: 'get', path: '/models' } as FinalRequestOptions;
+        await client.callPrepareOptions(options);
+        expect(options.body).to.equal(undefined);
+    });
+
+    it('leaves a body without messages alone', async () => {
+        const options = { method: 'post', path: '/embeddings', body: { input: 'hello' } } as FinalRequestOptions;
+        await client.callPrepareOptions(options);
+        expect(options.body).to.deep.equal({ input: 'hello' });
+    });
+
+    it('replaces the null refusal of an assistant tool call with undefined', async () => {
+        const options = {
+            method: 'post',
+            path: '/chat/completions',
+            body: {
+                messages: [
+                    // eslint-disable-next-line no-null/no-null
+                    { role: 'assistant', tool_calls: [{ id: 't1' }], refusal: null, parsed: null }
+                ]
+            }
+        } as FinalRequestOptions;
+        await client.callPrepareOptions(options);
+        const message = (options.body as { messages: Array<Record<string, unknown>> }).messages[0];
+        expect(message.refusal).to.equal(undefined);
+        expect(message.parsed).to.equal(undefined);
+    });
+});
+
 describe('OpenAiModelUtils Chat Completions processMessages', () => {
     it('drops a CompactionMessage without throwing when useResponseApi is off', () => {
         const utils = new OpenAiModelUtils();

package/src/node/openai-language-model.ts

@@ -30,7 +30,7 @@ import {
     ServerToolDescriptor,
     formatToolCallContentForModel
 } from '@theia/ai-core';
-import { CancellationToken } from '@theia/core';
+import { CancellationToken, isObject } from '@theia/core';
 import { injectable } from '@theia/core/shared/inversify';
 import { OpenAI, AzureOpenAI } from 'openai';
 import { ChatCompletionStream } from 'openai/lib/ChatCompletionStream';
@@ -46,9 +46,11 @@ import { createProxyFetch } from '@theia/ai-core/lib/node';
 
 export class MistralFixedOpenAI extends OpenAI {
     protected override async prepareOptions(options: FinalRequestOptions): Promise<void> {
-        const messages = (options.body as { messages: Array<ChatCompletionMessageParam> }).messages;
+        // Every request the client issues passes through here, including the body-less `GET /models`
+        // that model discovery runs, so the body cannot be assumed to exist, let alone to carry messages.
+        const messages = (options.body as { messages?: Array<ChatCompletionMessageParam> } | undefined)?.messages;
         if (Array.isArray(messages)) {
-            (options.body as { messages: Array<ChatCompletionMessageParam> }).messages.forEach(m => {
+            messages.forEach(m => {
                 if (m.role === 'assistant' && m.tool_calls) {
                     // Mistral OpenAI Endpoint expects refusal to be undefined and not null for optional properties
                     // eslint-disable-next-line no-null/no-null
@@ -71,6 +73,36 @@ export const OpenAiModelIdentifier = Symbol('OpenAiModelIdentifier');
 
 export type DeveloperMessageSettings = 'user' | 'system' | 'developer' | 'mergeWithFollowingUserMessage' | 'skip';
 
+/** Options for {@link createOpenAiClient}. */
+export interface OpenAiClientOptions {
+    /** The key to authenticate with. A custom endpoint may need none. */
+    readonly apiKey: string | undefined;
+    /** Base URL of a custom endpoint; the SDK's own default is used without one. */
+    readonly baseURL?: string;
+    /** Azure API version. Its presence is what selects the Azure client over the plain one. */
+    readonly apiVersion?: string;
+    readonly deployment?: string;
+    readonly proxyUrl?: string;
+    /** Additional HTTP headers sent with every request, e.g. headers required by a gateway in front of the API. */
+    readonly headers?: Record<string, string>;
+}
+
+/**
+ * The single place an OpenAI SDK client is built, so that a chat request and the model discovery
+ * reach the provider the same way: through the configured proxy, with a key the SDK accepts, and
+ * with the Azure client where an API version says so.
+ */
+export function createOpenAiClient(options: OpenAiClientOptions): OpenAI {
+    // The SDK refuses to be constructed without a key, so an endpoint that needs none still gets one.
+    const apiKey = options.apiKey ?? 'no-key';
+    const proxyFetch = createProxyFetch(options.proxyUrl);
+    return options.apiVersion
+        ? new AzureOpenAI({
+            apiKey, baseURL: options.baseURL, apiVersion: options.apiVersion, deployment: options.deployment, fetch: proxyFetch, defaultHeaders: options.headers
+        })
+        : new MistralFixedOpenAI({ apiKey, baseURL: options.baseURL, fetch: proxyFetch, defaultHeaders: options.headers });
+}
+
 export class OpenAiModel implements LanguageModel {
 
     readonly vendor = 'openai';
@@ -119,15 +151,24 @@ export class OpenAiModel implements LanguageModel {
         public serverTools?: ServerToolDescriptor[],
         public serverSideCompactionSupport: boolean = false,
         public serverSideCompactionEnabledByDefault: boolean = false,
-        public serverSideCompactionTokenThresholdByDefault?: number
+        public serverSideCompactionTokenThresholdByDefault?: number,
+        public headers?: Record<string, string>,
+        public released?: number
     ) { }
 
-    /** Reasoning-level translation lives in {@link openAiReasoningFor}. */
+    /**
+     * Reasoning-level translation lives in {@link openAiReasoningFor}. On the Responses API, user-configured `reasoning`
+     * fields from the request settings (e.g. `summary`) are kept; the selected level still decides `effort`.
+     */
     protected getSettings(request: LanguageModelRequest, forResponseApi: boolean = false): Record<string, unknown> {
-        return {
-            ...request.settings,
-            ...openAiReasoningFor(request.reasoning?.level, forResponseApi, !!this.reasoningSupport)
-        };
+        const reasoning = openAiReasoningFor(request.reasoning?.level, forResponseApi, !!this.reasoningSupport);
+        const ours = reasoning.reasoning;
+        const theirs = request.settings?.reasoning;
+        if (isObject(ours) && isObject(theirs)) {
+            const effort = (ours as { effort?: string }).effort;
+            return { ...request.settings, reasoning: { ...ours, ...theirs, ...(effort !== undefined && { effort }) } };
+        }
+        return { ...request.settings, ...reasoning };
     }
 
     async request(request: UserRequest, cancellationToken?: CancellationToken): Promise<LanguageModelResponse> {
@@ -247,17 +288,14 @@ export class OpenAiModel implements LanguageModel {
             throw new Error('Please provide OPENAI_API_KEY in preferences or via environment variable');
         }
 
-        const apiVersion = this.apiVersion();
-        // We need to hand over "some" key, even if a custom url is not key protected as otherwise the OpenAI client will throw an error
-        const key = apiKey ?? 'no-key';
-
-        const proxyFetch = createProxyFetch(this.proxy);
-
-        if (apiVersion) {
-            return new AzureOpenAI({ apiKey: key, baseURL: this.url, apiVersion: apiVersion, deployment: this.deployment, fetch: proxyFetch });
-        } else {
-            return new MistralFixedOpenAI({ apiKey: key, baseURL: this.url, fetch: proxyFetch });
-        }
+        return createOpenAiClient({
+            apiKey,
+            baseURL: this.url,
+            apiVersion: this.apiVersion(),
+            deployment: this.deployment,
+            proxyUrl: this.proxy,
+            headers: this.headers
+        });
     }
 
     /**