@bitkyc08/opencodex 2.29.0 → 2.31.0-preview.20260822

package/src/service.ts

@@ -3274,6 +3274,7 @@ export async function serviceStatusReport(
 }
 
 export function normalizeServiceSubcommand(sub?: string): string {
+  if (sub === "restart") return "repair";
   return sub ?? "install";
 }
 
@@ -3283,6 +3284,119 @@ export interface ParsedServiceArgs {
   invalid: string[];
 }
 
+export type ServiceInstallationState = "installed" | "absent" | "unknown";
+
+export interface ServiceInstallationProbe {
+  state: ServiceInstallationState;
+  detail?: string;
+}
+
+export interface ServiceInstallationProbeHooks {
+  platform?: NodeJS.Platform;
+  exists?: (path: string) => boolean;
+  probeWindowsTask?: () => WindowsSchedulerTaskProbe;
+  nativeStatus?: () => WinswStatus;
+}
+
+/**
+ * Read only enough registration state to choose between install and repair.
+ * Windows must keep query failure distinct from proven absence: treating an
+ * unreadable scheduler/SCM as absent would send a bare command into the
+ * elevated registration path and recreate the original #2287 failure.
+ */
+export function probeServiceInstallation(
+  hooks: ServiceInstallationProbeHooks = {},
+): ServiceInstallationProbe {
+  const platform = hooks.platform ?? process.platform;
+  const exists = hooks.exists ?? existsSync;
+  if (platform === "darwin") {
+    return { state: exists(plistPath()) ? "installed" : "absent" };
+  }
+  if (platform === "linux") {
+    return { state: exists(unitPath()) ? "installed" : "absent" };
+  }
+  if (platform !== "win32") return { state: "absent" };
+
+  let scheduler: WindowsSchedulerTaskProbe;
+  try {
+    scheduler = (hooks.probeWindowsTask ?? probeWindowsSchedulerTask)();
+  } catch (cause) {
+    scheduler = { status: "unknown", detail: schtasksErrorDetail(cause) };
+  }
+  let native: WinswStatus;
+  try {
+    native = (hooks.nativeStatus ?? statusWinswRaw)();
+  } catch {
+    native = "unknown";
+  }
+
+  if (scheduler.status === "present" || native === "started" || native === "stopped") {
+    return { state: "installed" };
+  }
+  if (scheduler.status === "unknown" || native === "unknown") {
+    const parts = [
+      scheduler.status === "unknown" ? `Task Scheduler: ${scheduler.detail}` : null,
+      native === "unknown" ? "WinSW status could not be determined" : null,
+    ].filter((part): part is string => Boolean(part));
+    return { state: "unknown", detail: parts.join("; ") };
+  }
+  return { state: "absent" };
+}
+
+/**
+ * A bare invocation is an idempotent "make the installed service current"
+ * operation. First-time setup still installs, but an existing registration must
+ * use the repair path so Windows does not re-run the elevated `schtasks /create`.
+ * Backend flags remain an explicit install request because they select which
+ * registration mechanism to create.
+ */
+export function selectServiceSubcommand(
+  parsed: ParsedServiceArgs,
+  options: { hasExplicitSubcommand: boolean; installed: boolean },
+): string {
+  if (!options.hasExplicitSubcommand && parsed.backend === null && options.installed) return "repair";
+  return parsed.sub;
+}
+
+export type ServiceCommandPlan =
+  | { ok: true; parsed: ParsedServiceArgs; command: string }
+  | { ok: false; message: string };
+
+export function planServiceCommand(
+  args: string[],
+  options: { platform?: NodeJS.Platform; probeInstallation?: () => ServiceInstallationProbe } = {},
+): ServiceCommandPlan {
+  const parsed = parseServiceArgs(args);
+  if (parsed.invalid.length > 0) {
+    return { ok: false, message: `Unknown service option: ${parsed.invalid.join(" ")}` };
+  }
+  if (parsed.backend && parsed.sub !== "install") {
+    return { ok: false, message: "--native/--scheduler apply to `ocx service install` only; other subcommands use the installed backend." };
+  }
+  if (parsed.backend === "native" && (options.platform ?? process.platform) !== "win32") {
+    return { ok: false, message: "--native (WinSW) is Windows-only." };
+  }
+
+  const hasExplicitSubcommand = args.some(arg => !arg.startsWith("--"));
+  let installed = false;
+  if (!hasExplicitSubcommand && parsed.backend === null) {
+    const probe = (options.probeInstallation ?? probeServiceInstallation)();
+    if (probe.state === "unknown") {
+      const suffix = probe.detail ? ` (${probe.detail})` : "";
+      return {
+        ok: false,
+        message: `Could not safely determine whether the service is installed${suffix}. Run 'ocx service status' and retry; use explicit 'ocx service install' only after confirming it is absent.`,
+      };
+    }
+    installed = probe.state === "installed";
+  }
+  return {
+    ok: true,
+    parsed,
+    command: selectServiceSubcommand(parsed, { hasExplicitSubcommand, installed }),
+  };
+}
+
 /**
  * `ocx service [sub] [--native|--scheduler]`. The first non-flag token is the
  * subcommand; backend flags are only meaningful for `install` (validated by the caller).
@@ -3308,20 +3422,13 @@ export function parseServiceArgs(args: string[]): ParsedServiceArgs {
 }
 
 export async function serviceCommand(...args: (string | undefined)[]): Promise<void> {
-  const parsed = parseServiceArgs(args.filter((a): a is string => Boolean(a)));
-  const command = parsed.sub;
-  if (parsed.invalid.length > 0) {
-    console.error(`Unknown service option: ${parsed.invalid.join(" ")}`);
-    process.exit(1);
-  }
-  if (parsed.backend && command !== "install") {
-    console.error("--native/--scheduler apply to `ocx service install` only; other subcommands use the installed backend.");
-    process.exit(1);
-  }
-  if (parsed.backend === "native" && process.platform !== "win32") {
-    console.error("--native (WinSW) is Windows-only.");
+  const filteredArgs = args.filter((a): a is string => Boolean(a));
+  const plan = planServiceCommand(filteredArgs);
+  if (!plan.ok) {
+    console.error(plan.message);
     process.exit(1);
   }
+  const { parsed, command } = plan;
   if (command === "repair") {
     assertServiceEnvironmentMatchesInstall();
     assertServiceAuthEnvironment();
@@ -3458,9 +3565,10 @@ export async function serviceCommand(...args: (string | undefined)[]): Promise<v
       console.log("✅ service uninstalled.");
       break;
     default:
-      console.error("Usage: ocx service [install|repair|start|stop|status|uninstall|remove] [--native|--scheduler]");
-      console.error("       With no subcommand, installs/updates and starts the background service.");
+      console.error("Usage: ocx service [install|repair|restart|start|stop|status|uninstall|remove] [--native|--scheduler]");
+      console.error("       With no subcommand, installs when absent or repairs/restarts an existing service.");
       console.error("       repair: refresh assets and restart an already-installed service (no admin re-prompt).");
+      console.error("       restart: alias of repair.");
       console.error("       --native (Windows only): register a real SCM service via WinSW instead of Task Scheduler.");
       process.exit(1);
   }

package/src/types/config.ts

@@ -130,7 +130,7 @@ export interface OcxClaudeCodeConfig {
   /** Claude-originated web-search override. Unset fields inherit the global sidecar settings. */
   webSearchSidecar?: { backend?: "openai" | "anthropic" | "xai" | "gemini" | "exa"; model?: string };
   /** Claude-originated vision override. Unset fields inherit the global sidecar settings. */
-  visionSidecar?: { backend?: "openai" | "anthropic"; model?: string };
+  visionSidecar?: { backend?: "openai" | "anthropic" | "routed"; model?: string };
   /** Persisted Claude Desktop four-family routing profile. */
   desktopProfile?: OcxClaudeDesktopProfile;
   /** Auto-reconcile Desktop 3P config when provider catalog changes. Default: enabled. */
@@ -774,8 +774,14 @@ export interface OcxSearchConfig {
 export interface OcxVisionSidecarConfig {
   /** Master switch. Default: enabled when the selected backend has a usable credential. */
   enabled?: boolean;
-  /** Description backend. Unset prefers a usable stored Anthropic OAuth credential, else OpenAI. */
-  backend?: "openai" | "anthropic";
+  /**
+   * Description backend. Unset prefers a usable stored Anthropic OAuth credential, else OpenAI —
+   * the historical default order, deliberately unchanged by the union widening (#2188 roadmap
+   * 170/180 revised): "routed" describes through the proxy's OWN routing (loopback
+   * /v1/chat/completions) with a NAMESPACED "provider/model" describer, is explicit-only, and is
+   * never auto-selected from credential availability.
+   */
+  backend?: "openai" | "anthropic" | "routed";
   /** Vision model that describes images. */
   model?: string;
   /** Max description cache misses admitted in one main-model turn. Zero disables description calls. */

package/src/types/provider.ts

@@ -352,6 +352,12 @@ export interface OcxProviderConfig {
    * passthrough compatibility for OpenAI and unclassified gateways.
    */
   supportsOpenAiWebSearchToolFields?: boolean;
+  /**
+   * Whether the Responses upstream accepts native custom tools and custom_tool_call items.
+   * Set false only for a provider whose native contract rejects them; absence preserves
+   * apply_patch passthrough compatibility for OpenAI and unclassified gateways.
+   */
+  supportsResponsesCustomTools?: boolean;
   /**
    * Provider-local repair for Responses gateways whose lifecycle snapshots omit canonical
    * fields or closing events (#893). Disabled by default and applied only to client-facing

package/src/usage/cost.ts

@@ -22,7 +22,8 @@ import { activeConfiguredProviders, activeUserCostOverlays, userCostOverlayVersi
 import {
   EXPECTED_PRICE_OVERLAYS,
   findExpectedPriceOverlay,
-  resolvePriorityMultiplier,
+  findVerifiedPriceOverride,
+  findPriorityPricingRule,
   findContextTier,
   isLongContext,
   type Cost4,
@@ -81,12 +82,12 @@ export interface AttemptCostEstimate {
   price: MatchedPrice;
   cost: CostBreakdown;
   estimated: boolean;
-  /** Applied OpenAI priority-tier multiplier (undefined or 1 = standard). */
+  /** Applied provider priority-tier multiplier (undefined or 1 = standard). */
   priorityMultiplier?: number;
-  /** Standard-price estimate is a known floor for a confirmed, unpriced priority endpoint. */
-  priorityLowerBound?: boolean;
   /** Set when the published long-context rate was applied (#908). */
   contextTier?: ContextTierName;
+  /** The numeric estimate is a known floor because the exact Priority price is unavailable. */
+  priorityLowerBound?: boolean;
 }
 
 export interface CostEstimate {
@@ -95,12 +96,12 @@ export interface CostEstimate {
   estimated: boolean;
   attempts?: AttemptCostEstimate[];
   price?: MatchedPrice;
-  /** Applied OpenAI priority-tier multiplier (undefined or 1 = standard). */
+  /** Applied provider priority-tier multiplier (undefined or 1 = standard). */
   priorityMultiplier?: number;
-  /** Standard-price estimate is a known floor for a confirmed, unpriced priority endpoint. */
-  priorityLowerBound?: boolean;
   /** Set when any priced attempt used the published long-context rate (#908). */
   contextTier?: ContextTierName;
+  /** The aggregate is a known floor because every priced attempt is a lower bound. */
+  priorityLowerBound?: boolean;
 }
 
 function finiteNonNegative(value: number): boolean {
@@ -236,7 +237,7 @@ function resolveMatchedPriceInner(
 
 /**
  * Exact provider/model price lookup: user-configured `modelCosts` first, then
- * the jawcode provider bundle, then the expected-price overlay, then the
+ * an exact official correction, the jawcode provider bundle, the expected-price overlay, then the
  * model-level vendor fallback. All-zero rows fall through ("not billable").
  */
 function resolveMatchedPriceExact(
@@ -249,6 +250,20 @@ function resolveMatchedPriceExact(
   // operator's explicit price is authoritative for the ~$ estimate.
   const userOverlay = userOverlayMatch(provider, modelId, userOverlays);
   if (userOverlay) return userOverlay;
+  const verifiedOverride = overlays === EXPECTED_PRICE_OVERLAYS
+    ? findVerifiedPriceOverride(provider, modelId)
+    : undefined;
+  if (verifiedOverride && validCost4(verifiedOverride.cost4) && hasNonZeroCost(verifiedOverride.cost4)) {
+    return {
+      provider,
+      modelId,
+      cost4: verifiedOverride.cost4,
+      source: "expected",
+      sourceRef: verifiedOverride.source,
+      verifiedAt: verifiedOverride.verifiedAt,
+      status: "verified",
+    };
+  }
   const metadataProvider = resolveMetadataProvider(provider);
   const bundled = metadataProvider
     ? getModelMetadata(metadataProvider, modelId)
@@ -320,13 +335,6 @@ function isEstimated(usage: OcxUsage, usageStatus: UsageStatus, priceStatus: Exp
   return usage.estimated === true || usageStatus === "estimated" || priceStatus === "verified-derived";
 }
 
-/**
- * OpenAI provider ids eligible for service_tier "priority" price multipliers.
- * Only canonical OpenAI forward providers use the priority tier; routed providers
- * (OpenRouter, Cursor, etc.) may share model slugs but have independent pricing.
- */
-const OPENAI_TIER_PROVIDER_IDS = new Set(["openai", "openai-apikey"]);
-
 /**
  * Resolve the effective service tier from persisted log fields.
  * Priority: responseServiceTier (server-confirmed) > requestedServiceTier
@@ -405,9 +413,9 @@ function isConfirmedFast(tier?: ServiceTierInput): boolean {
  * normalized billable input — normalization subtracts cache read/write, so a
  * cache-heavy long prompt would fall below the boundary and under-bill.
  *
- * Skipped entirely for a response-confirmed Fast request: OpenAI does not serve
- * long context in Fast mode, so the two are mutually exclusive regimes rather
- * than composable multipliers.
+ * A provider's declaration decides how a response-confirmed priority tier relates to this band.
+ * OpenAI declares the bands exclusive. xAI publishes neither a combined rate nor an exclusion,
+ * so its long-context rate remains the known lower bound instead of inventing a stacked multiplier.
  */
 function applyContextTier(
   cost4: Cost4,
@@ -415,25 +423,27 @@ function applyContextTier(
   modelId: string,
   rawInputTokens: number | undefined,
   tier?: ServiceTierInput,
-): [Cost4, ContextTierName | undefined] {
-  if (rawInputTokens === undefined) return [cost4, undefined];
-  if (isConfirmedFast(tier)) return [cost4, undefined];
+): [Cost4, ContextTierName | undefined, boolean] {
+  if (rawInputTokens === undefined) return [cost4, undefined, false];
   const rule = findContextTier(baseProviderLabel(provider), modelId);
-  if (!rule || !isLongContext(rule, rawInputTokens)) return [cost4, undefined];
+  if (!rule || !isLongContext(rule, rawInputTokens)) return [cost4, undefined, false];
+  const confirmedFast = isConfirmedFast(tier);
+  if (confirmedFast && rule.confirmedPriorityRelation === "exclusive") {
+    return [cost4, undefined, false];
+  }
   return [{
     input: cost4.input * rule.multiplier.input,
     output: cost4.output * rule.multiplier.output,
     cacheRead: cost4.cacheRead * rule.multiplier.cacheRead,
     cacheWrite: cost4.cacheWrite * rule.multiplier.cacheWrite,
-  }, "long"];
+  }, "long", confirmedFast && rule.confirmedPriorityRelation === "lower-bound"];
 }
 
 /**
- * Apply the OpenAI priority-tier multiplier to a Cost4 when applicable.
+ * Apply a declared provider/model priority-tier multiplier to a Cost4 when applicable.
  * Returns [effectiveCost4, multiplier]. Multiplier is 1 (no-op) when:
  * - serviceTier is not "priority"
- * - provider is not a canonical OpenAI forward provider
- * - model is not in PRIORITY_MULTIPLIERS
+ * - no exact provider/model rule exists
  */
 function applyPriorityMultiplier(
   cost4: Cost4,
@@ -443,8 +453,9 @@ function applyPriorityMultiplier(
 ): [Cost4, number] {
   if (tierScalar(serviceTier) !== "priority") return [cost4, 1];
   const base = baseProviderLabel(provider);
-  if (!OPENAI_TIER_PROVIDER_IDS.has(base)) return [cost4, 1];
-  const multiplier = resolvePriorityMultiplier(modelId);
+  const rule = findPriorityPricingRule(base, modelId);
+  if (rule?.requiresResponseConfirmation && !isConfirmedFast(serviceTier)) return [cost4, 1];
+  const multiplier = rule?.multiplier ?? 1;
   if (multiplier === 1) return [cost4, 1];
   return [{
     input: cost4.input * multiplier,
@@ -495,16 +506,17 @@ export function estimateAttemptCost(
   const attemptServiceTier = attempt.tierOutcome
     ? serviceTierContextFromOutcome(attempt.tierOutcome)
     : serviceTier;
-  const [tieredCost4, contextTier] = applyContextTier(
+  const [tieredCost4, contextTier, contextPriorityLowerBound] = applyContextTier(
     price.cost4, attempt.provider, attempt.model, attempt.usage.inputTokens, attemptServiceTier,
   );
-  // Exclusive both ways: if the long rate applied, the request was NOT served as
-  // Fast (Fast does not support long context), so the Fast multiplier must not
-  // also apply — otherwise a downgraded request bills at both rates.
+  // A published long-context row owns the numeric estimate. OpenAI declares that band
+  // exclusive with Fast; xAI's confirmed combination is deliberately left unmultiplied
+  // and marked as a lower bound because no combined price has been published.
   const [effectiveCost4, multiplier] = contextTier
     ? [tieredCost4, 1] as const
     : applyPriorityMultiplier(tieredCost4, attempt.provider, attempt.model, attemptServiceTier);
-  const priorityLowerBound = isOpenRouterPriorityLowerBound(attempt.provider, attempt.tierOutcome);
+  const priorityLowerBound = contextPriorityLowerBound
+    || isOpenRouterPriorityLowerBound(attempt.provider, attempt.tierOutcome);
   return {
     ordinal: attempt.ordinal,
     provider: attempt.provider,
@@ -514,8 +526,8 @@ export function estimateAttemptCost(
     cost: calculateCost(tokens, effectiveCost4),
     estimated: isEstimated(attempt.usage, attempt.usageStatus, price.status),
     ...(multiplier !== 1 ? { priorityMultiplier: multiplier } : {}),
-    ...(priorityLowerBound ? { priorityLowerBound: true } : {}),
     ...(contextTier ? { contextTier } : {}),
+    ...(priorityLowerBound ? { priorityLowerBound: true } : {}),
   };
 }
 
@@ -557,8 +569,10 @@ export function estimateComboCost(
     ...(estimates.some(est => est.priorityMultiplier && est.priorityMultiplier !== 1)
       ? { priorityMultiplier: estimates.find(est => est.priorityMultiplier)?.priorityMultiplier }
       : {}),
-    ...(estimates.some(est => est.priorityLowerBound) ? { priorityLowerBound: true } : {}),
     ...(estimates.some(est => est.contextTier) ? { contextTier: "long" as const } : {}),
+    ...(estimates.every(est => est.priorityLowerBound === true)
+      ? { priorityLowerBound: true as const }
+      : {}),
   };
 }
 
@@ -579,13 +593,13 @@ export function estimateRequestCost(
   if (!tokens) return null;
   const price = resolveMatchedPrice(input.provider, input.model, overlays, userOverlays);
   if (!price) return null;
-  const [tieredCost4, contextTier] = applyContextTier(
+  const [tieredCost4, contextTier, contextPriorityLowerBound] = applyContextTier(
     price.cost4, input.provider, input.model, input.usage.inputTokens, input.serviceTier,
   );
   const [effectiveCost4, multiplier] = contextTier
     ? [tieredCost4, 1] as const
     : applyPriorityMultiplier(tieredCost4, input.provider, input.model, input.serviceTier);
-  const priorityLowerBound = isOpenRouterPriorityLowerBound(
+  const priorityLowerBound = contextPriorityLowerBound || isOpenRouterPriorityLowerBound(
     input.provider,
     typeof input.serviceTier === "object" ? input.serviceTier.tierOutcome : undefined,
   );
@@ -595,8 +609,8 @@ export function estimateRequestCost(
     cost: calculateCost(tokens, effectiveCost4),
     estimated: isEstimated(input.usage, input.usageStatus, price.status),
     ...(multiplier !== 1 ? { priorityMultiplier: multiplier } : {}),
-    ...(priorityLowerBound ? { priorityLowerBound: true } : {}),
     ...(contextTier ? { contextTier } : {}),
+    ...(priorityLowerBound ? { priorityLowerBound: true } : {}),
   };
 }
 

package/src/usage/expected-prices.ts

@@ -181,6 +181,30 @@ export const EXPECTED_PRICE_OVERLAYS: readonly ExpectedPriceOverlay[] = [
   { provider: "cursor", modelId: "auto", cost4: { input: 1.25, output: 6, cacheRead: 0.25, cacheWrite: 1.25 }, source: "https://docs.cursor.com/account/pricing + https://cursor.com/blog/aug-2025-pricing", verifiedAt: "2026-07-20", status: "verified" },
 ];
 
+/**
+ * Exact official corrections for stale nonzero catalog rows. These are intentionally separate
+ * from fallback overlays: they win over the bundled row only for the declared provider/model and
+ * therefore cannot reprice routed resellers that reuse the same model slug.
+ */
+export const VERIFIED_PRICE_OVERRIDES: readonly ExpectedPriceOverlay[] = [
+  {
+    provider: "xai",
+    modelId: "grok-4.6",
+    cost4: { input: 2, output: 6, cacheRead: 0.5, cacheWrite: 0 },
+    source: "https://docs.x.ai/developers/pricing",
+    verifiedAt: "2026-08-18",
+    status: "verified",
+  },
+];
+
+export function findVerifiedPriceOverride(
+  provider: string,
+  modelId: string,
+  overrides: readonly ExpectedPriceOverlay[] = VERIFIED_PRICE_OVERRIDES,
+): ExpectedPriceOverlay | undefined {
+  return overrides.find(row => row.provider === provider && row.modelId === modelId);
+}
+
 /**
  * Exact-key overlay lookup. Returns verified first, then verified-derived.
  * NEVER returns "unverified" rows — fail-closed is enforced in code, not just docs.
@@ -196,12 +220,7 @@ export function findExpectedPriceOverlay(
     ?? exact.find(row => row.status === "verified-derived");
 }
 
-/**
- * OpenAI Fast mode (`service_tier=priority`) price multipliers by model slug.
- * Source: https://openai.com/api-fast-mode/ (2026-07-31).
- * Fast pricing applies uniformly to all token types (input, output, cache).
- * Models not listed here fall back to 1× (no multiplier).
- */
+/** OpenAI Fast price multipliers retained as a compatibility export. */
 export const PRIORITY_MULTIPLIERS: Readonly<Record<string, number>> = {
   "gpt-5.6-sol": 2,
   // Post-price-cut Fast tables (https://openai.com/api-fast-mode/, 2026-08-05):
@@ -219,6 +238,52 @@ export function resolvePriorityMultiplier(modelId: string): number {
   return PRIORITY_MULTIPLIERS[modelId] ?? 1;
 }
 
+export interface PriorityPricingRule {
+  provider: string;
+  modelId: string;
+  multiplier: number;
+  /** Apply the premium only after the upstream response confirms this tier. */
+  requiresResponseConfirmation?: true;
+  source: string;
+  verifiedAt: string;
+}
+
+const OPENAI_FAST_PRICING = "https://openai.com/api-fast-mode/";
+const XAI_PRIORITY_PRICING = "https://docs.x.ai/developers/advanced-api-usage/priority-processing";
+
+/**
+ * Exact provider/model priority premiums. Routed resellers never inherit a vendor rule merely
+ * because they reuse its model slug. Multipliers apply uniformly after cache discounts.
+ */
+export const PRIORITY_PRICING_RULES: readonly PriorityPricingRule[] = [
+  ...["openai", "openai-apikey"].flatMap(provider =>
+    Object.entries(PRIORITY_MULTIPLIERS).map(([modelId, multiplier]): PriorityPricingRule => ({
+      provider,
+      modelId,
+      multiplier,
+      source: OPENAI_FAST_PRICING,
+      verifiedAt: "2026-08-05",
+    })),
+  ),
+  ...["grok-4.5", "grok-4.6"].map((modelId): PriorityPricingRule => ({
+    provider: "xai",
+    modelId,
+    multiplier: 2,
+    requiresResponseConfirmation: true,
+    source: XAI_PRIORITY_PRICING,
+    verifiedAt: "2026-08-18",
+  })),
+];
+
+/** Exact provider/model priority-pricing lookup. */
+export function findPriorityPricingRule(
+  provider: string,
+  modelId: string,
+  rules: readonly PriorityPricingRule[] = PRIORITY_PRICING_RULES,
+): PriorityPricingRule | undefined {
+  return rules.find(rule => rule.provider === provider && rule.modelId === modelId);
+}
+
 /**
  * Long-context pricing tiers (#908). Several vendors reprice the ENTIRE request
  * once the prompt crosses a published input-token threshold, so a flat Cost4
@@ -244,6 +309,8 @@ export interface ContextTier {
   inclusive: boolean;
   /** Per-field factor from the short rate to the published long rate. */
   multiplier: Cost4;
+  /** Published relationship between confirmed priority and long-context bands. */
+  confirmedPriorityRelation?: "exclusive" | "lower-bound";
   source: string;
   verifiedAt: string;
 }
@@ -277,6 +344,7 @@ export const CONTEXT_TIERS: readonly ContextTier[] = [
       thresholdInputTokens: 272_000,
       inclusive: false,
       multiplier: OPENAI_LONG_CONTEXT,
+      confirmedPriorityRelation: "exclusive",
       source: OPENAI_PRICING_DOC,
       verifiedAt: "2026-08-03",
     })),
@@ -287,19 +355,21 @@ export const CONTEXT_TIERS: readonly ContextTier[] = [
     thresholdInputTokens: 200_000,
     inclusive: true,
     multiplier: UNIFORM_DOUBLE,
+    confirmedPriorityRelation: "lower-bound",
     source: "https://docs.x.ai/developers/pricing",
     verifiedAt: "2026-08-03",
   },
   {
-    // 260813: grok-4.6 long-context tier mirrored from grok-4.5; the official pricing row
-    // was not yet published when the model page went up, so treat as provisional.
+    // xAI publishes the whole-request >=200k band for grok-4.6. Its combination with
+    // Priority Processing is not published, so confirmed priority uses this row as a lower bound.
     provider: "xai",
     modelId: "grok-4.6",
     thresholdInputTokens: 200_000,
     inclusive: true,
     multiplier: UNIFORM_DOUBLE,
+    confirmedPriorityRelation: "lower-bound",
     source: "https://docs.x.ai/developers/pricing",
-    verifiedAt: "2026-08-13",
+    verifiedAt: "2026-08-18",
   },
   {
     // daybreak-blue-latest aliases gpt-5.6-sol, which publishes the full long-context row

package/src/vision/backends.ts

@@ -0,0 +1,97 @@
+/**
+ * Which backends may DESCRIBE images for the vision sidecar, and which
+ * candidate rows each can describe through (#2188 vision rules; roadmap 170
+ * REVISED: the "routed" backend).
+ *
+ * A SIBLING of WEB_SEARCH_BACKENDS, not a shared table: vision has no
+ * per-model probe (rule 2 is "− provably text-only", enforced by
+ * modelAcceptsImageInput, not here), carries per-side baseline models, and
+ * excludes non-LLM backends like exa.
+ *
+ * Three backends, not one per provider: "openai" and "anthropic" carry auth
+ * semantics loopback routing cannot replicate (forwarded ChatGPT headers,
+ * OAuth beta fences) and their defaults must not drift. Every OTHER
+ * picker-visible provider row reaches the describer through "routed" — a
+ * loopback self-fetch of the proxy's own /v1/chat/completions, where the
+ * router and adapters already speak each provider's wire. That is what makes
+ * this table closed under provider growth: a new provider needs no new
+ * describe executor.
+ */
+import type { OcxConfig } from "../types";
+import type { SidecarAuthState } from "../sidecar/auth";
+import { listOpenAiForwardSidecarCandidates } from "../providers/openai-sidecar";
+import type { VisionCandidateModel, VisionSidecarBackend } from "./eligibility";
+
+export interface VisionBackendDescriptor {
+  backend: VisionSidecarBackend;
+  /** Liveness signal for this backend. */
+  isActive(auth: SidecarAuthState, config: OcxConfig): boolean;
+  /** Which candidate rows this backend's describe executor can actually run. */
+  candidateMatch(candidate: VisionCandidateModel, auth: SidecarAuthState): boolean;
+  /**
+   * Default entry for this side: cheap, image-capable, present in every
+   * deployment. Only the two universal sides carry one — "routed" has no
+   * universal model to name.
+   */
+  baseline?: string;
+  /** Stable option ordering (baselines first within a side). */
+  rank: number;
+}
+
+export const VISION_BACKENDS: readonly VisionBackendDescriptor[] = [
+  {
+    backend: "openai",
+    // The OpenAI describer needs a CANONICAL ChatGPT forward provider, not
+    // merely a provider keyed "openai" — same predicate the runtime sidecar
+    // resolver uses. Deliberately NOT auth.isCodexAuth: tightening to a live
+    // credential here would change which options a fresh install sees, and
+    // the options list is a suggestion surface, not the write gate.
+    isActive: (_auth, config) => listOpenAiForwardSidecarCandidates(config).length > 0,
+    candidateMatch: candidate => candidate.native === true || candidate.provider === "openai",
+    baseline: "gpt-5.6-luna",
+    rank: 0,
+  },
+  {
+    backend: "anthropic",
+    isActive: auth => auth.isAnthropicAuth,
+    // The runtime dispatches through exactly ONE Anthropic provider — the
+    // resolved OAuth row. Same-adapter keyed rows are unreachable (see
+    // visionBackendForCandidate's original stance).
+    candidateMatch: (candidate, auth) => candidate.provider === auth.anthropicProviderName,
+    baseline: "claude-haiku-4-5",
+    rank: 1,
+  },
+  {
+    backend: "routed",
+    // Always offered: options only materialize when a matching picker row
+    // exists, and the row's own provider config is the liveness signal — the
+    // loopback request fails closed through ordinary routing errors.
+    isActive: () => true,
+    // Any row the other two executors do NOT own. Auth-slot rows are
+    // entitlements of the openai/anthropic sides and never route here.
+    candidateMatch: (candidate, auth) =>
+      candidate.native !== true
+      && candidate.provider !== "openai"
+      && candidate.provider !== auth.anthropicProviderName,
+    rank: 2,
+  },
+];
+
+export function visionBackendDescriptor(backend: VisionSidecarBackend): VisionBackendDescriptor {
+  const descriptor = VISION_BACKENDS.find(entry => entry.backend === backend);
+  if (!descriptor) throw new Error(`unknown vision backend "${backend}"`);
+  return descriptor;
+}
+
+/**
+ * The active backend set for option generation. Falls back to the two
+ * UNIVERSAL sides when neither is active (fresh install: picker stays
+ * populated, permissive-unknown rule); "routed" is active by construction.
+ */
+export function activeVisionBackends(auth: SidecarAuthState, config: OcxConfig): VisionSidecarBackend[] {
+  const active = VISION_BACKENDS.filter(entry => entry.isActive(auth, config)).map(entry => entry.backend);
+  return active.includes("openai") || active.includes("anthropic")
+    ? active
+    : ["openai", "anthropic", ...active.filter(backend => backend === "routed")];
+}
+