@bitkyc08/opencodex 2.40.0 → 2.42.0

package/src/server/auth-cors.ts

@@ -749,73 +749,258 @@ export function copyIfDefined<K extends keyof OcxProviderConfig>(
   if (value !== undefined) out[key as string] = value as unknown;
 }
 
+/**
+ * Exhaustive provider-field policy shared by dashboard redaction and editor
+ * admission. `satisfies Record<keyof OcxProviderConfig, ...>` makes a newly added
+ * provider field fail typecheck until it is deliberately classified.
+ *
+ * `editor` fields are user-authored, `redacted` fields may contain credentials,
+ * and `runtime` fields are observations/limits that must never become editor write
+ * authority. MCP and desktop executor blocks are redacted as a whole because both
+ * contain arbitrary environment variables and/or headers.
+ */
+type ProviderConfigFieldPolicy = "editor" | "redacted" | "runtime";
+
+const PROVIDER_CONFIG_FIELD_POLICY = {
+  alias: "editor",
+  modelAliases: "editor",
+  modelDisplayNames: "editor",
+  defaultAliases: "editor",
+  adapter: "editor",
+  codexToolMode: "editor",
+  requestPacing: "editor",
+  mcpMaxTools: "editor",
+  mcpMaxSchemaBytes: "editor",
+  mcpMaxResultBytes: "editor",
+  modelAdapters: "editor",
+  fastWire: "editor",
+  baseUrl: "editor",
+  responsesPath: "editor",
+  commandCodeVersion: "editor",
+  statelessResponses: "editor",
+  requiresAdjacentResponsesToolResults: "editor",
+  annotateEmptyToolOutputs: "editor",
+  supportsServiceTier: "editor",
+  modelSupportsServiceTier: "editor",
+  preserveResponsesReasoningContent: "editor",
+  decodesNativeCompactionBlobs: "editor",
+  allowPrivateNetwork: "editor",
+  upstreamHttpVersion: "editor",
+  upstreamWebsocket: "editor",
+  directGeminiWireRenames: "editor",
+  disabled: "editor",
+  codexAccountMode: "editor",
+  apiKey: "redacted",
+  apiKeyTransport: "editor",
+  apiKeyPool: "redacted",
+  defaultModel: "editor",
+  models: "editor",
+  liveModels: "editor",
+  selectedModels: "editor",
+  retainModels: "editor",
+  newModelPolicy: "editor",
+  modelPreset: "editor",
+  contextWindow: "editor",
+  modelContextWindows: "editor",
+  modelInputModalities: "editor",
+  modelMaxInputTokens: "runtime",
+  modelAutoCompactTokenLimits: "editor",
+  defaultMaxOutputTokens: "editor",
+  modelMaxOutputTokens: "editor",
+  modelCosts: "editor",
+  headers: "redacted",
+  openRouterRouting: "editor",
+  modelOpenRouterRouting: "editor",
+  vercelGatewayRouting: "editor",
+  modelVercelGatewayRouting: "editor",
+  authMode: "editor",
+  oauthAccountFailover: "editor",
+  keyOptional: "editor",
+  freeTier: "editor",
+  note: "editor",
+  modelSuffixBracketStrip: "editor",
+  refreshPolicy: "editor",
+  reasoningEfforts: "editor",
+  modelReasoningEfforts: "editor",
+  modelDefaultReasoningEfforts: "editor",
+  modelSupportsReasoningSummaries: "editor",
+  modelSupportsVerbosity: "editor",
+  supportsVerbosity: "editor",
+  modelReasoningSummaryDelivery: "editor",
+  modelPreferHostedTools: "editor",
+  supportsOpenAiWebSearchToolFields: "editor",
+  xaiResponsesXSearch: "editor",
+  supportsResponsesCustomTools: "editor",
+  responsesSnapshotRepair: "editor",
+  reasoningEffortMap: "editor",
+  modelReasoningEffortMap: "editor",
+  reasoningWireFormat: "editor",
+  noReasoningModels: "editor",
+  noTemperatureModels: "editor",
+  noTopPModels: "editor",
+  noPenaltyModels: "editor",
+  noStructuredOutputModels: "editor",
+  omitReasoningEffortWithToolsModels: "editor",
+  parallelToolCalls: "editor",
+  pinParallelToolCallsFalse: "editor",
+  terminalContinuationGuard: "editor",
+  openaiChatEofTolerance: "editor",
+  promptCacheKey: "editor",
+  chatServiceTier: "editor",
+  responsesItemIdRepair: "editor",
+  autoToolChoiceOnlyModels: "editor",
+  preserveReasoningContentModels: "editor",
+  requiresReasoningPlaceholderModels: "editor",
+  retryOn429: "editor",
+  transientRetryOn5xx: "editor",
+  reasoningSplitModels: "editor",
+  reasoningDetailsModels: "editor",
+  thinkingToggleModels: "editor",
+  thinkingBudgetModels: "editor",
+  escapeBuiltinToolNames: "editor",
+  anthropicEofTolerance: "editor",
+  noVisionModels: "editor",
+  googleMode: "editor",
+  project: "editor",
+  location: "editor",
+  mcpServers: "redacted",
+  desktopExecutor: "redacted",
+  unsafeAllowNativeLocalExec: "editor",
+  nativeLocalExec: "editor",
+} as const satisfies Record<keyof OcxProviderConfig, ProviderConfigFieldPolicy>;
+
+type ProviderFieldWithPolicy<Policy extends ProviderConfigFieldPolicy> = {
+  [Field in keyof typeof PROVIDER_CONFIG_FIELD_POLICY]:
+    typeof PROVIDER_CONFIG_FIELD_POLICY[Field] extends Policy ? Field : never;
+}[keyof typeof PROVIDER_CONFIG_FIELD_POLICY];
+
+type RedactedProviderField = ProviderFieldWithPolicy<"redacted">;
+type RuntimeProviderField = ProviderFieldWithPolicy<"runtime">;
+export const REDACTED_PROVIDER_FIELDS = Object.freeze(Object.entries(PROVIDER_CONFIG_FIELD_POLICY)
+  .filter(([, policy]) => policy === "redacted")
+  .map(([field]) => field as RedactedProviderField));
+const RUNTIME_PROVIDER_FIELDS = Object.freeze(Object.entries(PROVIDER_CONFIG_FIELD_POLICY)
+  .filter(([, policy]) => policy === "runtime")
+  .map(([field]) => field as RuntimeProviderField));
+
+const PROVIDER_EDITOR_DERIVED_FIELDS = [
+  ...RUNTIME_PROVIDER_FIELDS,
+  ...FORBIDDEN_PROVIDER_RUNTIME_FIELDS,
+  "fetch",
+  "hasApiKey",
+  "hasHeaders",
+  "xaiResponsesOptInState",
+] as const;
+
+export const PROVIDER_EDITOR_DENIED_FIELDS = [
+  ...REDACTED_PROVIDER_FIELDS,
+  ...PROVIDER_EDITOR_DERIVED_FIELDS,
+] as const;
+
+export type ProviderEditorProviderDTO = Omit<OcxProviderConfig, RedactedProviderField | RuntimeProviderField>
+  & Record<string, unknown>;
+
+export interface ProviderEditorConfigDTO {
+  defaultProvider: string;
+  providers: Record<string, ProviderEditorProviderDTO>;
+}
+
+export type ProviderEditorConfigParseResult =
+  | { ok: true; value: ProviderEditorConfigDTO }
+  | { ok: false; error: string; code: "invalid_provider_editor_body" | "invalid_provider_editor_field" };
+
+const PROVIDER_EDITOR_DENIED_FIELD_SET = new Set<string>(PROVIDER_EDITOR_DENIED_FIELDS);
+const PROVIDER_CONFIG_FIELD_SET = new Set<string>(Object.keys(PROVIDER_CONFIG_FIELD_POLICY));
+
+function isPlainDataRecord(value: unknown): value is Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+}
+
+/**
+ * Project one provider through the same redaction path used by both the public
+ * config DTO and the raw editor. Persisted unknown fields remain on disk but are
+ * not exposed until OcxProviderConfig classifies them as editor-safe.
+ */
+function providerEditorProviderDTO(name: string, provider: OcxProviderConfig): ProviderEditorProviderDTO {
+  const dto = Object.fromEntries(Object.entries(provider)
+    .filter(([field]) => PROVIDER_CONFIG_FIELD_SET.has(field) && !PROVIDER_EDITOR_DENIED_FIELD_SET.has(field))
+    .map(([field, value]) => [field, structuredClone(value)])) as Record<string, unknown>;
+  dto.baseUrl = publicProviderBaseUrl(provider.baseUrl);
+  const modelCosts = sanitizeModelCostsForDisplay(provider.modelCosts);
+  if (modelCosts) dto.modelCosts = modelCosts;
+  else delete dto.modelCosts;
+
+  const registryNote = (providerMatchesRegistryTransport(name, provider)
+    ? getProviderRegistryEntry(name)
+    : registryEntryForProviderDestination(provider))?.note;
+  if (typeof registryNote === "string" && registryNote.trim()) dto.note = registryNote;
+  const codexAccountMode = providerCodexAccountMode(name, provider);
+  if (codexAccountMode) dto.codexAccountMode = codexAccountMode;
+  return dto as ProviderEditorProviderDTO;
+}
+
+/** The complete non-secret provider shape the raw GUI editor may round-trip. */
+export function providerEditorConfigDTO(config: OcxConfig): ProviderEditorConfigDTO {
+  const providers: Record<string, ProviderEditorProviderDTO> = Object.create(null);
+  for (const [name, provider] of Object.entries(config.providers)) {
+    providers[name] = providerEditorProviderDTO(name, provider);
+  }
+  return { defaultProvider: config.defaultProvider, providers };
+}
+
+/** Parse an editor snapshot; unknown, redacted, and derived fields fail closed. */
+export function parseProviderEditorConfigDTO(value: unknown): ProviderEditorConfigParseResult {
+  if (!isPlainDataRecord(value)) {
+    return { ok: false, error: "provider editor config must be a plain object", code: "invalid_provider_editor_body" };
+  }
+  const rootKeys = Object.keys(value);
+  if (rootKeys.length !== 2 || !Object.hasOwn(value, "defaultProvider") || !Object.hasOwn(value, "providers")) {
+    return { ok: false, error: "provider editor config must contain only defaultProvider and providers", code: "invalid_provider_editor_body" };
+  }
+  if (typeof value.defaultProvider !== "string" || value.defaultProvider.trim() === "") {
+    return { ok: false, error: "defaultProvider must be a non-empty string", code: "invalid_provider_editor_body" };
+  }
+  if (!isPlainDataRecord(value.providers)) {
+    return { ok: false, error: "providers must be a plain object", code: "invalid_provider_editor_body" };
+  }
+
+  const providers: Record<string, ProviderEditorProviderDTO> = Object.create(null);
+  for (const [name, provider] of Object.entries(value.providers)) {
+    if (!isPlainDataRecord(provider)) {
+      return { ok: false, error: `provider ${JSON.stringify(redactSecretString(name))} must be a plain object`, code: "invalid_provider_editor_body" };
+    }
+    const deniedField = Object.keys(provider).find(field =>
+      !PROVIDER_CONFIG_FIELD_SET.has(field) || PROVIDER_EDITOR_DENIED_FIELD_SET.has(field));
+    if (deniedField) {
+      return {
+        ok: false,
+        error: `provider ${JSON.stringify(redactSecretString(name))} contains non-editable field ${JSON.stringify(redactSecretString(deniedField))}`,
+        code: "invalid_provider_editor_field",
+      };
+    }
+    providers[name] = structuredClone(provider) as ProviderEditorProviderDTO;
+  }
+  return {
+    ok: true,
+    value: { defaultProvider: value.defaultProvider, providers },
+  };
+}
+
 /** Public dashboard DTO for config.json: provider entries with secrets stripped and documented fields exposed (including `modelCosts`). */
 export function safeConfigDTO(config: OcxConfig): unknown {
+  const editor = providerEditorConfigDTO(config);
   const providers: Record<string, Record<string, unknown>> = {};
   for (const [name, provider] of Object.entries(config.providers)) {
     const dto: Record<string, unknown> = {
-      adapter: provider.adapter,
-      baseUrl: publicProviderBaseUrl(provider.baseUrl),
+      ...editor.providers[name],
       hasApiKey: !!provider.apiKey,
       hasHeaders: !!provider.headers && Object.keys(provider.headers).length > 0,
     };
     if (name === "xai") {
       dto.xaiResponsesOptInState = xaiResponsesOptInState(provider);
     }
-    for (const key of [
-      "defaultModel",
-      "alias",
-      "modelAliases",
-      "defaultAliases",
-      "disabled",
-      "allowPrivateNetwork",
-      "authMode",
-      "apiKeyTransport",
-      "keyOptional",
-      "freeTier",
-      "liveModels",
-      "requestPacing",
-      "models",
-      "contextWindow",
-      "modelContextWindows",
-      "modelAutoCompactTokenLimits",
-      "defaultMaxOutputTokens",
-      "modelMaxOutputTokens",
-      "openRouterRouting",
-      "modelOpenRouterRouting",
-      "vercelGatewayRouting",
-      "modelVercelGatewayRouting",
-      "reasoningEfforts",
-      "modelReasoningEfforts",
-      "reasoningWireFormat",
-      "noVisionModels",
-      "noReasoningModels",
-      "noTemperatureModels",
-      "noTopPModels",
-      "noPenaltyModels",
-      "noStructuredOutputModels",
-      "retainModels",
-      "omitReasoningEffortWithToolsModels",
-      "upstreamHttpVersion",
-      "autoToolChoiceOnlyModels",
-      "preserveReasoningContentModels",
-      "requiresReasoningPlaceholderModels",
-      "escapeBuiltinToolNames",
-    ] as const) {
-      copyIfDefined(dto, provider, key);
-    }
-    const modelCosts = sanitizeModelCostsForDisplay(provider.modelCosts);
-    if (modelCosts) dto.modelCosts = modelCosts;
-    // Resolve the note by DESTINATION, not by name. A preset saved under a custom name is
-    // still pointed at the same vendor route, and a usage restriction the user needs to see
-    // must not disappear because the row was renamed. Prefer the same-name entry so an
-    // unrenamed provider keeps its exact registry note.
-    const registryNote = (providerMatchesRegistryTransport(name, provider)
-      ? getProviderRegistryEntry(name)
-      : registryEntryForProviderDestination(provider))?.note;
-    if (typeof registryNote === "string" && registryNote.trim()) dto.note = registryNote;
-    const codexAccountMode = providerCodexAccountMode(name, provider);
-    if (codexAccountMode) dto.codexAccountMode = codexAccountMode;
     providers[name] = dto;
   }
   return {

package/src/server/chat-completions.ts

@@ -46,6 +46,7 @@ import {
   type TranslatorBudget,
 } from "../lib/translator-budget";
 import { handleNativeChatCompletions, isNativeChatRouteEligible } from "./chat-native";
+import { parseRequestEffortRowId } from "./effort-row";
 
 type Rec = Record<string, unknown>;
 
@@ -104,6 +105,8 @@ async function handleChatCompletionsWithBudget(
   }
 
   const requestedModel = chatBody.model as string;
+  const effortRow = parseRequestEffortRowId(requestedModel, config);
+  if (effortRow) chatBody.model = effortRow.baseId;
   const stream = chatBody.stream === true;
   // Best-effort Grok attribution: the managed fence stamps this header on every model
   // it registers (extra_headers, sent verbatim by upstream Grok). Dashboard usage
@@ -113,7 +116,7 @@ async function handleChatCompletionsWithBudget(
   let settledRoute: ReturnType<typeof routeModel> | null = null;
   let chatNativeRoute: ReturnType<typeof routeModel> | null = null;
   try {
-    const route = routeModel(config, requestedModel, evidenceFromBody(chatBody));
+    const route = routeModel(config, chatBody.model as string, evidenceFromBody(chatBody));
     // Settle the wire once so every branch below reads the adapter this model will
     // actually use, not the provider-wide default (#404).
     route.provider = resolveWireProtocolOverride(route.providerName, route.modelId, route.provider, "chat");
@@ -133,7 +136,7 @@ async function handleChatCompletionsWithBudget(
       if (chatBody.tools !== undefined) parts.push(JSON.stringify(chatBody.tools));
       logCtx.usageLogInputTokens = Math.max(1, estimateTokens(parts.join("\n"), requestedModel));
     }
-    if (isNativeChatRouteEligible(route, chatBody)) chatNativeRoute = route;
+    if (!effortRow && isNativeChatRouteEligible(route, chatBody)) chatNativeRoute = route;
   } catch (err) {
     if (err instanceof NoEligiblePolicyCandidateError) {
       logCtx.routeDecision = err.trace;
@@ -162,6 +165,12 @@ async function handleChatCompletionsWithBudget(
     // Validate the full Chat boundary after routing. Native Chat keeps `chatBody` as
     // its wire source; this Responses projection is used only by the fallback path.
     internalBody = chatCompletionsToResponsesBody(chatBody);
+    if (effortRow) {
+      internalBody.reasoning = {
+        ...(isRec(internalBody.reasoning) ? internalBody.reasoning : {}),
+        effort: effortRow.effort,
+      };
+    }
   } catch (err) {
     const overflow = isTranslatorBudgetExceededError(err);
     const status = overflow ? 413 : err instanceof ChatCompletionsRequestError ? 400 : 500;

package/src/server/chat-native.ts

@@ -204,12 +204,24 @@ export async function handleNativeChatCompletions(options: HandleNativeChatOptio
     return fail(400, error instanceof Error ? error.message : String(error), "invalid_request_error");
   }
 
+  // One inbound request owns one transient send allowance. Capture the policy before any
+  // key rotation so recovery cannot replace the ceiling along with the active credential.
+  const requestTransientPolicy = transientRetryPolicyFor(activeProvider);
+  let transientSendsUsed = 0;
+  const remainingTransientSends = (): number => requestTransientPolicy
+    ? Math.max(0, requestTransientPolicy.attempts - transientSendsUsed)
+    : Number.POSITIVE_INFINITY;
+  const transientSendAvailable = (): boolean => remainingTransientSends() > 0;
+
   const send = async (request: AdapterRequest, recovery?: "rate-limit-429" | "key-429"): Promise<Response> => {
     try {
       // #2643: opted-in key-auth openai-chat providers retry pre-stream transient statuses on
       // the native chat lane too; everyone else keeps reset-only semantics.
-      const transientPolicy = transientRetryPolicyFor(activeProvider);
-      const fetchWithPolicy = transientPolicy ? fetchWithTransientRetry : fetchWithResetRetry;
+      const remaining = remainingTransientSends();
+      if (requestTransientPolicy && remaining <= 0) {
+        throw new Error("native Chat transient send budget exhausted before recovery dispatch");
+      }
+      const fetchWithPolicy = requestTransientPolicy ? fetchWithTransientRetry : fetchWithResetRetry;
       return await fetchWithPolicy(
         (transportRecovery?: UpstreamSendRecovery) => {
           noteAttemptSend(attempt, logCtx.usageLogInputTokens, transportRecovery ?? recovery);
@@ -232,7 +244,12 @@ export async function handleNativeChatCompletions(options: HandleNativeChatOptio
         {
           abortSignal: upstream.signal,
           label: safeHostLabel(request.url),
-          ...(transientPolicy ? { attempts: transientPolicy.attempts } : {}),
+          ...(requestTransientPolicy
+            ? {
+              attempts: remaining,
+              onSendsConsumed: (sends: number) => { transientSendsUsed += Math.max(0, sends); },
+            }
+            : {}),
         },
       );
     } finally {
@@ -245,7 +262,12 @@ export async function handleNativeChatCompletions(options: HandleNativeChatOptio
     response = await send(activeRequest);
     const retryPolicy = rateLimitRetryPolicyFor(activeProvider);
     let retries = 0;
-    while (response.status === 429 && retryPolicy && retries < retryPolicy.attempts) {
+    while (
+      response.status === 429
+      && retryPolicy
+      && retries < retryPolicy.attempts
+      && transientSendAvailable()
+    ) {
       retries += 1;
       for await (const _ of prepareSameTarget429Wait({
         body: response.body,
@@ -263,6 +285,10 @@ export async function handleNativeChatCompletions(options: HandleNativeChatOptio
         promptCacheKey: typeof options.chatBody.prompt_cache_key === "string" ? options.chatBody.prompt_cache_key : undefined,
       });
       if (!rotated) break;
+      // Rotation also records the failed key's cooldown and persists the next healthy key.
+      // Keep that bookkeeping when this request has spent its final send, but preserve the
+      // terminal 429 body and do not dispatch with the replacement credential.
+      if (!transientSendAvailable()) break;
       try { void response.body?.cancel().catch(() => {}); } catch { /* already closed */ }
       activeProvider = rotated;
       activeAdapter = createOpenAIChatAdapter(activeProvider);

package/src/server/claude-messages.ts

@@ -50,6 +50,10 @@ import {
   isTranslatorBudgetExceededError,
   type TranslatorBudget,
 } from "../lib/translator-budget";
+import {
+  parseRequestEffortRowId,
+  type ParsedEffortRowId,
+} from "./effort-row";
 
 type Rec = Record<string, unknown>;
 
@@ -600,7 +604,9 @@ async function handleClaudeMessagesWithBudget(
   let anthropicBody: unknown;
   let internalBody: Rec;
   let cacheKeySource: ClaudeCacheKeySource = null;
-  let effortOverride: ReturnType<typeof extractOcxEffortDirective> = null;
+  let effortOverride: string | null = null;
+  let effortRow: ParsedEffortRowId | null = null;
+  let requestedModel = "";
   try {
     anthropicBody = await readAnthropicBody(req, translatorBudget);
     // Defensive [1m] strip (devlog 138): clients normally remove the context-variant
@@ -620,6 +626,14 @@ async function handleClaudeMessagesWithBudget(
         effortOverride = extractOcxEffortDirective(anthropicBody);
       }
     }
+    if (isRec(anthropicBody) && typeof anthropicBody.model === "string") {
+      requestedModel = anthropicBody.model;
+      effortRow = parseRequestEffortRowId(requestedModel, config);
+      if (effortRow) {
+        anthropicBody.model = effortRow.baseId;
+        effortOverride = effortRow.effort;
+      }
+    }
     // Debug capture (opt-in allowlist scalars) BEFORE the passthrough branch so
     // native, routed, and disabled-alias paths are all observable (devlog 130 B1).
     captureClaudeInbound(
@@ -643,7 +657,7 @@ async function handleClaudeMessagesWithBudget(
       );
       if (claudeConversationId) logCtx.conversationId = claudeConversationId;
     }
-    if (isRec(anthropicBody) && wantsNativePassthrough(req, config, requestPolicy, anthropicBody.model)) {
+    if (!effortRow && isRec(anthropicBody) && wantsNativePassthrough(req, config, requestPolicy, anthropicBody.model)) {
       return await anthropicNativePassthrough(req, config, logCtx, logIds, anthropicBody, "/v1/messages");
     }
     if (isRec(anthropicBody) && effortOverride) {
@@ -669,7 +683,7 @@ async function handleClaudeMessagesWithBudget(
     );
   }
 
-  const requestedModel = (anthropicBody as Rec).model as string;
+  if (!requestedModel) requestedModel = (anthropicBody as Rec).model as string;
   const stream = internalBody.stream === true;
   // Routed adapters only support streamed turns; always stream internally and fold
   // the translated Anthropic SSE into a message JSON for non-streaming clients.

package/src/server/effort-row.ts

@@ -0,0 +1,131 @@
+import { comboModelId, comboPublicModelId } from "../combos/types";
+import { detectCursorInstalls } from "../integrations/cursor-detect";
+import {
+  loadCursorEffortTable,
+  type CursorEffortTable,
+} from "../integrations/cursor-effort-table";
+import {
+  canonicalizeReasoningEfforts,
+  isDeclaredReasoningEffort,
+} from "../reasoning-effort";
+import { knownModelIdsForProvider } from "../router";
+import { policyModelId, policyPublicModelId } from "../routing/profile";
+import type { OcxConfig } from "../types";
+import { routedSlug } from "../providers/slug-codec";
+import { predictCursorEffort } from "./models-capabilities";
+
+const EFFORT_ROW_SEPARATOR = "--";
+
+export interface ParsedEffortRowId {
+  baseId: string;
+  effort: string;
+}
+
+export type EffortRowKnownIds = ReadonlySet<string> | ((id: string) => boolean);
+
+export interface EffortRowOptions {
+  knownIds?: EffortRowKnownIds;
+  table?: CursorEffortTable | null;
+  supportsReasoning?: boolean;
+}
+
+function isKnownId(knownIds: EffortRowKnownIds | undefined, id: string): boolean {
+  return typeof knownIds === "function" ? knownIds(id) : knownIds?.has(id) === true;
+}
+
+export function effortRowId(baseId: string, effort: string): string {
+  return `${baseId}${EFFORT_ROW_SEPARATOR}${effort}`;
+}
+
+/**
+ * Exact configured/public ids that must beat the synthetic terminal-suffix grammar.
+ * This is request-local because live-model cache contents can change while the server runs.
+ */
+export function knownEffortRowIds(config: OcxConfig): Set<string> {
+  const ids = new Set<string>();
+  for (const [providerName, provider] of Object.entries(config.providers)) {
+    const known = knownModelIdsForProvider(providerName, provider, config);
+    const namespaces = [providerName, provider.alias].filter((value): value is string => (
+      typeof value === "string" && value.length > 0
+    ));
+    for (const id of known) {
+      ids.add(id);
+      ids.add(routedSlug(providerName, id));
+      for (const namespace of namespaces) ids.add(`${namespace}/${id}`);
+    }
+    for (const alias of Object.values(provider.modelAliases ?? {})) {
+      ids.add(alias);
+      for (const namespace of namespaces) ids.add(`${namespace}/${alias}`);
+    }
+  }
+  for (const [id, combo] of Object.entries(config.combos ?? {})) {
+    ids.add(comboModelId(id));
+    ids.add(comboPublicModelId(id, combo));
+  }
+  for (const [id, profile] of Object.entries(config.routingProfiles ?? {})) {
+    ids.add(policyModelId(id));
+    ids.add(policyPublicModelId(id, profile));
+  }
+  return ids;
+}
+
+/** Resolve the installed Private Inference effort table once for the current request. */
+export function loadDetectedCursorEffortTable(): CursorEffortTable | null {
+  const privateInference = detectCursorInstalls().find(install => install.build === "private-inference");
+  return loadCursorEffortTable(privateInference);
+}
+
+export function parseEffortRowId(
+  id: string,
+  config: Pick<OcxConfig, "cursorEffortRows">,
+  options: EffortRowOptions = {},
+): ParsedEffortRowId | null {
+  if (config.cursorEffortRows !== true || isKnownId(options.knownIds, id)) return null;
+
+  const separator = id.lastIndexOf(EFFORT_ROW_SEPARATOR);
+  if (separator <= 0) return null;
+  const baseId = id.slice(0, separator);
+  const effort = id.slice(separator + EFFORT_ROW_SEPARATOR.length);
+  // "none" is never published as a row (discovery filters it), so it is never accepted either.
+  if (effort === "none" || !isDeclaredReasoningEffort(effort)) return null;
+  if (predictCursorEffort(baseId, options.table ?? null, options.supportsReasoning).ladder !== null) {
+    return null;
+  }
+  return { baseId, effort };
+}
+
+/** Parse one ingress selector against the current config and installed Cursor table. */
+export function parseRequestEffortRowId(id: string, config: OcxConfig): ParsedEffortRowId | null {
+  if (config.cursorEffortRows !== true) return null;
+  // Ordinary ids carry no separator; bail before the known-id scan and install detection so
+  // the flag costs nothing on the request path for models that are not effort rows.
+  if (id.lastIndexOf(EFFORT_ROW_SEPARATOR) <= 0) return null;
+  return parseEffortRowId(id, config, {
+    knownIds: knownEffortRowIds(config),
+    table: loadDetectedCursorEffortTable(),
+  });
+}
+
+export function expandCursorEffortRow<T extends { id: string }>(
+  row: T,
+  efforts: readonly string[] | undefined,
+  config: Pick<OcxConfig, "cursorEffortRows">,
+  options: EffortRowOptions = {},
+): T[] {
+  if (config.cursorEffortRows !== true) return [row];
+
+  const supported = canonicalizeReasoningEfforts(
+    (efforts ?? []).filter(effort => effort !== "none" && isDeclaredReasoningEffort(effort)),
+  );
+  const supportsReasoning = options.supportsReasoning ?? supported.length > 0;
+  if (predictCursorEffort(row.id, options.table ?? null, supportsReasoning).ladder !== null) {
+    return [row];
+  }
+  return [
+    row,
+    ...supported
+      .map(effort => effortRowId(row.id, effort))
+      .filter(id => !isKnownId(options.knownIds, id))
+      .map(id => ({ ...row, id })),
+  ];
+}