feat(cursor): opt-in effort-variant rows for models outside Cursor's effort table

devlog/_plan/260902_cursor_bundle_effort_table/030_wp3_effort_variant_rows.md

@@ -17,6 +17,15 @@ verbatim below. Amendments made at P of the wp3 cycle: (a) "table-less" must con
 as the static fallback, so the projection follows the installed bundle; (b) exact known full
 model ids take precedence over the synthetic grammar (open question 1 → yes).
 
+Amendment (c), audit blocker 1 (005): on `/v1/messages` reuse the existing `effortOverride`
+slot (`claude-messages.ts:603/649`, written as `output_config.effort` before translation and
+already respected by `anthropicToResponsesTranslation`) instead of injecting the internal
+Responses `reasoning.effort`: `effortOverride = effortRow?.effort ?? extractOcxEffortDirective(...)`.
+The `none` rung the lane worried about is never published as a row (Cursor's own ladders have
+no `none`; filter it from the row set), so the translator's exclusion of `none` is moot.
+Amendment (d): `tableLess` in the status route uses `predictCursorEffort(id, table, supportsReasoning).ladder === null`
+(wp1 landed the `supportsReasoning` parameter).
+
 ---
 
 No files were modified. The untracked `devlog/_plan/260902_cursor_bundle_effort_table/` appeared concurrently and was left untouched. No tests were run.
@@ -413,4 +422,3 @@ Do not run the repository-wide suite in this lane.
 - Should the dashboard merely report `effortRows`, or render them inline under each table-less base? This lane recommends the API contract now and leaves presentation to the UI/UX lane.
 - Should synthetic rows be added for table-less aliases of otherwise table-matched models? Recommended: yes—the matcher sees the public ID, so an alias such as `opus` genuinely has no Cursor control.
 
-

docs-site/src/content/docs/reference/configuration.md

@@ -48,6 +48,15 @@ Aliases are optional short request names. They never change the native model id
 
 Aliases match case-insensitively. A model alias works as `or/opus` or, when globally unique, bare `opus`; an ambiguous bare alias reports its qualified candidates. Codex model pickers show the qualified alias while preserving the canonical `provider/model` routing id. A provider's `defaultAliases` value overrides `defaultModelAliases`. Built-ins are skipped when multiple models in one provider match the same pattern.
 
+### Cursor effort rows
+
+`cursorEffortRows` is an optional boolean and defaults to `false`. When enabled, the raw OpenAI-style
+`/v1/models` list adds `<base-id>--<effort>` selectors for reasoning-capable models that Cursor Private
+Inference does not match in its installed effort table. Selecting a generated row routes the base model
+and applies that row's effort; models Cursor already recognizes receive no variants. The flag reserves a
+terminal `--<declared-effort>` suffix for generated selectors, except when the complete value is already
+a known configured model id. Cursor may require a model-list refresh or restart after this setting changes.
+
 Valid values in `config.json` override built-in defaults. Missing optional fields use the defaults
 documented on the domain pages. `OPENCODEX_HOME` takes precedence over the default configuration
 directory. Fields that accept an environment reference, such as `apiKey: "${PROVIDER_API_KEY}"`,

gui/src/pages/integrations/cursor-api.ts

@@ -13,6 +13,8 @@ export interface CursorModelExpectation {
   id: string;
   reasoning: string[] | null;
   family: string | null;
+  tableLess: boolean;
+  effortRows: string[];
   context: { defaultWindow: number; longWindow: number } | null;
 }
 

src/config.ts

@@ -1046,6 +1046,8 @@ const configSchema = z.object({
   providers: z.record(z.string(), providerConfigSchema),
   defaultProvider: z.string().min(1).default("openai"),
   defaultModelAliases: z.boolean().optional(),
+  // Malformed hand edits disable this opt-in projection without rejecting providers.
+  cursorEffortRows: z.boolean().optional().catch(false),
   // Future versions remain opaque through passthrough-compatible whole-config saves.
   // Only version 1 grants deletion authority in the rebase path.
   configRebaseProvenance: z.unknown().optional(),

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;

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.

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 })),
+  ];
+}