@bitkyc08/opencodex 2.80.0 → 2.82.0

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,

package/src/web-search/index.ts

@@ -6,7 +6,7 @@ import type { CodexAuthPolicyConfig } from "../codex/auth-context";
 import { isCodexReserveRequestEligible } from "../codex/loopback-target";
 import type { DataPlaneAdmission } from "../server/auth-cors";
 import type { ResolvedOpenAiForwardSidecar } from "../providers/openai-sidecar";
-import { resolveSidecarAuth } from "../sidecar/auth";
+import { resolveSidecarAuth, resolveAnthropicHelperInstance, withAnthropicHelperRefusal } from "../sidecar/auth";
 import { validateXaiSearchOptions, type XaiSearchOptions } from "./xai-executor";
 import type { OcxWebSearchSidecarConfig } from "../types";
 import { DEFAULT_STALL_TIMEOUT_SEC } from "../stall-timeout";
@@ -168,11 +168,15 @@ export function planWebSearch(
   const connectTimeoutMs = config.connectTimeoutMs ?? 200_000;
   // Shared auth state (#2188): presence only — backend PREFERENCE stays with
   // resolveSidecarBackend's explicit-or-openai contract.
-  const auth = resolveSidecarAuth(config);
+  const backend = resolveSidecarBackend(cfg.backend);
+  // Only the anthropic backend can be refused; an unavailable selected pool means no plan, so the
+  // main request takes the normal path instead of failing or borrowing another pool.
+  const auth = withAnthropicHelperRefusal("web-search", () => resolveSidecarAuth(config, resolveAnthropicHelperInstance(config,
+    { backendFamily: backend, anthropicInstance: cfg.anthropicInstance, parentProviderName: options.providerName })));
+  if (!auth) return undefined;
   const anthropicSidecar = auth.isAnthropicAuth && auth.anthropicProviderName && auth.anthropicProvider
     ? { providerName: auth.anthropicProviderName, provider: auth.anthropicProvider, config }
     : undefined;
-  const backend = resolveSidecarBackend(cfg.backend);
   const maxSearches = cfg.maxSearchesPerTurn ?? DEFAULT_MAX_SEARCHES;
   const stallTimeoutSec = webSearchStallTimeoutSec(
     config.stallTimeoutSec,

package/src/web-search/loop.ts

@@ -1,6 +1,7 @@
 import type { AdapterRequest, IncomingMeta, ProviderAdapter } from "../adapters/base";
 import type { AdapterEvent, OcxConfig, OcxMessage, OcxParsedRequest, OcxProviderConfig, OcxProviderOpaqueToolCallMetadata, OcxThinkingContent, OcxUsage, RateLimitRetryPolicy } from "../types";
 import { namespacedToolName, toolChoiceToolPredicate } from "../types";
+import { isAnthropicInstanceId } from "../providers/anthropic-instance-id";
 import { cloneProviderOpaqueToolCallMetadata } from "../responses/provider-opaque-metadata";
 import type { AttemptRecoveryKind } from "../usage/log";
 import { isTruncatedStopReason } from "../responses/truncated-stop-reason";
@@ -322,7 +323,7 @@ export interface WebSearchLoopDeps {
   /** Observe the exact adapter request selected for each routed-model iteration. */
   onRequestBuilt?: (request: AdapterRequest) => void;
   /** Request-scoped executor retains the core's selection binding across loop retries. */
-  fetchForRequest?: (request: AdapterRequest, parsed: OcxParsedRequest) => typeof globalThis.fetch;
+  fetchForRequest?: (request: AdapterRequest, parsed: OcxParsedRequest, adapter: ProviderAdapter) => typeof globalThis.fetch;
   /** Called before each routed-model dispatch in the loop, for attempt telemetry. Same-target 429 replays pass the `rate-limit-429` recovery kind. */
   onAttemptSend?: (recovery?: AttemptRecoveryKind) => void;
   /**
@@ -353,6 +354,8 @@ export interface WebSearchLoopDeps {
     | { adapter: ProviderAdapter; recoveryKind: AttemptRecoveryKind }
     | null
     | Promise<{ adapter: ProviderAdapter; recoveryKind: AttemptRecoveryKind } | null>;
+  /** Release a credential-hop permit if this iteration ended before the adapter used it. */
+  onIterationEnd?: () => void;
   /** Opt-in same-target 429 policy (key-auth providers). When present, 429 replays on the SAME key before on429 rotation. */
   retryOn429Policy?: Required<RateLimitRetryPolicy> | null;
   /** Called only when the final bridged Responses stream reaches completed or incomplete. */
@@ -491,7 +494,7 @@ export async function runWithWebSearch(deps: WebSearchLoopDeps): Promise<Respons
           cachedRequest = request;
           cachedAdapter = requestAdapter;
         }
-        const requestFetch = headerDeadline.pacedFetch(deps.fetchForRequest?.(request, iterParsed) ?? routedProviderFetch);
+        const requestFetch = headerDeadline.pacedFetch(deps.fetchForRequest?.(request, iterParsed, requestAdapter) ?? routedProviderFetch);
         let response: Response;
         try {
           if (requestAdapter.fetchResponse) {
@@ -501,7 +504,10 @@ export async function runWithWebSearch(deps: WebSearchLoopDeps): Promise<Respons
               timeoutMs: connectTimeoutMs,
               returnRawErrors: true,
               stream: true,
+              sendBudget: deps.incomingMeta.sendBudget,
+              onPhysicalSend: deps.incomingMeta.onPhysicalSend,
               executor: requestFetch,
+              onRecoveryWithheld: deps.incomingMeta.onRecoveryWithheld,
             });
           } else {
             response = await fetchWithResetRetry(
@@ -571,18 +577,36 @@ export async function runWithWebSearch(deps: WebSearchLoopDeps): Promise<Respons
       // 429 key-failover parity with the normal routed path: rotate pool keys until one responds
       // or the pool is exhausted (deps.on429 returns null — cooldown map guarantees termination).
       while ((prepared.response.status === 429
-        || (prepared.response.status === 403 && deps.incomingMeta?.providerName === "anthropic" && !accountRefusalOutputStarted)
+        || (prepared.response.status === 401 && isAnthropicInstanceId(deps.incomingMeta?.providerName)
+          && !accountRefusalOutputStarted)
+        || (prepared.response.status === 403
+          && (isAnthropicInstanceId(deps.incomingMeta?.providerName) || deps.incomingMeta?.providerName === "google-antigravity")
+          && !accountRefusalOutputStarted)
         || (iterParsed._kiroAuthContext && (prepared.response.status === 400 || prepared.response.status === 403))) && deps.on429) {
         const rotated = await deps.on429(prepared.response.headers.get("retry-after"), prepared.response.headers,
           iterParsed, prepared.response);
         if (!rotated) break;
-        // Never let a broken body's cancel promise outlive the cumulative header deadline. Observe
-        // it, but proceed immediately to the rotated fetch under the SAME deadline signal.
-        try { void prepared.response.body?.cancel().catch(() => {}); } catch { /* already closed */ }
+        const retainRefusal = prepared.response.status === 403
+          && deps.incomingMeta?.providerName === "google-antigravity" && rotated.recoveryKind === "oauth-account-403";
+        // Keep the bounded refusal readable until the sibling actually returns headers.
+        // Other rotation paths retain their existing cancellation boundary.
+        if (!retainRefusal) {
+          try { void prepared.response.body?.cancel().catch(() => {}); } catch { /* already closed */ }
+        }
         adapter = rotated.adapter;
         // Stall-watchdog seam between bounded retry fetches (audit 011 B3).
         yield { type: "heartbeat" };
-        prepared = await fetchOnce(adapter, rotated.recoveryKind);
+        let replacement: IterationResponse;
+        try {
+          replacement = await fetchOnce(adapter, rotated.recoveryKind);
+        } catch (error) {
+          if (!retainRefusal || signal.aborted || headerDeadline.didExpire() || isTranslatorBudgetExceededError(error)) throw error;
+          break; // Format the original 403 safely; replacement diagnostics are not client errors.
+        }
+        if (retainRefusal) {
+          try { void prepared.response.body?.cancel().catch(() => {}); } catch { /* already closed */ }
+        }
+        prepared = replacement;
       }
 
       // Final headers have arrived. Clear only the deadline timer before ANY body read.
@@ -623,6 +647,7 @@ export async function runWithWebSearch(deps: WebSearchLoopDeps): Promise<Respons
       throw new LoopError(502, `Provider unreachable: ${error instanceof Error ? error.message : String(error)}`);
     } finally {
       headerDeadline.clear();
+      deps.onIterationEnd?.();
     }
   };
 

package/src/web-search/passthrough-bridge.ts

@@ -76,6 +76,7 @@ import {
 import { providerDestinationConfigError } from "../lib/destination-policy";
 import { redactSecretString } from "../lib/redact";
 import { rememberBridgeSearchReplay } from "../responses/bridge-search-replay-cache";
+import { withAnthropicHelperRefusal } from "../sidecar/auth";
 
 /** Canonical Ollama Cloud origin. The only origin the "ollama" backend derives on its own. */
 export const OLLAMA_CLOUD_ORIGIN = "https://ollama.com";
@@ -246,12 +247,14 @@ export function resolvePassthroughWebSearchBridgeAuth(
   backend: ProviderWebSearchBridgeBackend | undefined,
   config: OcxConfig,
   openAiSidecar?: ResolvedOpenAiForwardSidecar,
+  parentProviderName?: string,
 ): PassthroughWebSearchBridgeAuth {
   switch (backend) {
     case "openai":
       return openAiSidecar ? { openAiSidecar } : {};
     case "anthropic": {
-      const anthropic = findAnthropicSidecarProvider(config);
+      // An unavailable selected pool leaves the bridge disarmed; it never fails the passthrough turn.
+      const anthropic = withAnthropicHelperRefusal("web-search", () => findAnthropicSidecarProvider(config, parentProviderName));
       return anthropic ? { anthropic } : {};
     }
     case "xai": {

package/src/web-search/sidecar-providers.ts

@@ -5,7 +5,7 @@
  * evaluating when the bridge asks for these names).
  */
 import type { OcxConfig, OcxProviderConfig, OcxWebSearchSidecarConfig } from "../types";
-import { resolveSidecarAuth } from "../sidecar/auth";
+import { resolveSidecarAuth, resolveAnthropicHelperInstance } from "../sidecar/auth";
 import { getAccountSet } from "../oauth/store";
 import type { XaiSearchOptions } from "./xai-executor";
 
@@ -46,8 +46,9 @@ export interface AnthropicSidecarProvider {
  * Delegates to the shared sidecar auth module (#2188) so web-search and vision
  * cannot drift on what "Anthropic auth present" means.
  */
-export function findAnthropicSidecarProvider(config: OcxConfig): AnthropicSidecarProvider | undefined {
-  const auth = resolveSidecarAuth(config);
+export function findAnthropicSidecarProvider(config: OcxConfig, parentProviderName?: string): AnthropicSidecarProvider | undefined {
+  const instance = resolveAnthropicHelperInstance(config, { backendFamily: "anthropic", anthropicInstance: config.webSearchSidecar?.anthropicInstance, parentProviderName });
+  const auth = resolveSidecarAuth(config, instance);
   if (!auth.isAnthropicAuth || !auth.anthropicProviderName || !auth.anthropicProvider) return undefined;
   return { providerName: auth.anthropicProviderName, provider: auth.anthropicProvider, config };
 }