cartethyia 2.7.9 → 2.8.1

package/src/providers/operations/provider-rules/qoder.ts

@@ -0,0 +1,70 @@
+import type {
+  AccountErrorRule,
+  AccountErrorSignals,
+} from "../account-error-classification";
+import { unsupportedModelCooldownMs } from "../account-error-classification";
+
+/**
+ * Qoder's quota verdicts (`110` billing-daily-count, pricing-url refusals)
+ * are per-model: one model's spend cap does not drain another. A day matches
+ * the daily billing window the provider names.
+ */
+export const QODER_QUOTA_COOLDOWN_MS = 24 * 60 * 60 * 1000;
+
+function isQoder(signals: AccountErrorSignals): boolean {
+  return signals.providerId === "qoder" || signals.providerId === "qodercn";
+}
+
+/**
+ * Qoder's code-112 pricing refusal (`{"code":"112","message":"{\"pricingUrl\":...}"}`)
+ * is a "this model is not included in this account's plan, buy more" verdict
+ * for one pair — the account keeps serving its other models. The probe path
+ * does not always carry the code in its evidence (only the message does), so
+ * the match keys on the provider id plus the pricing-page wording as well.
+ * It must run before `quota-exhausted`, which would park the whole account.
+ */
+export const qoderPlanGatedRule: AccountErrorRule = {
+  name: "qoder-plan-gated",
+  match: (s) =>
+    isQoder(s) &&
+    (s.providerCode === "112" || s.lower.includes("pricingurl")),
+  decide: (s) => {
+    const cooldownMs = unsupportedModelCooldownMs(s.modelBlockHits);
+    return s.result(
+      "model_unreachable",
+      "cooldown",
+      cooldownMs,
+      new Date(Date.now() + cooldownMs),
+      s.reason("Model not included in this account's plan"),
+      s.origin === "upstream" && s.modelId !== undefined,
+      true,
+    );
+  },
+};
+
+/**
+ * Qoder's quota verdicts — `110` "Billing daily count exceeded" — are per-model:
+ * one model's spend cap does not drain another. Scoping them to the model keeps
+ * the account serving its other models. Must run before `quota-exhausted`, which
+ * parks the whole account.
+ */
+export const qoderModelQuotaRule: AccountErrorRule = {
+  name: "qoder-model-quota",
+  match: (s) => isQoder(s) && s.quotaSignal,
+  decide: (s) => {
+    const cooldownMs = s.statedCooldownMs ?? QODER_QUOTA_COOLDOWN_MS;
+    return s.result(
+      "model_unreachable",
+      "cooldown",
+      cooldownMs,
+      new Date(Date.now() + cooldownMs),
+      s.reason("Qoder quota exhausted for this model"),
+      s.origin === "upstream" && s.modelId !== undefined,
+    );
+  },
+};
+
+export const qoderRules: readonly AccountErrorRule[] = [
+  qoderPlanGatedRule,
+  qoderModelQuotaRule,
+];

package/src/providers/operations/provider-rules/trae.ts

@@ -0,0 +1,81 @@
+import type {
+  AccountErrorRule,
+  AccountErrorSignals,
+} from "../account-error-classification";
+
+/**
+ * Trae answers `4013 "AI service is not available in the current region now."`
+ * when the upstream does not serve the account's region. A day because the
+ * verdict is durable: it reproduces on every request until the region opens,
+ * and the account must not be re-dialled every thirty seconds for the whole
+ * window.
+ */
+export const TRAE_REGION_COOLDOWN_MS = 24 * 60 * 60 * 1000;
+
+/**
+ * Trae's free-tier quota (`4008` / "exceeded the quota") resets daily, so its
+ * exhaustion is a full-day model backoff — never the generic 1h fallback,
+ * which let the account re-enter rotation inside the window.
+ */
+export const TRAE_QUOTA_COOLDOWN_MS = 24 * 60 * 60 * 1000;
+
+function isTrae(signals: AccountErrorSignals): boolean {
+  return signals.providerId === "trae" || signals.providerId === "traecn";
+}
+
+export const traeRules: readonly AccountErrorRule[] = [
+  {
+    // Trae answers `4013 "AI service is not available in the current region
+    // now."` when the upstream does not serve the account's region. That is a
+    // durable verdict on the account, not a transient transport fault: it
+    // reproduces on every request until the region opens, so it must cool hard
+    // for a day rather than be re-dialled every thirty seconds. Must run
+    // before `transport-fault`, which would read the 502 as a short
+    // `server_error`.
+    name: "trae-region-unavailable",
+    match: (s) =>
+      isTrae(s) &&
+      (s.providerCode === "4013" || s.lower.includes("not available in the current region")),
+    decide: (s) => {
+      const cooldownMs = TRAE_REGION_COOLDOWN_MS;
+      return s.result(
+        "quota_exhausted",
+        "cooldown",
+        cooldownMs,
+        new Date(Date.now() + cooldownMs),
+        s.reason("Trae service unavailable in the current region"),
+        // Account-scoped provider evidence still has to reach the writer: a
+        // stream frame carries no credential detail, so `canMutate` is false
+        // and without this the account stays in rotation to reproduce the
+        // refusal for the whole window the region is closed for.
+        true,
+      );
+    },
+  },
+  {
+    // Trae's free-tier quota (`4008` / "exceeded the quota") resets daily.
+    // Treating it like the generic quota cooldown (1h account-wide fallback)
+    // let the account re-enter rotation inside the window and reproduce the
+    // refusal every few minutes — the "cooldown not holding" report. The
+    // verdict is a full-day backoff on *any* model (the account's quota is
+    // spent, so every model on it shares the wall). Scoped to the model so
+    // the account is not disabled wholesale; the 1-day window means a model
+    // stays parked for the day instead of flapping. Must run before
+    // `quota-exhausted`, which would apply the generic shorter fallback.
+    name: "trae-quota-exhausted",
+    match: (s) =>
+      isTrae(s) &&
+      (s.providerCode === "4008" || s.lower.includes("have exceeded the quota")),
+    decide: (s) => {
+      const cooldownMs = s.statedCooldownMs ?? TRAE_QUOTA_COOLDOWN_MS;
+      return s.result(
+        "model_unreachable",
+        "cooldown",
+        cooldownMs,
+        new Date(Date.now() + cooldownMs),
+        s.reason("Trae quota exhausted for this model"),
+        s.origin === "upstream" && s.modelId !== undefined,
+      );
+    },
+  },
+];

package/src/providers/operations/session-resolution.ts

@@ -13,13 +13,29 @@ const SESSION_HEADERS = [
   "session-id",
 ] as const;
 
+/** Ceiling for a session id, mirroring the OpenCode free tier's 256-char cap. */
+const MAX_INBOUND_SESSION_LENGTH = 256;
+
+/**
+ * Normalize an inbound session id the same way the OpenCode CLI does: trim,
+ * reject empty strings, and cap pathological lengths so a defective header can
+ * never become a cache key or a sticky-routing key hundreds of bytes long.
+ * Returns undefined when the value is unusable.
+ */
+export function normalizeInboundSessionId(value: string | undefined): string | undefined {
+  if (typeof value !== "string") return undefined;
+  const trimmed = value.trim();
+  if (trimmed.length === 0 || trimmed.length > MAX_INBOUND_SESSION_LENGTH) return undefined;
+  return trimmed;
+}
+
 export function resolveInboundSessionId(
   context?: ProviderDispatchContext,
   request?: CanonicalRequest,
 ): string | undefined {
   const headers = context?.request_headers;
   for (const name of SESSION_HEADERS) {
-    const value = headers?.[name]?.trim();
+    const value = normalizeInboundSessionId(headers?.[name]);
     if (value) return value;
   }
   const conversationId = request?.conversation?.conversation_id;

package/src/providers/provider-contracts.ts

@@ -5,10 +5,12 @@
 import type { CanonicalEvent, CanonicalRequest, WireFamily } from "../protocol/canonical-model";
 import { GatewayError } from "../protocol/gateway-error";
 import { BUNDLED_PROVIDER_METADATA, type BundledProviderId } from "./provider-metadata";
-import type { ValidatedOutboundHttp2Bidi } from "../network/http2-bidi";
+import type { ValidatedOutboundHttp2Bidi } from "../network/bidi";
 
 /** Closed union of every shipped provider ID. */
-export const BUNDLED_PROVIDER_IDS = BUNDLED_PROVIDER_METADATA.map((definition) => definition.id) as readonly BundledProviderId[];
+export const BUNDLED_PROVIDER_IDS: ReadonlySet<BundledProviderId> = new Set(
+  BUNDLED_PROVIDER_METADATA.map((definition) => definition.id),
+);
 
 /** Normalized builtin or validated custom provider identifier. */
 declare const customProviderIdBrand: unique symbol;
@@ -132,7 +134,7 @@ export type ValidatedOutboundWebSocket = (
 /**
  * The dialer contract handed to a provider adapter.
  *
- * Declared in `network/http2-bidi.ts` — the transport owns the contract — and
+ * Declared in `network/bidi.ts` — the transport owns the contract — and
  * re-exported here so provider code keeps one import site.
  */
 export type { ValidatedOutboundHttp2Bidi };
@@ -451,7 +453,7 @@ function normalizeProviderSlug(id: string): string {
 /** Returns true for one of Cartethyia's reserved builtin IDs, case-insensitively. */
 export function isBundledProviderId(value: string): value is BundledProviderId {
   const normalized = value.trim().toLowerCase();
-  return (BUNDLED_PROVIDER_IDS as readonly string[]).includes(normalized);
+  return BUNDLED_PROVIDER_IDS.has(normalized as BundledProviderId);
 }
 
 /** Normalizes a provider identifier before persistence or registry lookup. */

package/src/providers/{provider-credential-resolver.ts → provider-credentials.ts}

@@ -1,10 +1,47 @@
-// Control-plane credential selection: picks the first usable upstream
-// credential alternative in operator order.
+/**
+ * Provider credential envelope and resolution handling.
+ *
+ * Strips token envelopes so adapters never emit `Bearer Bearer`, and resolves
+ * ordered upstream credential alternatives for the control plane.
+ */
 
 import { GatewayError } from "../protocol/gateway-error";
-import { unwrapProviderToken } from "./provider-credential-envelope";
 import type { CredentialKind, ProviderId, ResolvedCredential } from "./provider-contracts";
 
+/** Envelope labels a stored credential may carry. */
+export type TokenEnvelope = "bearer" | "oauth" | "provider";
+
+const ENVELOPE_PREFIXES: Record<TokenEnvelope, string> = {
+  bearer: "Bearer ",
+  oauth: "OAuth ",
+  provider: "provider:",
+};
+
+/**
+ * Removes one explicitly identified envelope so adapters never emit
+ * `Bearer Bearer`. The bearer branch strips case-insensitively with
+ * surrounding-whitespace normalization; oauth/provider envelopes keep their
+ * exact byte slices. Input without the identified envelope passes through
+ * untouched.
+ */
+export function unwrapProviderToken(
+  value: string | Uint8Array,
+  envelope?: TokenEnvelope,
+): Uint8Array {
+  const bytes = typeof value === "string" ? new TextEncoder().encode(value) : value;
+  const text = new TextDecoder().decode(bytes);
+  if (envelope === "bearer") {
+    const trimmed = text.trim();
+    const match = /^bearer\s+(.+)$/is.exec(trimmed);
+    return new TextEncoder().encode((match?.[1] ?? trimmed).trim());
+  }
+  const prefix = envelope === undefined ? undefined : ENVELOPE_PREFIXES[envelope];
+  if (prefix !== undefined && text.toLowerCase().startsWith(prefix.toLowerCase())) {
+    return new TextEncoder().encode(text.slice(prefix.length));
+  }
+  return new Uint8Array(bytes);
+}
+
 /** One control-plane credential alternative, ordered by operator preference. */
 export interface CredentialAlternative {
   readonly provider_id: ProviderId;

package/src/providers/provider-metadata.ts

@@ -172,6 +172,14 @@ const RAW_BUNDLED_PROVIDER_METADATA = [
   { id: "opencode-go", displayName: "OpenCode Go", baseUrl: "https://opencode.ai", credentialUrl: "https://opencode.ai/auth" },
   { id: "cerebras", displayName: "Cerebras", baseUrl: "https://api.cerebras.ai/v1", credentialUrl: "https://cloud.cerebras.ai/platform" },
   { id: "openrouter", displayName: "OpenRouter", baseUrl: "https://openrouter.ai/api/v1", credentialUrl: "https://openrouter.ai/settings/keys" },
+  {
+    id: "vercel",
+    displayName: "Vercel AI Gateway",
+    baseUrl: "https://ai-gateway.vercel.sh/v1",
+    defaultSkipProxy: true,
+    credentialUrl: "https://vercel.com/dashboard/ai",
+    credentialHint: "Create an AI Gateway API key (`vercel ai-gateway api-keys create`) or paste an existing `vck_` key. The key is bearer-authenticated against the OpenAI-compatible /v1 surface.",
+  },
   { id: "mistral", displayName: "Mistral AI", baseUrl: "https://api.mistral.ai/v1", credentialUrl: "https://console.mistral.ai/api-keys" },
   { id: "fireworks", displayName: "Fireworks AI", baseUrl: "https://api.fireworks.ai/inference/v1", credentialUrl: "https://fireworks.ai/account/api-keys" },
   { id: "nvidia", displayName: "NVIDIA NIM", baseUrl: "https://integrate.api.nvidia.com/v1", credentialUrl: "https://build.nvidia.com/settings/api-keys" },
@@ -180,6 +188,22 @@ const RAW_BUNDLED_PROVIDER_METADATA = [
   // and the registry pins the Messages endpoint separately.
   { id: "deepseek", displayName: "DeepSeek", baseUrl: "https://api.deepseek.com", wireFamilyDefault: "messages", credentialUrl: "https://platform.deepseek.com/api_keys" },
   { id: "gmi", displayName: "GMI Cloud", baseUrl: "https://api.gmi-serving.com/v1", credentialUrl: "https://console.gmicloud.ai" },
+  {
+    id: "clixad",
+    displayName: "Clixad",
+    baseUrl: "https://clixad.onrender.com/v1",
+    requiresAccount: true,
+    credentialUrl: "https://clixad.io",
+    credentialHint: "Sign in with GitHub (device flow) or paste a Clixad token (adg_...). Model calls draw from the account balance and a daily free tier (120k credits/day).",
+  },
+  {
+    id: "deepai",
+    displayName: "DeepAI",
+    baseUrl: "https://api.deepai.org",
+    requiresAccount: true,
+    credentialUrl: "https://deepai.org",
+    credentialHint: "Sign in via the DeepAI desktop flow (loopback exchange → api_key) or paste a DeepAI api_key. Model calls are authenticated with the Api-Key header; the daily free allowance is 50 Theos and 11 models draw nothing from it.",
+  },
 
   // OpenAI-compatible bearer aggregators. Each is a bare host already rooted at
   // its own version prefix, so the `/v1`-prefixed wire paths stay pinned by the
@@ -198,6 +222,12 @@ const RAW_BUNDLED_PROVIDER_METADATA = [
   { id: "synthetic", displayName: "Synthetic", baseUrl: "https://api.synthetic.new/v1", credentialUrl: "https://app.synthetic.new/api-keys" },
   { id: "stepfun", displayName: "StepFun", baseUrl: "https://api.stepfun.com/v1", credentialUrl: "https://platform.stepfun.com/console/keys" },
   { id: "sakana", displayName: "Sakana AI", baseUrl: "https://api.sakana.ai/v1", credentialUrl: "https://console.sakana.ai/api-keys" },
+  // SenseNova keys are per-site: China keys (token.sensenova.cn) and
+  // international keys (token.sensenova.ai) reject each other with 401
+  // "Forbidden", so the two deployments are separate providers with separate
+  // hosts and catalogs — the same split as CodeBuddy cb/cbcn.
+  { id: "sensenova", displayName: "SenseNova", baseUrl: "https://token.sensenova.cn/v1", serviceKinds: ["llm", "imageGeneration"], credentialUrl: "https://token.sensenova.cn", credentialHint: "Paste a SenseNova API key created on platform.sensenova.cn. International accounts use SenseNova (Intl)." },
+  { id: "sensenova-intl", displayName: "SenseNova (Intl)", baseUrl: "https://token.sensenova.ai/v1", serviceKinds: ["llm", "imageGeneration"], credentialUrl: "https://platform.sensenova.ai", credentialHint: "Paste a SenseNova API key created on platform.sensenova.ai. China accounts use SenseNova." },
   { id: "helmcode", displayName: "HelmCode", baseUrl: "https://api.helmcode.com/v1", credentialUrl: "https://helmcode.com/dashboard" },
   { id: "coralbricks", displayName: "CoralBricks", baseUrl: "https://api.coralbricks.com/v1", credentialUrl: "https://coralbricks.com/api-keys" },
   { id: "aiand", displayName: "ai&", baseUrl: "https://api.aiand.com/v1", credentialUrl: "https://console.aiand.com/api-keys" },
@@ -490,6 +520,31 @@ const RAW_BUNDLED_PROVIDER_METADATA = [
   // rows are served by `/v1/search`, never by the canonical chat pipeline.
   { id: "exa", displayName: "Exa", baseUrl: "https://mcp.exa.ai", serviceKinds: ["websearch"], requiresAccount: false, credentialHint: "No API key. Search goes through the public MCP." },
   { id: "parallel", displayName: "Parallel", baseUrl: "https://search.parallel.ai", serviceKinds: ["websearch"], requiresAccount: false, credentialUrl: "https://platform.parallel.ai/settings?tab=api-keys", credentialHint: "Optional. Leave empty for the public MCP, or paste an API key for the higher-limit search API." },
+  {
+    // Freebuff (Codebuff Desktop). OAuth code flow → bearer token; every
+    // dispatch carries the desktop identity group + Ed25519 device signature
+    // (see documentation/research/freebuff/). The chat surface is
+    // OpenAI-compatible on `/api/v1/chat/completions` but requires a stateful
+    // session admission + agent-runs preflight — handled by the custom adapter.
+    id: "freebuff",
+    displayName: "Freebuff",
+    baseUrl: "https://www.codebuff.com",
+    hasAdapterUserAgent: true,
+    credentialUrl: "https://www.codebuff.com/login",
+    credentialHint: "Sign in with your Freebuff account (Desktop/CLI code flow).",
+  },
+  {
+    // Zro (moonmath). Fast, private, multi-region inference for open models.
+    // Claude Code connects via the Messages wire with a plain bearer key; the
+    // provider's own Claude Code docs configure `ANTHROPIC_BASE_URL` +
+    // `ANTHROPIC_AUTH_TOKEN`. No quota endpoint exists — entitlement is the
+    // `/v1/models` list itself (a key only sees the models it may call).
+    id: "zro",
+    displayName: "Zro",
+    baseUrl: "https://zro.moonmath.ai",
+    credentialUrl: "https://zro.moonmath.ai/docs/key-controls",
+    credentialHint: "Create or copy an API key (sk-...) from the Zro key controls page (docs/key-controls).",
+  },
 ] as const;
 
 /**
@@ -617,6 +672,11 @@ const ADAPTER_USER_AGENT_PROVIDER_IDS: ReadonlySet<string> = new Set(
   BUNDLED_PROVIDER_METADATA.filter((provider) => provider.hasAdapterUserAgent).map((provider) => provider.id),
 );
 
+/** Bundled metadata keyed by provider id for O(1) lookups. */
+const BUNDLED_PROVIDER_BY_ID: ReadonlyMap<BundledProviderId, BundledProviderMetadata> = new Map(
+  BUNDLED_PROVIDER_METADATA.map((definition) => [definition.id, definition]),
+);
+
 /** Whether the bundled adapter provides its own upstream User-Agent. */
 export function providerHasAdapterUserAgent(providerId: string): boolean {
   return ADAPTER_USER_AGENT_PROVIDER_IDS.has(providerId);
@@ -628,7 +688,7 @@ export function providerHasAdapterUserAgent(providerId: string): boolean {
  * minted inside a device/browser flow with no dedicated key page).
  */
 export function providerCredentialUrl(providerId: string): string | undefined {
-  return BUNDLED_PROVIDER_METADATA.find((candidate) => candidate.id === providerId)?.credentialUrl;
+  return BUNDLED_PROVIDER_BY_ID.get(providerId as BundledProviderId)?.credentialUrl;
 }
 
 /**
@@ -636,18 +696,18 @@ export function providerCredentialUrl(providerId: string): string | undefined {
  * `undefined` where the link alone is self-explanatory.
  */
 export function providerCredentialHint(providerId: string): string | undefined {
-  return BUNDLED_PROVIDER_METADATA.find((candidate) => candidate.id === providerId)?.credentialHint;
+  return BUNDLED_PROVIDER_BY_ID.get(providerId as BundledProviderId)?.credentialHint;
 }
 
 /** Presentation-only limitation for the provider detail page. */
 export function providerOperatorNotice(providerId: string): string | undefined {
-  return BUNDLED_PROVIDER_METADATA.find((candidate) => candidate.id === providerId)?.operatorNotice;
+  return BUNDLED_PROVIDER_BY_ID.get(providerId as BundledProviderId)?.operatorNotice;
 }
 
 /** Canonical builtin display name; falls back to the provider id for unknowns. */
 export function providerDisplayName(providerId: string): string {
   return (
-    BUNDLED_PROVIDER_METADATA.find((candidate) => candidate.id === providerId)?.displayName ??
+    BUNDLED_PROVIDER_BY_ID.get(providerId as BundledProviderId)?.displayName ??
     providerId
   );
 }
@@ -679,7 +739,7 @@ export function providerDisplayName(providerId: string): string {
  * gateway guessing it will not.
  */
 export function providerServiceKinds(providerId: string): readonly ServiceKind[] {
-  const declared = BUNDLED_PROVIDER_METADATA.find((candidate) => candidate.id === providerId)
+  const declared = BUNDLED_PROVIDER_BY_ID.get(providerId as BundledProviderId)
     ?.serviceKinds;
   // Bundled providers are explicit: they say which surfaces they serve, and a
   // bundled provider without the declaration serves LLM only.
@@ -708,7 +768,7 @@ export function customProviderServiceKinds(
 
 /** Canonical builtin base URL used by adapters, discovery, and quota clients. */
 export function providerBaseUrl(providerId: string): string {
-  const entry = BUNDLED_PROVIDER_METADATA.find((candidate) => candidate.id === providerId);
+  const entry = BUNDLED_PROVIDER_BY_ID.get(providerId as BundledProviderId);
   if (!entry) throw new Error(`Unknown builtin provider "${providerId}"`);
   return entry.baseUrl.replace(/\/+$/, "");
 }
@@ -744,7 +804,7 @@ export const PROVIDER_COMPATIBILITY_PROFILES: Record<string, CompatibilityProfil
 
 /** Default wire family for a builtin provider. */
 export function providerDefaultWireFamily(providerId: string): WireFamily {
-  return BUNDLED_PROVIDER_METADATA.find((candidate) => candidate.id === providerId)?.wireFamilyDefault ?? "chat";
+  return BUNDLED_PROVIDER_BY_ID.get(providerId as BundledProviderId)?.wireFamilyDefault ?? "chat";
 }
 
 /**
@@ -754,12 +814,12 @@ export function providerDefaultWireFamily(providerId: string): WireFamily {
  * OpenAI-compatible adapter.
  */
 export function providerUsesBespokeWire(providerId: string): boolean {
-  return BUNDLED_PROVIDER_METADATA.find((candidate) => candidate.id === providerId)?.bespokeWire ?? false;
+  return BUNDLED_PROVIDER_BY_ID.get(providerId as BundledProviderId)?.bespokeWire ?? false;
 }
 
 /** Whether a builtin provider requires a persisted account row. */
 export function providerRequiresAccount(providerId: string): boolean {
-  return BUNDLED_PROVIDER_METADATA.find((candidate) => candidate.id === providerId)?.requiresAccount ?? true;
+  return BUNDLED_PROVIDER_BY_ID.get(providerId as BundledProviderId)?.requiresAccount ?? true;
 }
 
 /**
@@ -769,7 +829,7 @@ export function providerRequiresAccount(providerId: string): boolean {
  */
 export function providerJwtVerification(providerId: string): ProviderJwtVerification {
   return (
-    BUNDLED_PROVIDER_METADATA.find((candidate) => candidate.id === providerId)?.jwtVerification ?? {}
+    BUNDLED_PROVIDER_BY_ID.get(providerId as BundledProviderId)?.jwtVerification ?? {}
   );
 }
 

package/src/providers/provider-probe.ts

@@ -16,7 +16,21 @@ import { resolveDialect } from "../protocol/translation/dialect/resolver";
 import type { CanonicalRequest } from "../protocol/canonical-model";
 import type { ProviderDispatchContext } from "./provider-contracts";
 import { providerBaseUrl, providerRateLimitIsIpScoped } from "./provider-metadata";
-import type { ProviderDispatchTarget, ProviderId } from "./provider-contracts";
+import type { ProviderDispatchTarget, ProviderId, ValidatedOutboundFetch } from "./provider-contracts";
+
+/**
+ * Probe fetch wrapper: merges `Request`-carried headers with per-call init
+ * headers before delegating to the validated fetch. Required wherever the
+ * fetch is handed to adapters as `outbound_fetch`, because adapters may call
+ * it with a `Request` whose headers would otherwise be dropped.
+ */
+export function createProbeFetch(fetcher: ValidatedOutboundFetch): ValidatedOutboundFetch {
+  return (input, init) => {
+    const headers = new Headers(input instanceof Request ? input.headers : undefined);
+    new Headers(init?.headers).forEach((value, name) => headers.set(name, value));
+    return fetcher(input, { ...init, headers });
+  };
+}
 
 
 /**

package/src/providers/provider-registry.ts

@@ -58,6 +58,36 @@ export interface ProviderAuthentication {
   readonly refresher?: OAuthTokenRefresher;
 }
 
+/** Provider implementation fields composed with canonical metadata. */
+export type ProviderModuleCapabilities = Partial<Omit<ProviderModule, "loadAdapter">> &
+  Pick<ProviderModule, "loadAdapter">;
+
+/**
+ * Creates a lazy authentication loader from a dynamic import and client export.
+ * Most OAuth clients also refresh their own tokens.
+ */
+export function oauthCapability<M, K extends keyof M>(
+  loader: () => Promise<M>,
+  exportName: K,
+  options: { readonly withRefresher?: boolean } = {},
+): () => Promise<ProviderAuthentication> {
+  return async () => {
+    const module = await loader();
+    const client = (module as Record<string, unknown>)[exportName as string] as OAuthLoginClient & { refresh: unknown };
+    return options.withRefresher
+      ? ({ client, refresher: client } as ProviderAuthentication)
+      : ({ client } as ProviderAuthentication);
+  };
+}
+
+/** Creates a lazy quota collector loader from a dynamic import and export name. */
+export function quotaCapability<M, K extends keyof M>(
+  loader: () => Promise<M>,
+  exportName: K,
+): () => Promise<QuotaFetcher> {
+  return () => loader().then((module) => (module as Record<string, unknown>)[exportName as string] as QuotaFetcher);
+}
+
 /**
  * Derives a registry registration from a fully populated provider module.
  * Keeps the registration shape in one place so the default registry and any
@@ -95,12 +125,6 @@ function assertAdapterIdentity(expected: ProviderId, adapter: ProviderAdapter):
   });
 }
 
-/** Result of loading the configured provider registrations. */
-export interface ProviderRegistrySnapshot {
-  readonly revision: number;
-  readonly adapters: ReadonlyMap<ProviderId, ProviderAdapter>;
-}
-
 /**
  * Single provider-registration authority. Every registration loads on
  * demand through its own loader; registrations that are not added are
@@ -116,7 +140,6 @@ export class ProviderRegistry {
   #quotaLoading = new Map<ProviderId, Promise<QuotaFetcher>>();
   #modelDiscovery = new Map<ProviderId, ProviderModelDiscovery>();
   #modelDiscoveryLoading = new Map<ProviderId, Promise<ProviderModelDiscovery>>();
-  #revision = 0;
 
   /** Adds one registration and rejects duplicate canonical IDs. */
   register(registration: ProviderRegistration): void {
@@ -132,7 +155,6 @@ export class ProviderRegistry {
       });
     }
     this.#registrations.set(providerId, registration);
-    this.#revision += 1;
   }
   /** Removes one registration and any cached adapter/auth/quota/discovery state. */
   unregister(providerId: string): boolean {
@@ -142,7 +164,6 @@ export class ProviderRegistry {
     this.#authentication.delete(normalized);
     this.#quotaCollectors.delete(normalized);
     this.#modelDiscovery.delete(normalized);
-    if (removed) this.#revision += 1;
     return removed;
   }
 
@@ -170,28 +191,25 @@ export class ProviderRegistry {
     this.#authentication.delete(providerId);
     this.#quotaCollectors.delete(providerId);
     this.#modelDiscovery.delete(providerId);
-    this.#revision += 1;
     return replaced;
   }
 
-  /** Loads one registered provider, or `undefined` when it is not registered. */
-  async loadOne(providerId: string): Promise<ProviderAdapter | undefined> {
-    const normalized = parseProviderId(providerId);
-    const registration = this.#registrations.get(normalized);
-    if (registration === undefined) return undefined;
-    return this.#loadRegistration(normalized, registration);
-  }
-
   /**
    * Resolves one adapter on demand, returning the cached instance when it has
-   * already loaded. This never evaluates a provider's module graph until that
-   * provider is actually dispatched to, so heavy bespoke adapters
-   * (protobuf-based providers) stay out of the startup path.
+   * already loaded — unless `force` is set, which rebuilds the adapter from
+   * the registration (single-flight, and the fresh instance replaces the
+   * cache). This never evaluates a provider's module graph until that provider
+   * is actually dispatched to, so heavy bespoke adapters (protobuf-based
+   * providers) stay out of the startup path. `force` is used by the probe
+   * path, which wants the adapter rebuilt against the latest registration
+   * rather than a cached instance.
    */
-  async resolve(providerId: string): Promise<ProviderAdapter | undefined> {
+  async resolve(providerId: string, opts: { readonly force?: boolean } = {}): Promise<ProviderAdapter | undefined> {
     const normalized = parseProviderId(providerId);
-    const cached = this.#loaded.get(normalized);
-    if (cached !== undefined) return cached;
+    if (!opts.force) {
+      const cached = this.#loaded.get(normalized);
+      if (cached !== undefined) return cached;
+    }
     const registration = this.#registrations.get(normalized);
     if (registration === undefined) return undefined;
     return this.#loadRegistration(normalized, registration);
@@ -306,7 +324,6 @@ export class ProviderRegistry {
       metrics.proxy_provider_adapter_load_ms.observe(durationMs);
       trackAdapterLoad(providerId, durationMs);
       this.#loaded.set(providerId, adapter);
-      this.#revision += 1;
       return adapter;
     })().finally(() => {
       this.#loading.delete(providerId);
@@ -315,14 +332,6 @@ export class ProviderRegistry {
     return task;
   }
 
-  /** Returns the immutable registry snapshot; disabled optional providers are absent. */
-  snapshot(): ProviderRegistrySnapshot {
-    return {
-      revision: this.#revision,
-      adapters: new Map(this.#loaded),
-    };
-  }
-
   /** Returns registration metadata without loading optional code. */
   registrations(): readonly ProviderRegistration[] {
     return [...this.#registrations.values()];

package/src/providers/quota/quota-contracts.ts

@@ -29,6 +29,8 @@ export interface ProviderQuotaResult {
   readonly plan: string | null;
   readonly windows: readonly ProviderQuotaWindow[];
   readonly error: string | null;
+  /** The provider explicitly rejected the account credential; do not retry it automatically. */
+  readonly authInvalidated?: boolean;
   /** Display identity the billing surface reported, when it reported one. */
   readonly accountLabel?: string;
 }

package/src/providers/quota/quota-limit-windows.ts

@@ -10,6 +10,7 @@
  */
 import type { ProviderQuotaWindow } from "./quota-contracts";
 import { isoDate, number, percentWindow, record, text } from "./quota-contracts";
+import { resolveWindowEmission } from "./quota-window-parser";
 
 /** Where one provider's limit entries and their fields live. */
 export interface LimitWindowShape {
@@ -77,14 +78,24 @@ export function parseLimitWindows(
     const kind = text(readFirst(limit, shape.kindPaths)) ?? `window-${index + 1}`;
     const percent = number(readFirst(limit, shape.percentPaths));
     const reset = isoDate(readFirst(limit, shape.resetPaths));
-    if (percent === null && reset === null) continue;
+    const rawUsed = shape.usedPaths ? number(readFirst(limit, shape.usedPaths)) : null;
     const limitValue = shape.limitPaths
       ? number(readFirst(limit, shape.limitPaths))
       : null;
-    const usedValue =
-      (shape.usedPaths ? number(readFirst(limit, shape.usedPaths)) : null) ??
-      shape.deriveUsed?.(limit, percent, limitValue) ??
-      null;
+    const { emit } = resolveWindowEmission({
+      explicitPercent: null,
+      usedPercent: percent,
+      remainingPercent: null,
+      used: rawUsed,
+      limit: limitValue,
+      reset,
+      deriveFromUsedLimit: false,
+      // The array walker has always emitted a reset-only window (percent null,
+      // reset present); only an entry with neither is dropped.
+      emitWithoutPercent: true,
+    });
+    if (!emit) continue;
+    const usedValue = rawUsed ?? shape.deriveUsed?.(limit, percent, limitValue) ?? null;
     const label =
       shape.labelFor?.(kind, limit) ?? shape.fallbackLabel?.(kind) ?? humanize(kind);
     windows.push(percentWindow(kind, label, percent, reset, usedValue, limitValue, "independent"));