cartethyia 2.7.8 → 2.8.0

package/src/providers/provider-metadata.ts

@@ -32,6 +32,14 @@ export interface CompatibilityProfile {
    * bundled specs declare it on `ApiKeyProviderSpec.gatewayUserAgent`.
    */
   readonly gateway_user_agent?: boolean;
+  /**
+   * Which service surfaces this custom provider may serve. Absent means every
+   * kind is enabled (the historical default). The operator narrows this by
+   * checking only the capabilities their upstream actually answers — agentic
+   * (LLM) is always on when the list is present, and a kind the upstream
+   * cannot serve stays out of the provider's tab set.
+   */
+  readonly service_kinds?: readonly ServiceKind[];
 }
 
 /** Identity and routing defaults for every builtin provider. */
@@ -144,6 +152,20 @@ const RAW_BUNDLED_PROVIDER_METADATA = [
     credentialUrl: "https://cursor.com",
     credentialHint: "Sign in with Cursor or import a Cursor API key.",
   },
+  {
+    id: "devin",
+    displayName: "Devin",
+    baseUrl: "https://server.codeium.com",
+    wireFamilyDefault: "chat",
+    requiresAccount: true,
+    bespokeWire: true,
+    hasAdapterUserAgent: true,
+    // Devin's upstream is a Connect-RPC protobuf service with its own framing;
+    // an egress proxy in front of it breaks the stream shape. Direct only.
+    defaultSkipProxy: true,
+    credentialUrl: "https://devin.ai",
+    credentialHint: "Sign in with Devin, Windsurf Enterprise, or import a Devin session token / Windsurf seat key.",
+  },
   { id: "kimi", displayName: "Kimi Code", baseUrl: "https://api.kimi.com/coding", credentialUrl: "https://platform.moonshot.ai/console/api-keys" },
   { id: "opencode", displayName: "OpenCode Free", baseUrl: "https://opencode.ai", requiresAccount: false, ipScopedRateLimit: true, hasAdapterUserAgent: true },
   { id: "opencode-zen", displayName: "OpenCode Zen", baseUrl: "https://opencode.ai", hasAdapterUserAgent: true, credentialUrl: "https://opencode.ai/auth" },
@@ -344,6 +366,7 @@ const RAW_BUNDLED_PROVIDER_METADATA = [
     // User-Agent. Letting the operator overwrite it would let them break the
     // provider, so the console locks the control.
     hasAdapterUserAgent: true,
+    credentialHint: "Paste a Nous Portal API key (portal.nousresearch.com → API keys), or sign in with the Nous Portal device code (OAuth) for the subscription route.",
   },
   { id: "bai", displayName: "B.AI", baseUrl: "https://api.b.ai/v1", credentialUrl: "https://b.ai" },
   {
@@ -367,8 +390,6 @@ const RAW_BUNDLED_PROVIDER_METADATA = [
   { id: "cline", displayName: "Cline", baseUrl: "https://api.cline.bot/api/v1", hasAdapterUserAgent: true, defaultSkipProxy: true, credentialUrl: "https://app.cline.bot" },
   { id: "cb", displayName: "CodeBuddy", baseUrl: "https://www.codebuddy.ai/v2", hasAdapterUserAgent: true, serviceKinds: ["llm", "imageGeneration", "videoGeneration"], credentialUrl: "https://www.codebuddy.ai", credentialHint: "Sign in with the same CodeBuddy account you use in the desktop app." },
   { id: "cbcn", displayName: "CodeBuddy CN", baseUrl: "https://copilot.tencent.com/v2", hasAdapterUserAgent: true, credentialUrl: "https://copilot.tencent.com", credentialHint: "Sign in with the same CodeBuddy China account you use in the desktop app." },
-  { id: "workbuddy", displayName: "WorkBuddy", baseUrl: "https://www.workbuddy.ai", hasAdapterUserAgent: true, serviceKinds: ["llm", "imageGeneration", "videoGeneration"], credentialUrl: "https://www.workbuddy.ai", credentialHint: "Sign in with the same WorkBuddy account you use in the desktop app." },
-  { id: "workbuddycn", displayName: "WorkBuddy CN", baseUrl: "https://www.workbuddy.cn", hasAdapterUserAgent: true, serviceKinds: ["llm", "imageGeneration", "videoGeneration"], credentialUrl: "https://www.workbuddy.cn", credentialHint: "Sign in with the same WorkBuddy China account you use in the desktop app." },
   {
     // Kilo Code resells the OpenRouter catalog. The base URL carries the API's
     // path prefix (`/api/openrouter`) and every model row carries only the wire
@@ -432,6 +453,22 @@ const RAW_BUNDLED_PROVIDER_METADATA = [
     credentialUrl: "https://www.trae.com.cn/",
     credentialHint: "Paste a Trae CN account export (accessToken + refreshToken) or the raw access token from a Trae China account.",
   },
+  {
+    id: "freepi",
+    displayName: "Free-pi",
+    baseUrl: "https://api.freepi.ai/v1/chat/completions",
+    defaultSkipProxy: true,
+    credentialUrl: "https://freepi.ai",
+    credentialHint: "Sign in with a GitHub device code (free-pi login), or paste a free-pi JWT issued by the backend.",
+  },
+  {
+    id: "perch",
+    displayName: "Perch",
+    baseUrl: "https://app.perchai.app",
+    defaultSkipProxy: true,
+    credentialUrl: "https://chat.perchai.app",
+    credentialHint: "Sign in with Google or GitHub (Perch account). Starter includes Roost Standard and Standard 1M.",
+  },
   { id: "ollamacloud", displayName: "Ollama Cloud", baseUrl: "https://ollama.com/v1", credentialUrl: "https://ollama.com/settings/keys" },
   { id: "gemini", displayName: "Google Gemini", baseUrl: "https://generativelanguage.googleapis.com/v1beta", serviceKinds: ["llm", "websearch", "imageGeneration"], credentialUrl: "https://aistudio.google.com/app/apikey" },
   { id: "xiaomipg", displayName: "Xiaomi MiMo (PAYG)", baseUrl: "https://api.xiaomimimo.com/v1", credentialUrl: "https://platform.xiaomimimo.com" },
@@ -453,6 +490,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;
 
 /**
@@ -472,7 +534,7 @@ const RAW_BUNDLED_PROVIDER_METADATA = [
 export type BundledProviderId = (typeof RAW_BUNDLED_PROVIDER_METADATA)[number]["id"];
 
 /**
- * The Buddy family: CodeBuddy, its China tenant, and WorkBuddy.
+ * The Buddy family: CodeBuddy and its China tenant.
  *
  * They share one billing and credit system, so several layers need to ask "is
  * this a Buddy provider" — the health recorder, the request preparer, and the
@@ -480,7 +542,7 @@ export type BundledProviderId = (typeof RAW_BUNDLED_PROVIDER_METADATA)[number]["
  * get added in one place and silently missed in the others. Declared here
  * beside the identities it names; the layers keep their own *policies*.
  */
-export const BUDDY_PROVIDER_IDS: ReadonlySet<string> = new Set(["cb", "cbcn", "workbuddy", "workbuddycn"]);
+export const BUDDY_PROVIDER_IDS: ReadonlySet<string> = new Set(["cb", "cbcn"]);
 
 /**
  * Per-provider JWT verification defaults for issued OAuth access tokens. An
@@ -580,6 +642,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);
@@ -591,7 +658,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;
 }
 
 /**
@@ -599,18 +666,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
   );
 }
@@ -642,7 +709,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.
@@ -650,10 +717,28 @@ export function providerServiceKinds(providerId: string): readonly ServiceKind[]
   return SERVICE_KINDS;
 }
 
+/**
+ * Resolves the service kinds for a custom (BYOK) provider row.
+ *
+ * The operator may narrow the surface set via `compatibilityProfile.service_kinds`
+ * (the Advanced Capabilities checkboxes in the Add Custom Provider modal). Absent,
+ * every kind is allowed — the historical default. A present list never drops
+ * `llm` (agentic is the floor of a custom provider).
+ */
+export function customProviderServiceKinds(
+  compatibilityProfile: CompatibilityProfile | null | undefined,
+): readonly ServiceKind[] {
+  const kinds = compatibilityProfile?.service_kinds;
+  if (kinds === undefined || kinds.length === 0) return SERVICE_KINDS;
+  const set = new Set<ServiceKind>(SERVICE_KINDS.filter((kind) => kinds.includes(kind)));
+  set.add("llm");
+  return SERVICE_KINDS.filter((kind) => set.has(kind));
+}
+
 
 /** 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(/\/+$/, "");
 }
@@ -689,7 +774,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";
 }
 
 /**
@@ -699,12 +784,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;
 }
 
 /**
@@ -714,7 +799,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-model-definition.ts

@@ -33,6 +33,37 @@ export const FREE_TIER_COST: ModelCostDefinition = {
   pricing_model: "pay-per-use",
 };
 
+/**
+ * Severity of one display-only model warning. `warn` is the default so a
+ * catalog that omits severity does not silently render a critical banner.
+ */
+export type ModelWarningSeverity = "info" | "warn" | "critical";
+
+/** Severity values accepted on the wire, as a runtime tuple. */
+export const MODEL_WARNING_SEVERITIES = ["info", "warn", "critical"] as const;
+
+/** Longest accepted warning `kind` / `message`, in UTF-16 code units. */
+export const MODEL_WARNING_KIND_MAX_LENGTH = 64;
+export const MODEL_WARNING_MESSAGE_MAX_LENGTH = 500;
+
+/**
+ * One display-only warning attached to a model row. `kind` is an open string
+ * with three defined values (`fallback_model`, `cache_reliability`,
+ * `model_refusal`) so a new category needs no migration. Persisted as
+ * `{ warnings: ModelWarning[] }` in `models.warning_metadata`; never read by
+ * routing.
+ */
+export interface ModelWarning {
+  /** Stable machine-readable category; open vocabulary. */
+  readonly kind: string;
+  /** Operator-facing text. Provider-level claims use "may". */
+  readonly message: string;
+  /** Defaults to `warn` when absent. */
+  readonly severity?: ModelWarningSeverity;
+  /** ISO timestamp of the last edit, when known. */
+  readonly updatedAt?: string;
+}
+
 /** Canonical static metadata for one provider model. */
 export interface ModelDefinition {
   readonly modelId: string;
@@ -118,6 +149,8 @@ export interface ModelDefinition {
    * turns a gap in our catalog into a claim about someone else's model.
    */
   readonly limitsEstimated?: boolean;
+  /** Display-only warnings carried from a static catalog into the seeded row. */
+  readonly warnings?: readonly ModelWarning[];
 }
 
 /**
@@ -205,6 +238,8 @@ export interface ModelHelperRow {
   readonly proOnly?: boolean;
   /** Explicit wire dialect override for this row. See `ModelDefinition.dialect`. */
   readonly dialect?: DialectId;
+  /** Display-only warnings to carry onto the built row. */
+  readonly warnings?: readonly ModelWarning[];
 }
 
 function defaultEndpoint(wireFamily: ModelDefinition["wireFamily"]): string {
@@ -309,6 +344,7 @@ export function defineModel(row: ModelHelperRow): ModelDefinition {
     ...(row.proOnly === undefined ? {} : { proOnly: row.proOnly }),
     ...(row.dialect === undefined ? {} : { dialect: row.dialect }),
     ...(limitsEstimated ? { limitsEstimated: true } : {}),
+    ...(row.warnings === undefined ? {} : { warnings: row.warnings }),
   };
 }
 

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-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"));

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

@@ -3,7 +3,7 @@ import { cleanError, unsupportedQuota } from "./quota-contracts";
 import type { ProviderRegistry } from "../provider-registry";
 import { parseProviderId } from "../provider-contracts";
 import { providerBaseUrl } from "../provider-metadata";
-import { createProbeFetch } from "../operations/probe-fetch";
+import { createProbeFetch } from "../provider-probe";
 /**
  * Verifies an API key against the provider's OpenAI-compatible `/models`
  * endpoint. For providers that expose no billing/quota surface, a reachable

package/src/providers/quota/quota-window-parser.ts

@@ -98,6 +98,75 @@ function findReset(root: unknown, mapping: QuotaWindowMapping): string | null {
   return mapping.resetFallback ?? null;
 }
 
+/**
+ * The raw per-window candidates the shared emission core resolves.
+ *
+ * Both quota walkers (`parseQuotaWindows` and `parseLimitWindows`) feed their
+ * independently-read fields into one resolution so the percent fallback chain
+ * and the skip rule cannot drift between them.
+ */
+export interface WindowFieldCandidates {
+  /** Provider-preferred percent (e.g. a `derivePercent` result). */
+  readonly explicitPercent: number | null;
+  /** Raw used-percent read from the payload. */
+  readonly usedPercent: number | null;
+  /** Raw remaining-percent read from the payload. */
+  readonly remainingPercent: number | null;
+  /** Absolute used value. */
+  readonly used: number | null;
+  /** Absolute limit value. */
+  readonly limit: number | null;
+  /** Reset timestamp; required to emit a reset-only window. */
+  readonly reset: string | null;
+  /**
+   * Whether percent may be derived from absolute used/limit when no percentage
+   * was reported. Only `parseQuotaWindows` does this — `parseLimitWindows`
+   * reports percentages and resets the upstream gave it, never ones it
+   * invented, so Cline entries stay reset-only instead of gaining a derived
+   * percent.
+   */
+  readonly deriveFromUsedLimit: boolean;
+  /**
+   * When true, a reset-only window (percent null, reset present) is still
+   * emitted. When false/absent, an entry with neither percent nor reset is
+   * dropped — never rendered as 0% — and a reset-only window is dropped too.
+   */
+  readonly emitWithoutPercent?: boolean;
+}
+
+/**
+ * Shared per-window field resolution: the percent fallback chain plus the
+ * "emit or skip" decision.
+ *
+ * Percent resolution order is exact: explicit percent, then used-percent, then
+ * remaining-percent inverted (100 − remaining), then derived from absolute
+ * used/limit (only when the limit is positive and `deriveFromUsedLimit` is
+ * set). The result is never coerced to 0: a missing percentage stays `null`,
+ * so a window can be omitted or rendered as a countdown depending on
+ * `emitWithoutPercent`.
+ */
+export function resolveWindowEmission(candidates: WindowFieldCandidates): {
+  readonly emit: boolean;
+  readonly percent: number | null;
+} {
+  let percent = candidates.explicitPercent;
+  if (percent === null && candidates.usedPercent !== null) percent = candidates.usedPercent;
+  if (percent === null && candidates.remainingPercent !== null) {
+    percent = Math.max(0, 100 - candidates.remainingPercent);
+  }
+  if (
+    percent === null &&
+    candidates.deriveFromUsedLimit &&
+    candidates.used !== null &&
+    candidates.limit !== null &&
+    candidates.limit > 0
+  ) {
+    percent = (candidates.used / candidates.limit) * 100;
+  }
+  const emit = percent !== null || (candidates.emitWithoutPercent === true && candidates.reset !== null);
+  return { emit, percent };
+}
+
 /** Parses a generic quota payload using the provided window mappings. */
 export function parseQuotaWindows(
   body: unknown,
@@ -110,27 +179,30 @@ export function parseQuotaWindows(
   for (const mapping of windowMappings) {
     const used = findNumber(payload, mapping.usedPaths);
     const limit = findNumber(payload, mapping.limitPaths);
+    const reset = findReset(payload, mapping);
 
-    let percent: number | null = mapping.derivePercent ? mapping.derivePercent(payload) : null;
-    if (percent === null) {
-      const usedPercent = findNumber(payload, mapping.usedPercentPaths);
-      const remainingPercent = findNumber(payload, mapping.remainingPercentPaths);
-      if (usedPercent !== null) {
-        percent = usedPercent;
-      } else if (remainingPercent !== null) {
-        percent = Math.max(0, 100 - remainingPercent);
-      } else if (used !== null && limit !== null && limit > 0) {
-        percent = (used / limit) * 100;
-      }
-    }
-    if (percent !== null && mapping.valueMultiplier !== undefined && mapping.valueMultiplier !== 0) {
-      percent = Math.min(100, Math.max(0, percent * mapping.valueMultiplier));
-    }
+    const { emit, percent } = resolveWindowEmission({
+      explicitPercent: mapping.derivePercent ? mapping.derivePercent(payload) : null,
+      usedPercent: findNumber(payload, mapping.usedPercentPaths),
+      remainingPercent: findNumber(payload, mapping.remainingPercentPaths),
+      used,
+      limit,
+      reset,
+      deriveFromUsedLimit: true,
+      ...(mapping.emitWithoutPercent === undefined ? {} : { emitWithoutPercent: mapping.emitWithoutPercent }),
+    });
+    if (!emit) continue;
 
-    const reset = findReset(payload, mapping);
-    if (percent === null && !(mapping.emitWithoutPercent === true && reset !== null)) continue;
+    let resolvedPercent = percent;
+    if (
+      resolvedPercent !== null &&
+      mapping.valueMultiplier !== undefined &&
+      mapping.valueMultiplier !== 0
+    ) {
+      resolvedPercent = Math.min(100, Math.max(0, resolvedPercent * mapping.valueMultiplier));
+    }
 
-    windows.push(percentWindow(mapping.kind, mapping.label, percent, reset, used, limit, "independent"));
+    windows.push(percentWindow(mapping.kind, mapping.label, resolvedPercent, reset, used, limit, "independent"));
   }
 
   if (options.extraWindows) windows.push(...options.extraWindows(payload));