From 56faf01da68de436195b8a51b65ea0868093d2bf Mon Sep 17 00:00:00 2001 From: KO Ho Tin Date: Sun, 26 Jul 2026 17:01:24 +0800 Subject: [PATCH 1/3] fix(agent-core): only send prompt_cache_key to the official OpenAI endpoint Since 0.29.0 every OpenAI-compatible provider received the session prompt_cache_key in the request body. Strictly-validating endpoints reject the unknown parameter with a 400, breaking custom providers. Gate the field on the effective base URL targeting api.openai.com (or being unset, which the client defaults there), in both the v1 provider config resolution and the v2 OpenAI chat-completions/responses bases. Vendors that support the field (e.g. Kimi) keep encoding it through their own branch or cacheKey trait hook. Fixes #2166 --- .../prompt-cache-key-official-openai-only.md | 5 ++ .../provider/bases/openai/openai-common.ts | 17 +++++ .../provider/bases/openai/openai-legacy.ts | 10 ++- .../provider/bases/openai/openai-responses.ts | 7 +- .../test/kosong/provider/composition.test.ts | 30 +++++++++ .../src/session/provider-manager.ts | 49 ++++++++++---- .../test/harness/runtime-provider.test.ts | 65 +++++++++++++++++++ 7 files changed, 169 insertions(+), 14 deletions(-) create mode 100644 .changeset/prompt-cache-key-official-openai-only.md diff --git a/.changeset/prompt-cache-key-official-openai-only.md b/.changeset/prompt-cache-key-official-openai-only.md new file mode 100644 index 00000000000..0b0f429fb25 --- /dev/null +++ b/.changeset/prompt-cache-key-official-openai-only.md @@ -0,0 +1,5 @@ +--- +"@moonshot-ai/kimi-code": patch +--- + +Stop sending the OpenAI prompt cache key to custom OpenAI-compatible endpoints, which reject the unknown field with a 400 error; the key is still sent to the official OpenAI API. diff --git a/packages/agent-core-v2/src/kosong/provider/bases/openai/openai-common.ts b/packages/agent-core-v2/src/kosong/provider/bases/openai/openai-common.ts index 68eed46d317..ff1fd54a333 100644 --- a/packages/agent-core-v2/src/kosong/provider/bases/openai/openai-common.ts +++ b/packages/agent-core-v2/src/kosong/provider/bases/openai/openai-common.ts @@ -262,3 +262,20 @@ export function isOpenAIReasoningModel(normalizedModelName: string): boolean { export function hasModelPrefix(modelName: string, prefixes: readonly string[]): boolean { return prefixes.some((prefix) => modelName.startsWith(prefix)); } + +/** + * `prompt_cache_key` is an official-OpenAI request field: strictly-validating + * OpenAI-compatible endpoints reject unknown parameters with a 400, so the + * bases only fall back to it when the effective base URL targets + * `api.openai.com` (or is unset, which the client defaults there). + */ +export function isOfficialOpenAIBaseUrl(baseUrl: string | undefined): boolean { + if (baseUrl === undefined) { + return true; + } + try { + return new URL(baseUrl).hostname === 'api.openai.com'; + } catch { + return false; + } +} diff --git a/packages/agent-core-v2/src/kosong/provider/bases/openai/openai-legacy.ts b/packages/agent-core-v2/src/kosong/provider/bases/openai/openai-legacy.ts index 7c7215005a1..484a3ae452e 100644 --- a/packages/agent-core-v2/src/kosong/provider/bases/openai/openai-legacy.ts +++ b/packages/agent-core-v2/src/kosong/provider/bases/openai/openai-legacy.ts @@ -60,6 +60,7 @@ import { extractUsage, hasModelPrefix, isFunctionToolCall, + isOfficialOpenAIBaseUrl, isOpenAIReasoningModel, normalizeOpenAIFinishReason, OPENAI_REASONING_CAPABILITY, @@ -704,7 +705,14 @@ export class OpenAILegacyChatProvider implements ChatProvider { if (options?.cacheKey !== undefined) { const hooked = this._hooks?.cacheKey?.(options.cacheKey); - kwargs = { ...kwargs, ...(hooked ?? { prompt_cache_key: options.cacheKey }) }; + if (hooked !== undefined) { + kwargs = { ...kwargs, ...hooked }; + } else if (isOfficialOpenAIBaseUrl(this._baseUrl)) { + // The bare `prompt_cache_key` fallback is official-OpenAI only: + // strictly-validating compatible endpoints 400 on unknown fields + // (#2166); vendors that support it encode it via their cacheKey hook. + kwargs = { ...kwargs, prompt_cache_key: options.cacheKey }; + } } if (options?.sampling?.temperature !== undefined) { diff --git a/packages/agent-core-v2/src/kosong/provider/bases/openai/openai-responses.ts b/packages/agent-core-v2/src/kosong/provider/bases/openai/openai-responses.ts index dfb482f2dd2..8ef9a0077ac 100644 --- a/packages/agent-core-v2/src/kosong/provider/bases/openai/openai-responses.ts +++ b/packages/agent-core-v2/src/kosong/provider/bases/openai/openai-responses.ts @@ -41,6 +41,7 @@ import { convertOpenAIError, hasModelPrefix, isMediaPart, + isOfficialOpenAIBaseUrl, isOpenAIReasoningModel, OPENAI_REASONING_CAPABILITY, OPENAI_VISION_TOOL_CAPABILITY, @@ -1059,8 +1060,10 @@ export class OpenAIResponsesChatProvider implements ChatProvider { let kwargs: Record = { ...this._generationKwargs }; - // Per-turn intent overlays in the fixed contract order. - if (options?.cacheKey !== undefined) { + // Per-turn intent overlays in the fixed contract order. The + // `prompt_cache_key` overlay is official-OpenAI only: strictly-validating + // compatible endpoints reject unknown fields with a 400 (#2166). + if (options?.cacheKey !== undefined && isOfficialOpenAIBaseUrl(this._baseUrl)) { kwargs = { ...kwargs, prompt_cache_key: options.cacheKey }; } if (options?.sampling?.temperature !== undefined) { diff --git a/packages/agent-core-v2/test/kosong/provider/composition.test.ts b/packages/agent-core-v2/test/kosong/provider/composition.test.ts index 331281ef5ab..8d9ca3a1d15 100644 --- a/packages/agent-core-v2/test/kosong/provider/composition.test.ts +++ b/packages/agent-core-v2/test/kosong/provider/composition.test.ts @@ -700,6 +700,36 @@ describe('per-turn intent wire encoding (behavior probes)', () => { expect(body['prompt_cache_key']).toBe('session-probe'); }); + it('omits prompt_cache_key on OpenAI-compatible custom endpoints (chat completions + responses)', async () => { + // Strictly-validating OpenAI-compatible servers reject the unknown + // `prompt_cache_key` field with a 400, so the bare fallback stays + // official-endpoint only (#2166). + const legacy = registry.createChatProvider({ + protocol: 'openai', + modelName: 'gpt-4o', + apiKey: 'sk-probe', + baseUrl: 'https://openai-compatible.example.test/v1', + }); + const legacyBody = await captureOpenAIBody(legacy, { cacheKey: 'session-probe' }); + expect(legacyBody).not.toHaveProperty('prompt_cache_key'); + + const responses = new OpenAIResponsesChatProvider({ + model: 'gpt-4.1', + apiKey: 'sk-probe', + baseUrl: 'https://openai-compatible.example.test/v1', + }); + const responsesBody = await captureResponsesBody(responses, { cacheKey: 'session-probe' }); + expect(responsesBody).not.toHaveProperty('prompt_cache_key'); + }); + + it('keeps prompt_cache_key on the official OpenAI Responses endpoint', async () => { + const provider = new OpenAIResponsesChatProvider({ model: 'gpt-4.1', apiKey: 'sk-probe' }); + + const body = await captureResponsesBody(provider, { cacheKey: 'session-probe' }); + + expect(body['prompt_cache_key']).toBe('session-probe'); + }); + it('encodes cacheKey on Anthropic as metadata.user_id', async () => { const provider = registry.createChatProvider({ protocol: 'anthropic', diff --git a/packages/agent-core/src/session/provider-manager.ts b/packages/agent-core/src/session/provider-manager.ts index e8028c76c19..5dcb464e10d 100644 --- a/packages/agent-core/src/session/provider-manager.ts +++ b/packages/agent-core/src/session/provider-manager.ts @@ -303,28 +303,34 @@ function toKosongProviderConfig( ), }; } - case 'openai': + case 'openai': { + // A per-model endpoint (catalog gateway override) wins over the + // provider-level base URL, same as the Anthropic branch. + const baseUrl = + modelBaseUrl ?? providerValue(provider.baseUrl, provider.env, 'OPENAI_BASE_URL'); return { type: 'openai', model, - // A per-model endpoint (catalog gateway override) wins over the - // provider-level base URL, same as the Anthropic branch. - baseUrl: - modelBaseUrl ?? providerValue(provider.baseUrl, provider.env, 'OPENAI_BASE_URL'), + baseUrl, apiKey: providerApiKey(provider), reasoningKey, offEffort, // Session affinity: route every request of this session through the // same provider-side prompt cache (the OpenAI analog of Anthropic // `metadata.user_id` above). Undefined values are stripped at - // generate time, matching the `kimi` branch below. - generationKwargs: { prompt_cache_key: promptCacheKey }, + // generate time, matching the `kimi` branch below. Official-endpoint + // only: strictly-validating OpenAI-compatible servers reject the + // unknown `prompt_cache_key` field with a 400 (#2166). + generationKwargs: { + prompt_cache_key: isOfficialOpenAIBaseUrl(baseUrl) ? promptCacheKey : undefined, + }, ...defaultHeadersField({ ...envCustomHeaders, ...kimiUserAgentHeader(kimiRequestHeaders), ...provider.customHeaders, }), }; + } case 'kimi': return { type: 'kimi', @@ -351,23 +357,27 @@ function toKosongProviderConfig( ...provider.customHeaders, }), }; - case 'openai_responses': + case 'openai_responses': { + const baseUrl = + modelBaseUrl ?? providerValue(provider.baseUrl, provider.env, 'OPENAI_BASE_URL'); return { type: 'openai_responses', model, - baseUrl: - modelBaseUrl ?? providerValue(provider.baseUrl, provider.env, 'OPENAI_BASE_URL'), + baseUrl, apiKey: providerApiKey(provider), offEffort, // Session affinity: same `prompt_cache_key` intent as the `openai` // branch; the Responses API accepts it as a top-level request field. - generationKwargs: { prompt_cache_key: promptCacheKey }, + generationKwargs: { + prompt_cache_key: isOfficialOpenAIBaseUrl(baseUrl) ? promptCacheKey : undefined, + }, ...defaultHeadersField({ ...envCustomHeaders, ...kimiUserAgentHeader(kimiRequestHeaders), ...provider.customHeaders, }), }; + } case 'vertexai': { // Resolve the effective endpoint once (config `base_url` or the // GOOGLE_VERTEX_BASE_URL env fallback) and use it for BOTH forwarding and @@ -467,6 +477,23 @@ function vertexAILocation( return envValue(provider.env, 'GOOGLE_CLOUD_LOCATION') ?? locationFromVertexAIBaseUrl(baseUrl); } +/** + * `prompt_cache_key` is an official-OpenAI request field: strictly-validating + * OpenAI-compatible endpoints reject unknown parameters with a 400, so session + * cache affinity is only requested when the effective base URL targets + * `api.openai.com` (or is unset, which the transport defaults there). + */ +function isOfficialOpenAIBaseUrl(baseUrl: string | undefined): boolean { + if (baseUrl === undefined) { + return true; + } + try { + return new URL(baseUrl).hostname === 'api.openai.com'; + } catch { + return false; + } +} + function providerValue( configured: string | undefined, env: Record | undefined, diff --git a/packages/agent-core/test/harness/runtime-provider.test.ts b/packages/agent-core/test/harness/runtime-provider.test.ts index 1d209032348..1c61bebebb7 100644 --- a/packages/agent-core/test/harness/runtime-provider.test.ts +++ b/packages/agent-core/test/harness/runtime-provider.test.ts @@ -968,6 +968,71 @@ describe('ProviderManager prompt cache key', () => { } }); + it('omits the prompt cache key for OpenAI providers on custom base URLs', () => { + for (const type of ['openai', 'openai_responses'] as const) { + const manager = new ProviderManager({ + promptCacheKey: 'session-test', + config: { + defaultModel: 'gpt-alias', + providers: { + openai: { + type, + apiKey: 'sk-compat', + baseUrl: 'https://openai-compatible.example.test/v1', + }, + }, + models: { + 'gpt-alias': { + provider: 'openai', + model: 'gpt-runtime', + maxContextSize: 200000, + }, + }, + }, + }); + const resolved = manager.resolveProviderConfig('gpt-alias'); + + // Strictly-validating OpenAI-compatible endpoints reject the unknown + // `prompt_cache_key` field with a 400, so it must stay official-only. + const kwargs = (resolved.provider as { generationKwargs?: Record }) + .generationKwargs; + expect(kwargs?.['prompt_cache_key']).toBeUndefined(); + } + }); + + it('keeps the prompt cache key when the base URL targets the official OpenAI API', () => { + for (const type of ['openai', 'openai_responses'] as const) { + const manager = new ProviderManager({ + promptCacheKey: 'session-test', + config: { + defaultModel: 'gpt-alias', + providers: { + openai: { + type, + apiKey: 'sk-openai', + baseUrl: 'https://api.openai.com/v1', + }, + }, + models: { + 'gpt-alias': { + provider: 'openai', + model: 'gpt-runtime', + maxContextSize: 200000, + }, + }, + }, + }); + const resolved = manager.resolveProviderConfig('gpt-alias'); + + expect(resolved.provider).toMatchObject({ + type, + generationKwargs: { + prompt_cache_key: 'session-test', + }, + }); + } + }); + it('reads the current config when constructed with a function', () => { let sharedConfig: KimiConfig = { providers: {} }; const manager = new ProviderManager({ From a8295aca533e07d4e0a3a1084a066fa07b5a56fc Mon Sep 17 00:00:00 2001 From: KO Ho Tin Date: Sun, 26 Jul 2026 17:38:59 +0800 Subject: [PATCH 2/3] fix(agent-core): treat regional OpenAI endpoints as official for prompt cache affinity Data-residency endpoints (eu.api.openai.com, us.api.openai.com) are official OpenAI hosts and accept prompt_cache_key; match any *.api.openai.com hostname instead of the apex only. --- .../src/kosong/provider/bases/openai/openai-common.ts | 6 ++++-- packages/agent-core/src/session/provider-manager.ts | 6 ++++-- packages/agent-core/test/harness/runtime-provider.test.ts | 8 ++++++-- 3 files changed, 14 insertions(+), 6 deletions(-) diff --git a/packages/agent-core-v2/src/kosong/provider/bases/openai/openai-common.ts b/packages/agent-core-v2/src/kosong/provider/bases/openai/openai-common.ts index ff1fd54a333..0098b6dc8f5 100644 --- a/packages/agent-core-v2/src/kosong/provider/bases/openai/openai-common.ts +++ b/packages/agent-core-v2/src/kosong/provider/bases/openai/openai-common.ts @@ -267,14 +267,16 @@ export function hasModelPrefix(modelName: string, prefixes: readonly string[]): * `prompt_cache_key` is an official-OpenAI request field: strictly-validating * OpenAI-compatible endpoints reject unknown parameters with a 400, so the * bases only fall back to it when the effective base URL targets - * `api.openai.com` (or is unset, which the client defaults there). + * `api.openai.com` or a regional variant like `eu.api.openai.com` (or is + * unset, which the client defaults there). */ export function isOfficialOpenAIBaseUrl(baseUrl: string | undefined): boolean { if (baseUrl === undefined) { return true; } try { - return new URL(baseUrl).hostname === 'api.openai.com'; + const hostname = new URL(baseUrl).hostname; + return hostname === 'api.openai.com' || hostname.endsWith('.api.openai.com'); } catch { return false; } diff --git a/packages/agent-core/src/session/provider-manager.ts b/packages/agent-core/src/session/provider-manager.ts index 5dcb464e10d..7a3ae6a0eeb 100644 --- a/packages/agent-core/src/session/provider-manager.ts +++ b/packages/agent-core/src/session/provider-manager.ts @@ -481,14 +481,16 @@ function vertexAILocation( * `prompt_cache_key` is an official-OpenAI request field: strictly-validating * OpenAI-compatible endpoints reject unknown parameters with a 400, so session * cache affinity is only requested when the effective base URL targets - * `api.openai.com` (or is unset, which the transport defaults there). + * `api.openai.com` or a regional variant like `eu.api.openai.com` (or is + * unset, which the transport defaults there). */ function isOfficialOpenAIBaseUrl(baseUrl: string | undefined): boolean { if (baseUrl === undefined) { return true; } try { - return new URL(baseUrl).hostname === 'api.openai.com'; + const hostname = new URL(baseUrl).hostname; + return hostname === 'api.openai.com' || hostname.endsWith('.api.openai.com'); } catch { return false; } diff --git a/packages/agent-core/test/harness/runtime-provider.test.ts b/packages/agent-core/test/harness/runtime-provider.test.ts index 1c61bebebb7..a06e13c100f 100644 --- a/packages/agent-core/test/harness/runtime-provider.test.ts +++ b/packages/agent-core/test/harness/runtime-provider.test.ts @@ -1001,7 +1001,11 @@ describe('ProviderManager prompt cache key', () => { }); it('keeps the prompt cache key when the base URL targets the official OpenAI API', () => { - for (const type of ['openai', 'openai_responses'] as const) { + for (const [type, baseUrl] of [ + ['openai', 'https://api.openai.com/v1'], + ['openai_responses', 'https://api.openai.com/v1'], + ['openai', 'https://eu.api.openai.com/v1'], + ] as const) { const manager = new ProviderManager({ promptCacheKey: 'session-test', config: { @@ -1010,7 +1014,7 @@ describe('ProviderManager prompt cache key', () => { openai: { type, apiKey: 'sk-openai', - baseUrl: 'https://api.openai.com/v1', + baseUrl, }, }, models: { From e50f3ebe50059d076bd34f23762c4a1e5a5a09a0 Mon Sep 17 00:00:00 2001 From: KO Ho Tin Date: Sun, 26 Jul 2026 17:51:55 +0800 Subject: [PATCH 3/3] docs(agent-core-v2): keep endpoint-gate commentary in module headers The package convention allows comments only in the top-of-file block; move the prompt_cache_key gating notes there. --- .../kosong/provider/bases/openai/openai-common.ts | 15 +++++++-------- .../kosong/provider/bases/openai/openai-legacy.ts | 6 +++--- .../provider/bases/openai/openai-responses.ts | 11 +++++------ .../test/kosong/provider/composition.test.ts | 3 --- 4 files changed, 15 insertions(+), 20 deletions(-) diff --git a/packages/agent-core-v2/src/kosong/provider/bases/openai/openai-common.ts b/packages/agent-core-v2/src/kosong/provider/bases/openai/openai-common.ts index 0098b6dc8f5..511e3ff7933 100644 --- a/packages/agent-core-v2/src/kosong/provider/bases/openai/openai-common.ts +++ b/packages/agent-core-v2/src/kosong/provider/bases/openai/openai-common.ts @@ -3,7 +3,13 @@ * * Everything the Chat Completions and Responses bases share: content-part and * tool conversion, usage extraction, finish-reason normalization, the - * capability constants, and the error converter. + * capability constants, the error converter, and the official-endpoint gate + * for the OpenAI-only `prompt_cache_key` request field + * (`isOfficialOpenAIBaseUrl`): the bases only fall back to that field when + * the effective base URL targets `api.openai.com` or a regional + * `*.api.openai.com` variant (or is unset, which the client defaults there), + * because strictly-validating OpenAI-compatible endpoints reject unknown + * parameters with a 400. * * `convertOpenAIError`'s FIRST line is the contract's `throwIfAbortError` * guard: a user cancellation (SDK `APIUserAbortError`, bare `AbortError`, the @@ -263,13 +269,6 @@ export function hasModelPrefix(modelName: string, prefixes: readonly string[]): return prefixes.some((prefix) => modelName.startsWith(prefix)); } -/** - * `prompt_cache_key` is an official-OpenAI request field: strictly-validating - * OpenAI-compatible endpoints reject unknown parameters with a 400, so the - * bases only fall back to it when the effective base URL targets - * `api.openai.com` or a regional variant like `eu.api.openai.com` (or is - * unset, which the client defaults there). - */ export function isOfficialOpenAIBaseUrl(baseUrl: string | undefined): boolean { if (baseUrl === undefined) { return true; diff --git a/packages/agent-core-v2/src/kosong/provider/bases/openai/openai-legacy.ts b/packages/agent-core-v2/src/kosong/provider/bases/openai/openai-legacy.ts index 484a3ae452e..d790949796c 100644 --- a/packages/agent-core-v2/src/kosong/provider/bases/openai/openai-legacy.ts +++ b/packages/agent-core-v2/src/kosong/provider/bases/openai/openai-legacy.ts @@ -9,6 +9,9 @@ * * Per-turn intent assembly (`_resolveRequestKwargs`) applies overlays in the * fixed contract order: cacheKey → sampling → thinking → maxCompletionTokens. + * The bare `prompt_cache_key` cacheKey fallback is gated by + * `isOfficialOpenAIBaseUrl`; vendors that support the field on other hosts + * encode it through their `cacheKey` hook. * The context-window clamp on the completion budget (floor 1) runs BEFORE any * hook and cannot be skipped; the 128k ceiling clamp can be taken over by the * `withMaxCompletionTokens` hook. @@ -708,9 +711,6 @@ export class OpenAILegacyChatProvider implements ChatProvider { if (hooked !== undefined) { kwargs = { ...kwargs, ...hooked }; } else if (isOfficialOpenAIBaseUrl(this._baseUrl)) { - // The bare `prompt_cache_key` fallback is official-OpenAI only: - // strictly-validating compatible endpoints 400 on unknown fields - // (#2166); vendors that support it encode it via their cacheKey hook. kwargs = { ...kwargs, prompt_cache_key: options.cacheKey }; } } diff --git a/packages/agent-core-v2/src/kosong/provider/bases/openai/openai-responses.ts b/packages/agent-core-v2/src/kosong/provider/bases/openai/openai-responses.ts index 8ef9a0077ac..c7b3dd22b50 100644 --- a/packages/agent-core-v2/src/kosong/provider/bases/openai/openai-responses.ts +++ b/packages/agent-core-v2/src/kosong/provider/bases/openai/openai-responses.ts @@ -4,9 +4,10 @@ * Speaks the Responses wire format: `input` items, `instructions`, * `reasoning` blocks with encrypted content, and the native * `prompt_cache_key` field (a cache key is encoded directly — no hook - * needed). This base carries no hook surface today; per-turn intents are - * encoded inline in the fixed contract order. The developer-role model - * detection lives here. + * needed — and only for official `api.openai.com` hosts, via + * `isOfficialOpenAIBaseUrl`). This base carries no hook surface today; + * per-turn intents are encoded inline in the fixed contract order. The + * developer-role model detection lives here. */ import OpenAI from 'openai'; @@ -1060,9 +1061,7 @@ export class OpenAIResponsesChatProvider implements ChatProvider { let kwargs: Record = { ...this._generationKwargs }; - // Per-turn intent overlays in the fixed contract order. The - // `prompt_cache_key` overlay is official-OpenAI only: strictly-validating - // compatible endpoints reject unknown fields with a 400 (#2166). + // Per-turn intent overlays in the fixed contract order. if (options?.cacheKey !== undefined && isOfficialOpenAIBaseUrl(this._baseUrl)) { kwargs = { ...kwargs, prompt_cache_key: options.cacheKey }; } diff --git a/packages/agent-core-v2/test/kosong/provider/composition.test.ts b/packages/agent-core-v2/test/kosong/provider/composition.test.ts index 8d9ca3a1d15..67b92a648dc 100644 --- a/packages/agent-core-v2/test/kosong/provider/composition.test.ts +++ b/packages/agent-core-v2/test/kosong/provider/composition.test.ts @@ -701,9 +701,6 @@ describe('per-turn intent wire encoding (behavior probes)', () => { }); it('omits prompt_cache_key on OpenAI-compatible custom endpoints (chat completions + responses)', async () => { - // Strictly-validating OpenAI-compatible servers reject the unknown - // `prompt_cache_key` field with a 400, so the bare fallback stays - // official-endpoint only (#2166). const legacy = registry.createChatProvider({ protocol: 'openai', modelName: 'gpt-4o',