pi-clinepass 0.1.0 → 0.1.2

package/src/catalog.ts

@@ -5,6 +5,10 @@
  * (verified against real usage), not the published reference table which
  * drifts from actual billing. `cacheWrite` is kept at 0: pi's cost model
  * requires the field, but we do not display or track cache-write pricing.
+ *
+ * Context is capped to 921,600 for models whose gateway reports ~1M
+ * (pool max, not single-node) to leave headroom; max output is capped to
+ * 131,072. Models under 1M keep their tested values.
  */
 
 export type ThinkingLevel = "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
@@ -15,7 +19,7 @@ export interface ClinePassModel {
   id: string;
   name: string;
   reasoning: boolean;
-  input: readonly ["text"];
+  input: readonly ("text" | "image")[];
   cost: {
     input: number;
     output: number;
@@ -32,10 +36,10 @@ export interface ClinePassModel {
   };
 }
 
-/** All levels supported (off → "none"), minimal unsupported. */
-const FULL_THINKING: ThinkingLevelMap = {
+/** All 7 levels supported (off → "none"). Used when `supportedEfforts: null` + mandatory false. */
+const ALL_THINKING: ThinkingLevelMap = {
   off: "none",
-  minimal: null,
+  minimal: "minimal",
   low: "low",
   medium: "medium",
   high: "high",
@@ -43,10 +47,59 @@ const FULL_THINKING: ThinkingLevelMap = {
   max: "max",
 };
 
-/** ox-alpha requires reasoning upstream: off → null (unsupported). */
-const OX_ALPHA_THINKING: ThinkingLevelMap = {
-  ...FULL_THINKING,
+/** All levels except off (mandatory reasoning). Used when `mandatory: true` + `supportedEfforts: null`. */
+const ALL_MANDATORY: ThinkingLevelMap = {
+  off: null,
+  minimal: "minimal",
+  low: "low",
+  medium: "medium",
+  high: "high",
+  xhigh: "xhigh",
+  max: "max",
+};
+
+/** Only max/high/low + off. Used for deepseek, glm-5.3, kimi-k3, free models. */
+const MAX_HIGH_LOW: ThinkingLevelMap = {
+  off: "none",
+  minimal: null,
+  low: "low",
+  medium: null,
+  high: "high",
+  xhigh: null,
+  max: "max",
+};
+
+/** Max/high/low but off not allowed (mandatory). */
+const MAX_HIGH_LOW_MANDATORY: ThinkingLevelMap = {
   off: null,
+  minimal: null,
+  low: "low",
+  medium: null,
+  high: "high",
+  xhigh: null,
+  max: "max",
+};
+
+/** Only xhigh/high + off. Used for glm-5.2. */
+const XHIGH_HIGH: ThinkingLevelMap = {
+  off: "none",
+  minimal: null,
+  low: null,
+  medium: null,
+  high: "high",
+  xhigh: "xhigh",
+  max: null,
+};
+
+/** xhigh/medium/low + off. Used for qwen3.8-max. */
+const XHIGH_MEDIUM_LOW: ThinkingLevelMap = {
+  off: "none",
+  minimal: null,
+  low: "low",
+  medium: "medium",
+  high: null,
+  xhigh: "xhigh",
+  max: null,
 };
 
 /**
@@ -70,13 +123,14 @@ function model(
   cost: [input: number, output: number, cacheRead: number],
   contextWindow: number,
   maxTokens: number,
-  thinkingLevelMap: ThinkingLevelMap = FULL_THINKING,
+  input: readonly ("text" | "image")[] = ["text"],
+  thinkingLevelMap: ThinkingLevelMap = ALL_THINKING,
 ): ClinePassModel {
   return {
     id,
     name,
     reasoning: true,
-    input: ["text"],
+    input,
     cost: { input: cost[0], output: cost[1], cacheRead: cost[2], cacheWrite: 0 },
     contextWindow,
     maxTokens,
@@ -85,33 +139,36 @@ function model(
   };
 }
 
-/** Measured prices ($/1M tokens: input/output/cacheRead). */
+/** Measured prices ($/1M tokens: input/output/cacheRead) — latest verified. */
 export const MODELS: readonly ClinePassModel[] = [
   // ── Free models (Cline free tier, cost 0) ──────────────────────────────
-  model("deepseek/deepseek-v4-flash", "DeepSeek V4 Flash (Cline Free)", [0, 0, 0], 1_024_000, 384_000),
-  model("stealth/ox-alpha", "Ox Alpha (Cline Free)", [0, 0, 0], 1_048_576, 131_072, OX_ALPHA_THINKING),
-  model("poolside/laguna-s-2.1:free", "Poolside Laguna S-2.1 (Cline Free)", [0, 0, 0], 262_144, 32_768),
+  model("cline-free/longcat-2.0", "LongCat 2.0", [0, 0, 0], 921_600, 131_072, ["text"], ALL_THINKING),
+  model("z-ai/glm-5.3-flash", "GLM-5.3 Flash", [0, 0, 0], 921_600, 131_072, ["text", "image"], MAX_HIGH_LOW_MANDATORY),
+  model("deepseek/deepseek-v4-flash", "DeepSeek V4 Flash", [0, 0, 0], 921_600, 131_072, ["text", "image"], MAX_HIGH_LOW),
+  model("poolside/laguna-s-2.1:free", "Laguna S-2.1", [0, 0, 0], 262_144, 131_072, ["text"], ALL_THINKING),
   // ── ClinePass models (measured billing prices) ─────────────────────────
-  model("cline-pass/glm-5.3", "GLM-5.3 (ClinePass)", [1.4, 4.4, 0.26], 1_048_576, 131_072),
-  model("cline-pass/glm-5.2", "GLM-5.2 (ClinePass)", [1.4, 4.4, 0.26], 1_048_576, 262_144),
-  model("cline-pass/kimi-k2.7-code", "Kimi K2.7 Code (ClinePass)", [1.58, 6.67, 0.317], 262_144, 262_144),
-  model("cline-pass/kimi-k2.6", "Kimi K2.6 (ClinePass)", [1.58, 6.67, 0.267], 262_144, 262_144),
-  model("cline-pass/kimi-k3", "Kimi K3 (ClinePass)", [6.0, 30.0, 0.6], 1_048_576, 1_048_576),
-  model("cline-pass/deepseek-v4-pro", "DeepSeek V4 Pro (ClinePass)", [1.65, 4.95, 0.06], 1_024_000, 384_000),
-  model("cline-pass/deepseek-v4-flash", "DeepSeek V4 Flash (ClinePass)", [0.44, 1.32, 0.014], 1_024_000, 384_000),
-  model("cline-pass/mimo-v2.5", "MiMo-V2.5 (ClinePass)", [0.14, 0.28, 0.0028], 1_048_576, 131_072),
-  model("cline-pass/mimo-v2.5-pro", "MiMo-V2.5-Pro (ClinePass)", [0.435, 0.87, 0.0036], 1_048_576, 131_072),
-  model("cline-pass/minimax-m3", "MiniMax M3 (ClinePass)", [0.5, 2.0, 0.1], 524_288, 512_000),
-  model("cline-pass/qwen3.7-plus", "Qwen3.7 Plus (ClinePass)", [0.67, 2.68, 0.067], 1_000_000, 131_072),
-  model("cline-pass/qwen3.7-max", "Qwen3.7 Max (ClinePass)", [4.17, 12.51, 0.83], 1_000_000, 131_072),
-  model("cline-pass/qwen3.8-max", "Qwen3.8 Max (ClinePass)", [2.75, 8.25, 0.344], 1_000_000, 131_072),
+  model("cline-pass/glm-5.3-flash", "GLM-5.3 Flash", [0.15, 0.5, 0.03], 921_600, 131_072, ["text", "image"], MAX_HIGH_LOW_MANDATORY),
+  model("cline-pass/glm-5.3", "GLM-5.3", [1.4, 4.4, 0.26], 921_600, 131_072, ["text", "image"], MAX_HIGH_LOW_MANDATORY),
+  model("cline-pass/glm-5.2", "GLM-5.2", [1.4, 4.4, 0.26], 921_600, 131_072, ["text"], XHIGH_HIGH),
+  model("cline-pass/kimi-k2.7-code", "Kimi K2.7 Code", [1.58, 6.67, 0.32], 262_144, 131_072, ["text", "image"], ALL_MANDATORY),
+  model("cline-pass/kimi-k2.6", "Kimi K2.6", [1.58, 6.67, 0.27], 262_144, 131_072, ["text", "image"], ALL_THINKING),
+  model("cline-pass/kimi-k3", "Kimi K3", [6.0, 30.0, 0.6], 921_600, 131_072, ["text", "image"], MAX_HIGH_LOW),
+  model("cline-pass/deepseek-v4-pro", "DeepSeek V4 Pro", [1.65, 4.95, 0.06], 921_600, 131_072, ["text"], MAX_HIGH_LOW),
+  model("cline-pass/deepseek-v4-flash", "DeepSeek V4 Flash", [0.44, 1.32, 0.014], 921_600, 131_072, ["text", "image"], MAX_HIGH_LOW),
+  model("cline-pass/mimo-v2.5", "MiMo-V2.5", [0.14, 0.28, 0.0028], 921_600, 131_072, ["text"], ALL_THINKING),
+  model("cline-pass/mimo-v2.5-pro", "MiMo-V2.5-Pro", [0.435, 0.87, 0.0036], 921_600, 131_072, ["text"], ALL_THINKING),
+  model("cline-pass/minimax-m3", "MiniMax M3", [0.5, 2.0, 0.1], 921_600, 131_072, ["text", "image"], ALL_THINKING),
+  model("cline-pass/qwen3.7-plus", "Qwen3.7 Plus", [0.67, 2.67, 0.07], 921_600, 131_072, ["text", "image"], ALL_THINKING),
+  model("cline-pass/qwen3.7-max", "Qwen3.7 Max", [4.17, 12.5, 0.83], 921_600, 131_072, ["text"], ALL_THINKING),
+  model("cline-pass/qwen3.8-max", "Qwen3.8 Max", [2.75, 8.25, 0.34], 921_600, 131_072, ["text"], XHIGH_MEDIUM_LOW),
 ];
 
 export function modelIds(): string[] {
   return MODELS.map((m) => m.id);
 }
 
-/** True for the Cline free-tier models (cost 0). */
+/** True for the Cline free-tier models — derived from the catalog itself
+ * (cost 0), so adding a free model never needs a second edit here. */
 export function isFreeModel(id: string): boolean {
-  return id.includes(":free") || id.includes("ox-alpha") || id === "deepseek/deepseek-v4-flash";
+  return MODELS.some((m) => m.id === id && m.cost.input === 0);
 }

package/src/errors.ts

@@ -1,112 +1,114 @@
-/**
- * ClinePass error classification — maps provider error text to friendly,
- * actionable messages surfaced through pi's UI.
- *
- * Classification order matters: the free-model route returns plain
- * `403 Forbidden` when its Cline-CLI header gate rejects us, which must not
- * be reported as a subscription problem, and free-limit errors may arrive
- * wrapped in a generic 403/429 shell.
- */
-
-import { isFreeDeepSeekModel } from "./headers.js";
-
-export type ClinePassErrorType =
-  | "not_subscribed"
-  | "auth_expired"
-  | "rate_limited"
-  | "free_limit_reached"
-  | "free_route_forbidden"
-  | "unknown";
-
-function matchesAny(text: string, patterns: string[]): boolean {
-  return patterns.some((p) => text.includes(p));
-}
-
-export const CLINEPASS_ERROR_MESSAGES: Record<ClinePassErrorType, string> = {
-  not_subscribed:
-    "ClinePass subscription required — or the organization account cannot use ClinePass. " +
-    "Visit app.cline.bot to subscribe / switch to your personal account, or run `pi /login`.",
-  auth_expired:
-    "ClinePass authentication expired. Run `pi /login` and select ClinePass to refresh credentials.",
-  rate_limited:
-    "ClinePass rate limit reached. Wait a moment and try again, or check your plan at app.cline.bot.",
-  free_limit_reached:
-    "Free model rate limit reached. Please wait a few moments and try again.",
-  free_route_forbidden:
-    "Free model route unavailable (HTTP 403). The free DeepSeek route is gated to Cline product " +
-    "surfaces — retry in a moment, or switch to a ClinePass model.",
-  unknown: "ClinePass request failed. Check your subscription at app.cline.bot or run `pi /login`.",
-};
-
-/**
- * Classify a provider error string. `modelId` (the model of the failed
- * request, e.g. "deepseek/deepseek-v4-flash") disambiguates 403s on the
- * free route from subscription problems.
- */
-export function classifyClinePassError(
-  errorMessage: string,
-  modelId?: string,
-): {
-  type: ClinePassErrorType;
-  message: string;
-} {
-  const lower = errorMessage.toLowerCase();
-
-  if (matchesAny(lower, ["401", "unauthorized", "invalid api key", "invalid_api_key"])) {
-    return { type: "auth_expired", message: CLINEPASS_ERROR_MESSAGES.auth_expired };
-  }
-  if (matchesAny(lower, ["429", "rate limit", "too many requests", "rate_limit"])) {
-    return { type: "rate_limited", message: CLINEPASS_ERROR_MESSAGES.rate_limited };
-  }
-  if (matchesAny(lower, ["free limit reached", "free limit", "try again in"])) {
-    return { type: "free_limit_reached", message: CLINEPASS_ERROR_MESSAGES.free_limit_reached };
-  }
-  if (
-    matchesAny(lower, [
-      "403",
-      "forbidden",
-      "subscription required",
-      "not subscribed",
-      "organization accounts cannot use",
-    ])
-  ) {
-    if (modelId && isFreeDeepSeekModel(modelId)) {
-      return { type: "free_route_forbidden", message: CLINEPASS_ERROR_MESSAGES.free_route_forbidden };
-    }
-    return { type: "not_subscribed", message: CLINEPASS_ERROR_MESSAGES.not_subscribed };
-  }
-  return { type: "unknown", message: CLINEPASS_ERROR_MESSAGES.unknown };
-}
-
-export interface ErrorContext {
-  hasUI: boolean;
-  ui: {
-    notify: (msg: string, type: "info" | "warning" | "error") => void;
-  };
-  model?: { provider?: string };
-}
-
-/** Handle a message_end event: classify ClinePass errors and notify. */
-export function handleClinePassError(
-  event: { message: unknown },
-  ctx: ErrorContext,
-): void {
-  if (!event.message) return;
-  const msg = event.message as {
-    stopReason?: string;
-    errorMessage?: string;
-    provider?: string;
-    model?: string;
-  };
-  if (msg.stopReason !== "error" || !msg.errorMessage) return;
-
-  const provider = msg.provider ?? ctx.model?.provider;
-  if (provider !== "clinepass" && provider !== "cline-pass") return;
-
-  const { message: friendly } = classifyClinePassError(msg.errorMessage, msg.model);
-  if (ctx.hasUI) {
-    ctx.ui.notify(friendly, "error");
-  } else {
-    console.error(`[pi-clinepass] ${friendly}`);
-  }
-}
+/**
+ * ClinePass error classification — maps provider error text to friendly,
+ * actionable messages surfaced through pi's UI.
+ *
+ * Classification order matters: the free-model routes return plain
+ * `403 Forbidden` when their Cline-CLI header gate rejects us, which must not
+ * be reported as a subscription problem, and free-limit errors may arrive
+ * wrapped in a generic 403/429 shell.
+ */
+
+import { isFreeModel } from "./catalog.js";
+
+export type ClinePassErrorType =
+  | "not_subscribed"
+  | "auth_expired"
+  | "rate_limited"
+  | "free_limit_reached"
+  | "free_route_forbidden"
+  | "unknown";
+
+function matchesAny(text: string, patterns: string[]): boolean {
+  return patterns.some((p) => text.includes(p));
+}
+
+export const CLINEPASS_ERROR_MESSAGES: Record<ClinePassErrorType, string> = {
+  not_subscribed:
+    "ClinePass subscription required — or the organization account cannot use ClinePass. " +
+    "Visit app.cline.bot to subscribe / switch to your personal account, or run `pi /login`.",
+  auth_expired:
+    "ClinePass authentication expired. Run `pi /login` and select ClinePass to refresh credentials.",
+  rate_limited:
+    "ClinePass rate limit reached. Wait a moment and try again, or check your plan at app.cline.bot.",
+  free_limit_reached:
+    "Free model rate limit reached. Please wait a few moments and try again.",
+  free_route_forbidden:
+    "Free model route unavailable (HTTP 403). The free route is gated to Cline product " +
+    "surfaces — retry in a moment, or switch to a ClinePass model.",
+  unknown: "ClinePass request failed. Check your subscription at app.cline.bot or run `pi /login`.",
+};
+
+/**
+ * Classify a provider error string. `modelId` (the model of the failed
+ * request, e.g. "deepseek/deepseek-v4-flash") disambiguates 403s on free
+ * routes from subscription problems.
+ */
+export function classifyClinePassError(
+  errorMessage: string,
+  modelId?: string,
+): {
+  type: ClinePassErrorType;
+  message: string;
+} {
+  const lower = errorMessage.toLowerCase();
+
+  if (matchesAny(lower, ["401", "unauthorized", "invalid api key", "invalid_api_key"])) {
+    return { type: "auth_expired", message: CLINEPASS_ERROR_MESSAGES.auth_expired };
+  }
+  if (matchesAny(lower, ["429", "rate limit", "too many requests", "rate_limit"])) {
+    return { type: "rate_limited", message: CLINEPASS_ERROR_MESSAGES.rate_limited };
+  }
+  if (matchesAny(lower, ["free limit reached", "free limit", "try again in"])) {
+    return { type: "free_limit_reached", message: CLINEPASS_ERROR_MESSAGES.free_limit_reached };
+  }
+  if (
+    matchesAny(lower, [
+      "403",
+      "forbidden",
+      "subscription required",
+      "not subscribed",
+      "organization accounts cannot use",
+    ])
+  ) {
+    // Every free-tier route is gated to Cline product surfaces — a 403 on a
+    // free model is a route-gate rejection, not a subscription problem.
+    if (modelId && isFreeModel(modelId)) {
+      return { type: "free_route_forbidden", message: CLINEPASS_ERROR_MESSAGES.free_route_forbidden };
+    }
+    return { type: "not_subscribed", message: CLINEPASS_ERROR_MESSAGES.not_subscribed };
+  }
+  return { type: "unknown", message: CLINEPASS_ERROR_MESSAGES.unknown };
+}
+
+export interface ErrorContext {
+  hasUI: boolean;
+  ui: {
+    notify: (msg: string, type: "info" | "warning" | "error") => void;
+  };
+  model?: { provider?: string };
+}
+
+/** Handle a message_end event: classify ClinePass errors and notify. */
+export function handleClinePassError(
+  event: { message: unknown },
+  ctx: ErrorContext,
+): void {
+  if (!event.message) return;
+  const msg = event.message as {
+    stopReason?: string;
+    errorMessage?: string;
+    provider?: string;
+    model?: string;
+  };
+  if (msg.stopReason !== "error" || !msg.errorMessage) return;
+
+  const provider = msg.provider ?? ctx.model?.provider;
+  if (provider !== "clinepass" && provider !== "cline-pass") return;
+
+  const { message: friendly } = classifyClinePassError(msg.errorMessage, msg.model);
+  if (ctx.hasUI) {
+    ctx.ui.notify(friendly, "error");
+  } else {
+    console.error(`[pi-clinepass] ${friendly}`);
+  }
+}

package/src/headers.ts

@@ -1,80 +1,83 @@
-/**
- * Free-model request headers.
- *
- * The gateway gates the free `deepseek/deepseek-v4-flash` route behind
- * "Cline product surfaces" (HTTP 403 without them). We identify as the
- * Cline CLI with a current version fetched from the npm registry, cached
- * for 24h with a bundled fallback. Only the free deepseek model is affected.
- */
-
-import { release } from "node:os";
-
-export const FREE_DEEPSEEK_MODEL = "deepseek/deepseek-v4-flash";
-const FALLBACK_CLINE_VERSION = "3.0.54";
-const VERSION_CACHE_TTL_MS = 24 * 60 * 60 * 1000;
-const NPM_REGISTRY_URL = "https://registry.npmjs.org/cline/latest";
-
-let cachedVersion: string | undefined;
-let cachedAt = 0;
-let inflightVersion: Promise<string> | undefined;
-
-export async function getClineVersion(
-  fetchFn: typeof globalThis.fetch = globalThis.fetch,
-): Promise<string> {
-  if (cachedVersion && Date.now() - cachedAt < VERSION_CACHE_TTL_MS) return cachedVersion;
-  // Deduplicate concurrent callers (e.g. session_start + a command racing).
-  if (inflightVersion) return inflightVersion;
-  inflightVersion = (async () => {
-    try {
-      const res = await fetchFn(NPM_REGISTRY_URL);
-      if (res.ok) {
-        const data = (await res.json()) as { version?: unknown };
-        if (typeof data.version === "string" && data.version) {
-          cachedVersion = data.version;
-          cachedAt = Date.now();
-          return cachedVersion;
-        }
-      }
-    } catch {
-      // fall through to bundled default
-    }
-    // Registry unreachable: use the bundled fallback but do not cache it
-    // for the full TTL — the next session retries so a transient outage
-    // doesn't pin an outdated version for a day.
-    cachedVersion = FALLBACK_CLINE_VERSION;
-    cachedAt = 0;
-    return cachedVersion;
-  })();
-  try {
-    return await inflightVersion;
-  } finally {
-    inflightVersion = undefined;
-  }
-}
-
-export function isFreeDeepSeekModel(modelId: string): boolean {
-  return modelId.includes(FREE_DEEPSEEK_MODEL) && !modelId.includes("cline-pass/");
-}
-
-/** Whether the given model id needs the Cline-CLI identifying headers. */
-export function needsFreeModelHeaders(modelId: string): boolean {
-  return isFreeDeepSeekModel(modelId);
-}
-
-/**
- * Build the headers that make the free deepseek route servable.
- * Synchronous: uses the cached version (pre-warmed at startup or from a
- * previous request), falling back to the bundled default. Never fetches
- * inside a request path.
- */
-export function buildFreeModelHeadersSync(): Record<string, string> {
-  const version = cachedVersion ?? FALLBACK_CLINE_VERSION;
-  return {
-    "x-client-type": "cli",
-    "x-client-version": version,
-    "x-core-version": version,
-    "x-platform": process.platform,
-    "x-platform-version": release(),
-    "user-agent": `Cline/${version}`,
-  };
-}
+/**
+ * Free-model request headers.
+ *
+ * The gateway gates Cline's free routes (":free" / cost-0 models) behind
+ * "Cline product surfaces" (HTTP 403 without them). We identify as the Cline
+ * CLI with a current version fetched from the npm registry, cached for 24h
+ * with a bundled fallback. Every free-tier model goes through this gate, so
+ * the identifying headers are applied to all of them via `isFreeModel`.
+ */
+
+import { release } from "node:os";
+import { isFreeModel } from "./catalog.js";
+
+const FALLBACK_CLINE_VERSION = "3.0.60";
+const VERSION_CACHE_TTL_MS = 24 * 60 * 60 * 1000;
+const NPM_REGISTRY_URL = "https://registry.npmjs.org/cline/latest";
+
+/** Header-safe version shape (semver-ish tokens only): a malformed registry
+ * response must never reach request headers, where control chars would make
+ * undici throw and break the request. */
+const VERSION_PATTERN = /^[\w.\-+]+$/;
+
+let cachedVersion: string | undefined;
+let cachedAt = 0;
+let inflightVersion: Promise<string> | undefined;
+
+export async function getClineVersion(
+  fetchFn: typeof globalThis.fetch = globalThis.fetch,
+): Promise<string> {
+  if (cachedVersion && Date.now() - cachedAt < VERSION_CACHE_TTL_MS) return cachedVersion;
+  // Deduplicate concurrent callers (e.g. session_start + a command racing).
+  if (inflightVersion) return inflightVersion;
+  inflightVersion = (async () => {
+    try {
+      const res = await fetchFn(NPM_REGISTRY_URL);
+      if (res.ok) {
+        const data = (await res.json()) as { version?: unknown };
+        if (typeof data.version === "string" && VERSION_PATTERN.test(data.version)) {
+          cachedVersion = data.version;
+          cachedAt = Date.now();
+          return cachedVersion;
+        }
+      }
+    } catch {
+      // fall through to bundled default
+    }
+    // Registry unreachable: use the bundled fallback but do not cache it
+    // for the full TTL — the next session retries so a transient outage
+    // doesn't pin an outdated version for a day.
+    cachedVersion = FALLBACK_CLINE_VERSION;
+    cachedAt = 0;
+    return cachedVersion;
+  })();
+  try {
+    return await inflightVersion;
+  } finally {
+    inflightVersion = undefined;
+  }
+}
+
+/** Whether the given model id needs the Cline-CLI identifying headers (all
+ * free-tier models do — the free route is gated to Cline product surfaces). */
+export function needsFreeModelHeaders(modelId: string): boolean {
+  return isFreeModel(modelId);
+}
+
+/**
+ * Build the headers that make the free deepseek route servable.
+ * Synchronous: uses the cached version (pre-warmed at startup or from a
+ * previous request), falling back to the bundled default. Never fetches
+ * inside a request path.
+ */
+export function buildFreeModelHeadersSync(): Record<string, string> {
+  const version = cachedVersion ?? FALLBACK_CLINE_VERSION;
+  return {
+    "x-client-type": "cli",
+    "x-client-version": version,
+    "x-core-version": version,
+    "x-platform": process.platform,
+    "x-platform-version": release(),
+    "user-agent": `Cline/${version}`,
+  };
+}