feat(providers): expose usage-supported in provider plugin manifest

changelog.d/features/12214-usage-supported-capability.md

@@ -0,0 +1 @@
+- **feat(providers):** the provider plugin manifest now also advertises a `usage-supported` capability for the 46 providers whose usage API is accepted by the server and Dashboard routes, so integrators can distinguish "the server will serve quota for this provider" from "a fetcher is wired" without reading TypeScript. Discovery only — no fetcher or quota change. `usage-fetch` resolves on id or alias (the usage dispatcher accepts both); `usage-supported` resolves on id alone, matching the runtime guard `USAGE_SUPPORTED_PROVIDERS.includes(providerId)`. `USAGE_SUPPORTED_PROVIDERS` moved to a zero-dependency leaf (`open-sse/services/usage/supportedProviders.ts`) and is re-exported from `providers.ts`, mirroring the `fetcherProviders` leaf from #11903 and keeping the manifest a light module. ([#12214](https://github.com/diegosouzapw/OmniRoute/pull/12214)) — thanks @maxmad64bis

docs/reference/PROVIDER_PLUGIN_MANIFEST.md

@@ -48,7 +48,7 @@ The manifest contains:
 - JSON-safe model metadata such as context length, vision/reasoning flags, and
   unsupported params
 - capability tags including `apikey`, `oauth`, `custom-executor`,
-  `passthrough-models`, `responses`, `sidecar-candidate`, and `usage-fetch`
+  `passthrough-models`, `responses`, `sidecar-candidate`, `usage-fetch`, and `usage-supported`
 
 The manifest intentionally excludes:
 
@@ -74,6 +74,7 @@ re-reading the TypeScript sources.
 | `custom-executor`    | Runs a non-default executor, so it stays on the TypeScript path.  |
 | `sidecar-candidate`  | Mirrors `sidecar.eligible` — safe to consider for sidecar import. |
 | `usage-fetch`        | Has a wired usage or quota fetcher (`getUsageForProvider`).       |
+| `usage-supported`    | The usage API accepts this provider (`isSupportedUsageConnection`). |
 
 `usage-fetch` is discovery only. It reports that OmniRoute knows how to read usage for the
 provider; it does not activate fetching, change quota semantics, or imply that the
@@ -86,6 +87,16 @@ with aliases and is slightly longer than the number of tagged providers: entries
 not chat providers in the manifest registry (for example the `firecrawl` search provider
 and the `amazon-q` ACP provider) have no manifest entry to tag.
 
+`usage-supported` answers whether the server and Dashboard usage routes accept a connection
+for the provider. It mirrors `isSupportedUsageConnection()` (`src/lib/usage/providerLimits.ts`)
+and `supportsProviderQuota()` (`src/shared/utils/providerQuotaVisibility.ts`), both gated by
+`USAGE_SUPPORTED_PROVIDERS` (`open-sse/services/usage/supportedProviders.ts`). Unlike
+`usage-fetch`, it is emitted on the provider id alone — the runtime guard does
+`USAGE_SUPPORTED_PROVIDERS.includes(providerId)` with no alias resolution, so the manifest
+keeps the same rule. The two tags have different perimeters: 4 providers carry only
+`usage-fetch` (`opencode`, `opencode-zen`, `openrouter`, `xai`) and 1 carries only
+`usage-supported` (`xiaomi-mimo-token-plan`), so one does not imply the other.
+
 ## Sidecar Use
 
 Sidecars should treat `sidecar.eligible` as a conservative candidate signal, not

open-sse/config/providerPluginManifest.ts

@@ -1,5 +1,6 @@
 import type { RegistryEntry, RegistryModel } from "./providers/shared.ts";
 import { USAGE_FETCHER_PROVIDERS } from "../services/usage/fetcherProviders.ts";
+import { USAGE_SUPPORTED_PROVIDERS } from "../services/usage/supportedProviders.ts";
 
 export type ProviderPluginCapability =
   | "apikey"
@@ -8,7 +9,8 @@ export type ProviderPluginCapability =
   | "passthrough-models"
   | "responses"
   | "sidecar-candidate"
-  | "usage-fetch";
+  | "usage-fetch"
+  | "usage-supported";
 
 export interface ProviderPluginModel {
   id: string;
@@ -66,6 +68,15 @@ const SIDECAR_COMPATIBLE_EXECUTORS = new Set(["default"]);
  */
 const USAGE_FETCHER_PROVIDER_SET = new Set<string>(USAGE_FETCHER_PROVIDERS);
 
+/**
+ * Providers whose usage API is accepted by dashboard/server routes (#10078).
+ * Unlike USAGE_FETCHER_PROVIDERS this gate is checked with a plain
+ * `USAGE_SUPPORTED_PROVIDERS.includes(providerId)` — no alias resolution —
+ * so the manifest must emit on the identifier alone to stay faithful to the
+ * runtime guard.
+ */
+const USAGE_SUPPORTED_PROVIDER_SET = new Set<string>(USAGE_SUPPORTED_PROVIDERS);
+
 function compactObject<T extends Record<string, unknown>>(value: T): Partial<T> {
   return Object.fromEntries(
     Object.entries(value).filter(([, entryValue]) => entryValue !== undefined)
@@ -142,6 +153,9 @@ function capabilitiesFor(entry: RegistryEntry, eligible: boolean): ProviderPlugi
   ) {
     capabilities.add("usage-fetch");
   }
+  if (USAGE_SUPPORTED_PROVIDER_SET.has(entry.id)) {
+    capabilities.add("usage-supported");
+  }
 
   return [...capabilities].sort();
 }

open-sse/services/usage/supportedProviders.ts

@@ -0,0 +1,79 @@
+/**
+ * usage/supportedProviders.ts — registration list of providers whose usage/quota
+ * API is accepted by the dashboard and server routes.
+ *
+ * Extracted from `src/shared/constants/providers.ts` so that light consumers —
+ * the provider-plugin manifest (`config/providerPluginManifest.ts`) above all —
+ * can read the list without pulling the ~12-module provider registry, and
+ * without an open-sse module reaching across the workspace boundary into
+ * `src/` (the open-sse typecheck gate forbids open-sse → src imports). Same
+ * pattern as `fetcherProviders.ts` (#11903): pure data — no imports, no module
+ * state — so it cannot introduce a cycle. `src/shared/constants/providers.ts`
+ * re-exports the value, so every existing `@/shared/constants/providers`
+ * import path keeps working unchanged.
+ *
+ * Typed `readonly string[]` (not `as const`): the dashboard/server gates call
+ * `USAGE_SUPPORTED_PROVIDERS.includes(providerId)` with a plain `string`, which
+ * a literal-tuple type would reject (TS2345).
+ */
+
+// Providers that support usage/quota API
+export const USAGE_SUPPORTED_PROVIDERS: readonly string[] = [
+  "antigravity",
+  "agy",
+  "kiro",
+  "amazon-q",
+  "github",
+  "codex",
+  "claude",
+  "cursor",
+  "qoder",
+  "kimi-coding",
+  "kimi-coding-apikey",
+  "glm",
+  "glm-cn",
+  "zai",
+  "glmt",
+  "opencode-go",
+  "ollama-cloud",
+  "minimax",
+  "minimax-cn",
+  "crof",
+  "nanogpt",
+  "deepseek",
+  "xiaomi-mimo",
+  "xiaomi-mimo-token-plan",
+  "vertex",
+  "vertex-partner",
+  "codebuddy-cn",
+  // PromptQL playground credits (getCreditSummary → USD micros)
+  "promptql",
+  "pql",
+  // Adobe Firefly web (cookie/JWT as apikey) — GET firefly.adobe.io/v1/credits/balance
+  "adobe-firefly",
+  "firefly",
+  "hyperagent",
+  "ha",
+  // xAI OAuth (Grok) weekly quota (id + public alias, same pattern as ha/agy)
+  "xai-oauth",
+  "xao",
+  // Grok Build subscription, billing credits, and auto top-up status
+  "grok-cli",
+  // Firecrawl team credits (GET /v2/team/credit-usage)
+  "firecrawl",
+  // Volcano Ark Plan subscriptions (agent-plan / coding-plan)
+  "volcengine-agent-plan",
+  "volcengine-coding-plan",
+  // Command Code credits + 5h/weekly rolling windows
+  "command-code",
+  "conol-web",
+  "cnl",
+  // Alibaba Coding Plan triple-window quota (#9603 UI gap — fetcher existed, list entry missing)
+  "bailian-coding-plan",
+  // Qwen Cloud / Model Studio personal Token Plan (cookie-authenticated console gateway)
+  "qwen-cloud-token-plan",
+  // AgentRouter (New-API) console balance quota (consoleApiKey + newApiUserId)
+  "agentrouter",
+  // Kilo Code personal USD balance (GET /api/profile/balance, existing OAuth token)
+  "kilocode",
+];

src/shared/constants/providers.ts

@@ -482,66 +482,7 @@ export const ID_TO_ALIAS = new Proxy({} as Record<string, string>, {
   },
 });
 
-// Providers that support usage/quota API
-export const USAGE_SUPPORTED_PROVIDERS = [
-  "antigravity",
-  "agy",
-  "kiro",
-  "amazon-q",
-  "github",
-  "codex",
-  "claude",
-  "cursor",
-  "qoder",
-  "kimi-coding",
-  "kimi-coding-apikey",
-  "glm",
-  "glm-cn",
-  "zai",
-  "glmt",
-  "opencode-go",
-  "ollama-cloud",
-  "minimax",
-  "minimax-cn",
-  "crof",
-  "nanogpt",
-  "deepseek",
-  "xiaomi-mimo",
-  "xiaomi-mimo-token-plan",
-  "vertex",
-  "vertex-partner",
-  "codebuddy-cn",
-  // PromptQL playground credits (getCreditSummary → USD micros)
-  "promptql",
-  "pql",
-  // Adobe Firefly web (cookie/JWT as apikey) — GET firefly.adobe.io/v1/credits/balance
-  "adobe-firefly",
-  "firefly",
-  "hyperagent",
-  "ha",
-  // xAI OAuth (Grok) weekly quota (id + public alias, same pattern as ha/agy)
-  "xai-oauth",
-  "xao",
-  // Grok Build subscription, billing credits, and auto top-up status
-  "grok-cli",
-  // Firecrawl team credits (GET /v2/team/credit-usage)
-  "firecrawl",
-  // Volcano Ark Plan subscriptions (agent-plan / coding-plan)
-  "volcengine-agent-plan",
-  "volcengine-coding-plan",
-  // Command Code credits + 5h/weekly rolling windows
-  "command-code",
-  "conol-web",
-  "cnl",
-  // Alibaba Coding Plan triple-window quota (#9603 UI gap — fetcher existed, list entry missing)
-  "bailian-coding-plan",
-  // Qwen Cloud / Model Studio personal Token Plan (cookie-authenticated console gateway)
-  "qwen-cloud-token-plan",
-  // AgentRouter (New-API) console balance quota (consoleApiKey + newApiUserId)
-  "agentrouter",
-  // Kilo Code personal USD balance (GET /api/profile/balance, existing OAuth token)
-  "kilocode",
-];
+export { USAGE_SUPPORTED_PROVIDERS } from "@omniroute/open-sse/services/usage/supportedProviders.ts";
 
 // ── Zod validation, lazily on first AI_PROVIDERS access (perf: skips the walk
 // for processes that never touch AI_PROVIDERS, e.g. short-lived CLI commands) ──

tests/unit/provider-plugin-manifest.test.ts

@@ -7,6 +7,7 @@ import {
 } from "../../open-sse/config/providerPluginManifest.ts";
 import type { RegistryEntry } from "../../open-sse/config/providers/shared.ts";
 import { USAGE_FETCHER_PROVIDERS } from "../../open-sse/services/usage/fetcherProviders.ts";
+import { USAGE_SUPPORTED_PROVIDERS } from "../../open-sse/services/usage/supportedProviders.ts";
 
 const registryFixture: Record<string, RegistryEntry> = {
   openai: {
@@ -182,3 +183,81 @@ test("usage-fetch matches the fetcher list by alias too (#11722)", () => {
   assert.ok(entry);
   assert.ok(entry.capabilities.includes("usage-fetch"));
 });
+
+test("manifest advertises usage-supported for providers whose usage API is accepted (#10078)", () => {
+  // claude is in USAGE_SUPPORTED_PROVIDERS, openai is not — assert against the real
+  // list so the test cannot drift silently if the list moves.
+  const claude = getProviderPluginManifestEntryFromRegistry(registryFixture, "claude");
+
+  assert.ok(claude);
+  assert.ok(
+    (USAGE_SUPPORTED_PROVIDERS as readonly string[]).includes("claude"),
+    "fixture guard: claude must stay in USAGE_SUPPORTED_PROVIDERS for this test to mean anything"
+  );
+  assert.ok(
+    claude.capabilities.includes("usage-supported"),
+    "claude is in USAGE_SUPPORTED_PROVIDERS, so the manifest must advertise usage-supported"
+  );
+});
+
+test("manifest omits usage-supported for providers outside USAGE_SUPPORTED_PROVIDERS (#10078)", () => {
+  for (const providerId of ["openai", "anthropic", "claude-web"]) {
+    const entry = getProviderPluginManifestEntryFromRegistry(registryFixture, providerId);
+
+    assert.ok(entry, `fixture guard: ${providerId} must resolve`);
+    assert.equal(
+      (USAGE_SUPPORTED_PROVIDERS as readonly string[]).includes(entry.id),
+      false,
+      `fixture guard: ${entry.id} must stay out of USAGE_SUPPORTED_PROVIDERS`
+    );
+    assert.equal(
+      entry.capabilities.includes("usage-supported"),
+      false,
+      `${entry.id} is not in USAGE_SUPPORTED_PROVIDERS, so usage-supported must not be advertised`
+    );
+  }
+});
+
+test("usage-supported matches only on id, not alias (#10078)", () => {
+  // USAGE_SUPPORTED_PROVIDERS is checked with a plain .includes(providerId) — no alias
+  // resolution (providerQuotaVisibility.ts:12, providerLimits.ts:178). The manifest must
+  // keep the same rule: an alias-only hit must NOT emit the tag.
+  const aliasOnlyFixture: Record<string, RegistryEntry> = {
+    "some-provider": {
+      id: "some-provider",
+      alias: "claude",
+      format: "openai",
+      executor: "default",
+      baseUrl: "https://some.example/v1/chat/completions",
+      authType: "apikey",
+      authHeader: "bearer",
+      models: [{ id: "m1", name: "M1" }],
+    },
+  };
+
+  assert.equal(
+    (USAGE_SUPPORTED_PROVIDERS as readonly string[]).includes("some-provider"),
+    false,
+    "fixture guard: the id must NOT be in the list"
+  );
+  assert.ok(
+    (USAGE_SUPPORTED_PROVIDERS as readonly string[]).includes("claude"),
+    "fixture guard: the alias must be in the list, otherwise this test proves nothing"
+  );
+
+  const entry = getProviderPluginManifestEntryFromRegistry(aliasOnlyFixture, "some-provider");
+
+  assert.ok(entry);
+  assert.equal(
+    entry.capabilities.includes("usage-supported"),
+    false,
+    "usage-supported is id-only — an alias hit must not advertise it"
+  );
+  // Sanity: the same entry MUST still carry usage-fetch via its alias, proving the
+  // two tags deliberately diverge on alias handling.
+  assert.ok(
+    (USAGE_FETCHER_PROVIDERS as readonly string[]).includes("claude"),
+    "fixture guard: claude must also be in USAGE_FETCHER_PROVIDERS for the divergence check"
+  );
+  assert.ok(entry.capabilities.includes("usage-fetch"));
+});