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>

Author: olddonkey

docs-site/src/content/docs/guides/providers.md

@@ -90,6 +90,11 @@ 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 the request's stable `prompt_cache_key` to the Chat Completions request. Kimi
+documents a stable session/task key as required for Kimi Code Plan cache hits; providers that may
+reject the field are left unchanged.
+
 You can also start OAuth from the [web dashboard](/guides/web-dashboard/).
 
 ### Multiple OAuth accounts

docs-site/src/content/docs/ja/guides/providers.md

@@ -84,6 +84,11 @@ 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 のドキュメントでは、Kimi Code Plan のキャッシュヒットには安定したセッション/タスク key が
+必須とされています。このフィールドを拒否する可能性がある他のプロバイダーは変更されません。
+
 [ウェブダッシュボード](/ja/guides/web-dashboard/)からも OAuth を開始できます。
 
 ### 複数の OAuth アカウント

docs-site/src/content/docs/ko/guides/providers.md

@@ -84,6 +84,11 @@ 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 문서는 Kimi
+Code Plan 캐시 적중을 위해 안정적인 세션/작업 key를 필수로 명시합니다. 이 필드를 거부할 수
+있는 다른 프로바이더는 변경되지 않습니다.
+
 [웹 대시보드](/ko/guides/web-dashboard/)에서도 OAuth를 시작할 수 있습니다.
 
 ### 여러 OAuth 계정

docs-site/src/content/docs/ru/guides/providers.md

@@ -93,6 +93,11 @@ 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 передаёт стабильный `prompt_cache_key` запроса в запрос Chat Completions. Документация
+Kimi требует стабильный ключ сессии/задачи для попаданий в кэш Kimi Code Plan; провайдеры,
+которые могут отклонить это поле, остаются без изменений.
+
 OAuth можно запустить и из [веб-дашборда](/ru/guides/web-dashboard/).
 
 ### Несколько OAuth-аккаунтов

docs-site/src/content/docs/zh-cn/guides/providers.md

@@ -78,6 +78,10 @@ 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 文档要求 Kimi Code
+Plan 使用稳定的会话/任务 key 才能获得可靠的缓存命中；可能拒绝该字段的其他 provider 保持不变。
+
 你也可以从 [web 仪表盘](/zh-cn/guides/web-dashboard/) 启动 OAuth。
 
 ### 多个 OAuth 账号

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];

src/providers/registry.ts

@@ -480,6 +480,11 @@ export const PROVIDER_REGISTRY: readonly ProviderRegistryEntry[] = [
     baseUrl: "https://api.kimi.com/coding/v1",
     authKind: "oauth",
     modelSuffixBracketStrip: true,
+    // Kimi Code Plan requires a stable session/task prompt_cache_key for reliable cache affinity.
+    // 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 +1023,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,

structure/04_transports-and-sidecars.md

@@ -271,6 +271,19 @@ 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 for reliable prompt-cache affinity. 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` so key-pool 429 rotation keeps
+it. 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:

tests/openai-chat-hardening.test.ts

@@ -161,6 +161,61 @@ describe("openai-chat credential hardening", () => {
 
     expect(body).not.toHaveProperty("prompt_cache_key");
   });
+
+  test("canonical Kimi Coding Plan routes forward Codex prompt_cache_key", () => {
+    for (const [providerName, authMode] of [
+      ["kimi", "oauth"],
+      ["kimi-code", "key"],
+    ] as const) {
+      const config: OcxConfig = {
+        port: 10100,
+        defaultProvider: providerName,
+        providers: {
+          [providerName]: {
+            adapter: "openai-chat",
+            baseUrl: "https://api.kimi.com/coding/v1",
+            apiKey: "test-kimi-credential",
+            authMode,
+          },
+        },
+      };
+      const route = routeModel(config, `${providerName}/k3`);
+      const req = parsed();
+      req.modelId = route.modelId;
+      req.options.promptCacheKey = "codex-kimi-session-v1";
+
+      expect(route.provider.promptCacheKey).toBe(true);
+      const body = JSON.parse(createOpenAIChatAdapter(route.provider).buildRequest(req).body);
+      expect(body).toMatchObject({
+        model: "k3",
+        prompt_cache_key: "codex-kimi-session-v1",
+      });
+    }
+  });
+
+  test("an explicit Kimi promptCacheKey false remains an opt-out", () => {
+    const config: OcxConfig = {
+      port: 10100,
+      defaultProvider: "kimi",
+      providers: {
+        kimi: {
+          adapter: "openai-chat",
+          baseUrl: "https://api.kimi.com/coding/v1",
+          apiKey: "test-kimi-credential",
+          authMode: "oauth",
+          promptCacheKey: false,
+        },
+      },
+    };
+    const route = routeModel(config, "kimi/k3");
+    const req = parsed();
+    req.modelId = route.modelId;
+    req.options.promptCacheKey = "codex-kimi-session-v1";
+
+    expect(route.provider.promptCacheKey).toBe(false);
+    const body = JSON.parse(createOpenAIChatAdapter(route.provider).buildRequest(req).body);
+    expect(body).not.toHaveProperty("prompt_cache_key");
+  });
 });
 
 describe("openai-chat max output defaults", () => {

tests/provider-registry-parity.test.ts

@@ -374,6 +374,13 @@ describe("provider registry parity", () => {
         expect(entry?.[field]).toContain("kimi-for-coding");
       }
       expect(entry?.modelSuffixBracketStrip).toBe(true);
+      expect(entry?.promptCacheKey).toBe(true);
+      // Key-pool 429 rotation rebuilds the provider from the persisted config (not the routed
+      // one), so the flag must survive seeding/enrichment, not just the router's registry backfill.
+      expect(providerConfigSeed(entry!).promptCacheKey).toBe(true);
+      const enriched: OcxProviderConfig = { adapter: "openai-chat", baseUrl: entry!.baseUrl };
+      enrichProviderFromCatalog(providerId, enriched);
+      expect(enriched.promptCacheKey).toBe(true);
       expect(entry?.noReasoningModels).not.toContain("k3");
       expect(entry?.noReasoningModels).not.toContain("k3[1m]");
       expect(entry?.modelReasoningEfforts?.k3).toEqual(["low", "high", "max"]);