@bitkyc08/opencodex 2.11.1 → 2.12.0

package/src/oauth/login-cli.ts

@@ -4,7 +4,7 @@ import { loadConfig, saveConfig } from "../config";
 import { findLiveProxy, probeHostname } from "../server/proxy-liveness";
 import { isPublicOAuthProvider, listOAuthProviders, runLogin } from "./index";
 import { KEY_LOGIN_PROVIDERS, isKeyLoginProvider, validateApiKey, type KeyLoginProvider } from "./key-providers";
-import type { OcxProviderConfig } from "../types";
+import type { OcxConfig, OcxProviderConfig } from "../types";
 import { configuredAdminToken } from "../lib/admin-secrets";
 import { codexAccountNamespaceProviderCollisionError } from "../codex/account-namespace-match";
 
@@ -102,10 +102,46 @@ export function providerConfigFromKeyLoginProvider(def: KeyLoginProvider, key: s
     ...(def.noPenaltyModels ? { noPenaltyModels: [...def.noPenaltyModels] } : {}),
     ...(def.autoToolChoiceOnlyModels ? { autoToolChoiceOnlyModels: [...def.autoToolChoiceOnlyModels] } : {}),
     ...(def.preserveReasoningContentModels ? { preserveReasoningContentModels: [...def.preserveReasoningContentModels] } : {}),
+    ...(def.requiresReasoningPlaceholderModels ? { requiresReasoningPlaceholderModels: [...def.requiresReasoningPlaceholderModels] } : {}),
     ...(def.escapeBuiltinToolNames !== undefined ? { escapeBuiltinToolNames: def.escapeBuiltinToolNames } : {}),
   };
 }
 
+/**
+ * Merge a freshly built key-login provider row with a previously saved row,
+ * carrying operator-owned fields the key-provider preset cannot know about.
+ * Currently that is the user-configured modelCosts overlay: rotating the API
+ * key must not silently revert Logs/Usage estimates to catalog prices.
+ */
+export function mergeKeyLoginProviderRow(
+  provider: OcxProviderConfig,
+  existing: OcxProviderConfig | undefined,
+): OcxProviderConfig {
+  return {
+    ...provider,
+    ...(existing?.modelCosts !== undefined ? { modelCosts: existing.modelCosts } : {}),
+  };
+}
+
+/**
+ * Commit a fresh key-login provider row: merge operator-owned fields from the
+ * existing row (currently the modelCosts overlay), persist the merged row, and
+ * push the SAME merged row to a running proxy so its live config cannot diverge
+ * from disk (e.g. by replacing the overlay with catalog prices until reload).
+ * Returns the merged row that was persisted and notified.
+ */
+export async function commitKeyLoginProvider(
+  config: OcxConfig,
+  name: string,
+  provider: OcxProviderConfig,
+): Promise<OcxProviderConfig> {
+  const mergedProvider = mergeKeyLoginProviderRow(provider, config.providers[name]);
+  config.providers[name] = mergedProvider;
+  saveConfig(config);
+  await notifyRunningProxy(name, mergedProvider);
+  return mergedProvider;
+}
+
 async function handleKeyLogin(name: string): Promise<void> {
   const def = KEY_LOGIN_PROVIDERS[name];
   const preflightConfig = loadConfig();
@@ -148,9 +184,7 @@ async function handleKeyLogin(name: string): Promise<void> {
     console.error(`Error: ${commitCollision}.`);
     process.exit(1);
   }
-  config.providers[name] = provider;
-  saveConfig(config);
-  await notifyRunningProxy(name, provider);
+  await commitKeyLoginProvider(config, name, provider);
   console.log(`✅ ${def.label} added. Try: ocx sync`);
 }
 

package/src/providers/alibaba-region-migration.ts

@@ -24,7 +24,7 @@ const INTL_ID = "alibaba-token-plan-intl";
  * the one matching the destination's registry contract.
  * `defaultModel` and `note` are user-editable too and are handled below.
  */
-const USER_OWNED_FIELDS = ["apiKey", "apiKeyPool", "disabled", "baseUrl", "allowPrivateNetwork", "liveModels"] as const;
+const USER_OWNED_FIELDS = ["apiKey", "apiKeyPool", "disabled", "baseUrl", "allowPrivateNetwork", "liveModels", "modelCosts"] as const;
 
 export interface AlibabaRegionMigrationProjection {
   config: OcxConfig;

package/src/providers/codex-capacity.ts

@@ -1,3 +1,5 @@
+import { codexPlanKey, codexPlanValue } from "../codex/plan";
+
 export const CODEX_CONFIGURED_CAPACITY_WEIGHTS = {
   plus: 1,
   business: 1,
@@ -22,7 +24,7 @@ export type CodexCapacityQuota = {
 export interface CodexCapacityAccount {
   isMain: boolean;
   active?: boolean;
-  plan?: string | null;
+  plan?: unknown;
   paused: boolean;
   needsReauth?: boolean;
   quota: CodexCapacityQuota | null;
@@ -82,8 +84,8 @@ type MutableWindow = {
   oldestUpdatedAt: number;
 };
 
-function configuredWeight(plan: string | null | undefined): number | undefined {
-  const normalized = plan?.trim().toLowerCase();
+function configuredWeight(plan: unknown): number | undefined {
+  const normalized = codexPlanKey(plan);
   return normalized && Object.hasOwn(CODEX_CONFIGURED_CAPACITY_WEIGHTS, normalized)
     ? CODEX_CONFIGURED_CAPACITY_WEIGHTS[normalized as keyof typeof CODEX_CONFIGURED_CAPACITY_WEIGHTS]
     : undefined;
@@ -168,9 +170,10 @@ export function aggregateCodexPoolCapacity(
   const current = accounts.find(account => account.active)
     ?? accounts.find(account => account.isMain)
     ?? accounts[0];
+  const currentPlan = codexPlanValue(current?.plan);
   const currentAccount = current ? {
     isMain: current.isMain,
-    ...(current.plan !== undefined ? { plan: current.plan } : {}),
+    ...(currentPlan !== undefined ? { plan: currentPlan } : {}),
     quota: currentQuotaForDisplay(current, now),
   } : undefined;
   const windows = new Map<string, MutableWindow>();

package/src/providers/command-code-efforts.ts

@@ -31,7 +31,8 @@ function keyFor(modelId: string): string {
 
 export function commandCodeReasoningEfforts(modelId: string): readonly string[] | undefined {
   const key = keyFor(modelId);
-  return refreshedEfforts.get(key) ?? COMMAND_CODE_MODEL_REASONING_EFFORTS[key];
+  return refreshedEfforts.get(key)
+    ?? (Object.hasOwn(COMMAND_CODE_MODEL_REASONING_EFFORTS, key) ? COMMAND_CODE_MODEL_REASONING_EFFORTS[key] : undefined);
 }
 
 function parsedProfileEfforts(page: string): string[] | undefined {
@@ -59,7 +60,9 @@ export async function refreshCommandCodeReasoningEfforts(
   fetchFn: typeof globalThis.fetch = globalThis.fetch,
 ): Promise<readonly string[] | undefined> {
   const key = keyFor(modelId);
-  const profile = COMMAND_CODE_MODEL_EFFORTS[key as keyof typeof COMMAND_CODE_MODEL_EFFORTS];
+  const profile = Object.hasOwn(COMMAND_CODE_MODEL_EFFORTS, key)
+    ? COMMAND_CODE_MODEL_EFFORTS[key as keyof typeof COMMAND_CODE_MODEL_EFFORTS]
+    : undefined;
   if (!profile) return undefined;
   try {
     const response = await fetchFn(profile.profileUrl, {

package/src/providers/derive.ts

@@ -36,6 +36,7 @@ export interface DerivedKeyLoginProvider {
   noPenaltyModels?: string[];
   autoToolChoiceOnlyModels?: string[];
   preserveReasoningContentModels?: string[];
+  requiresReasoningPlaceholderModels?: string[];
   reasoningSplitModels?: string[];
   thinkingToggleModels?: string[];
   thinkingBudgetModels?: string[];
@@ -109,6 +110,94 @@ function cloneNestedRecord(input: Record<string, Record<string, string>>): Recor
   return Object.fromEntries(Object.entries(input).map(([key, value]) => [key, { ...value }]));
 }
 
+function sameStringArray(left: readonly string[] | undefined, right: readonly string[]): boolean {
+  return left?.length === right.length && left.every((value, index) => value === right[index]);
+}
+
+type DirectReasoningEffortOverrides = Pick<
+  OcxProviderConfig,
+  "thinkingBudgetModels" | "modelReasoningEfforts" | "modelDefaultReasoningEfforts" | "modelReasoningEffortMap"
+>;
+
+function fillFoldedModelDefault<T>(
+  merged: Record<string, T> | undefined,
+  explicit: Record<string, T> | undefined,
+  model: string,
+  registryDefault: T | undefined,
+  clone: (value: T) => T,
+): Record<string, T> | undefined {
+  const folded = model.toLowerCase();
+  const explicitEntries = Object.entries(explicit ?? {}).filter(([key]) => key.toLowerCase() === folded);
+  if (explicitEntries.length === 0) {
+    return registryDefault === undefined ? merged : { ...(merged ?? {}), [model]: clone(registryDefault) };
+  }
+
+  const next = Object.fromEntries(
+    Object.entries(merged ?? {}).filter(([key]) => key.toLowerCase() !== folded),
+  ) as Record<string, T>;
+  for (const [key, value] of explicitEntries) next[key] = clone(value);
+  return next;
+}
+
+/**
+ * Apply a registry-owned direct `reasoning_effort` contract after user/seed metadata is merged.
+ *
+ * Provider presets are persisted with capability metadata, so an existing config can retain an
+ * obsolete thinking-budget classification after the registry learns that a model has a native
+ * effort field. The registry opts only verified model contracts into this repair; providers that
+ * do not resolve through the matching registry entry keep their user-supplied classification.
+ */
+export function applyDirectReasoningEffortContracts(
+  entry: ProviderRegistryEntry,
+  prov: OcxProviderConfig,
+  explicit: DirectReasoningEffortOverrides = prov,
+): void {
+  const models = entry.directReasoningEffortModels;
+  if (!models || models.length === 0) return;
+
+  for (const model of models) {
+    // Old generated presets persisted the direct model at the front of the registry's budget
+    // list. Routing merges registry-first, which moves that one stale entry to the end. Repair
+    // only those two exact generated shapes; any partial, reordered, or case-varied list is a
+    // deliberate user value and remains untouched.
+    const currentBudgetModels = entry.thinkingBudgetModels ?? [];
+    const staleSeedShape = [model, ...currentBudgetModels];
+    const staleRoutedShape = [...currentBudgetModels, model];
+    if (sameStringArray(explicit.thinkingBudgetModels, staleSeedShape)
+      || sameStringArray(explicit.thinkingBudgetModels, staleRoutedShape)) {
+      prov.thinkingBudgetModels = [...currentBudgetModels];
+    }
+
+    const efforts = entry.modelReasoningEfforts?.[model];
+    prov.modelReasoningEfforts = fillFoldedModelDefault(
+      prov.modelReasoningEfforts,
+      explicit.modelReasoningEfforts,
+      model,
+      efforts,
+      value => [...value],
+    );
+
+    const defaultEffort = entry.modelDefaultReasoningEfforts?.[model];
+    prov.modelDefaultReasoningEfforts = fillFoldedModelDefault(
+      prov.modelDefaultReasoningEfforts,
+      explicit.modelDefaultReasoningEfforts,
+      model,
+      defaultEffort,
+      value => value,
+    );
+
+    // An explicit empty model map masks any provider-wide aliases. Without it, a stale global
+    // mapping such as xhigh -> max would win before the verified direct ladder can clamp it.
+    prov.modelReasoningEffortMap = fillFoldedModelDefault(
+      prov.modelReasoningEffortMap,
+      explicit.modelReasoningEffortMap,
+      model,
+      {},
+      value => ({ ...value }),
+    );
+  }
+}
+
 /**
  * Build the provider config a registry entry contributes when a preset is materialized.
  * The registry auth kind is preserved verbatim (including `"local"`) so fail-closed gates
@@ -152,8 +241,12 @@ export function providerConfigSeed(entry: ProviderRegistryEntry): OcxProviderCon
     ...(entry.promptCacheKey !== undefined ? { promptCacheKey: entry.promptCacheKey } : {}),
     ...(entry.responsesPath !== undefined ? { responsesPath: entry.responsesPath } : {}),
     ...(entry.statelessResponses !== undefined ? { statelessResponses: entry.statelessResponses } : {}),
+    ...(entry.requiresAdjacentResponsesToolResults !== undefined
+      ? { requiresAdjacentResponsesToolResults: entry.requiresAdjacentResponsesToolResults }
+      : {}),
     ...(entry.autoToolChoiceOnlyModels ? { autoToolChoiceOnlyModels: [...entry.autoToolChoiceOnlyModels] } : {}),
     ...(entry.preserveReasoningContentModels ? { preserveReasoningContentModels: [...entry.preserveReasoningContentModels] } : {}),
+    ...(entry.requiresReasoningPlaceholderModels ? { requiresReasoningPlaceholderModels: [...entry.requiresReasoningPlaceholderModels] } : {}),
     ...(entry.reasoningSplitModels ? { reasoningSplitModels: [...entry.reasoningSplitModels] } : {}),
     ...(entry.thinkingToggleModels ? { thinkingToggleModels: [...entry.thinkingToggleModels] } : {}),
     ...(entry.thinkingBudgetModels ? { thinkingBudgetModels: [...entry.thinkingBudgetModels] } : {}),
@@ -199,6 +292,7 @@ export function deriveKeyLoginMap(): Record<string, DerivedKeyLoginProvider> {
       ...(entry.noPenaltyModels ? { noPenaltyModels: [...entry.noPenaltyModels] } : {}),
       ...(entry.autoToolChoiceOnlyModels ? { autoToolChoiceOnlyModels: [...entry.autoToolChoiceOnlyModels] } : {}),
       ...(entry.preserveReasoningContentModels ? { preserveReasoningContentModels: [...entry.preserveReasoningContentModels] } : {}),
+      ...(entry.requiresReasoningPlaceholderModels ? { requiresReasoningPlaceholderModels: [...entry.requiresReasoningPlaceholderModels] } : {}),
       ...(entry.reasoningSplitModels ? { reasoningSplitModels: [...entry.reasoningSplitModels] } : {}),
       ...(entry.thinkingToggleModels ? { thinkingToggleModels: [...entry.thinkingToggleModels] } : {}),
       ...(entry.thinkingBudgetModels ? { thinkingBudgetModels: [...entry.thinkingBudgetModels] } : {}),
@@ -293,6 +387,12 @@ export function enrichProviderFromRegistry(name: string, prov: OcxProviderConfig
     enrichReasoningSummariesByDestination(prov);
     return;
   }
+  const explicitDirectReasoning: DirectReasoningEffortOverrides = {
+    thinkingBudgetModels: prov.thinkingBudgetModels,
+    modelReasoningEfforts: prov.modelReasoningEfforts,
+    modelDefaultReasoningEfforts: prov.modelDefaultReasoningEfforts,
+    modelReasoningEffortMap: prov.modelReasoningEffortMap,
+  };
   const seed = providerConfigSeed(entry);
   if (prov.apiKeyTransport === undefined && seed.apiKeyTransport !== undefined) prov.apiKeyTransport = seed.apiKeyTransport;
   if (!prov.defaultModel && seed.defaultModel) prov.defaultModel = seed.defaultModel;
@@ -323,6 +423,9 @@ export function enrichProviderFromRegistry(name: string, prov: OcxProviderConfig
   // learned this route still gets backfilled.
   if (prov.responsesPath === undefined && seed.responsesPath !== undefined) prov.responsesPath = seed.responsesPath;
   if (prov.statelessResponses === undefined && seed.statelessResponses !== undefined) prov.statelessResponses = seed.statelessResponses;
+  if (prov.requiresAdjacentResponsesToolResults === undefined && seed.requiresAdjacentResponsesToolResults !== undefined) {
+    prov.requiresAdjacentResponsesToolResults = seed.requiresAdjacentResponsesToolResults;
+  }
   // Registry-only metadata (never seeded into saved config): backfill straight from
   // the entry so an explicit user value stays distinguishable from the default.
   if (prov.supportsServiceTier === undefined && entry.supportsServiceTier !== undefined) prov.supportsServiceTier = entry.supportsServiceTier;
@@ -345,6 +448,7 @@ export function enrichProviderFromRegistry(name: string, prov: OcxProviderConfig
   }
   if (!prov.autoToolChoiceOnlyModels && seed.autoToolChoiceOnlyModels) prov.autoToolChoiceOnlyModels = [...seed.autoToolChoiceOnlyModels];
   if (!prov.preserveReasoningContentModels && seed.preserveReasoningContentModels) prov.preserveReasoningContentModels = [...seed.preserveReasoningContentModels];
+  if (!prov.requiresReasoningPlaceholderModels && seed.requiresReasoningPlaceholderModels) prov.requiresReasoningPlaceholderModels = [...seed.requiresReasoningPlaceholderModels];
   if (!prov.reasoningSplitModels && seed.reasoningSplitModels) prov.reasoningSplitModels = [...seed.reasoningSplitModels];
   if (!prov.thinkingToggleModels && seed.thinkingToggleModels) prov.thinkingToggleModels = [...seed.thinkingToggleModels];
   if (!prov.thinkingBudgetModels && seed.thinkingBudgetModels) prov.thinkingBudgetModels = [...seed.thinkingBudgetModels];
@@ -353,6 +457,7 @@ export function enrichProviderFromRegistry(name: string, prov: OcxProviderConfig
   if (prov.freeTier === undefined && seed.freeTier !== undefined) prov.freeTier = seed.freeTier;
   if (prov.modelSuffixBracketStrip === undefined && seed.modelSuffixBracketStrip !== undefined) prov.modelSuffixBracketStrip = seed.modelSuffixBracketStrip;
   if (!prov.headers && seed.headers) prov.headers = { ...seed.headers };
+  applyDirectReasoningEffortContracts(entry, prov, explicitDirectReasoning);
 }
 
 export function deriveFeaturedProviderIds(): string[] {

package/src/providers/label.ts

@@ -1,6 +1,6 @@
 import { CODEX_ACCOUNT_LOG_LABEL_RE } from "../codex/account-label";
 
-function canonicalUsageProviderLabel(provider: string): string {
+export function canonicalUsageProviderLabel(provider: string): string {
   return provider === "chatgpt" || provider === "openai-multi" ? "openai" : provider;
 }
 

package/src/providers/openai-tiers.ts

@@ -1,5 +1,6 @@
-import type { CodexAccountMode, OcxConfig, OcxProviderConfig } from "../types";
+import type { CodexAccountMode, OcxConfig, OcxProviderConfig, ProviderCostOverlay } from "../types";
 import { OPENAI_PROVIDER_TIER_VERSION } from "../types";
+import { MAX_COST4_RATE } from "../usage/expected-prices";
 
 export const OPENAI_CODEX_PROVIDER_ID = "openai";
 export const LEGACY_OPENAI_MULTI_PROVIDER_ID = "openai-multi";
@@ -69,11 +70,17 @@ export class OpenAiTierMigrationCollisionError extends Error {
   }
 }
 
-function managedLegacyMultiOverlay(provider: OcxProviderConfig): Pick<OcxProviderConfig, "disabled" | "selectedModels"> | null {
-  const allowed = new Set(["adapter", "authMode", "baseUrl", "disabled", "selectedModels"]);
+function managedLegacyMultiOverlay(
+  provider: OcxProviderConfig,
+): Pick<OcxProviderConfig, "disabled" | "selectedModels" | "modelCosts"> | null {
+  const allowed = new Set(["adapter", "authMode", "baseUrl", "disabled", "selectedModels", "modelCosts"]);
   if (!Object.keys(provider).every(key => allowed.has(key))) return null;
   if (!isCanonicalOpenAiForwardProvider(provider)) return null;
   if (provider.disabled !== undefined && typeof provider.disabled !== "boolean") return null;
+  // Keep the migration self-contained: a malformed overlay is a collision, not
+  // something to carry into the canonical row (importing config.ts here would
+  // create an import cycle — config.ts already imports this module).
+  if (provider.modelCosts !== undefined && !validLegacyOverlayCosts(provider.modelCosts)) return null;
   if (provider.selectedModels !== undefined && (
     !Array.isArray(provider.selectedModels)
     || provider.selectedModels.some(model => typeof model !== "string")
@@ -81,9 +88,26 @@ function managedLegacyMultiOverlay(provider: OcxProviderConfig): Pick<OcxProvide
   return {
     ...(provider.disabled !== undefined ? { disabled: provider.disabled } : {}),
     ...(provider.selectedModels !== undefined ? { selectedModels: [...provider.selectedModels] } : {}),
+    ...(provider.modelCosts !== undefined ? { modelCosts: provider.modelCosts } : {}),
   };
 }
 
+/** Shape check for a legacy overlay: a plain record of complete non-negative finite Cost4 rows. */
+function validLegacyOverlayCosts(value: unknown): boolean {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const fields = ["input", "output", "cacheRead", "cacheWrite"] as const;
+  return Object.values(value as Record<string, unknown>).every(entry => {
+    if (!entry || typeof entry !== "object" || Array.isArray(entry)) return false;
+    const rates = entry as Record<string, unknown>;
+    return Object.keys(rates).length === fields.length
+      && fields.every(key => Object.hasOwn(rates, key)
+        && typeof rates[key] === "number"
+        && Number.isFinite(rates[key])
+        && (rates[key] as number) >= 0
+        && (rates[key] as number) <= MAX_COST4_RATE);
+  });
+}
+
 function rewriteLegacyOpenAiSelectedId(value: string): string {
   return value.startsWith(LEGACY_OPENAI_MULTI_PREFIX)
     ? value.slice(LEGACY_OPENAI_MULTI_PREFIX.length)
@@ -95,6 +119,28 @@ function rewriteLegacyOpenAiModelList(values: string[] | undefined): string[] |
   return [...new Set(values.map(rewriteLegacyOpenAiSelectedId))];
 }
 
+/**
+ * Rewrite legacy `openai-multi/<model>` keys in a modelCosts overlay so the
+ * prices still match after the migration resolves logs as provider `openai`
+ * with the bare model id. Keys without the legacy prefix pass through.
+ */
+function rewriteLegacyOpenAiCostKeys(costs: Record<string, ProviderCostOverlay> | undefined): Record<string, ProviderCostOverlay> {
+  // Null-prototype map so prototype-named model ids (e.g. "__proto__") are
+  // stored as own properties instead of invoking the inherited setter.
+  const rewritten = Object.create(null) as Record<string, ProviderCostOverlay>;
+  if (costs) {
+    for (const [key, value] of Object.entries(costs)) {
+      const canonicalKey = rewriteLegacyOpenAiSelectedId(key);
+      // A bare <model> key always wins over its openai-multi/<model> equivalent
+      // inside the same row, regardless of JSON property order.
+      if (key === canonicalKey || !Object.hasOwn(rewritten, canonicalKey)) {
+        rewritten[canonicalKey] = value;
+      }
+    }
+  }
+  return rewritten;
+}
+
 function mergeLegacyOpenAiProviderRows(
   openai: OcxProviderConfig | undefined,
   legacyMulti: OcxProviderConfig | undefined,
@@ -104,12 +150,22 @@ function mergeLegacyOpenAiProviderRows(
     ...(openai?.selectedModels ?? []),
     ...(legacyMulti?.selectedModels ?? []),
   ]);
+  // Both rows can carry disjoint overlays; merge them (canonical openai wins on
+  // key conflicts) so legacy Multi prices are not silently dropped. Keys are
+  // rewritten first so `openai-multi/<model>` entries still resolve after the
+  // provider is canonicalized to `openai`.
+  const modelCosts = {
+    ...rewriteLegacyOpenAiCostKeys(legacyMulti?.modelCosts),
+    ...rewriteLegacyOpenAiCostKeys(openai?.modelCosts),
+  };
+  const hasModelCosts = Object.keys(modelCosts).length > 0;
   const formerRows = [openai, legacyMulti].filter((row): row is OcxProviderConfig => row !== undefined);
   const disabled = formerRows.length > 0 && formerRows.every(row => row.disabled === true);
   return {
     ...canonicalCodexForwardProvider(mode),
     ...(disabled ? { disabled: true } : {}),
     ...(selectedModels && selectedModels.length > 0 ? { selectedModels } : {}),
+    ...(hasModelCosts ? { modelCosts } : {}),
   };
 }
 

package/src/providers/opencode-zen-rate-limit.ts

@@ -0,0 +1,102 @@
+/**
+ * OpenCode Zen short-window rate-limit guidance (#1145 / OCX-56).
+ *
+ * OpenCode's keyed and keyless Zen chat endpoints share `https://opencode.ai/zen/v1`.
+ * Free-model traffic can hit a short-window burst ceiling around 15–20 RPM
+ * (community-measured). Zen often answers with opaque `429 Rate limit exceeded`
+ * bodies and may omit `Retry-After` / `X-RateLimit-*`; when those headers are
+ * present they still take precedence. Distinct from the keyless desktop
+ * ~200 requests / 5h quota documented on `opencode-free`.
+ */
+import { validateClientRetryAfterHeader } from "../lib/retry-after";
+import { registryEntryForProviderDestination } from "./registry";
+
+const OPENCODE_ZEN_PROVIDER_IDS = new Set(["opencode-zen", "opencode-free"]);
+
+/** Observed free-model burst ceiling on Zen (not an official OpenCode figure). */
+export const OPENCODE_ZEN_OBSERVED_RPM_HINT = "roughly 15-20 requests per minute";
+
+/**
+ * Synthetic client backoff when Zen omits Retry-After after a rate-limit 429.
+ * Longer than the generic 2s default so Codex-shaped clients do not immediately
+ * re-hammer a ~15-20 RPM window.
+ */
+export const OPENCODE_ZEN_SYNTHETIC_RETRY_AFTER_SEC = 15;
+
+const ENRICHMENT_MARKER = "15-20 requests per minute";
+
+export function isOpenCodeZenRateLimitProvider(opts: {
+  providerName?: string;
+  baseUrl?: string;
+  adapter?: string;
+}): boolean {
+  const name = opts.providerName?.trim();
+  if (name && OPENCODE_ZEN_PROVIDER_IDS.has(name)) return true;
+  const baseUrl = opts.baseUrl?.trim();
+  if (!baseUrl) return false;
+  const entry = registryEntryForProviderDestination({
+    baseUrl,
+    adapter: opts.adapter?.trim() || "openai-chat",
+    authMode: "key",
+  });
+  return entry !== undefined && OPENCODE_ZEN_PROVIDER_IDS.has(entry.id);
+}
+
+/**
+ * Same-key `retryOn429` only applies on key-authenticated HTTP paths — not
+ * keyless `opencode-free` traffic and not custom `runTurn` transports.
+ */
+export function supportsOpenCodeZenRetryOn429Guidance(opts: {
+  authMode?: string;
+  hasApiKey?: boolean;
+  supportsHttpSameKeyRetry?: boolean;
+}): boolean {
+  if (opts.supportsHttpSameKeyRetry === false) return false;
+  if (opts.authMode !== undefined && opts.authMode !== "key") return false;
+  return opts.hasApiKey === true;
+}
+
+/**
+ * Append actionable Zen rate-limit context to a generic upstream 429 message and
+ * embed a parseable `try again in Ns` hint so {@link resolveClientRetryAfter}
+ * surfaces a useful Retry-After when the gateway sent none.
+ */
+export function enrichOpenCodeZenRateLimitMessage(
+  message: string,
+  opts: {
+    status: number;
+    providerName?: string;
+    baseUrl?: string;
+    adapter?: string;
+    authMode?: string;
+    hasApiKey?: boolean;
+    /** Upstream Retry-After header; when valid, skip the synthetic 15s text hint. */
+    upstreamRetryAfter?: string | null;
+    /** False for custom `runTurn` transports outside the HTTP retry loop. */
+    supportsHttpSameKeyRetry?: boolean;
+    now?: number;
+  },
+): string {
+  if (opts.status !== 429) return message;
+  if (!isOpenCodeZenRateLimitProvider(opts)) return message;
+  if (!/rate\s*limit/i.test(message)) return message;
+  if (message.includes(ENRICHMENT_MARKER)) return message;
+
+  const upstreamRetry = validateClientRetryAfterHeader(
+    opts.upstreamRetryAfter,
+    opts.now ?? Date.now(),
+  );
+  const retryHint = upstreamRetry || /try again in \d/i.test(message)
+    ? ""
+    : ` Try again in ${OPENCODE_ZEN_SYNTHETIC_RETRY_AFTER_SEC}s.`;
+  const paceHint = supportsOpenCodeZenRetryOn429Guidance(opts)
+    ? " Slow the request pace, or set providers.opencode-zen.retryOn429 for same-key backoff."
+    : " Slow the request pace.";
+  return (
+    `${message}`
+    + ` OpenCode Zen free-model traffic is often limited to ${OPENCODE_ZEN_OBSERVED_RPM_HINT}`
+    + ` (observed; OpenCode does not publish this RPM, and may omit rate-limit headers).`
+    + `${retryHint}`
+    + paceHint
+  );
+}