pi-cache-optimizer 2.8.25 → 2.8.27

package/src/diagnostics.ts

@@ -2,7 +2,7 @@ import { type CacheProviderAdapter } from "./adapters.ts";
 import { type PiModel, type UnknownRecord, asRecord, isNonEmptyString, lower } from "./common.ts";
 import { type CompatAdvicePlacement, appendCredentialSafeProviderGuidance, appendDeepSeekCompatAdviceLines, appendOpenAIProxyCompatAdviceLines, buildDeepSeekCompatSuggestion, buildSafeOpenAIProxyCompatSuggestion, describeMissingCacheCompatForModel, getModelsJsonDisplayPath, isAdaptiveThinkingCompatApplicable, isDeepSeekWireCompatApplicable } from "./compat-advice.ts";
 import { type FixSuggestion } from "./fix-types.ts";
-import { getCompat, isKnownThirdPartyOpenAIEndpoint, isMistralConversationsApi, isNativeVirtualModel, isOfficialOpenAIBaseUrl, isOpenAICompatibleApi, isOpenAICompatibleProxyApi, isPiBuiltInLlamaCppModel, modelKey } from "./model-identity.ts";
+import { getCompat, isKnownThirdPartyOpenAIEndpoint, isMistralConversationsApi, isNativeVirtualModel, isOfficialOpenAIBaseUrl, isOpenAICompatibleApi, isOfficialKimiCodeEndpoint, isOpenAICompatibleProxyApi, isPiBuiltInLlamaCppModel, isThirdPartyOpenAIProxyEndpoint, modelKey } from "./model-identity.ts";
 import { type CacheUsageSample, formatRecentTrendSummary } from "./stats-report.ts";
 import { type CacheStats, emptyCacheStats } from "./stats-store.ts";
 import { snapshotBaseUrlForDiagnostics } from "./request-state.ts";
@@ -38,7 +38,7 @@ export function describeOptionalOpenAICompatibleProxyCompat(model: PiModel): str
   const optional: string[] = [];
 
   if (!isOpenAICompatibleProxyApi(model.api)) return optional;
-  if (!isKnownThirdPartyOpenAIEndpoint(model)) return optional;
+  if (!isThirdPartyOpenAIProxyEndpoint(model)) return optional;
   if (isPiBuiltInLlamaCppModel(model)) return optional;
 
   if (compat.supportsLongCacheRetention !== true) {
@@ -143,7 +143,7 @@ export function isDeepSeekCompatCheckApplicable(model: PiModel): boolean {
 }
 
 export function isCompatCheckApplicable(model: PiModel): boolean {
-  return isOpenAICompatibleProxyApi(model.api) && isKnownThirdPartyOpenAIEndpoint(model) && !isPiBuiltInLlamaCppModel(model);
+  return isOpenAICompatibleProxyApi(model.api) && isThirdPartyOpenAIProxyEndpoint(model) && !isPiBuiltInLlamaCppModel(model);
 }
 
 export function isPromptCacheRetention400Applicable(model: PiModel): boolean {
@@ -223,7 +223,7 @@ export function describeRouterChannelDiagnostics(model: PiModel): string[] {
 
   // Unknown/default endpoints and official OpenAI are not diagnosable as
   // third-party router channels. Request-header bridging also fails closed.
-  if (!isKnownThirdPartyOpenAIEndpoint(model)) {
+  if (!isThirdPartyOpenAIProxyEndpoint(model)) {
     return notes;
   }
 
@@ -404,6 +404,13 @@ export function getCompatCheckNotApplicableLines(model: PiModel): string[] {
     ];
   }
 
+  if (isOpenAICompatibleApi(api) && isOfficialKimiCodeEndpoint(model)) {
+    return [
+      "ℹ️ Compat check not applicable for this model.",
+      "   Official Kimi Code endpoint: Pi ships this provider's compat itself, and proxy session-affinity flags do not apply to a first-party origin.",
+    ];
+  }
+
   return ["ℹ️ Compat check not applicable for this model."];
 }
 
@@ -499,7 +506,9 @@ export function buildDoctorDiagnosis(model: PiModel, options: { promptCacheReten
       lines.push("   (session_id, x-client-request-id, x-session-affinity) and return 403. If you");
       lines.push("   see 403 errors, run /cache-optimizer fix to set sendSessionAffinityHeaders: false.");
     }
-  } else if (isOpenAISdkHeader403Applicable(model)) {
+  } else if (isOpenAISdkHeader403Applicable(model) && (options.openAISdkHeader403 || !isOfficialKimiCodeEndpoint(model))) {
+    // Official Kimi Code gets the 403 hint only after a 403 was observed; the
+    // passive "after disabling sendSessionAffinityHeaders" advice is proxy-only.
     lines.push("");
     if (options.openAISdkHeader403) {
       lines.push("⚠️  A 403 response was observed while sendSessionAffinityHeaders is not enabled.");

package/src/fix-types.ts

@@ -35,11 +35,12 @@ export function samePromptCacheLifetimes(left: unknown, right: unknown): boolean
 /**
  * Version 1 receipts record scalar compat changes only. Version 2 receipts
  * also record a `promptCache` object the fix added (it never overwrites one),
- * so rollback can remove exactly that property. Older extension versions
- * reject version 2 receipts instead of misreading them.
+ * so rollback can remove exactly that property. Version 3 receipts record a
+ * single `baseUrl` string rewrite (`/cache-optimizer fix kimi-base-url`).
+ * Older extension versions reject newer receipts instead of misreading them.
  */
 export type ModelsJsonFixReceiptV1 = {
-  version: 1 | 2;
+  version: 1 | 2 | 3;
   kind: "pi-cache-optimizer-fix-receipt";
   transactionId: string;
   provider: string;
@@ -49,6 +50,11 @@ export type ModelsJsonFixReceiptV1 = {
   changedKeys: Record<string, FixReceiptCompatChange>;
   /** Version 2 only: the promptCache object added at the target (absent before). */
   promptCacheAdded?: PromptCacheLifetimes;
+  /**
+   * Version 3 only: the `baseUrl` string the fix rewrote at the provider or
+   * custom model target (official Kimi Code `/coding` → `/coding/v1`).
+   */
+  baseUrlChange?: { before: string; after: string };
   beforeHash: string;
   afterHash: string;
   backupFile: string;

package/src/kimi-base-url-fix.ts

@@ -0,0 +1,249 @@
+import { type PiModel, asRecord, isNonEmptyString } from "./common.ts";
+import { parseJsonc } from "./jsonc.ts";
+import { kimiCodeV1BaseUrl, normalizeBaseUrlForComparison, parseOfficialKimiCodeBaseUrl } from "./kimi-code.ts";
+import { isValidModelsConfigForEffectiveCompat } from "./model-identity.ts";
+import { type BaseUrlFixPlacement, locateBaseUrlTarget, readBaseUrlState, replaceBaseUrlValue } from "./models-json-fix.ts";
+
+/**
+ * Kimi Code base URL check and `/cache-optimizer fix kimi-base-url`.
+ *
+ * Pi 1.3.0 moved the built-in kimi-coding provider from anthropic-messages
+ * (`https://api.kimi.com/coding`) to OpenAI Chat Completions
+ * (`https://api.kimi.com/coding/v1`). A models.json `baseUrl` left over from
+ * the Anthropic era keeps `/coding`, so Pi posts to `/coding/chat/completions`
+ * and every request fails.
+ *
+ * The fix only appends `/v1`, and only when the live model uses
+ * openai-completions and its base URL is exactly an official Kimi Code host
+ * with the bare `/coding` path. The effective API is the real condition: Pi
+ * versions before 1.3.0 ship kimi-coding as anthropic-messages, and Kimi's
+ * OpenAI-compatible endpoint has always been `/coding/v1`. Proxies, other
+ * paths, and Anthropic-protocol entries only get a hint.
+ */
+
+export type KimiBaseUrlStatus =
+  | { kind: "not-applicable" }
+  | { kind: "fixable"; current: string; suggested: string }
+  | { kind: "hint"; lines: string[] };
+
+const KIMI_CODING_PATH = /\/coding\/*$/i;
+
+export function diagnoseKimiCodeBaseUrl(model: PiModel | undefined): KimiBaseUrlStatus {
+  if (!model || !isNonEmptyString(model.baseUrl)) return { kind: "not-applicable" };
+  const api = String(model.api ?? "").toLowerCase();
+  const official = parseOfficialKimiCodeBaseUrl(model.baseUrl);
+
+  if (api === "openai-completions") {
+    if (official && !official.hasV1) {
+      const suggested = kimiCodeV1BaseUrl(model.baseUrl);
+      if (suggested) return { kind: "fixable", current: model.baseUrl, suggested };
+    }
+    if (!official && isKimiLike(model) && KIMI_CODING_PATH.test(pathOf(model.baseUrl))) {
+      return {
+        kind: "hint",
+        lines: [
+          "ℹ️ This Kimi entry uses OpenAI Chat Completions, and its base URL ends in /coding without /v1.",
+          "   Kimi Code's official OpenAI endpoint is https://api.kimi.com/coding/v1. Check what your proxy expects;",
+          "   it is not an official Kimi host, so /cache-optimizer fix leaves it unchanged.",
+        ],
+      };
+    }
+    return { kind: "not-applicable" };
+  }
+
+  if (api === "anthropic-messages" && official?.hasV1) {
+    return {
+      kind: "hint",
+      lines: [
+        "ℹ️ This Kimi Code entry uses the Anthropic Messages API, but its base URL ends in /coding/v1.",
+        "   The Anthropic endpoint is https://api.kimi.com/coding (Pi appends /v1/messages itself).",
+        "   Pi 1.3.0+ ships kimi-coding on OpenAI Chat Completions; drop the api override or the /v1. Not changed automatically.",
+      ],
+    };
+  }
+  return { kind: "not-applicable" };
+}
+
+function isKimiLike(model: PiModel): boolean {
+  const provider = String(model.provider ?? "").toLowerCase();
+  const baseUrl = String(model.baseUrl ?? "").toLowerCase();
+  return provider.includes("kimi") || provider.includes("moonshot") || baseUrl.includes("kimi") || baseUrl.includes("moonshot");
+}
+
+function pathOf(baseUrl: string): string {
+  try {
+    return new URL(baseUrl.trim()).pathname;
+  } catch {
+    return "";
+  }
+}
+
+export function buildKimiBaseUrlDoctorLines(model: PiModel | undefined): string[] {
+  const status = diagnoseKimiCodeBaseUrl(model);
+  if (status.kind === "fixable") {
+    return [
+      "",
+      "⚠️  Kimi Code base URL is missing /v1.",
+      `   Current:  ${status.current}`,
+      `   Expected: ${status.suggested}`,
+      "   This model uses OpenAI Chat Completions (Pi 1.3.0+ kimi-coding), so requests to /coding/chat/completions fail.",
+      "   Run /cache-optimizer fix kimi-base-url to append /v1 with a preview, backup and rollback.",
+    ];
+  }
+  if (status.kind === "hint") return ["", ...status.lines];
+  return [];
+}
+
+export type KimiBaseUrlFixPlan = {
+  modifiedText: string;
+  placement: BaseUrlFixPlacement;
+  before: string;
+  after: string;
+  locationLabel: string;
+  /** Other models whose base URL changes too (provider-level edits). */
+  affectedNote?: string;
+};
+
+/**
+ * Plan the models.json edit for the active model. The `baseUrl` Pi uses comes
+ * from the model's own custom `models[]` entry when it has one, otherwise
+ * from the provider entry. The located string must match the live base URL;
+ * a mismatch means something else (an extension, another file) supplies it.
+ */
+export function planKimiBaseUrlFix(
+  originalText: string,
+  model: PiModel,
+  /** Live models from Pi's registry (`modelRegistry.getAll()`), when available. */
+  registeredModels?: readonly PiModel[],
+): KimiBaseUrlFixPlan | { error: string } {
+  const status = diagnoseKimiCodeBaseUrl(model);
+  if (status.kind !== "fixable") return { error: "the active model does not need the Kimi Code /v1 fix" };
+
+  let parsed: unknown;
+  try {
+    parsed = parseJsonc(originalText);
+  } catch {
+    return { error: "models.json is not valid JSONC" };
+  }
+  if (!isValidModelsConfigForEffectiveCompat(parsed)) {
+    return { error: "models.json does not match Pi's model configuration schema" };
+  }
+  const providerRecord = asRecord(asRecord(asRecord(parsed)?.providers)?.[model.provider]);
+  if (!providerRecord) {
+    return { error: `models.json has no "${model.provider}" provider entry, so the base URL comes from somewhere else (an extension or Pi's built-in catalog)` };
+  }
+  const definitions = (Array.isArray(providerRecord.models) ? providerRecord.models : []).map(asRecord);
+  const ownDefinitions = definitions.filter((entry) => entry?.id === model.id);
+  if (ownDefinitions.length > 1) return { error: `models.json defines ${model.provider}/${model.id} more than once` };
+
+  let placement: BaseUrlFixPlacement;
+  if (ownDefinitions[0] && ownDefinitions[0].baseUrl !== undefined) {
+    placement = "model";
+  } else if (providerRecord.baseUrl !== undefined) {
+    placement = "provider";
+    if (providerRecord.oauth === "radius") {
+      return { error: "the provider uses oauth \"radius\", where Pi ignores the provider baseUrl for built-in models" };
+    }
+    // A provider-level baseUrl also feeds custom models without their own.
+    // Refuse when one of them is declared on another protocol, since /v1
+    // would break it (Anthropic Messages wants the bare /coding path).
+    const providerApi = providerRecord.api;
+    const conflicting = definitions
+      .filter((entry) => entry && entry.baseUrl === undefined)
+      .filter((entry) => {
+        const api = entry?.api ?? providerApi;
+        return api !== undefined && String(api).toLowerCase() !== "openai-completions";
+      })
+      .map((entry) => String(entry?.id));
+    if (conflicting.length > 0) {
+      return { error: `the provider baseUrl is shared with custom models on another API (${conflicting.join(", ")}); give each its own baseUrl first` };
+    }
+    // The provider baseUrl also overrides every built-in model of the
+    // provider. On Pi < 1.3.0 the built-in kimi-coding models are
+    // anthropic-messages, so a custom openai-completions entry inheriting the
+    // provider baseUrl must not drag them onto /coding/v1. Check the live
+    // registry; without it, refuse for a custom entry (built-ins unknown).
+    const ownIds = new Set(definitions.map((entry) => entry?.id));
+    if (registeredModels) {
+      const builtInConflicts = registeredModels
+        .filter((entry) => entry.provider === model.provider && !ownIds.has(entry.id))
+        .filter((entry) => String(entry.api ?? "").toLowerCase() !== "openai-completions")
+        .filter((entry) => isNonEmptyString(entry.baseUrl) && normalizeBaseUrlForComparison(entry.baseUrl) === normalizeBaseUrlForComparison(String(providerRecord.baseUrl)))
+        .map((entry) => String(entry.id));
+      if (builtInConflicts.length > 0) {
+        return { error: `the provider baseUrl is shared with built-in models on another API (${builtInConflicts.join(", ")}); set baseUrl on the ${model.id} models[] entry instead` };
+      }
+    } else if (ownDefinitions[0]) {
+      return { error: `the provider baseUrl may also feed built-in ${model.provider} models on another API; set baseUrl on the ${model.id} models[] entry instead` };
+    }
+  } else {
+    return { error: `models.json sets no baseUrl for ${model.provider}/${model.id}, so the base URL comes from somewhere else` };
+  }
+
+  const target = locateBaseUrlTarget(originalText, model.provider, model.id, placement);
+  const before = readBaseUrlState(originalText, target);
+  if (!target || before === undefined || before === "invalid") {
+    return { error: "the baseUrl entry is duplicated or cannot be located safely" };
+  }
+  if (normalizeBaseUrlForComparison(before) !== normalizeBaseUrlForComparison(status.current)) {
+    return { error: "the baseUrl in models.json differs from the active model's base URL (an extension or another source overrides it)" };
+  }
+  const after = kimiCodeV1BaseUrl(before);
+  if (!after) return { error: "the baseUrl in models.json is not a bare official Kimi Code /coding URL" };
+  const modifiedText = replaceBaseUrlValue(originalText, target, after);
+  if (modifiedText === undefined) return { error: "the baseUrl value cannot be rewritten safely" };
+
+  const locationLabel = placement === "provider"
+    ? `providers[${JSON.stringify(model.provider)}].baseUrl`
+    : `providers[${JSON.stringify(model.provider)}].models[id=${JSON.stringify(model.id)}].baseUrl`;
+  const plan: KimiBaseUrlFixPlan = {
+    modifiedText,
+    placement,
+    before,
+    after,
+    locationLabel,
+    ...(placement === "provider" ? { affectedNote: `Every ${model.provider} model without its own baseUrl uses this value.` } : {}),
+  };
+  const checkError = selfCheckKimiBaseUrlFix(originalText, plan, model.provider, model.id);
+  if (checkError) return { error: `self-check failed: ${checkError}` };
+  return plan;
+}
+
+/** The edit must be valid, write `after`, and change nothing but that string. */
+export function selfCheckKimiBaseUrlFix(originalText: string, plan: KimiBaseUrlFixPlan, provider: string, modelId: string): string | null {
+  let original: unknown;
+  let modified: unknown;
+  try {
+    original = parseJsonc(originalText);
+    modified = parseJsonc(plan.modifiedText);
+  } catch {
+    return "the edited file is not valid JSONC";
+  }
+  if (!isValidModelsConfigForEffectiveCompat(modified)) return "the edited file does not match Pi's model configuration schema";
+  if (readBaseUrlState(plan.modifiedText, locateBaseUrlTarget(plan.modifiedText, provider, modelId, plan.placement)) !== plan.after) {
+    return "baseUrl was not written at the target";
+  }
+  const reverted = JSON.parse(JSON.stringify(modified)) as Record<string, unknown>;
+  const providerRecord = asRecord(asRecord(reverted.providers)?.[provider]);
+  if (!providerRecord) return "the provider entry disappeared";
+  if (plan.placement === "provider") {
+    providerRecord.baseUrl = plan.before;
+  } else {
+    const entry = (Array.isArray(providerRecord.models) ? providerRecord.models : []).map(asRecord).find((item) => item?.id === modelId);
+    if (!entry) return "the model entry disappeared";
+    entry.baseUrl = plan.before;
+  }
+  if (JSON.stringify(reverted) !== JSON.stringify(original)) return "unrelated configuration was altered";
+  return null;
+}
+
+/** Validate a file written by the fix transaction (re-read from disk). */
+export function validateWrittenKimiBaseUrlFix(writtenText: string, plan: KimiBaseUrlFixPlan): string | null {
+  if (writtenText !== plan.modifiedText) return "models.json content differs from the previewed edit";
+  try {
+    parseJsonc(writtenText);
+  } catch {
+    return "the written file is not valid JSONC";
+  }
+  return null;
+}

package/src/kimi-code.ts

@@ -0,0 +1,53 @@
+import { isNonEmptyString } from "./common.ts";
+
+// Moonshot's official Kimi Code hosts (China and international). Pi 1.3.0
+// ships kimi-coding as openai-completions at `<host>/coding/v1`; older Pi
+// versions used anthropic-messages at `<host>/coding`.
+const OFFICIAL_KIMI_CODE_HOSTS = new Set(["api.kimi.com", "api.kimi.ai"]);
+
+export type OfficialKimiCodeBaseUrl = {
+  host: string;
+  /** Whether the path is `/coding/v1` (true) or bare `/coding` (false). */
+  hasV1: boolean;
+};
+
+/**
+ * Parse an official Kimi Code base URL: https, one of the official hosts, no
+ * port, credentials, query or fragment, and a path of exactly `/coding` or
+ * `/coding/v1` (trailing slashes ignored). Anything else, including proxies
+ * that mirror the path, returns undefined.
+ */
+export function parseOfficialKimiCodeBaseUrl(baseUrl: unknown): OfficialKimiCodeBaseUrl | undefined {
+  if (!isNonEmptyString(baseUrl)) return undefined;
+  let url: URL;
+  try {
+    url = new URL(baseUrl.trim());
+  } catch {
+    return undefined;
+  }
+  if (url.protocol !== "https:" || url.port !== "" || url.username !== "" || url.password !== "") return undefined;
+  if (url.search !== "" || url.hash !== "" || /[?#]/.test(baseUrl)) return undefined;
+  const host = url.hostname.toLowerCase();
+  if (!OFFICIAL_KIMI_CODE_HOSTS.has(host)) return undefined;
+  const path = url.pathname.replace(/\/+$/, "").toLowerCase();
+  if (path === "/coding") return { host, hasV1: false };
+  if (path === "/coding/v1") return { host, hasV1: true };
+  return undefined;
+}
+
+/** Strip surrounding whitespace and trailing slashes for base URL comparison. */
+export function normalizeBaseUrlForComparison(baseUrl: string): string {
+  return baseUrl.trim().replace(/\/+$/, "");
+}
+
+/** The `/coding/v1` form of a bare official `/coding` base URL, keeping its spelling. */
+export function kimiCodeV1BaseUrl(baseUrl: string): string | undefined {
+  const parsed = parseOfficialKimiCodeBaseUrl(baseUrl);
+  if (!parsed || parsed.hasV1) return undefined;
+  return `${normalizeBaseUrlForComparison(baseUrl)}/v1`;
+}
+
+/** A receipt-recorded base URL change is exactly "bare official /coding" → "+ /v1". */
+export function isKimiCodeV1BaseUrlChange(before: unknown, after: unknown): boolean {
+  return typeof before === "string" && typeof after === "string" && kimiCodeV1BaseUrl(before) === after;
+}

package/src/model-identity.ts

@@ -2,6 +2,7 @@ import { type ModelIdentity, type PiModel, type UnknownRecord, asRecord, isNonEm
 import { type CacheCompat, NESTED_COMPAT_KEYS, resolveEffectiveCompatFromConfig } from "./compat-config.ts";
 import { parseJsonc } from "./jsonc.ts";
 import { getAssistantMessageModelTokenValues, getModelIdNameTokenValues, hasAnyTokenContaining, isKimiCodingAdaptiveModel, modelOrAssistantMessageHas } from "./model-detect.ts";
+import { parseOfficialKimiCodeBaseUrl } from "./kimi-code.ts";
 import { MODELS_JSON_PATH } from "./paths.ts";
 import { readFileSync, statSync } from "node:fs";
 
@@ -363,6 +364,21 @@ export function isKnownThirdPartyOpenAIEndpoint(model: PiModel): boolean {
   return isNonEmptyString(model.baseUrl) && !isOfficialOpenAIBaseUrl(model);
 }
 
+/** The model talks to Moonshot's official Kimi Code endpoint directly. */
+export function isOfficialKimiCodeEndpoint(model: PiModel | undefined): boolean {
+  return parseOfficialKimiCodeBaseUrl(model?.baseUrl) !== undefined;
+}
+
+/**
+ * A non-official OpenAI-compatible endpoint that may sit in front of several
+ * backends (relay, aggregator, gateway), where session-affinity headers help
+ * keep one session on one cache. Official first-party endpoints that Pi
+ * configures itself (Kimi Code) are origins, not proxies.
+ */
+export function isThirdPartyOpenAIProxyEndpoint(model: PiModel): boolean {
+  return isKnownThirdPartyOpenAIEndpoint(model) && !isOfficialKimiCodeEndpoint(model);
+}
+
 export function invalidateModelsConfigCache(): void {
   modelsConfigCache = undefined;
 }

package/src/models-json-fix.ts

@@ -8,6 +8,7 @@ import { findLastExactModelDefinition, resolveEffectiveCompatFromConfig } from "
 import { type FixReceiptCompatChange, type FixReceiptPlacement, type ModelsJsonFixReceiptV1, type PromptCacheLifetimes, RECEIPT_COMPAT_KEYS, type ReceiptScalar, type ReceiptScalarState, isReceiptTimestamp, isValidPromptCacheLifetimes, samePromptCacheLifetimes, isSafeReceiptText, isSha256 } from "./fix-types.ts";
 import { type JsonPropertyEdit, type ModelNodeLocation, deepEqualIgnoringKeys, deriveInnerIndent, findExistingCompatKeysInJsonc, findJsonObjectKey, findMatchingBracket, isJsonWhitespace, lineIndentOf, locateJsonPropertyValueSpan, locateModelOverrideInJsonc, locateProviderCompatInJsonc, parseJsonc, readJsonStringLiteral, skipJsonValue, skipJsonWhitespace, stripJsoncComments } from "./jsonc.ts";
 import { isAdaptiveGenerationModel, isKimiCodingAdaptiveModel } from "./model-detect.ts";
+import { isKimiCodeV1BaseUrlChange } from "./kimi-code.ts";
 import { FIX_RECEIPT_PATH, MODELS_JSON_PATH } from "./paths.ts";
 
 export type ExplicitCompatSource = "modelOverride" | "model" | "provider";
@@ -1528,10 +1529,10 @@ export function createRollbackBackupPath(modelsPath: string = MODELS_JSON_PATH):
 
 export function parseModelsJsonFixReceipt(value: unknown): ModelsJsonFixReceiptV1 | undefined {
   const record = asRecord(value);
-  if (!record || (record.version !== 1 && record.version !== 2) || record.kind !== "pi-cache-optimizer-fix-receipt") return undefined;
+  if (!record || (record.version !== 1 && record.version !== 2 && record.version !== 3) || record.kind !== "pi-cache-optimizer-fix-receipt") return undefined;
   const allowedKeys = new Set([
     "version", "kind", "transactionId", "provider", "modelId", "placement",
-    "targetExistedBefore", "changedKeys", "promptCacheAdded", "beforeHash", "afterHash", "backupFile",
+    "targetExistedBefore", "changedKeys", "promptCacheAdded", "baseUrlChange", "beforeHash", "afterHash", "backupFile",
     "createdAt", "appliedAt", "status", "rolledBackAt",
   ]);
   if (Object.keys(record).some((key) => !allowedKeys.has(key))) return undefined;
@@ -1549,8 +1550,19 @@ export function parseModelsJsonFixReceipt(value: unknown): ModelsJsonFixReceiptV
   const isV2 = record.version === 2;
   if (isV2 !== (record.promptCacheAdded !== undefined)) return undefined;
   if (isV2 && (!isValidPromptCacheLifetimes(record.promptCacheAdded) || record.placement === "provider")) return undefined;
+  // baseUrlChange is the version 3 marker: a single official Kimi Code
+  // `/coding` → `/coding/v1` rewrite at an existing provider or model target.
+  const isV3 = record.version === 3;
+  if (isV3 !== (record.baseUrlChange !== undefined)) return undefined;
+  const rawBaseUrlChange = asRecord(record.baseUrlChange);
+  if (isV3) {
+    if (!rawBaseUrlChange || Object.keys(rawBaseUrlChange).some((key) => key !== "before" && key !== "after")) return undefined;
+    if (!isKimiCodeV1BaseUrlChange(rawBaseUrlChange.before, rawBaseUrlChange.after)) return undefined;
+    if (record.placement === "modelOverride" || record.targetExistedBefore !== true) return undefined;
+  }
   const changedKeys = asRecord(record.changedKeys);
-  if (!changedKeys || (Object.keys(changedKeys).length === 0 && !isV2)) return undefined;
+  if (!changedKeys || (Object.keys(changedKeys).length === 0 && record.version === 1)) return undefined;
+  if (isV3 && Object.keys(changedKeys).length > 0) return undefined;
 
   const parsedChanges: Record<string, FixReceiptCompatChange> = {};
   for (const [key, rawChange] of Object.entries(changedKeys)) {
@@ -1569,8 +1581,11 @@ export function parseModelsJsonFixReceipt(value: unknown): ModelsJsonFixReceiptV
   if (record.status === undefined && record.rolledBackAt !== undefined) return undefined;
 
   const promptCacheAdded = isV2 ? record.promptCacheAdded as PromptCacheLifetimes : undefined;
+  const baseUrlChange = isV3 && rawBaseUrlChange
+    ? { before: rawBaseUrlChange.before as string, after: rawBaseUrlChange.after as string }
+    : undefined;
   return {
-    version: isV2 ? 2 : 1,
+    version: isV3 ? 3 : isV2 ? 2 : 1,
     kind: "pi-cache-optimizer-fix-receipt",
     transactionId: record.transactionId.trim(),
     provider: record.provider.trim(),
@@ -1579,6 +1594,7 @@ export function parseModelsJsonFixReceipt(value: unknown): ModelsJsonFixReceiptV
     targetExistedBefore: record.targetExistedBefore,
     changedKeys: parsedChanges,
     ...(promptCacheAdded ? { promptCacheAdded: { ...(promptCacheAdded.short !== undefined ? { short: promptCacheAdded.short } : {}), ...(promptCacheAdded.long !== undefined ? { long: promptCacheAdded.long } : {}) } } : {}),
+    ...(baseUrlChange ? { baseUrlChange } : {}),
     beforeHash,
     afterHash,
     backupFile: record.backupFile,
@@ -1854,6 +1870,100 @@ export function createPromptCacheFixReceipt(
   });
 }
 
+export type BaseUrlFixPlacement = "provider" | "model";
+
+/**
+ * Locate the object that holds a direct `baseUrl`: the provider object, or
+ * the single custom `models[]` entry with this id. Duplicate provider keys or
+ * duplicate model ids are refused.
+ */
+export function locateBaseUrlTarget(
+  text: string,
+  provider: string,
+  modelId: string,
+  placement: BaseUrlFixPlacement,
+): { objectBrace: number; objectEnd: number } | undefined {
+  if (placement === "provider") {
+    const location = locateProviderCompatInJsonc(text, provider);
+    return location ? { objectBrace: location.providerObjectBrace, objectEnd: location.providerObjectEnd } : undefined;
+  }
+  const location = locateModelInJsonc(text, provider, modelId);
+  if (!location || location.providerKeyCount !== 1 || location.modelObjectBrace < 0) return undefined;
+  if (location.allModelIds.filter((id) => id === modelId).length !== 1) return undefined;
+  return { objectBrace: location.modelObjectBrace, objectEnd: location.modelObjectEnd };
+}
+
+/**
+ * Read the direct `baseUrl` of a target: its string value, `undefined` when
+ * absent, or "invalid" when duplicated, not a string, or unreadable.
+ */
+export function readBaseUrlState(
+  text: string,
+  target: { objectBrace: number; objectEnd: number } | undefined,
+): string | undefined | "invalid" {
+  if (!target) return "invalid";
+  const clean = stripJsoncComments(text);
+  const property = findJsonObjectKey(clean, target.objectBrace, "baseUrl");
+  if (!property || property.keyStart >= target.objectEnd) return undefined;
+  if (property.count !== 1) return "invalid";
+  const valueStart = skipJsonWhitespace(clean, property.valueStart);
+  if (clean[valueStart] !== "\"") return "invalid";
+  const literal = readJsonStringLiteral(clean, valueStart);
+  if (!literal || literal.end > target.objectEnd) return "invalid";
+  return literal.value;
+}
+
+/** Replace the direct `baseUrl` string of a target, or explain why it cannot. */
+export function replaceBaseUrlValue(
+  text: string,
+  target: { objectBrace: number; objectEnd: number },
+  value: string,
+): string | undefined {
+  const property = locateJsonPropertyValueSpan(text, target.objectBrace, target.objectEnd, "baseUrl");
+  if (!property) return undefined;
+  const clean = stripJsoncComments(text);
+  if (clean[property.valueStart] !== "\"") return undefined;
+  return text.slice(0, property.valueStart) + JSON.stringify(value) + text.slice(property.valueEnd);
+}
+
+/**
+ * Receipt for `/cache-optimizer fix kimi-base-url`: a version 3 receipt with
+ * no compat changes and the single baseUrl string the fix rewrote.
+ */
+export function createBaseUrlFixReceipt(
+  originalText: string,
+  modifiedText: string,
+  provider: string,
+  modelId: string,
+  placement: BaseUrlFixPlacement,
+  before: string,
+  after: string,
+  backupPath: string,
+  now: number = Date.now(),
+): ModelsJsonFixReceiptV1 | undefined {
+  const backupFile = basename(backupPath);
+  if (!/^models\.json\.backup-cache-optimizer-/.test(backupFile)) return undefined;
+  if (!isKimiCodeV1BaseUrlChange(before, after)) return undefined;
+  if (readBaseUrlState(originalText, locateBaseUrlTarget(originalText, provider, modelId, placement)) !== before) return undefined;
+  if (readBaseUrlState(modifiedText, locateBaseUrlTarget(modifiedText, provider, modelId, placement)) !== after) return undefined;
+  return parseModelsJsonFixReceipt({
+    version: 3,
+    kind: "pi-cache-optimizer-fix-receipt",
+    transactionId: randomUUID(),
+    provider,
+    modelId,
+    placement,
+    targetExistedBefore: true,
+    changedKeys: {},
+    baseUrlChange: { before, after },
+    beforeHash: hashText(originalText),
+    afterHash: hashText(modifiedText),
+    backupFile,
+    createdAt: now,
+    appliedAt: now,
+  });
+}
+
 export function createModelsJsonFixReceipt(
   originalText: string,
   modifiedText: string,
@@ -1908,6 +2018,19 @@ export function composeModelsJsonReceiptRollback(
     return { error: "the fix created a new target entry and the file changed; refusing to remove user changes automatically" };
   }
 
+  if (receipt.baseUrlChange) {
+    if (receipt.placement === "modelOverride") return { error: "the receipt's baseUrl target is not supported" };
+    const baseUrlTarget = locateBaseUrlTarget(currentText, receipt.provider, receipt.modelId, receipt.placement);
+    const current = readBaseUrlState(currentText, baseUrlTarget);
+    if (current === "invalid" || !baseUrlTarget) return { error: "receipt-owned baseUrl is no longer safely locatable" };
+    if (current !== receipt.baseUrlChange.after) {
+      return { error: "receipt-owned baseUrl was changed after the fix; refusing to overwrite it" };
+    }
+    const modifiedText = replaceBaseUrlValue(currentText, baseUrlTarget, receipt.baseUrlChange.before);
+    if (modifiedText === undefined) return { error: "receipt-owned baseUrl is no longer safely locatable" };
+    return { modifiedText, changed: modifiedText !== currentText };
+  }
+
   const target = locateReceiptCompatTarget(currentText, receipt.provider, receipt.modelId, receipt.placement);
   if (!target?.targetExists) {
     return { error: "the original target entry is missing or no longer safely locatable" };
@@ -1969,6 +2092,12 @@ export function validateModelsJsonRollback(
   // newly created target entry (which intentionally did not exist before).
   if (expectedHash !== undefined) return null;
 
+  if (receipt.baseUrlChange) {
+    if (receipt.placement === "modelOverride") return "rollback result has an unsupported baseUrl target";
+    const state = readBaseUrlState(writtenText, locateBaseUrlTarget(writtenText, receipt.provider, receipt.modelId, receipt.placement));
+    return state === receipt.baseUrlChange.before ? null : "rollback result did not restore baseUrl";
+  }
+
   const target = locateReceiptCompatTarget(writtenText, receipt.provider, receipt.modelId, receipt.placement);
   if (!target?.targetExists) return "rollback result lost the original target entry";
   for (const [key, change] of Object.entries(receipt.changedKeys)) {