feat(kimi): forward prompt_cache_key on the Kimi Coding Plan presets (#597)

olddonkey · claude · web-flow · commit 0338b788fcb2 · 2026-07-28T07:43:31.000+02:00
* feat(kimi): forward prompt_cache_key on the Kimi Coding Plan presets Kimi's Chat Completions API documents prompt_cache_key as required for Kimi Code Plan cache hits (a stable session/task id, unchanged across exit and resume). Opt the canonical `kimi` OAuth and `kimi-code` API-key presets into the existing openai-chat forwarding flag so the caller-supplied key reaches https://api.kimi.com/coding/v1. The adapter never invents a key: it forwards what the internal request already carries (Codex's session key on /v1/responses, or the session-scoped key the Claude /v1/messages inbound derives), an absent field stays absent, and an explicit provider-level `promptCacheKey: false` still opts out. All other OpenAI-compatible presets remain deny-by-default because strict backends reject the OpenAI-specific field. Also persist the flag through providerConfigSeed / enrichProviderFromRegistry like the sibling scalars (parallelToolCalls, modelSuffixBracketStrip): key-pool 429 rotation rebuilds the provider from the persisted config rather than the routed one, so without seeding the retried request would silently drop the key on exactly the quota-sensitive turns that need affinity most. Evidence: https://platform.kimi.com/docs/api/chat Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> * Preserve Kimi prompt cache key on failover * fix(server): inherit routed provider config across 429 key rotation Generalize the promptCacheKey preservation from the previous commit: the narrow registry backfill in rotateProviderTransportOn429 covered only that one scalar, while every OTHER registry backfill routedProviderConfig merges at request time was still lost when the four 429-failover sites in src/server/responses/core.ts assigned the persisted-config snapshot to route.provider wholesale. Concretely: kimi-code's noTemperatureModels / modelReasoningEfforts / modelSuffixBracketStrip merges, NVIDIA NIM's parallelToolCalls: false, and a registry-pinned baseUrl all silently reverted on the rotated retry and later continuations in the turn. rotateProviderTransportOn429 now takes the request's routed provider and swaps ONLY the API key onto it before re-applying transport metadata, mirroring the OAuth-401 replay path (which already spreads route.provider). The registry lookup becomes unnecessary and is removed. Other failover paths were audited and are sound: Codex multi-account retry strips runtime fields off route.provider, and the Anthropic account pool spreads route.provider directly. Regression coverage: the existing Kimi unit test keeps asserting the wire body on both attempts; a new unit test proves arbitrary registry-backfilled fields survive rotation; a new e2e test on the kimi-code preset asserts prompt_cache_key is present on BOTH the initial attempt and the post-rotation retry (verified to fail against the pre-fix behavior). Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> --------- Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
diff --git a/docs-site/src/content/docs/guides/providers.md b/docs-site/src/content/docs/guides/providers.md
@@ -90,6 +90,13 @@ ocx logout <provider>
 | `cursor` | `cursor` | `https://api2.cursor.sh` | Experimental PKCE login, live HTTP/2 transport, and account-filtered model discovery. |
 | `github-copilot` | `openai-chat` | `https://api.githubcopilot.com` | Experimental. GitHub device flow + `copilot_internal` exchange (VS Code OAuth client). Requires an active Copilot subscription; not an official third-party API. |
 
+For the canonical Kimi Coding Plan presets (`kimi` account login and `kimi-code` API key),
+opencodex forwards only a caller-supplied stable `prompt_cache_key` to the Chat Completions request;
+it never generates one. Kimi documents a stable session/task key as required to improve Code Plan
+cache hit rates, while requests without a key remain keyless. If an opted-in upstream rejects the
+field, opencodex does not strip it and retry or mutate saved configuration. Other providers remain
+deny-by-default.
+
 You can also start OAuth from the [web dashboard](/guides/web-dashboard/).
 
 ### Multiple OAuth accounts
diff --git a/docs-site/src/content/docs/ja/guides/providers.md b/docs-site/src/content/docs/ja/guides/providers.md
@@ -84,6 +84,13 @@ ocx logout <provider>
 | `google-antigravity` | `google` | `https://daily-cloudcode-pa.googleapis.com` | Google OAuth を Cloud Code Assist wire で使用。 |
 | `cursor` | `cursor` | `https://api2.cursor.sh` | 実験的 PKCE ログイン、HTTP/2 トランスポート、アカウント別モデル探索をサポート。 |
 
+正規の Kimi Coding Plan プリセット（`kimi` アカウントログインと `kimi-code` API key）では、
+opencodex は呼び出し元が指定した安定した `prompt_cache_key` だけを Chat Completions リクエストへ
+転送し、自ら生成しません。Kimi のドキュメントでは、Code Plan のキャッシュヒット率を高めるために
+安定したセッション/タスク key が必須とされています。key のないリクエストは keyless のままです。
+opt-in した上流がこのフィールドを拒否しても、opencodex はフィールドを削除して再試行したり、保存済み
+設定を変更したりしません。他のプロバイダーは deny-by-default のままです。
+
 [ウェブダッシュボード](/ja/guides/web-dashboard/)からも OAuth を開始できます。
 
 ### 複数の OAuth アカウント
diff --git a/docs-site/src/content/docs/ko/guides/providers.md b/docs-site/src/content/docs/ko/guides/providers.md
@@ -84,6 +84,13 @@ ocx logout <provider>
 | `google-antigravity` | `google` | `https://daily-cloudcode-pa.googleapis.com` | Google OAuth를 Cloud Code Assist wire로 사용합니다. |
 | `cursor` | `cursor` | `https://api2.cursor.sh` | 실험적 PKCE 로그인, HTTP/2 전송, 계정별 모델 탐색을 지원합니다. |
 
+정식 Kimi Coding Plan 프리셋(`kimi` 계정 로그인과 `kimi-code` API key)의 경우, opencodex는
+호출자가 제공한 안정적인 `prompt_cache_key`만 Chat Completions 요청으로 전달하며 직접 생성하지
+않습니다. Kimi 문서는 Code Plan 캐시 적중률을 높이기 위해 안정적인 세션/작업 key가 필요하다고
+명시합니다. key가 없는 요청은 keyless 상태로 유지됩니다. opt-in한 업스트림이 이 필드를 거부해도
+opencodex는 필드를 제거해 재시도하거나 저장된 설정을 변경하지 않습니다. 다른 프로바이더는
+deny-by-default 상태로 유지됩니다.
+
 [웹 대시보드](/ko/guides/web-dashboard/)에서도 OAuth를 시작할 수 있습니다.
 
 ### 여러 OAuth 계정
diff --git a/docs-site/src/content/docs/ru/guides/providers.md b/docs-site/src/content/docs/ru/guides/providers.md
@@ -93,6 +93,13 @@ ocx logout <provider>
 | `cursor` | `cursor` | `https://api2.cursor.sh` | Экспериментальный PKCE-вход, живой транспорт HTTP/2 и обнаружение моделей с фильтрацией по аккаунту. |
 | `github-copilot` | `openai-chat` | `https://api.githubcopilot.com` | Экспериментально. Device flow GitHub + обмен `copilot_internal` (OAuth-клиент VS Code). Требуется активная подписка Copilot; это не официальный сторонний API. |
 
+Для канонических пресетов Kimi Coding Plan (вход через аккаунт `kimi` и API-ключ `kimi-code`)
+opencodex передаёт в запрос Chat Completions только стабильный `prompt_cache_key`, предоставленный
+вызывающей стороной, и никогда не создаёт его сам. Документация Kimi требует стабильный ключ
+сессии/задачи для повышения доли попаданий в кэш Code Plan; запрос без ключа остаётся без ключа.
+Если включённый провайдер отклоняет поле, opencodex не удаляет его для повторной попытки и не
+изменяет сохранённую конфигурацию. Для остальных провайдеров действует deny-by-default.
+
 OAuth можно запустить и из [веб-дашборда](/ru/guides/web-dashboard/).
 
 ### Несколько OAuth-аккаунтов
diff --git a/docs-site/src/content/docs/zh-cn/guides/providers.md b/docs-site/src/content/docs/zh-cn/guides/providers.md
@@ -78,6 +78,12 @@ ocx logout <provider>
 | `google-antigravity` | `google` | `https://daily-cloudcode-pa.googleapis.com` | 通过 Cloud Code Assist 协议使用 Google OAuth。 |
 | `cursor` | `cursor` | `https://api2.cursor.sh` | 实验性 PKCE 登录、HTTP/2 传输和按账号筛选的模型发现。 |
 
+对于规范的 Kimi Coding Plan 预设（`kimi` 账号登录和 `kimi-code` API key），opencodex
+只会把调用方提供的稳定 `prompt_cache_key` 转发到 Chat Completions 请求，绝不自行生成。Kimi
+文档要求使用稳定的会话/任务 key 来提高 Code Plan 缓存命中率；没有 key 的请求仍保持不带 key。
+若已 opt-in 的上游拒绝该字段，opencodex 不会删除字段后重试，也不会改动已保存配置；其他
+provider 仍保持 deny-by-default。
+
 你也可以从 [web 仪表盘](/zh-cn/guides/web-dashboard/) 启动 OAuth。
 
 ### 多个 OAuth 账号
diff --git a/src/providers/derive.ts b/src/providers/derive.ts
@@ -129,6 +129,7 @@ export function providerConfigSeed(entry: ProviderRegistryEntry): OcxProviderCon
     ...(entry.noTopPModels ? { noTopPModels: [...entry.noTopPModels] } : {}),
     ...(entry.noPenaltyModels ? { noPenaltyModels: [...entry.noPenaltyModels] } : {}),
     ...(entry.parallelToolCalls !== undefined ? { parallelToolCalls: entry.parallelToolCalls } : {}),
+    ...(entry.promptCacheKey !== undefined ? { promptCacheKey: entry.promptCacheKey } : {}),
     ...(entry.autoToolChoiceOnlyModels ? { autoToolChoiceOnlyModels: [...entry.autoToolChoiceOnlyModels] } : {}),
     ...(entry.preserveReasoningContentModels ? { preserveReasoningContentModels: [...entry.preserveReasoningContentModels] } : {}),
     ...(entry.reasoningSplitModels ? { reasoningSplitModels: [...entry.reasoningSplitModels] } : {}),
@@ -242,6 +243,7 @@ export function enrichProviderFromRegistry(name: string, prov: OcxProviderConfig
   if (!prov.noTopPModels && seed.noTopPModels) prov.noTopPModels = [...seed.noTopPModels];
   if (!prov.noPenaltyModels && seed.noPenaltyModels) prov.noPenaltyModels = [...seed.noPenaltyModels];
   if (prov.parallelToolCalls === undefined && seed.parallelToolCalls !== undefined) prov.parallelToolCalls = seed.parallelToolCalls;
+  if (prov.promptCacheKey === undefined && seed.promptCacheKey !== undefined) prov.promptCacheKey = seed.promptCacheKey;
   if (!prov.autoToolChoiceOnlyModels && seed.autoToolChoiceOnlyModels) prov.autoToolChoiceOnlyModels = [...seed.autoToolChoiceOnlyModels];
   if (!prov.preserveReasoningContentModels && seed.preserveReasoningContentModels) prov.preserveReasoningContentModels = [...seed.preserveReasoningContentModels];
   if (!prov.reasoningSplitModels && seed.reasoningSplitModels) prov.reasoningSplitModels = [...seed.reasoningSplitModels];
diff --git a/src/providers/key-failover.ts b/src/providers/key-failover.ts
@@ -10,7 +10,7 @@
  */
 import { saveConfigPreservingClaudeCode } from "../config";
 import type { OcxConfig, OcxProviderConfig } from "../types";
-import { resolveProviderTransport } from "./xai-transport";
+import { resolveProviderTransport, type OcxProviderTransport } from "./xai-transport";
 
 // ---- cooldown state (in-memory, same as codex/routing.ts) ----
 
@@ -69,6 +69,11 @@ export function hasKeyPoolFailover(provider: OcxProviderConfig): boolean {
  *
  * @returns A new OcxProviderConfig with the swapped key (and mutated config on disk),
  *          or `null` when no alternative key is available (all in cooldown or pool < 2).
+ *
+ * The returned object is a snapshot of the PERSISTED config — it carries none of the
+ * registry backfills `routedProviderConfig` merges in at request time. Request paths must
+ * not assign it to an active route wholesale; use `rotateProviderTransportOn429`, which
+ * takes only the swapped key and keeps the routed provider intact.
  */
 export function rotateKeyOn429(
   config: OcxConfig,
@@ -133,12 +138,23 @@ interface RotateProviderTransportOptions {
   promptCacheKey?: string;
 }
 
-/** Rotate a failed key and re-apply provider-specific transport metadata to the replacement. */
+/**
+ * Rotate a failed key and re-apply provider-specific transport metadata to the replacement.
+ *
+ * `routedProvider` is the request's active provider (the `routedProviderConfig` output the
+ * route was built with). The result inherits it and swaps ONLY the API key: the persisted
+ * config that `rotateKeyOn429` snapshots predates registry backfill, so building the retry
+ * provider from that snapshot would silently drop every field the registry merged in at
+ * routing time (scalar flags like `promptCacheKey`/`parallelToolCalls`, merged model
+ * metadata such as `noTemperatureModels`, a pinned baseUrl). Mirrors the OAuth-401 replay
+ * path in src/server/responses/core.ts, which spreads `route.provider` for the same reason.
+ */
 export function rotateProviderTransportOn429(
   config: OcxConfig,
   providerName: string,
+  routedProvider: OcxProviderTransport,
   options: RotateProviderTransportOptions = {},
-): OcxProviderConfig | null {
+): OcxProviderTransport | null {
   const rotated = rotateKeyOn429(
     config,
     providerName,
@@ -147,7 +163,11 @@ export function rotateProviderTransportOn429(
     options.attemptedKey,
   );
   return rotated
-    ? resolveProviderTransport(providerName, rotated, options.promptCacheKey)
+    ? resolveProviderTransport(
+        providerName,
+        { ...routedProvider, apiKey: rotated.apiKey },
+        options.promptCacheKey,
+      )
     : null;
 }
 
diff --git a/src/providers/registry.ts b/src/providers/registry.ts
@@ -480,6 +480,12 @@ export const PROVIDER_REGISTRY: readonly ProviderRegistryEntry[] = [
     baseUrl: "https://api.kimi.com/coding/v1",
     authKind: "oauth",
     modelSuffixBracketStrip: true,
+    // Kimi Code Plan documents a stable session/task prompt_cache_key as required to improve
+    // cache hit rates.
+    // The chat adapter only forwards a key already on the internal request (Codex's session key,
+    // or the one the Claude /v1/messages inbound derives); the adapter itself never invents one.
+    // Evidence: https://platform.kimi.com/docs/api/chat
+    promptCacheKey: true,
     featured: true,
     oauthId: "kimi",
     jawcodeBundle: "moonshot",
@@ -1018,6 +1024,8 @@ export const PROVIDER_REGISTRY: readonly ProviderRegistryEntry[] = [
     id: "kimi-code", label: "Kimi (coding)", baseUrl: "https://api.kimi.com/coding/v1", adapter: "openai-chat", authKind: "key",
     dashboardUrl: "https://platform.moonshot.cn/console/api-keys", defaultModel: "kimi-k2.7-code",
     modelSuffixBracketStrip: true,
+    // API-key form of the same Kimi Code Plan transport; keep cache affinity identical to OAuth.
+    promptCacheKey: true,
     models: KIMI_CODING_MODELS,
     modelContextWindows: KIMI_CODING_MODEL_CONTEXT_WINDOWS,
     modelInputModalities: KIMI_CODING_MODEL_INPUT_MODALITIES,
diff --git a/src/server/responses/core.ts b/src/server/responses/core.ts
@@ -1756,7 +1756,7 @@ export async function handleResponses(
         }
       },
       on429: retryAfter => {
-        const rotated = rotateProviderTransportOn429(config, route.providerName, {
+        const rotated = rotateProviderTransportOn429(config, route.providerName, route.provider, {
           retryAfter,
           now: Date.now(),
           attemptedKey: route.provider.apiKey,
@@ -1822,7 +1822,7 @@ export async function handleResponses(
       routedModelStallTimeoutMs: wsPlan.routedModelStallTimeoutMs,
       stallTimeoutSec: wsPlan.stallTimeoutSec,
       on429: retryAfter => {
-        const rotated = rotateProviderTransportOn429(config, route.providerName, {
+        const rotated = rotateProviderTransportOn429(config, route.providerName, route.provider, {
           retryAfter,
           now: Date.now(),
           attemptedKey: route.provider.apiKey,
@@ -2094,7 +2094,7 @@ export async function handleResponses(
       // SAME request once per remaining key. OAuth/forward providers and single-key pools
       // return null immediately, so this stays a no-op for them (src/providers/key-failover.ts).
       while (upstreamResponse.status === 429 && hasKeyPoolFailover(route.provider)) {
-        const rotated = rotateProviderTransportOn429(config, route.providerName, {
+        const rotated = rotateProviderTransportOn429(config, route.providerName, route.provider, {
           retryAfter: upstreamResponse.headers.get("retry-after"),
           now: Date.now(),
           attemptedKey: route.provider.apiKey,
@@ -2257,7 +2257,7 @@ export async function handleResponses(
       }
 
       if (response.status === 429 && hasKeyPoolFailover(route.provider)) {
-        const rotated = rotateProviderTransportOn429(config, route.providerName, {
+        const rotated = rotateProviderTransportOn429(config, route.providerName, route.provider, {
           retryAfter: response.headers.get("retry-after"),
           now: Date.now(),
           attemptedKey: route.provider.apiKey,
diff --git a/structure/04_transports-and-sidecars.md b/structure/04_transports-and-sidecars.md
@@ -271,6 +271,22 @@ lookalike hosts, and custom proxy paths fail validation. A model override replac
 merges the provider-wide default, keeping precedence deterministic. With no preference configured,
 the request body is byte-for-byte unchanged in this area and OpenRouter retains its default routing.
 
+## Kimi Coding Plan prompt-cache affinity
+
+The canonical `kimi` OAuth and `kimi-code` API-key presets opt into forwarding the internal
+request's `prompt_cache_key` to Kimi's Chat Completions body. Kimi Code Plan documents a stable
+session/task key as required to improve cache hit rates. The chat adapter never invents a key of
+its own: it forwards what the request already carries — Codex's session key on
+`/v1/responses`, or the session-scoped key the Claude `/v1/messages` inbound derives
+(metadata.user_id hash, else the system+tools cohort hash) — and a request with no key stays
+keyless. An explicit provider-level `promptCacheKey: false` continues to opt out, and the flag is
+persisted through `providerConfigSeed`/`enrichProviderFromRegistry` for new configs; key-pool 429
+rotation keeps it — along with every other registry backfill — because the retry inherits the
+request's routed provider and swaps only the API key (`rotateProviderTransportOn429` in
+src/providers/key-failover.ts). If an opted-in upstream rejects the field, OpenCodex does not strip it and retry or mutate the
+saved configuration. Other OpenAI-compatible providers remain deny-by-default because strict
+backends may reject the OpenAI-specific field.
+
 ## xAI Grok hardening (official Grok Build contract parity)
 
 Grounded in the open-sourced official client (xai-org/grok-build); unit + evidence:
diff --git a/tests/key-failover.test.ts b/tests/key-failover.test.ts
@@ -2,6 +2,7 @@ import { afterEach, beforeEach, describe, expect, test } from "bun:test";
 import { mkdtempSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
+import { createOpenAIChatAdapter } from "../src/adapters/openai-chat";
 import {
   clearKeyCooldowns,
   getKeyCooldownUntil,
@@ -10,7 +11,8 @@ import {
   rotateProviderTransportOn429,
 } from "../src/providers/key-failover";
 import { deriveXaiConvId } from "../src/providers/xai-transport";
-import type { OcxConfig, OcxProviderConfig } from "../src/types";
+import { routeModel } from "../src/router";
+import type { OcxConfig, OcxParsedRequest, OcxProviderConfig } from "../src/types";
 
 let home: string;
 
@@ -130,6 +132,72 @@ describe("rotateKeyOn429", () => {
 });
 
 describe("rotateProviderTransportOn429", () => {
+  test("keeps Kimi prompt-cache forwarding after rotating a stale pre-upgrade config", () => {
+    const promptCacheKey = "stable-kimi-conversation-429";
+    const config = makeConfig({
+      authMode: "key",
+      apiKey: "key-alpha-000111222333",
+      apiKeyPool: pool3(),
+    });
+    config.defaultProvider = "kimi-code";
+    config.providers["kimi-code"] = {
+      ...config.providers.p,
+      baseUrl: "https://api.kimi.com/coding/v1",
+    };
+    delete config.providers.p;
+    expect(config.providers["kimi-code"].promptCacheKey).toBeUndefined();
+
+    const parsed: OcxParsedRequest = {
+      modelId: "k3",
+      context: { messages: [{ role: "user", content: "hi", timestamp: 0 }] },
+      stream: false,
+      options: { promptCacheKey },
+    };
+    const initial = routeModel(config, "kimi-code/k3").provider;
+    const initialBody = JSON.parse(createOpenAIChatAdapter(initial).buildRequest(parsed).body);
+    expect(initialBody.prompt_cache_key).toBe(promptCacheKey);
+
+    const rotated = rotateProviderTransportOn429(config, "kimi-code", initial, {
+      now: 1_000_000,
+      attemptedKey: "key-alpha-000111222333",
+      promptCacheKey,
+    });
+    expect(rotated?.apiKey).toBe("key-beta-444555666777");
+    expect(rotated?.promptCacheKey).toBe(true);
+    const retryBody = JSON.parse(createOpenAIChatAdapter(rotated!).buildRequest(parsed).body);
+    expect(retryBody.prompt_cache_key).toBe(promptCacheKey);
+  });
+
+  test("inherits the routed provider's registry backfills; only the key changes", () => {
+    // The persisted config predates the registry scalar flags and merged metadata —
+    // routedProviderConfig backfilled them at request time. Rotation must not fall back
+    // to the bare persisted snapshot and silently drop them for the retried request.
+    const config = makeConfig({ apiKey: "key-alpha-000111222333", apiKeyPool: pool3() });
+    const routedProvider = {
+      ...config.providers.p,
+      baseUrl: "https://registry-pinned.example/v1",
+      promptCacheKey: true,
+      parallelToolCalls: false,
+      modelContextWindows: { "some-model": 262_144 },
+      noTemperatureModels: ["some-model"],
+    } as OcxProviderConfig;
+
+    const rotated = rotateProviderTransportOn429(config, "p", routedProvider, {
+      now: 1_000_000,
+      attemptedKey: "key-alpha-000111222333",
+    });
+
+    expect(rotated?.apiKey).toBe("key-beta-444555666777");
+    expect(rotated?.baseUrl).toBe("https://registry-pinned.example/v1");
+    expect(rotated?.promptCacheKey).toBe(true);
+    expect(rotated?.parallelToolCalls).toBe(false);
+    expect(rotated?.modelContextWindows).toEqual({ "some-model": 262_144 });
+    expect(rotated?.noTemperatureModels).toEqual(["some-model"]);
+    // The pool swap still lands in the persisted config.
+    expect(config.providers.p.apiKey).toBe("key-beta-444555666777");
+    expect(config.providers.p.promptCacheKey).toBeUndefined();
+  });
+
   test("re-applies xAI cache affinity without OAuth CLI headers after key rotation", () => {
     const promptCacheKey = "stable-conversation-429";
     const config = makeConfig({
@@ -140,7 +208,7 @@ describe("rotateProviderTransportOn429", () => {
     config.providers.xai = config.providers.p;
     delete config.providers.p;
 
-    const rotated = rotateProviderTransportOn429(config, "xai", {
+    const rotated = rotateProviderTransportOn429(config, "xai", { ...config.providers.xai }, {
       now: 1_000_000,
       attemptedKey: "key-alpha-000111222333",
       promptCacheKey,
diff --git a/tests/openai-chat-hardening.test.ts b/tests/openai-chat-hardening.test.ts
diff --git a/tests/provider-registry-parity.test.ts b/tests/provider-registry-parity.test.ts
diff --git a/tests/server-key-failover-e2e.test.ts b/tests/server-key-failover-e2e.test.ts
