From d2149bdca48ac677cb85d7bd5e0d23b186155e4d 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 0000000000..0b0f429fb2 --- /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 d636c1cb1a..b0b5bdcd78 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 @@ -286,3 +286,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 78f94c7e58..058e11ce62 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, @@ -709,7 +710,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 20d24559cc..834effed3e 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 @@ -46,6 +46,7 @@ import { convertOpenAIError, hasModelPrefix, isMediaPart, + isOfficialOpenAIBaseUrl, isOpenAIInsufficientQuotaCode, isOpenAIReasoningModel, OPENAI_REASONING_CAPABILITY, @@ -1092,8 +1093,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 c7ebdb9feb..31784461a7 100644 --- a/packages/agent-core-v2/test/kosong/provider/composition.test.ts +++ b/packages/agent-core-v2/test/kosong/provider/composition.test.ts @@ -707,6 +707,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 7fb313b461..fc62c909ed 100644 --- a/packages/agent-core/src/session/provider-manager.ts +++ b/packages/agent-core/src/session/provider-manager.ts @@ -314,28 +314,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', @@ -362,23 +368,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 @@ -478,6 +488,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 96afbf4f15..838ce7f078 100644 --- a/packages/agent-core/test/harness/runtime-provider.test.ts +++ b/packages/agent-core/test/harness/runtime-provider.test.ts @@ -969,6 +969,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 34cade67b6bc73a04b95b4d00b0c67735305beb1 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 b0b5bdcd78..c5015b2fdc 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 @@ -291,14 +291,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 fc62c909ed..6dc2c376ac 100644 --- a/packages/agent-core/src/session/provider-manager.ts +++ b/packages/agent-core/src/session/provider-manager.ts @@ -492,14 +492,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 838ce7f078..6fe038ec89 100644 --- a/packages/agent-core/test/harness/runtime-provider.test.ts +++ b/packages/agent-core/test/harness/runtime-provider.test.ts @@ -1002,7 +1002,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: { @@ -1011,7 +1015,7 @@ describe('ProviderManager prompt cache key', () => { openai: { type, apiKey: 'sk-openai', - baseUrl: 'https://api.openai.com/v1', + baseUrl, }, }, models: { From 8e8f60155b24ad2293120b25958d49e296c62434 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 | 10 +++++----- .../test/kosong/provider/composition.test.ts | 3 --- 4 files changed, 15 insertions(+), 19 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 c5015b2fdc..e86c163832 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 @@ -287,13 +293,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 058e11ce62..2584ef91ba 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. @@ -713,9 +716,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 834effed3e..75dd692d1a 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,8 +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). Per-turn intents are encoded inline in the fixed contract order; - * the base's only hook surface is the trait-composed `convertError` option, + * needed — and only for official `api.openai.com` hosts, via + * `isOfficialOpenAIBaseUrl`). Per-turn intents are encoded inline in the + * fixed contract order; the base's only hook surface is the trait-composed + * `convertError` option, * consulted with each raw failure exactly once — the SDK error on HTTP * paths, the raw event on in-stream error paths — before the base's own * classification (already-converted errors crossing an outer catch pass @@ -1093,9 +1095,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 31784461a7..17a07e07bc 100644 --- a/packages/agent-core-v2/test/kosong/provider/composition.test.ts +++ b/packages/agent-core-v2/test/kosong/provider/composition.test.ts @@ -708,9 +708,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',