@bitkyc08/opencodex 2.30.0-preview.20260821 → 2.31.0

package/src/oauth/cursor.ts

@@ -101,6 +101,19 @@ function sleep(ms: number, signal?: AbortSignal): Promise<void> {
   });
 }
 
+/** Terminal poll statuses (T07, senpi PR #905): the login is denied/expired — retrying cannot succeed. */
+const POLL_TERMINAL_STATUSES = new Set([400, 401, 403, 410]);
+
+export class CursorAuthTerminalError extends Error {
+  readonly status: number;
+
+  constructor(status: number) {
+    super(`Cursor login rejected by the auth server (HTTP ${status}); start a new login`);
+    this.name = "CursorAuthTerminalError";
+    this.status = status;
+  }
+}
+
 /**
  * Poll cursor.com for login completion. 404 = still pending (back off), 200 = tokens.
  * `baseDelayMs` is injectable so tests can avoid the real 1s cadence; production uses the default.
@@ -135,9 +148,17 @@ export async function pollCursorAuth(
         return { accessToken: data.accessToken, refreshToken: data.refreshToken };
       }
 
+      // T07: a terminal auth status means the login attempt itself is dead (denied,
+      // expired, revoked). Fail on the FIRST such response instead of burning the
+      // 3-strike retry budget and masking the reason behind a generic error.
+      if (POLL_TERMINAL_STATUSES.has(response.status)) {
+        throw new CursorAuthTerminalError(response.status);
+      }
+
       throw new Error(`Cursor auth poll failed: ${response.status}`);
     } catch (err) {
       if (signal?.aborted) throw err instanceof Error ? err : new Error("Cursor login cancelled");
+      if (err instanceof CursorAuthTerminalError) throw err;
       consecutiveErrors++;
       if (consecutiveErrors >= 3) {
         throw new Error("Too many consecutive errors during Cursor auth polling");

package/src/providers/cursor-pool.ts

@@ -0,0 +1,72 @@
+/**
+ * Weighted credential routing for Cursor accounts.
+ *
+ * Transfer from yelixir-dev/cursor-ai-proxy-bridge credentials.ts:
+ * weighted round-robin selection with per-credential auth-failure cooldown
+ * and one-retry failover on a different account before surfacing the error.
+ *
+ * OpenCodex already has JWT-based multi-account identification (src/oauth/cursor.ts)
+ * and Anthropic-specific 429 rotation; this module adds Cursor-aware weighted
+ * routing on top of those primitives.
+ */
+
+export interface CursorCredential {
+  readonly id: string;
+  weight: number;
+}
+
+interface CredentialState {
+  readonly credential: CursorCredential;
+  currentWeight: number;
+  disabledUntil: number;
+}
+
+export class NoAvailableCursorCredentialError extends Error {
+  constructor(message = "No available Cursor credentials") { super(message); }
+}
+
+export class CursorCredentialRouter {
+  private states: CredentialState[] = [];
+  private readonly cooldownMs: number;
+
+  constructor(credentials: ReadonlyArray<CursorCredential>, cooldownMs = 300_000) {
+    this.cooldownMs = cooldownMs;
+    this.replace(credentials);
+  }
+
+  replace(credentials: ReadonlyArray<CursorCredential>): void {
+    this.states = credentials.map(c => ({
+      credential: { ...c, weight: Math.max(1, c.weight || 1) },
+      currentWeight: 0,
+      disabledUntil: 0,
+    }));
+  }
+
+  pick(excludeIds: ReadonlySet<string> = new Set()): CursorCredential {
+    const now = Date.now();
+    const candidates = this.states.filter(s =>
+      !excludeIds.has(s.credential.id) && s.disabledUntil <= now,
+    );
+    if (candidates.length === 0) throw new NoAvailableCursorCredentialError();
+    let selected: CredentialState | undefined;
+    let totalWeight = 0;
+    for (const state of candidates) {
+      state.currentWeight += state.credential.weight;
+      totalWeight += state.credential.weight;
+      if (!selected || state.currentWeight > selected.currentWeight) selected = state;
+    }
+    if (!selected) throw new NoAvailableCursorCredentialError();
+    selected.currentWeight -= totalWeight;
+    return { ...selected.credential };
+  }
+
+  disable(id: string): void {
+    const state = this.states.find(s => s.credential.id === id);
+    if (state) state.disabledUntil = Date.now() + this.cooldownMs;
+  }
+
+  get snapshot(): ReadonlyArray<{ id: string; disabled: boolean }> {
+    const now = Date.now();
+    return this.states.map(s => ({ id: s.credential.id, disabled: s.disabledUntil > now }));
+  }
+}

package/src/providers/derive.ts

@@ -483,6 +483,9 @@ export function enrichProviderFromRegistry(name: string, prov: OcxProviderConfig
   if (prov.supportsOpenAiWebSearchToolFields === undefined && entry.supportsOpenAiWebSearchToolFields !== undefined) {
     prov.supportsOpenAiWebSearchToolFields = entry.supportsOpenAiWebSearchToolFields;
   }
+  if (prov.supportsResponsesCustomTools === undefined && entry.supportsResponsesCustomTools !== undefined) {
+    prov.supportsResponsesCustomTools = entry.supportsResponsesCustomTools;
+  }
   if (prov.preserveResponsesReasoningContent === undefined && entry.preserveResponsesReasoningContent !== undefined) prov.preserveResponsesReasoningContent = entry.preserveResponsesReasoningContent;
   applyReasoningSummaryDefaults(prov, entry.modelSupportsReasoningSummaries);
   applyServiceTierModelDefaults(prov, serviceTierModelDefaultsFor(entry, prov));

package/src/providers/fastwire.ts

@@ -33,6 +33,7 @@ export interface FastPolicyAuthority {
   readonly providerAdapter: string;
   readonly providerAuthMode?: ProviderAuthKind;
   readonly fastWireDeclaration: FastWire | null | undefined;
+  readonly fastTierDescription?: string;
   readonly modelWireOverrideAllowed: boolean;
   readonly authTransport: FastPolicyAuthTransport;
   readonly capability: {
@@ -55,6 +56,7 @@ export interface ResolvedFastPolicy {
     | "pin-unavailable";
   readonly adapter: string;
   readonly fastWire: FastWire | null;
+  readonly fastTierDescription?: string;
   readonly forwardCallerTier: boolean;
 }
 
@@ -222,7 +224,16 @@ export function resolveFastPolicy(
   else if (capability === undefined) eligibility = "unclassified";
   else eligibility = "eligible";
 
-  return { capability, eligibility, adapter, fastWire, forwardCallerTier };
+  return {
+    capability,
+    eligibility,
+    adapter,
+    fastWire,
+    ...(authority.fastTierDescription !== undefined
+      ? { fastTierDescription: authority.fastTierDescription }
+      : {}),
+    forwardCallerTier,
+  };
 }
 
 export function canonicalFastTierMarker(callerTier: string | undefined): "priority" | undefined {

package/src/providers/openai-sidecar.ts

@@ -169,6 +169,7 @@ export async function resolveFirstUsableOpenAiSidecar(
             authContext.accountId,
             outcome,
             {
+              threadId: authContext.affinityKey,
               probeLeaseId: authContext.probeLeaseId,
               writerGeneration: authContext.writerGeneration,
             },

package/src/providers/registry.ts

@@ -225,8 +225,22 @@ export interface ProviderRegistryEntry {
   supportsServiceTier?: boolean;
   /** Registry default for OpenAI extended hosted web_search field support. */
   supportsOpenAiWebSearchToolFields?: boolean;
+  /** Registry default for native Responses custom-tool support. */
+  supportsResponsesCustomTools?: boolean;
   /** Registry default for exact model service-tier capability; explicit config keys win. */
   modelSupportsServiceTier?: Record<string, boolean>;
+  /**
+   * Registry-only service-tier defaults for an OAuth preset's explicit API-key transport.
+   * Applied only when `allowKeyAuthOverride` is true and the captured effective auth transport
+   * is key-based. Explicit provider config still wins field-by-field, including `false`.
+   */
+  keyAuthServiceTier?: {
+    supportsServiceTier?: boolean;
+    modelSupportsServiceTier?: Record<string, boolean>;
+    chatServiceTier?: boolean;
+  };
+  /** Provider-specific copy for the Codex catalog's Fast tier. */
+  fastTierDescription?: string;
   /**
    * Registry-only destination guard for `modelSupportsServiceTier`. This scopes vendor evidence
    * without changing provider ownership, routing, authentication, or config validation.
@@ -1023,10 +1037,21 @@ export const PROVIDER_REGISTRY: readonly ProviderRegistryEntry[] = [
     baseUrl: "https://api.x.ai/v1",
     authKind: "oauth",
     allowKeyAuthOverride: true,
+    // Priority Processing is documented for xAI's public API-key Chat Completions and
+    // Responses endpoints. OAuth is a separate Grok CLI subscription gateway and remains
+    // unclassified; do not turn this into a provider-wide supportsServiceTier declaration.
+    keyAuthServiceTier: {
+      supportsServiceTier: true,
+      chatServiceTier: true,
+    },
+    fastTierDescription: "Priority processing, 2x token price",
     featured: true,
     oauthId: "xai",
     jawcodeBundle: "xai",
     supportsOpenAiWebSearchToolFields: false,
+    // Live A/B on 2026-08-20: xAI rejects native custom/custom_tool_call shapes while accepting
+    // the otherwise-identical request after the custom tool is lowered to a function.
+    supportsResponsesCustomTools: false,
     note: "Log in with your Grok account",
     // Parallel tool calls: officially supported and default-on per docs.x.ai function-calling
     // (verified 260709, devlog/_plan/260709_parallel_tool_calls). Streamed calls arrive whole

package/src/providers/service-tier.ts

@@ -70,11 +70,22 @@ function buildFastPolicyAuthority(
   capabilityProvider: ServiceTierCapabilityProvider = provider,
 ): FastPolicyAuthority {
   const registry = registryTransportMatch ? getProviderRegistryEntry(providerName) : undefined;
+  const authTransport = resolveProviderAuthTransport(
+    provider.adapter,
+    provider.authMode ?? registry?.authKind ?? "key",
+    provider.apiKeyTransport,
+  );
+  const keyAuthDefaults = registry?.allowKeyAuthOverride === true
+    && (authTransport === "authorization_bearer" || authTransport === "x_api_key")
+    ? registry.keyAuthServiceTier
+    : undefined;
   const registryModelCapabilities = registry
     && registryModelServiceTierCapabilityApplies(registry, capabilityProvider)
     ? registry.modelSupportsServiceTier
     : undefined;
-  const providerCapability = capabilityProvider.supportsServiceTier ?? registry?.supportsServiceTier;
+  const providerCapability = capabilityProvider.supportsServiceTier
+    ?? keyAuthDefaults?.supportsServiceTier
+    ?? registry?.supportsServiceTier;
   const authority: FastPolicyAuthority = Object.freeze({
     providerAdapter: provider.adapter,
     providerAuthMode: provider.authMode ?? registry?.authKind ?? "key",
@@ -82,19 +93,23 @@ function buildFastPolicyAuthority(
       provider.fastWire !== undefined ? provider.fastWire : registry?.fastWire,
       { freeze: true },
     ),
+    ...(registry?.fastTierDescription !== undefined
+      ? { fastTierDescription: registry.fastTierDescription }
+      : {}),
     modelWireOverrideAllowed: !isCanonicalOpenAiForwardProvider(provider as OcxProviderConfig),
-    authTransport: resolveProviderAuthTransport(
-      provider.adapter,
-      provider.authMode ?? registry?.authKind ?? "key",
-      provider.apiKeyTransport,
-    ),
+    authTransport,
     capability: Object.freeze({
       ...(providerCapability !== undefined ? { provider: providerCapability } : {}),
       models: Object.freeze({
         ...(registryModelCapabilities ?? {}),
+        ...(keyAuthDefaults?.modelSupportsServiceTier ?? {}),
         ...(capabilityProvider.modelSupportsServiceTier ?? {}),
       }),
-      ...(provider.chatServiceTier !== undefined ? { chatServiceTier: provider.chatServiceTier } : {}),
+      ...(provider.chatServiceTier !== undefined
+        ? { chatServiceTier: provider.chatServiceTier }
+        : keyAuthDefaults?.chatServiceTier !== undefined
+          ? { chatServiceTier: keyAuthDefaults.chatServiceTier }
+          : {}),
     }),
     modelAdapters: Object.freeze({ ...(provider.modelAdapters ?? {}) }),
     hardPins: captureWireAdapterHardPins(providerName),

package/src/responses/custom-tool-compat.ts

@@ -4,6 +4,13 @@ import { collectResponsesToolGroups } from "./tool-groups";
 const ROUTED_CUSTOM_TOOL_PASSTHROUGH = new Set(["apply_patch"]);
 const BUILTIN_FUNCTIONS_NAMESPACE = "functions";
 
+function routedCustomToolPassesThrough(
+  name: string,
+  supportsResponsesCustomTools: boolean | undefined,
+): boolean {
+  return supportsResponsesCustomTools !== false && ROUTED_CUSTOM_TOOL_PASSTHROUGH.has(name);
+}
+
 function isPlainObject(value: unknown): value is Record<string, unknown> {
   return !!value && typeof value === "object" && !Array.isArray(value);
 }
@@ -34,7 +41,10 @@ export function routedCustomToolWireName(value: unknown): string | undefined {
  * Names of converted custom declarations after namespace lowering. Restoration uses these exact
  * wire identities so same-named function and custom children in different namespaces stay distinct.
  */
-function collectRoutedCustomToolWireNames(body: unknown): Set<string> {
+function collectRoutedCustomToolWireNames(
+  body: unknown,
+  supportsResponsesCustomTools?: boolean,
+): Set<string> {
   const names = new Set<string>();
   const groups = collectResponsesToolGroups(body);
   const bareWireNames = new Set<string>();
@@ -54,7 +64,7 @@ function collectRoutedCustomToolWireNames(body: unknown): Set<string> {
       if (
         tool.type === "custom"
         && typeof tool.name === "string"
-        && !ROUTED_CUSTOM_TOOL_PASSTHROUGH.has(tool.name)
+        && !routedCustomToolPassesThrough(tool.name, supportsResponsesCustomTools)
       ) {
         names.add(tool.name);
         continue;
@@ -67,7 +77,7 @@ function collectRoutedCustomToolWireNames(body: unknown): Set<string> {
           isPlainObject(child)
           && child.type === "custom"
           && typeof child.name === "string"
-          && !ROUTED_CUSTOM_TOOL_PASSTHROUGH.has(child.name)
+          && !routedCustomToolPassesThrough(child.name, supportsResponsesCustomTools)
           && !(tool.name === BUILTIN_FUNCTIONS_NAMESPACE && bareWireNames.has(child.name))
         ) names.add(customToolWireName(tool.name, child.name));
       }
@@ -81,7 +91,10 @@ export function customToolItemId(id: unknown): unknown {
   return id.startsWith("fc_") ? `ctc_${id.slice(3)}` : id;
 }
 
-export function collectRoutedCustomToolNames(body: unknown): Set<string> {
+export function collectRoutedCustomToolNames(
+  body: unknown,
+  supportsResponsesCustomTools?: boolean,
+): Set<string> {
   const names = new Set<string>();
   const visit = (value: unknown): void => {
     if (Array.isArray(value)) {
@@ -92,7 +105,7 @@ export function collectRoutedCustomToolNames(body: unknown): Set<string> {
     if (
       value.type === "custom"
       && typeof value.name === "string"
-      && !ROUTED_CUSTOM_TOOL_PASSTHROUGH.has(value.name)
+      && !routedCustomToolPassesThrough(value.name, supportsResponsesCustomTools)
     ) {
       names.add(value.name);
     }
@@ -184,12 +197,15 @@ function rewriteForUpstream(
   return changed ? next : value;
 }
 
-export function rewriteRoutedCustomToolsForUpstream(body: unknown): {
+export function rewriteRoutedCustomToolsForUpstream(
+  body: unknown,
+  supportsResponsesCustomTools?: boolean,
+): {
   body: unknown;
   names: Set<string>;
 } {
-  const conversionNames = collectRoutedCustomToolNames(body);
-  const names = collectRoutedCustomToolWireNames(body);
+  const conversionNames = collectRoutedCustomToolNames(body, supportsResponsesCustomTools);
+  const names = collectRoutedCustomToolWireNames(body, supportsResponsesCustomTools);
   if (conversionNames.size === 0) return { body, names };
   const callIds = new Set<string>();
   collectConvertedCallIds(body, conversionNames, callIds);

package/src/responses/namespace-tool-compat.ts

@@ -268,9 +268,8 @@ export function rewriteRoutedNamespaceToolsForUpstream(body: unknown): {
   const groups = collectResponsesToolGroups(body);
   const plan = buildRewritePlan(groups);
 
-  // Deliberately not gated on the plan being non-empty: a turn whose catalog is gone still replays
-  // call items carrying a private `namespace`, and the routed compaction turn strips the whole tool
-  // surface before this runs.
+  // Deliberately not gated on the plan being non-empty: a turn whose catalog is absent can still
+  // replay call items carrying a private `namespace`.
   const emitted = new Set<string>();
   const tools = Array.isArray(body.tools) ? rewriteToolList(body.tools, plan, emitted) : body.tools;
 

package/src/router.ts

@@ -366,6 +366,9 @@ export function routedProviderConfig(providerName: string, provider: OcxProvider
       && registryEntry.supportsOpenAiWebSearchToolFields !== undefined
       ? { supportsOpenAiWebSearchToolFields: registryEntry.supportsOpenAiWebSearchToolFields }
       : {}),
+    ...(provider.supportsResponsesCustomTools === undefined && registryEntry.supportsResponsesCustomTools !== undefined
+      ? { supportsResponsesCustomTools: registryEntry.supportsResponsesCustomTools }
+      : {}),
     ...(provider.preserveResponsesReasoningContent === undefined && registryEntry.preserveResponsesReasoningContent !== undefined
       ? { preserveResponsesReasoningContent: registryEntry.preserveResponsesReasoningContent }
       : {}),

package/src/server/chat-completions.ts

@@ -258,6 +258,10 @@ async function handleChatCompletionsWithBudget(
     abortSignal: req.signal,
     // Body is Responses-shaped by now, but the client spoke Chat Completions.
     inboundWire: "chat",
+    // Terminal vision-describe marker (roadmap 180): the bridge rebuilds
+    // headers from the FORWARD_HEADERS allowlist, which would drop the raw
+    // header — so the fact is detected here and carried as an option flag.
+    ...(req.headers.get("x-opencodex-vision-describe") === "1" ? { visionDescribeTerminal: true } : {}),
     translatorBudget,
     ...(logIds ? { onFirstOutput: () => recordFirstOutput(logCtx, logIds.start) } : {}),
     onNativePassthroughTerminal: status => finalizeNativeLog(httpStatusForRequestLogTerminal(status, logCtx), { terminalStatus: status, closeReason: "terminal" }),

package/src/server/chat-native.ts

@@ -11,6 +11,7 @@ import type { AdmissionLease } from "../lib/admission";
 import { readBoundedResponseBody } from "../lib/bounded-body";
 import { redactSecretString } from "../lib/redact";
 import { resolveClientRetryAfter } from "../lib/retry-after";
+import { isModelTextOnly } from "../vision";
 import {
   applyUpstreamRecoveryInit,
   fetchWithResetRetry,
@@ -61,6 +62,12 @@ export function isNativeChatRouteEligible(route: RouteResult, rawBody: Rec): boo
   if (rawBody.store === true || rawBody.background === true) return false;
   if (typeof rawBody.previous_response_id === "string" && rawBody.previous_response_id.length > 0) return false;
   if (rawBody.compaction_trigger !== undefined) return false;
+  // Vision sidecar coverage (roadmap 180): a text-only routed model with an
+  // image-bearing body must go through the Responses pipeline, whose plan
+  // site describes or strips the image. The native fast path has no vision
+  // handling, so letting it keep such a request forwards raw pixels to a
+  // model the operator declared blind.
+  if (isModelTextOnly(provider, route.modelId) && chatBodyCarriesImage(rawBody)) return false;
   if (Array.isArray(rawBody.tools)) {
     for (const tool of rawBody.tools) {
       if (!isRec(tool)) continue;
@@ -72,6 +79,19 @@ export function isNativeChatRouteEligible(route: RouteResult, rawBody: Rec): boo
   return true;
 }
 
+/** Any messages[].content[] part of type image_url. */
+function chatBodyCarriesImage(rawBody: Rec): boolean {
+  const messages = rawBody.messages;
+  if (!Array.isArray(messages)) return false;
+  for (const message of messages) {
+    if (!isRec(message) || !Array.isArray(message.content)) continue;
+    for (const part of message.content) {
+      if (isRec(part) && part.type === "image_url") return true;
+    }
+  }
+  return false;
+}
+
 function chatCompletionJson(value: unknown): Rec | null {
   if (!isRec(value) || !Array.isArray(value.choices) || value.choices.length === 0) return null;
   return value;

package/src/server/management/agent-settings-routes.ts

@@ -1073,13 +1073,14 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
       const section = body[field];
       if (section === undefined || section === null) continue;
       if (!isPlainObject(section)) return jsonResponse({ error: `${field} must be an object or null` }, 400);
-      // The widened union applies to the WEB-SEARCH override only (roadmap 060).
-      // Vision keeps its two-backend contract — accepting a wider id there would
-      // persist a backend the vision resolver reads as unset, silently activating
-      // a backend the operator never chose (review F1).
+      // Both overrides now speak their full unions (roadmap 060 web, 170
+      // vision revised). Vision's third arm is "routed" (loopback through the
+      // proxy's own router), never exa: exa is not an LLM, and accepting an
+      // unknown literal would persist a backend the vision resolver reads as
+      // unset (review F1's failure mode).
       const allowedBackends = field === "webSearchSidecar"
         ? ["openai", "anthropic", "xai", "gemini", "exa"]
-        : ["openai", "anthropic"];
+        : ["openai", "anthropic", "routed"];
       if (section.backend !== undefined && section.backend !== null
         && !allowedBackends.includes(section.backend as string)) {
         return jsonResponse({ error: `${field}.backend must be ${allowedBackends.join(", ")}, or null` }, 400);
@@ -1094,8 +1095,18 @@ export async function handleAgentSettingsRoutes(ctx: ManagementContext): Promise
         const requested = section.model;
         const candidates = await visionCandidateRows(config);
         const hint = section.backend === "anthropic" || section.backend === "openai"
+          || section.backend === "routed"
           ? section.backend
           : config.claudeCode?.visionSidecar?.backend;
+        // Same coherence rule as /api/sidecar-settings (roadmap 170 r2).
+        const effectiveBackend = hint ?? "openai";
+        const namespaced = requested.includes("/");
+        if (namespaced && effectiveBackend !== "routed") {
+          return jsonResponse({ error: `visionSidecar.model "${requested}" is provider-namespaced; it requires backend "routed"` }, 400);
+        }
+        if (!namespaced && effectiveBackend === "routed") {
+          return jsonResponse({ error: `visionSidecar.backend "routed" requires a provider-namespaced model ("provider/model"); got "${requested}"` }, 400);
+        }
         if (visionDescriberIsProvablyBlind(config, requested, candidates, hint)) {
           return jsonResponse(visionDescriberRejection("visionSidecar.model", requested, config, candidates), 400);
         }

package/src/server/management/config-routes.ts

@@ -113,8 +113,14 @@ async function sidecarVisionResponseSettings(config: OcxConfig): Promise<{
   // Match the runtime's one selected Anthropic executor for both backend fallback
   // and catalog reachability; resolving it once prevents the two projections drifting.
   const anthropicSidecar = findAnthropicVisionProvider(config);
-  const backend = resolveVisionBackend(vs.backend, anthropicSidecar);
-  const model = resolveEffectiveVisionModel(config, backend);
+  // The routed backend reports its own namespaced model verbatim: it is the
+  // dispatched value, and collapsing it through the legacy resolver would
+  // display a describer the runtime is not using (roadmap 190).
+  const routedActive = vs.backend === "routed" && !!vs.model && vs.model.includes("/");
+  const backend = routedActive ? "routed" as const : resolveVisionBackend(vs.backend, anthropicSidecar);
+  const model = routedActive && vs.model
+    ? vs.model
+    : resolveEffectiveVisionModel(config, backend === "routed" ? resolveVisionBackend(undefined, anthropicSidecar) : backend);
   const reasoning = normalizeVisionReasoningForModel(model, vs.reasoning) ?? "low";
   const models = await visionModelOptionsFor(config, anthropicSidecar);
   // Display-only grandfather: a persisted id stays selectable, but the write gate
@@ -592,8 +598,9 @@ export async function handleConfigRoutes(ctx: ManagementContext): Promise<Respon
       return jsonResponse({ error: "webSearch.streamRoutedModelOutput must be a boolean" }, 400);
     }
     if (body.vision && body.vision.backend !== undefined
-      && body.vision.backend !== null && body.vision.backend !== "openai" && body.vision.backend !== "anthropic") {
-      return jsonResponse({ error: "vision.backend must be openai, anthropic, or null" }, 400);
+      && body.vision.backend !== null && body.vision.backend !== "openai" && body.vision.backend !== "anthropic"
+      && body.vision.backend !== "routed") {
+      return jsonResponse({ error: "vision.backend must be openai, anthropic, routed, or null" }, 400);
     }
     if (body.vision && body.vision.maxDescriptionsPerTurn !== undefined
       && (typeof body.vision.maxDescriptionsPerTurn !== "number"
@@ -621,8 +628,20 @@ export async function handleConfigRoutes(ctx: ManagementContext): Promise<Respon
       const requested = body.vision.model;
       const candidates = await visionCandidateRows(config);
       const hint = body.vision.backend === "anthropic" || body.vision.backend === "openai"
+        || body.vision.backend === "routed"
         ? body.vision.backend
         : config.visionSidecar?.backend;
+      // Coherence (roadmap 170 r2): the forward/OAuth executors POST the model
+      // string VERBATIM, so a namespaced id on those backends persists a wire
+      // id they cannot run; and "routed" without a namespace cannot route.
+      const effectiveBackend = hint ?? "openai";
+      const namespaced = requested.includes("/");
+      if (namespaced && effectiveBackend !== "routed") {
+        return jsonResponse({ error: `vision.model "${requested}" is provider-namespaced; it requires vision.backend "routed"` }, 400);
+      }
+      if (!namespaced && effectiveBackend === "routed") {
+        return jsonResponse({ error: `vision.backend "routed" requires a provider-namespaced vision.model ("provider/model"); got "${requested}"` }, 400);
+      }
       if (visionDescriberIsProvablyBlind(config, requested, candidates, hint)) {
         return jsonResponse(visionDescriberRejection("vision.model", requested, config, candidates), 400);
       }
@@ -736,7 +755,8 @@ export async function handleConfigRoutes(ctx: ManagementContext): Promise<Respon
         else config.visionSidecar.model = body.vision.model;
       }
       if (body.vision.backend === null) delete config.visionSidecar.backend;
-      else if (body.vision.backend === "openai" || body.vision.backend === "anthropic") {
+      else if (body.vision.backend === "openai" || body.vision.backend === "anthropic"
+        || body.vision.backend === "routed") {
         config.visionSidecar.backend = body.vision.backend;
       }
       if (typeof body.vision.maxDescriptionsPerTurn === "number") {

package/src/server/management/vision-sidecar-options.ts

@@ -9,6 +9,7 @@
  */
 import type { OcxConfig } from "../../types";
 import { findAnthropicVisionProvider, type AnthropicVisionProvider } from "../../vision";
+import { VISION_BACKENDS } from "../../vision/backends";
 import {
   modelAcceptsImageInput,
   visionEligibleModelOptions,
@@ -16,30 +17,44 @@ import {
   type VisionModelOption,
   type VisionSidecarBackend,
 } from "../../vision/eligibility";
-import { listOpenAiForwardSidecarCandidates } from "../../providers/openai-sidecar";
 import { pickerVisibleSidecarCandidates } from "../../sidecar/candidates";
 import { resolveSidecarAuth } from "../../sidecar/auth";
 
 /**
- * Backends whose executor could actually run: openai forward, anthropic OAuth.
+ * Backends whose executor could actually run (#2188 roadmap 170): openai
+ * forward, anthropic OAuth, xai OAuth, Antigravity OAuth — resolved by the
+ * VISION_BACKENDS descriptor table so this module and the options path cannot
+ * drift on what "active" means.
  *
  * `anthropicSidecar` is REQUIRED rather than defaulted. `findAnthropicVisionProvider`
  * reads the OAuth account store from disk, and a default argument made every helper
  * in this chain re-resolve it whenever a caller passed an explicit `undefined` —
  * which is exactly the no-executor case. Passing it in keeps one read per request.
+ * The descriptor table re-derives the anthropic flag from the shared auth
+ * module; asserting the caller's resolution stays consistent with it is the
+ * job of the shared module, not this file.
  */
 export function enabledVisionBackends(
   config: OcxConfig,
   anthropicSidecar: AnthropicVisionProvider | undefined,
 ): VisionSidecarBackend[] {
-  const backends: VisionSidecarBackend[] = [];
-  // The OpenAI describer needs a CANONICAL ChatGPT forward provider, not merely a
-  // provider keyed "openai" — same predicate the runtime sidecar resolver uses.
-  if (listOpenAiForwardSidecarCandidates(config).length > 0) backends.push("openai");
-  if (anthropicSidecar) backends.push("anthropic");
-  // Neither side resolvable (fresh install, no login): fall back to both so the
-  // picker is populated rather than empty, matching the permissive-unknown rule.
-  return backends.length > 0 ? backends : ["openai", "anthropic"];
+  const auth = resolveSidecarAuth(config);
+  // Preserve the caller's resolution for the anthropic side: the descriptor
+  // reads the shared auth module, but a caller that already resolved "no
+  // executor" must not see anthropic options it cannot dispatch. The filter
+  // applies to the ACTIVE set only — the fresh-install fallback below stays
+  // both universal sides, exactly the pre-widening behavior (test 6 pins it).
+  const active = VISION_BACKENDS
+    .filter(descriptor => descriptor.isActive(auth, config))
+    .map(descriptor => descriptor.backend)
+    .filter(backend => backend !== "anthropic" || anthropicSidecar !== undefined);
+  // "routed" is active by construction, so the fresh-install fallback keys on
+  // the UNIVERSAL sides: when neither resolves, both are offered so the picker
+  // stays populated (permissive-unknown rule; test 6 pins it).
+  if (!active.includes("openai") && !active.includes("anthropic")) {
+    return ["openai", "anthropic", ...active];
+  }
+  return active;
 }
 
 /**
@@ -93,10 +108,16 @@ export async function visionModelOptionsFor(
  * When no catalog row matches, the caller's `backend` is only a HINT, never the
  * authority. Trusting it let a client launder a known-blind OpenAI model past the
  * gate by claiming `backend: "anthropic"`, since the id is absent from the
- * Anthropic table and absence reads as "unknown". Both families are therefore
- * consulted and any positive text-only verdict wins. That is safe precisely
- * because the two vendor tables share no bare model id, so they can never
- * disagree about one.
+ * Anthropic table and absence reads as "unknown".
+ *
+ * A NAMESPACED id ("provider/model", the routed-backend option shape) names
+ * its provider outright, so that provider's config row and metadata family
+ * are probed directly. A BARE id probes ALL configured provider families and
+ * any positive text-only verdict wins (roadmap 170: a bare `grok-4` is
+ * provably text-only in the xai vendor table and must not slip through a
+ * two-family probe). That is safe precisely because the vendor tables share
+ * no bare model id (collision scan in roadmap 160: openai 48, anthropic 26,
+ * xai 32, google 43, zero overlaps), so they can never disagree about one.
  */
 export function visionDescriberIsProvablyBlind(
   config: OcxConfig,
@@ -109,11 +130,25 @@ export function visionDescriberIsProvablyBlind(
   if (candidates.some(candidate => candidate.id === requested
     && modelAcceptsImageInput(config, candidate) === false)) return true;
 
-  const hinted: VisionSidecarBackend = backendHint === "anthropic" ? "anthropic" : "openai";
-  const probed: VisionSidecarBackend[] = hinted === "anthropic"
-    ? ["anthropic", "openai"]
-    : ["openai", "anthropic"];
-  return probed.some(provider => modelAcceptsImageInput(config, { provider, id: requested }) === false);
+  // Namespaced routed id: the provider is named, probe it directly (config
+  // row enrichment + its metadata family both flow through the predicate).
+  const sep = requested.indexOf("/");
+  if (sep > 0) {
+    const provider = requested.slice(0, sep);
+    const id = requested.slice(sep + 1);
+    if (modelAcceptsImageInput(config, { provider, id }) === false) return true;
+    // A namespaced candidate row (value shape) may also carry the proof.
+    return candidates.some(candidate => candidate.provider === provider && candidate.id === id
+      && modelAcceptsImageInput(config, candidate) === false);
+  }
+
+  // Bare id: probe the base vendor families plus every configured provider —
+  // a positive text-only verdict from any source wins.
+  const families = new Set(["openai", "anthropic", "xai", "google-antigravity", ...Object.keys(config.providers ?? {})]);
+  const ordered = backendHint === "anthropic"
+    ? ["anthropic", ...[...families].filter(family => family !== "anthropic")]
+    : ["openai", ...[...families].filter(family => family !== "openai")];
+  return ordered.some(provider => modelAcceptsImageInput(config, { provider, id: requested }) === false);
 }
 
 /** The 400 body both routes return, so the two errors cannot diverge either. */