@bitkyc08/opencodex 2.79.0 → 2.81.0

package/src/sidecar/auth.ts

@@ -17,6 +17,73 @@ import { OPENAI_CODEX_PROVIDER_ID } from "../providers/openai-tiers";
 import { isCodexAccountUsable } from "../codex/account-usability";
 import { MAIN_CODEX_ACCOUNT_ID, isSelectableCodexPoolAccount } from "../codex/account-id";
 import { getAccountSet } from "../oauth/store";
+import { configuredAnthropicInstance, type AnthropicInstanceId } from "../providers/anthropic-instance";
+import { isAnthropicInstanceId } from "../providers/anthropic-instance-id";
+
+/**
+ * The parent request's pool for an inheriting helper. A missing or disabled row keeps the parent's
+ * identity, so a pool removed mid-request refuses instead of discovering another pool; only a present
+ * custom row that is not the builtin instance (an unmarked custom `anthropic2`) stops inheritance.
+ */
+export function inheritedAnthropicInstance(config: OcxConfig, parentProviderName: string | undefined): AnthropicInstanceId | undefined {
+  if (!isAnthropicInstanceId(parentProviderName)) return undefined;
+  const row = config.providers?.[parentProviderName];
+  if (!row || row.disabled === true) return parentProviderName;
+  return configuredAnthropicInstance(config, parentProviderName);
+}
+
+export class AnthropicHelperUnavailableError extends Error {
+  readonly code = "anthropic_helper_unavailable";
+  constructor(readonly instance: AnthropicInstanceId) {
+    super(`The selected ${instance} helper account pool is unavailable`);
+    this.name = "AnthropicHelperUnavailableError";
+  }
+}
+export type AnthropicHelperContext = {
+  backendFamily: string;
+  anthropicInstance?: AnthropicInstanceId;
+  parentProviderName?: string;
+};
+
+/**
+ * Availability of one selected pool: the configured builtin row plus at least one stored account the
+ * pool could select. Which account actually sends (model route, cooldown, manual choice) is decided
+ * by snapshot resolution at send time, exactly as the main request path does, so a paused or
+ * reauth-pending ACTIVE account does not make a pool with another usable account unavailable.
+ */
+export function resolveAnthropicSidecarAuth(config: OcxConfig, instance: AnthropicInstanceId):
+  { anthropicProviderName: AnthropicInstanceId; anthropicProvider: OcxProviderConfig } | undefined {
+  const provider = config.providers[instance];
+  if (!provider || provider.disabled || provider.authMode !== "oauth" || provider.adapter !== "anthropic"
+    || configuredAnthropicInstance(config, instance) !== instance) return undefined;
+  if (!getAccountSet(instance)?.accounts.some(row => row.paused !== true && row.needsReauth !== true)) return undefined;
+  return { anthropicProviderName: instance, anthropicProvider: provider };
+}
+
+/**
+ * Explicit target, then the parent's CONFIGURED builtin instance. The parent name alone is not
+ * enough: a custom provider that happens to be named `anthropic2` is not Pool 2 and is never inherited.
+ */
+export function resolveAnthropicHelperInstance(config: OcxConfig, context: AnthropicHelperContext): AnthropicInstanceId | undefined {
+  if (context.backendFamily !== "anthropic") return undefined;
+  const instance = context.anthropicInstance ?? inheritedAnthropicInstance(config, context.parentProviderName);
+  if (instance && !resolveAnthropicSidecarAuth(config, instance)) throw new AnthropicHelperUnavailableError(instance);
+  return instance;
+}
+
+/**
+ * Planner boundary for the typed refusal: an unavailable selected pool means "this helper does not
+ * run", never "fail the main request" and never "discover another pool". Other errors propagate.
+ */
+export function withAnthropicHelperRefusal<T>(surface: string, resolve: () => T): T | undefined {
+  try {
+    return resolve();
+  } catch (error) {
+    if (!(error instanceof AnthropicHelperUnavailableError)) throw error;
+    console.warn(`[${surface}] ${error.message}; the request continues without this helper`);
+    return undefined;
+  }
+}
 
 export interface SidecarAuthState {
   /** ChatGPT login usable: canonical forward provider AND a live stored credential. */
@@ -63,6 +130,10 @@ function findAnthropicAuthProvider(
   config: OcxConfig,
 ): { providerName: string; provider: OcxProviderConfig } | undefined {
   for (const [providerName, provider] of Object.entries(config.providers)) {
+    // Never adds Pool 2 automatically. The OAuth store key `anthropic2` belongs to the builtin pool:
+    // its token path and the token guardian refuse an unmarked row of that name, so offering such a
+    // custom row here would advertise credentials no helper executor will spend.
+    if (providerName === "anthropic2") continue;
     if (provider.disabled === true) continue;
     if (provider.adapter !== "anthropic" || provider.authMode !== "oauth") continue;
     const set = getAccountSet(providerName);
@@ -72,8 +143,11 @@ function findAnthropicAuthProvider(
   return undefined;
 }
 
-export function resolveSidecarAuth(config: OcxConfig): SidecarAuthState {
-  const anthropic = findAnthropicAuthProvider(config);
+export function resolveSidecarAuth(config: OcxConfig, instance?: AnthropicInstanceId): SidecarAuthState {
+  const exact = instance ? resolveAnthropicSidecarAuth(config, instance) : undefined;
+  if (instance && !exact) throw new AnthropicHelperUnavailableError(instance);
+  const anthropic = exact ? { providerName: exact.anthropicProviderName, provider: exact.anthropicProvider }
+    : findAnthropicAuthProvider(config);
   return {
     isCodexAuth: hasUsableCodexLogin(config),
     isAnthropicAuth: anthropic !== undefined,

package/src/types/anthropic-account-pool.ts

@@ -0,0 +1,33 @@
+/**
+ * Anthropic OAuth account-pool settings. One shape, two locations:
+ * `config.anthropicAccountPool` for the `anthropic` instance and
+ * `config.providers.anthropic2.anthropicAccountPool` for `anthropic2`. Neither inherits from the other.
+ *
+ * Leaf module: `config.ts` and `provider.ts` import these types, never the reverse.
+ */
+export type OcxAccountPoolRotationStrategy = "quota" | "round-robin" | "fill-first";
+
+export type OcxAccountPoolQuotaWindow = "five-hour" | "weekly" | "max-utilization";
+
+export interface AnthropicModelRoute {
+  name: string;
+  match: string;
+  accounts: string[];
+  fallback?: boolean;
+}
+
+export interface AnthropicAccountPoolConfig {
+  enabled?: boolean;
+  /** Preserve native Claude Messages while the pool is enabled. Default true; false selects legacy translation. */
+  nativeMessages?: boolean;
+  /** Usage % threshold for new-session auto-pick. Default 80. 0 = disabled (affinity/active only). */
+  autoSwitchThreshold?: number;
+  /** New-session rotation strategy. Default quota (today's behaviour). */
+  strategy?: OcxAccountPoolRotationStrategy;
+  /** Successful new-session binds retained on one round-robin selection. Default 1; range 1..100. */
+  stickyLimit?: number;
+  /** Usage window for quota-based scoring. Default "five-hour" (today's behaviour). */
+  quotaWindow?: OcxAccountPoolQuotaWindow;
+  /** Ordered model allowlists; inactive while the pool is disabled. Stored account IDs only. */
+  routes?: AnthropicModelRoute[];
+}

package/src/types/config.ts

@@ -1,12 +1,8 @@
 import type { OcxProviderConfig } from "./provider";
 import type { CodexAccount } from "./accounts";
-
-export interface AnthropicModelRoute {
-  name: string;
-  match: string;
-  accounts: string[];
-  fallback?: boolean;
-}
+import type { AnthropicAccountPoolConfig, OcxAccountPoolRotationStrategy } from "./anthropic-account-pool";
+import type { AnthropicInstanceId } from "../providers/anthropic-instance-id";
+export type { AnthropicAccountPoolConfig, AnthropicModelRoute, OcxAccountPoolRotationStrategy, OcxAccountPoolQuotaWindow } from "./anthropic-account-pool";
 
 /** Public inference API exposure. Responses and Chat Completions are always served. */
 export interface OcxApiSurfacesConfig {
@@ -222,9 +218,9 @@ export interface OcxClaudeCodeConfig {
   /** Optional roster-style model forced on subagents at the next routed Claude Code launch. */
   subagentModelForce?: string;
   /** Claude-originated web-search override. Unset fields inherit the global sidecar settings. */
-  webSearchSidecar?: { backend?: "openai" | "anthropic" | "xai" | "gemini" | "exa"; model?: string };
+  webSearchSidecar?: { backend?: "openai" | "anthropic" | "xai" | "gemini" | "exa"; model?: string; anthropicInstance?: AnthropicInstanceId };
   /** Claude-originated vision override. Unset fields inherit the global sidecar settings. */
-  visionSidecar?: { backend?: "openai" | "anthropic" | "routed"; model?: string };
+  visionSidecar?: { backend?: "openai" | "anthropic" | "routed"; model?: string; anthropicInstance?: AnthropicInstanceId };
   /** Persisted Claude Desktop four-family routing profile. */
   desktopProfile?: OcxClaudeDesktopProfile;
   /**
@@ -1052,6 +1048,8 @@ export interface OcxConfig {
    * upgrade against a number nobody chose.
    */
   spend?: OcxSpendConfig;
+  /** Historical salted pool aliases; h(pool,P) cannot map to Q != P for any configured provider P. */
+  spendPoolAliases?: Record<string, string>;
   /** Opt-in per-account activation of newly reset Codex quota windows. */
   codexQuotaAutoRefresh?: Record<string, {
     fiveHour?: boolean;
@@ -1216,21 +1214,7 @@ export interface OcxConfig {
    * upstream has just rate-limited only ever runs after a refusal, so stranding it while a
    * second logged-in account sits idle is a defect rather than a configuration choice.
    */
-  anthropicAccountPool?: {
-    enabled?: boolean;
-    /** Preserve native Claude Messages while the pool is enabled. Default true; false selects legacy translation. */
-    nativeMessages?: boolean;
-    /** Usage % threshold for new-session auto-pick. Default 80. 0 = disabled (affinity/active only). */
-    autoSwitchThreshold?: number;
-    /** New-session rotation strategy. Default quota (today's behaviour). */
-    strategy?: OcxAccountPoolRotationStrategy;
-    /** Successful new-session binds retained on one round-robin selection. Default 1; range 1..100. */
-    stickyLimit?: number;
-    /** Usage window for quota-based scoring. Default "five-hour" (today's behaviour). */
-    quotaWindow?: OcxAccountPoolQuotaWindow;
-    /** Ordered model allowlists; inactive while the pool is disabled. Stored account IDs only. */
-    routes?: AnthropicModelRoute[];
-  };
+  anthropicAccountPool?: AnthropicAccountPoolConfig;
   /**
    * Generic OAuth multi-account PROACTIVE account preference (#2568, #695).
    *
@@ -1262,10 +1246,6 @@ export interface OcxConfig {
   corsAllowOrigins?: string[];
 }
 
-export type OcxAccountPoolRotationStrategy = "quota" | "round-robin" | "fill-first";
-
-export type OcxAccountPoolQuotaWindow = "five-hour" | "weekly" | "max-utilization";
-
 export type OcxComboStrategy = "failover" | "round-robin" | "random" | "least-used" | "reset-window" | "jev";
 export type OcxComboDefaultEffort = "low" | "medium" | "high" | "xhigh" | "max" | "ultra";
 export type OcxComboDefaultEffortMode = "fallback" | "force";
@@ -1526,6 +1506,8 @@ export interface OcxSearchConfig {
 }
 
 export interface OcxVisionSidecarConfig {
+  /** Explicit Anthropic account pool; unset inherits the request's instance. */
+  anthropicInstance?: AnthropicInstanceId;
   /** Master switch. Default: enabled when the selected backend has a usable credential. */
   enabled?: boolean;
   /**
@@ -1545,6 +1527,8 @@ export interface OcxVisionSidecarConfig {
 }
 
 export interface OcxWebSearchSidecarConfig {
+  /** Explicit Anthropic account pool; unset inherits the request's instance. */
+  anthropicInstance?: AnthropicInstanceId;
   /** Master switch. Default: enabled when a forward (ChatGPT) provider exists and the caller is logged in. */
   enabled?: boolean;
   /**

package/src/types/provider.ts

@@ -1,4 +1,5 @@
 import type { UpstreamHttpVersion, ReasoningSummaryDelivery, CodexAccountMode } from "./wire";
+import type { AnthropicAccountPoolConfig } from "./anthropic-account-pool";
 
 /**
  * Per-provider proactive-refresh policy. The guardian only ever touches a provider whose EFFECTIVE
@@ -274,6 +275,10 @@ export interface ModelCapabilities {
 }
 
 export interface OcxProviderConfig {
+  /** Explicit builtin Pool 2 provenance; endpoints never imply ownership. */
+  anthropicOAuthInstance?: "anthropic2";
+  /** Independent Anthropic pool settings; valid only on providers.anthropic2. */
+  anthropicAccountPool?: AnthropicAccountPoolConfig;
   /** Optional browser-compatible outbound TLS profile; disabled by default. */
   tlsProfile?: "antigravity-browser";
   /** Optional short provider namespace used only at request/catalog presentation time. */

package/src/types/tools.ts

@@ -399,6 +399,13 @@ export function isAllowedToolChoice(value: OcxToolChoice | undefined): value is
   return typeof value === "object" && value !== null && "allowedTools" in value;
 }
 
+export function requiresToolCall(choice: OcxToolChoice | undefined): boolean {
+  return choice === "required"
+    || (typeof choice === "object" && choice !== null && (
+      "name" in choice || ("mode" in choice && choice.mode === "required")
+    ));
+}
+
 /** Compile the request's tool-choice policy into a reusable advertisement/restoration predicate. */
 export function toolChoiceToolPredicate(
   choice: OcxToolChoice | undefined,

package/src/types.ts

@@ -16,6 +16,7 @@ export {
   resolveToolChoiceWireName,
   modelInList,
   isAllowedToolChoice,
+  requiresToolCall,
   toolChoiceToolPredicate,
   declaresCodeModeExec,
   toolRestrictsCallers,
@@ -23,6 +24,9 @@ export {
 } from "./types/tools";
 
 export type { UpstreamHttpVersion, ReasoningSummaryDelivery, CodexAccountMode } from "./types/wire";
+export type { AnthropicInstanceId } from "./providers/anthropic-instance-id";
+export { ANTHROPIC_INSTANCE_IDS, ANTHROPIC_PRIMARY_INSTANCE, ANTHROPIC_POOL2_INSTANCE, isAnthropicInstanceId } from "./providers/anthropic-instance-id";
+export type { AnthropicAccountPoolConfig, AnthropicModelRoute } from "./types/anthropic-account-pool";
 export {
   UPSTREAM_HTTP_VERSION_VALUES,
   REASONING_SUMMARY_DELIVERY_VALUES,

package/src/usage/cost.ts

@@ -30,6 +30,7 @@ import {
   cursorFastPriceSupported,
   findContextTier,
   isLongContext,
+  pricingFamilyProvider,
   type Cost4,
   type ExpectedPriceOverlay,
   type ExpectedPriceStatus,
@@ -262,7 +263,7 @@ function resolveMatchedPriceExact(
   if (userOverlay) return userOverlay;
   if (!cursorFastPriceSupported(provider, modelId)) return null;
   const verifiedOverride = overlays === EXPECTED_PRICE_OVERLAYS
-    ? findVerifiedPriceOverride(provider, modelId)
+    ? findVerifiedPriceOverride(pricingFamilyProvider(provider), modelId)
     : undefined;
   if (verifiedOverride && verifiedOverride.status !== "unverified" && validCost4(verifiedOverride.cost4) && hasNonZeroCost(verifiedOverride.cost4)) {
     return {
@@ -291,7 +292,7 @@ function resolveMatchedPriceExact(
       ...cursorFastPriceProvenance(provider, modelId),
     };
   }
-  const overlay = findExpectedPriceOverlay(provider, modelId, overlays);
+  const overlay = findExpectedPriceOverlay(overlays === EXPECTED_PRICE_OVERLAYS ? pricingFamilyProvider(provider) : provider, modelId, overlays);
   if (!overlay || !validCost4(overlay.cost4) || !hasNonZeroCost(overlay.cost4)) {
     if (options.allowModelLevelFallback === false) return null;
     const fallback = resolveModelLevelPrice(provider, modelId);

package/src/usage/expected-prices.ts

@@ -1,4 +1,15 @@
+import { CURSOR_CAPABILITIES } from "../adapters/cursor/catalog";
 import { normalizeCursorClaudeId } from "../adapters/cursor/claude-id";
+import { isAnthropicInstanceId } from "../providers/anthropic-instance-id";
+
+/**
+ * Provider key the compiled price catalogs are written under. Both Anthropic OAuth instances run
+ * the same models at the same published prices, so Pool 2 reads Pool 1's rows. Callers apply this
+ * only to the built-in catalogs; operator-supplied overlays and tiers stay keyed exactly.
+ */
+export function pricingFamilyProvider(provider: string): string {
+  return isAnthropicInstanceId(provider) ? "anthropic" : provider;
+}
 
 /**
  * Expected-price overlay for models whose jawcode cost rows are missing or all-zero
@@ -123,13 +134,23 @@ const CURSOR_OPUS_48 = CLAUDE_OPUS_46;
 // 0.1x most families use. 1M context and 128K output at one flat rate (no long-context tier).
 const CLAUDE_OPUS_55: Cost4 = { input: 4, output: 20, cacheRead: 0.2, cacheWrite: 5 };
 // Claude Sonnet 5.5 (claude-sonnet-5-5, released 2026-09-28): the Sonnet 5 tuple, 2 / 10, 5m cache
-// write 2.50, cache hit at the standard 0.1x (0.20). No fast mode and no long-context tier.
-const CLAUDE_SONNET_55: Cost4 = { input: 2, output: 10, cacheRead: 0.2, cacheWrite: 2.5 };
+// write 2.50; cache hits cut to 0.05x (0.10) on 2026-10-08. No fast mode or long-context tier.
+const CLAUDE_SONNET_55: Cost4 = { input: 2, output: 10, cacheRead: 0.1, cacheWrite: 2.5 };
+// Haiku 5.5 (2026-10-07): <=100K prompt base tuple; every rate is 5x above 100K.
+const CLAUDE_HAIKU_55: Cost4 = { input: 0.1, output: 0.5, cacheRead: 0.01, cacheWrite: 0.125 };
 const ANTHROPIC_PRICING = "https://platform.claude.com/docs/en/about-claude/pricing (official; 5m cache-write tier)";
 const CLAUDE_OPUS_5_SOURCE = `anthropic official Claude Opus 5 ${ANTHROPIC_PRICING}`;
 const CLAUDE_OPUS_55_SOURCE = `anthropic official Claude Opus 5.5 ${ANTHROPIC_PRICING}; cache hit = 0.05x base input`;
-const CLAUDE_SONNET_55_SOURCE = `anthropic official Claude Sonnet 5.5 ${ANTHROPIC_PRICING}`;
-const CURSOR_SONNET_55_PRICING = "https://cursor.com/docs/models/claude-sonnet-5-5 (same list rate as Anthropic)";
+const CLAUDE_SONNET_55_SOURCE = `anthropic official Claude Sonnet 5.5 ${ANTHROPIC_PRICING}; cache hit = 0.05x base input (2026-10-08 cut)`;
+const CLAUDE_HAIKU_55_SOURCE = `anthropic official Claude Haiku 5.5 ${ANTHROPIC_PRICING}; >100K prompt prices every token category at 5x`;
+const CURSOR_HAIKU_55_PRICING = "https://cursor.com/docs/models/claude-haiku-5-5 (same base and >100K rates as Anthropic)";
+const DEVIN_HAIKU_55_SOURCE = `derived (preemptive): Devin live catalog and modelCostData do not list claude-haiku-5-5 yet; Anthropic reference price ${ANTHROPIC_PRICING}`;
+const VENICE_55_SOURCE = "derived: Venice listing on https://models.dev/api.json (2026-10-08), 1.25x Anthropic list price";
+// Exact lookup must cover regular effort ids as well as every spelling Cursor can emit.
+const CURSOR_HAIKU_55_IDS = ["claude-haiku-5-5", "claude-haiku-5.5", "claude-5.5-haiku"].flatMap(base =>
+  [base, ...CURSOR_CAPABILITIES["claude-haiku-5-5"]!.variants.regular!.levels.map(level => `${base}-${level}`)],
+);
+const CURSOR_SONNET_55_PRICING = `https://cursor.com/docs/models/claude-sonnet-5-5 (same list rate as Anthropic; cache hit 0.05x) ${ANTHROPIC_PRICING}`;
 const DEVIN_SONNET_55_SOURCE = `derived (preemptive): Devin's live catalog and modelCostData table do not list claude-sonnet-5-5 yet; Anthropic list price shown as estimate ${ANTHROPIC_PRICING}`;
 const CURSOR_OPUS_55_PRICING = "https://cursor.com/docs/models/claude-opus-5-5 (Cursor Other Models pool; same list rate as Anthropic, Fast Mode billed separately)";
 const CURSOR_OPUS_48_FAST_PRICING = "https://cursor.com/docs/models/claude-opus-4-8";
@@ -291,11 +312,26 @@ export const EXPECTED_PRICE_OVERLAYS: readonly ExpectedPriceOverlay[] = [
   { provider: "anthropic-apikey", modelId: "claude-opus-5-5", cost4: CLAUDE_OPUS_55, source: CLAUDE_OPUS_55_SOURCE, verifiedAt: "2026-09-23", status: "verified" },
   // Cursor canonicalizes every Opus 5.5 spelling (thinking/effort/fast suffixes) onto this row.
   { provider: "cursor", modelId: "claude-opus-5-5", cost4: CLAUDE_OPUS_55, source: CURSOR_OPUS_55_PRICING, verifiedAt: "2026-09-23", status: "verified" },
+  // Haiku 5.5: official Anthropic and Cursor rates; reseller/preemptive rows remain estimates.
+  ...["anthropic", "anthropic-apikey"].map((provider): ExpectedPriceOverlay => ({
+    provider, modelId: "claude-haiku-5-5", cost4: CLAUDE_HAIKU_55,
+    source: CLAUDE_HAIKU_55_SOURCE, verifiedAt: "2026-10-08", status: "verified",
+  })),
+  ...CURSOR_HAIKU_55_IDS.map((modelId): ExpectedPriceOverlay => ({
+    provider: "cursor", modelId, cost4: CLAUDE_HAIKU_55,
+    source: CURSOR_HAIKU_55_PRICING, verifiedAt: "2026-10-08", status: "verified",
+  })),
+  ...["devin", "devin-cli"].map((provider): ExpectedPriceOverlay => ({
+    provider, modelId: "claude-haiku-5-5", cost4: CLAUDE_HAIKU_55,
+    source: DEVIN_HAIKU_55_SOURCE, verifiedAt: "2026-10-08", status: "verified-derived",
+  })),
+  { provider: "venice", modelId: "claude-haiku-5-5", cost4: { input: 0.125, output: 0.625, cacheRead: 0.0125, cacheWrite: 0.15625 }, source: VENICE_55_SOURCE, verifiedAt: "2026-10-08", status: "verified-derived" },
+  { provider: "venice", modelId: "claude-sonnet-5-5", cost4: { input: 2.5, output: 12.5, cacheRead: 0.125, cacheWrite: 3.125 }, source: VENICE_55_SOURCE, verifiedAt: "2026-10-08", status: "verified-derived" },
   // Claude Sonnet 5.5. Same layering as Opus 5.5: the anthropic bundle row wins for the bare id,
   // these cover account-label namespaces, and Cursor publishes the list rate on its model page.
-  { provider: "anthropic", modelId: "claude-sonnet-5-5", cost4: CLAUDE_SONNET_55, source: CLAUDE_SONNET_55_SOURCE, verifiedAt: "2026-09-29", status: "verified" },
-  { provider: "anthropic-apikey", modelId: "claude-sonnet-5-5", cost4: CLAUDE_SONNET_55, source: CLAUDE_SONNET_55_SOURCE, verifiedAt: "2026-09-29", status: "verified" },
-  { provider: "cursor", modelId: "claude-sonnet-5-5", cost4: CLAUDE_SONNET_55, source: CURSOR_SONNET_55_PRICING, verifiedAt: "2026-09-29", status: "verified" },
+  { provider: "anthropic", modelId: "claude-sonnet-5-5", cost4: CLAUDE_SONNET_55, source: CLAUDE_SONNET_55_SOURCE, verifiedAt: "2026-10-08", status: "verified" },
+  { provider: "anthropic-apikey", modelId: "claude-sonnet-5-5", cost4: CLAUDE_SONNET_55, source: CLAUDE_SONNET_55_SOURCE, verifiedAt: "2026-10-08", status: "verified" },
+  { provider: "cursor", modelId: "claude-sonnet-5-5", cost4: CLAUDE_SONNET_55, source: CURSOR_SONNET_55_PRICING, verifiedAt: "2026-10-08", status: "verified" },
   // MiniMax M2.1 highspeed — published PAYG price (verified).
   { provider: "minimax", modelId: "MiniMax-M2.1-highspeed", cost4: MINIMAX_M21_HIGHSPEED, source: MINIMAX_PRICING, verifiedAt: "2026-07-20", status: "verified" },
   { provider: "minimax-cn", modelId: "MiniMax-M2.1-highspeed", cost4: MINIMAX_M21_HIGHSPEED, source: MINIMAX_PRICING, verifiedAt: "2026-07-20", status: "verified" },
@@ -371,10 +407,10 @@ export const EXPECTED_PRICE_OVERLAYS: readonly ExpectedPriceOverlay[] = [
   // Alias without the Antigravity "-thinking" suffix (if logs/UI ever surface it).
   { provider: "google-antigravity", modelId: "claude-opus-4-6", cost4: CLAUDE_OPUS_46, source: `anthropic official Claude Opus 4.6 ${ANTHROPIC_PRICING}`, verifiedAt: "2026-07-23", status: "verified" },
   // Antigravity uses subscription quota; these are derived Anthropic reference estimates.
-  { provider: "google-antigravity", modelId: "claude-sonnet-5-5", cost4: CLAUDE_SONNET_55, source: `derived: Anthropic Claude Sonnet 5.5 reference price; ${ANTHROPIC_PRICING}`, verifiedAt: "2026-10-03", status: "verified-derived" },
-  { provider: "google-antigravity", modelId: "claude-sonnet-5-5-low", cost4: CLAUDE_SONNET_55, source: `derived: Anthropic Claude Sonnet 5.5 reference price; ${ANTHROPIC_PRICING}`, verifiedAt: "2026-10-03", status: "verified-derived" },
-  { provider: "google-antigravity", modelId: "claude-sonnet-5-5-medium", cost4: CLAUDE_SONNET_55, source: `derived: Anthropic Claude Sonnet 5.5 reference price; ${ANTHROPIC_PRICING}`, verifiedAt: "2026-10-03", status: "verified-derived" },
-  { provider: "google-antigravity", modelId: "claude-sonnet-5-5-high", cost4: CLAUDE_SONNET_55, source: `derived: Anthropic Claude Sonnet 5.5 reference price; ${ANTHROPIC_PRICING}`, verifiedAt: "2026-10-03", status: "verified-derived" },
+  { provider: "google-antigravity", modelId: "claude-sonnet-5-5", cost4: CLAUDE_SONNET_55, source: `derived: Anthropic Claude Sonnet 5.5 reference price (cache hit 0.05x); ${ANTHROPIC_PRICING}`, verifiedAt: "2026-10-08", status: "verified-derived" },
+  { provider: "google-antigravity", modelId: "claude-sonnet-5-5-low", cost4: CLAUDE_SONNET_55, source: `derived: Anthropic Claude Sonnet 5.5 reference price (cache hit 0.05x); ${ANTHROPIC_PRICING}`, verifiedAt: "2026-10-08", status: "verified-derived" },
+  { provider: "google-antigravity", modelId: "claude-sonnet-5-5-medium", cost4: CLAUDE_SONNET_55, source: `derived: Anthropic Claude Sonnet 5.5 reference price (cache hit 0.05x); ${ANTHROPIC_PRICING}`, verifiedAt: "2026-10-08", status: "verified-derived" },
+  { provider: "google-antigravity", modelId: "claude-sonnet-5-5-high", cost4: CLAUDE_SONNET_55, source: `derived: Anthropic Claude Sonnet 5.5 reference price (cache hit 0.05x); ${ANTHROPIC_PRICING}`, verifiedAt: "2026-10-08", status: "verified-derived" },
   { provider: "google-antigravity", modelId: "claude-opus-5-5", cost4: CLAUDE_OPUS_55, source: `derived: Anthropic Claude Opus 5.5 reference price; ${ANTHROPIC_PRICING}`, verifiedAt: "2026-10-03", status: "verified-derived" },
   { provider: "google-antigravity", modelId: "claude-opus-5-5-low", cost4: CLAUDE_OPUS_55, source: `derived: Anthropic Claude Opus 5.5 reference price; ${ANTHROPIC_PRICING}`, verifiedAt: "2026-10-03", status: "verified-derived" },
   { provider: "google-antigravity", modelId: "claude-opus-5-5-medium", cost4: CLAUDE_OPUS_55, source: `derived: Anthropic Claude Opus 5.5 reference price; ${ANTHROPIC_PRICING}`, verifiedAt: "2026-10-03", status: "verified-derived" },
@@ -482,7 +518,7 @@ export const EXPECTED_PRICE_OVERLAYS: readonly ExpectedPriceOverlay[] = [
   { provider: "devin-cli", modelId: "claude-opus-5", cost4: CLAUDE_OPUS_46, source: DEVIN_PRICING, verifiedAt: "2026-09-13", status: "verified-derived" },
   { provider: "devin-cli", modelId: "claude-opus-5-5", cost4: CLAUDE_OPUS_55, source: `derived: live Devin catalog lists claude-opus-5-5 but Devin's modelCostData table does not yet; Anthropic list price shown as estimate ${ANTHROPIC_PRICING}`, verifiedAt: "2026-09-23", status: "verified-derived" },
   { provider: "devin-cli", modelId: "claude-fable-5-1", cost4: CLAUDE_FABLE_51, source: DEVIN_PRICING, verifiedAt: "2026-09-13", status: "verified-derived" },
-  { provider: "devin-cli", modelId: "claude-sonnet-5-5", cost4: CLAUDE_SONNET_55, source: DEVIN_SONNET_55_SOURCE, verifiedAt: "2026-09-29", status: "verified-derived" },
+  { provider: "devin-cli", modelId: "claude-sonnet-5-5", cost4: CLAUDE_SONNET_55, source: DEVIN_SONNET_55_SOURCE, verifiedAt: "2026-10-08", status: "verified-derived" },
   { provider: "devin-cli", modelId: "claude-sonnet-5", cost4: DEVIN_SONNET_5, source: DEVIN_PRICING, verifiedAt: "2026-09-13", status: "verified-derived" },
   { provider: "devin-cli", modelId: "glm-5-3", cost4: GLM_53, source: DEVIN_PRICING, verifiedAt: "2026-09-13", status: "verified-derived" },
   { provider: "devin-cli", modelId: "kimi-k3", cost4: DEVIN_KIMI_K3, source: DEVIN_PRICING, verifiedAt: "2026-09-13", status: "verified-derived" },
@@ -501,7 +537,7 @@ export const EXPECTED_PRICE_OVERLAYS: readonly ExpectedPriceOverlay[] = [
   { provider: "devin", modelId: "claude-opus-4-8", cost4: CLAUDE_OPUS_46, source: DEVIN_PRICING, verifiedAt: "2026-09-13", status: "verified-derived" },
   { provider: "devin", modelId: "claude-opus-5-5", cost4: CLAUDE_OPUS_55, source: `derived: live Devin catalog lists claude-opus-5-5 but Devin's modelCostData table does not yet; Anthropic list price shown as estimate ${ANTHROPIC_PRICING}`, verifiedAt: "2026-09-23", status: "verified-derived" },
   { provider: "devin", modelId: "claude-fable-5-1", cost4: CLAUDE_FABLE_51, source: DEVIN_PRICING, verifiedAt: "2026-09-13", status: "verified-derived" },
-  { provider: "devin", modelId: "claude-sonnet-5-5", cost4: CLAUDE_SONNET_55, source: DEVIN_SONNET_55_SOURCE, verifiedAt: "2026-09-29", status: "verified-derived" },
+  { provider: "devin", modelId: "claude-sonnet-5-5", cost4: CLAUDE_SONNET_55, source: DEVIN_SONNET_55_SOURCE, verifiedAt: "2026-10-08", status: "verified-derived" },
   { provider: "devin", modelId: "claude-sonnet-5", cost4: DEVIN_SONNET_5, source: DEVIN_PRICING, verifiedAt: "2026-09-13", status: "verified-derived" },
   { provider: "devin", modelId: "glm-5-2", cost4: GLM_52, source: `enterprise list column (self-serve shows an unannounced 0 promo); ${DEVIN_PRICING}`, verifiedAt: "2026-09-13", status: "verified-derived" },
   { provider: "devin", modelId: "kimi-k2-7", cost4: DEVIN_KIMI_K27, source: DEVIN_PRICING, verifiedAt: "2026-09-13", status: "verified-derived" },
@@ -705,6 +741,8 @@ export interface ContextTier {
 const OPENAI_LONG_CONTEXT: Cost4 = { input: 2, output: 1.5, cacheRead: 2, cacheWrite: 2 };
 /** xAI and MiniMax double every rate uniformly past their thresholds. */
 const UNIFORM_DOUBLE: Cost4 = { input: 2, output: 2, cacheRead: 2, cacheWrite: 2 };
+// Haiku 5.5 reprices the whole request above 100K (official pricing, read 2026-10-08).
+const HAIKU_55_LONG_CONTEXT: Cost4 = { input: 5, output: 5, cacheRead: 5, cacheWrite: 5 };
 
 const OPENAI_PRICING_DOC = "https://developers.openai.com/api/docs/pricing";
 const OPENAI_CONTEXT_MODELS = [
@@ -723,6 +761,19 @@ const OPENAI_CONTEXT_MODELS = [
 ];
 
 export const CONTEXT_TIERS: readonly ContextTier[] = [
+  // Reference bands on preemptive/subscription surfaces follow their reference price, not billing.
+  ...[
+    ...["anthropic", "anthropic-apikey", "opencode-go", "opencode-zen", "venice", "github-copilot", "devin", "devin-cli", "claude-cli"].map(provider => [provider, "claude-haiku-5-5"]),
+    ...["", "global.", "us.", "eu.", "jp.", "au."].map(prefix => ["amazon-bedrock", `${prefix}anthropic.claude-haiku-5-5`]),
+    ...["openrouter", "vercel-ai-gateway", "zenmux"].map(provider => [provider, "anthropic/claude-haiku-5.5"]),
+    ["cloudflare-ai-gateway", "anthropic/claude-haiku-5-5"], ["kiro", "claude-haiku-5.5"],
+    ...CURSOR_HAIKU_55_IDS.map(modelId => ["cursor", modelId]),
+  ].map(([provider, modelId]): ContextTier => ({
+    provider, modelId, thresholdInputTokens: 100_000, inclusive: false,
+    multiplier: HAIKU_55_LONG_CONTEXT,
+    source: provider === "cursor" ? CURSOR_HAIKU_55_PRICING : ANTHROPIC_PRICING,
+    verifiedAt: "2026-10-08",
+  })),
   // API-reference estimates do not apply subscription-only exemptions or multipliers.
   ...["openai", "openai-apikey"].flatMap(provider =>
     OPENAI_CONTEXT_MODELS.map((modelId): ContextTier => ({
@@ -811,7 +862,8 @@ export function findContextTier(
   modelId: string,
   tiers: readonly ContextTier[] = CONTEXT_TIERS,
 ): ContextTier | undefined {
-  return tiers.find(tier => tier.provider === provider && tier.modelId === modelId);
+  const familyProvider = tiers === CONTEXT_TIERS ? pricingFamilyProvider(provider) : provider;
+  return tiers.find(tier => tier.provider === familyProvider && tier.modelId === modelId);
 }
 
 /** Whether a raw input-token count crosses the tier's published boundary. */

package/src/vision/anthropic-describe.ts

@@ -1,3 +1,6 @@
+import { resolveAnthropicHelperSnapshot, fetchAnthropicHelper, anthropicHelperMessagesUrl } from "../sidecar/anthropic-binding";
+import { isAnthropicInstanceId } from "../providers/anthropic-instance-id";
+import type { OAuthAccessSnapshot } from "../oauth";
 import type { OcxConfig, OcxProviderConfig } from "../types";
 import { sidecarThinkingOff } from "../adapters/anthropic-model-contract";
 import { CLAUDE_CODE_HEADERS, claudeCodeSessionId } from "../adapters/client-fingerprint";
@@ -159,8 +162,15 @@ export async function describeImageAnthropic(
   if (!image.block) return { text: "", error: image.error ?? "invalid image" };
 
   let token: string;
+  let snapshot: OAuthAccessSnapshot | undefined;
+  const capturedTarget = provider.baseUrl;
   try {
-    token = await getAnthropicSidecarAccessToken(providerName, settings.model, config);
+    if (config && isAnthropicInstanceId(providerName)) {
+      snapshot = await resolveAnthropicHelperSnapshot(config, providerName, settings.model);
+      token = snapshot.accessToken;
+    } else {
+      token = await getAnthropicSidecarAccessToken(providerName, settings.model, config);
+    }
   } catch (error) {
     return { text: "", error: `anthropic vision sidecar auth failed: ${publicOAuthAuthenticationErrorMessage(error)}` };
   }
@@ -195,13 +205,16 @@ export async function describeImageAnthropic(
 
   // Anthropic image blocks have no detail field, but detail remains part of the cache identity.
   void detail;
-  const base = provider.baseUrl.replace(/\/v1\/?$/, "");
+  const url = anthropicHelperMessagesUrl(provider.baseUrl);
+  const dispatch = (target: string, init: RequestInit) => snapshot && config
+    ? fetchAnthropicHelper(config, snapshot, settings.model, capturedTarget, target, init)
+    : fetch(target, init);
   const linkedSignal = signalWithTimeout(settings.timeoutMs, abortSignal);
   const sidecarExit = sidecarEnter("vision");
   const startedAt = Date.now();
   try {
     const res = await fetchWithResetRetry(
-      recovery => fetch(`${base}/v1/messages`, applyUpstreamRecoveryInit({
+      recovery => dispatch(url, applyUpstreamRecoveryInit({
         method: "POST",
         redirect: "manual",
         headers,

package/src/vision/index.ts

@@ -217,6 +217,9 @@ function descriptionIdentity(job: ImageJob, plan: VisionPlan): { key: string; pe
     key: JSON.stringify([
       plan.backend,
       plan.settings.model,
+      // Explicit identity: the resolved pool and reasoning. Settings that only gate or bound the call
+      // (enabled, timeoutMs, maxDescriptionsPerTurn) never split the cache.
+      ...(plan.backend === "anthropic" ? [plan.anthropicSidecar?.providerName ?? null, plan.settings.reasoning] : []),
       ...(plan.backend === "openai" ? [plan.settings.reasoning] : []),
       job.detail ?? "high",
       imageHash,

package/src/vision/plan.ts

@@ -11,7 +11,7 @@ import {
   modelAcceptsImageInput,
 } from "./eligibility";
 import { normalizeVisionReasoningForModel } from "./reasoning";
-import { resolveSidecarAuth } from "../sidecar/auth";
+import { inheritedAnthropicInstance, resolveSidecarAuth, resolveAnthropicHelperInstance, resolveAnthropicSidecarAuth, withAnthropicHelperRefusal } from "../sidecar/auth";
 import { DEFAULT_VISION_TIMEOUT_MS, MAX_VISION_TIMEOUT_MS, MIN_VISION_TIMEOUT_MS } from "./timeout-bounds";
 import { carriesImages } from "./image-rewrite";
 
@@ -50,8 +50,9 @@ export interface AnthropicVisionProvider {
  * First enabled Anthropic OAuth provider whose active stored account is not marked for reauth.
  * Delegates to the shared sidecar auth module (#2188) — same predicate as web-search.
  */
-export function findAnthropicVisionProvider(config: OcxConfig): AnthropicVisionProvider | undefined {
-  const auth = resolveSidecarAuth(config);
+export function findAnthropicVisionProvider(config: OcxConfig, parentProviderName?: string): AnthropicVisionProvider | undefined {
+  const instance = resolveAnthropicHelperInstance(config, { backendFamily: "anthropic", anthropicInstance: config.visionSidecar?.anthropicInstance, parentProviderName });
+  const auth = resolveSidecarAuth(config, instance);
   if (!auth.isAnthropicAuth || !auth.anthropicProviderName || !auth.anthropicProvider) return undefined;
   return { providerName: auth.anthropicProviderName, provider: auth.anthropicProvider, config };
 }
@@ -68,6 +69,16 @@ export function resolveVisionBackend(
   return anthropicSidecar ? "anthropic" : "openai";
 }
 
+/** Existing family preference, with a builtin parent contributing its own auth availability. */
+function preferredVisionBackend(config: OcxConfig, parentProviderName?: string): "openai" | "anthropic" {
+  const cfg = config.visionSidecar ?? {};
+  const requested = cfg.anthropicInstance ?? inheritedAnthropicInstance(config, parentProviderName);
+  const exact = requested ? resolveAnthropicSidecarAuth(config, requested) : undefined;
+  const legacy = findAnthropicVisionProvider({ ...config, visionSidecar: { ...cfg, anthropicInstance: undefined } });
+  return resolveVisionBackend(cfg.backend, exact
+    ? { providerName: exact.anthropicProviderName, provider: exact.anthropicProvider, config } : legacy);
+}
+
 /** Native model used by the OpenAI vision helper, including its bounded default. */
 export function resolveOpenAiVisionModel(config: Pick<OcxConfig, "visionSidecar">): string {
   const configured = config.visionSidecar?.model;
@@ -170,7 +181,7 @@ export function shouldResolveOpenAiVisionSidecar(
   const cfg = config.visionSidecar ?? {};
   if (cfg.enabled === false) return false;
   if (usableRoutedVisionModel(config)) return false;
-  return resolveVisionBackend(cfg.backend, findAnthropicVisionProvider(config)) === "openai";
+  return preferredVisionBackend(config, providerName) === "openai";
 }
 
 export interface VisionPlan {
@@ -241,8 +252,10 @@ export function planVisionSidecar(
   }
   // A non-dispatchable routed configuration keeps the legacy backend fallback below.
 
-  const anthropicSidecar = findAnthropicVisionProvider(config);
-  const backend = resolveVisionBackend(cfg.backend, anthropicSidecar);
+  const backend = preferredVisionBackend(config, options.providerName);
+  // An unavailable selected pool degrades to "no plan" (images stripped); it never fails the request.
+  const anthropicSidecar = backend === "anthropic"
+    ? withAnthropicHelperRefusal("vision", () => findAnthropicVisionProvider(config, options.providerName)) : undefined;
   // A namespaced routed model must never reach the forward/OAuth executors
   // (they POST the string verbatim); the effective-model resolver falls back
   // to each side's default in that case.

package/src/web-search/alpha-search.ts

@@ -1,3 +1,4 @@
+import { AnthropicHelperUnavailableError } from "../sidecar/auth";
 /**
  * Serve Codex's built-in `/v1/alpha/search` when no ChatGPT forward provider exists.
  *
@@ -101,7 +102,12 @@ export function resolveAlphaSearchSidecar(config: OcxConfig): AlphaSearchSidecar
   if (backend === "openai") return { status: "unconfigured" };
   switch (backend) {
     case "anthropic": {
-      const found = findAnthropicSidecarProvider(config);
+      let found;
+      try { found = findAnthropicSidecarProvider(config); }
+      catch (error) {
+        if (error instanceof AnthropicHelperUnavailableError) return { status: "missing-credential", backend };
+        throw error;
+      }
       return found
         ? { status: "ready", sidecar: { backend, providerName: found.providerName, provider: found.provider, config } }
         : { status: "missing-credential", backend };

package/src/web-search/anthropic-executor.ts

@@ -1,3 +1,6 @@
+import { resolveAnthropicHelperSnapshot, fetchAnthropicHelper, anthropicHelperMessagesUrl } from "../sidecar/anthropic-binding";
+import { isAnthropicInstanceId } from "../providers/anthropic-instance-id";
+import type { OAuthAccessSnapshot } from "../oauth";
 import type { OcxConfig, OcxProviderConfig } from "../types";
 import { publicOAuthAuthenticationErrorMessage } from "../oauth";
 import { getAnthropicSidecarAccessToken } from "../oauth/anthropic-routing";
@@ -167,11 +170,17 @@ export async function runAnthropicWebSearch(
   abortSignal?: AbortSignal,
   config?: OcxConfig,
 ): Promise<SidecarOutcome> {
-  const base = provider.baseUrl.replace(/\/v1\/?$/, "");
-  const url = `${base}/v1/messages`;
+  const url = anthropicHelperMessagesUrl(provider.baseUrl);
   let token: string;
+  let snapshot: OAuthAccessSnapshot | undefined;
+  const capturedTarget = provider.baseUrl;
   try {
-    token = await getAnthropicSidecarAccessToken(providerName, settings.model, config);
+    if (config && isAnthropicInstanceId(providerName)) {
+      snapshot = await resolveAnthropicHelperSnapshot(config, providerName, settings.model);
+      token = snapshot.accessToken;
+    } else {
+      token = await getAnthropicSidecarAccessToken(providerName, settings.model, config);
+    }
   } catch (e) {
     return { text: "", sources: [], error: `anthropic sidecar auth failed: ${publicOAuthAuthenticationErrorMessage(e)}` };
   }
@@ -205,6 +214,9 @@ export async function runAnthropicWebSearch(
     stream: true,
   };
 
+  const dispatch = (target: string, init: RequestInit) => snapshot && config
+    ? fetchAnthropicHelper(config, snapshot, settings.model, capturedTarget, target, init)
+    : fetch(target, init);
   const linkedSignal = signalWithTimeout(settings.timeoutMs, abortSignal);
   const sidecarExit = sidecarEnter("web-search");
   const t0 = Date.now();
@@ -212,7 +224,7 @@ export async function runAnthropicWebSearch(
     const res = await fetchWithResetRetry(
       // The replay needs `keepalive: false` to leave the half-closed pooled socket; Bun has
       // ignored a bare `Connection: close` (oven-sh/bun#20492).
-      recovery => fetch(url, applyUpstreamRecoveryInit({
+      recovery => dispatch(url, applyUpstreamRecoveryInit({
         method: "POST",
         redirect: "manual",
         headers,