fix(providers): disclose the Volcengine Plan usage restriction

Volcengine documents Coding Plan and Agent Plan quota as valid only inside
supported AI coding tools, and warns that using a plan key for general API calls
may suspend the subscription or ban the account. Routing Codex or Claude Code
through opencodex is the vendor's documented use, so the presets stay canonical —
but the user was never told about the boundary they must not cross.

`tencent-coding-plan` already ships this disclosure; these two entries did not.

- carry the restriction in both Plan `note` strings, worded per product so Agent
  Plan does not quote Coding-Plan-specific policy
- resolve the DTO note by DESTINATION rather than by provider name. The dashboard
  lets a preset be saved under any name, and a renamed row kept the credential
  destination while silently losing the warning about it
- declare the text-only Plan models so the vision sidecar cannot advertise image
  input for models that cannot accept it, matching the Tencent precedent
- document the restriction in the provider guide

The custom-name regression fails on the previous name-only lookup, verified by
reverting the resolver and re-running the test.

Author: lidge-jun

docs-site/src/content/docs/guides/providers.md

@@ -241,6 +241,12 @@ Volcengine Agent Plan uses its native Responses endpoint through `openai-respons
 > models. Coding Plan defaults to `ark-code-latest`, while Agent Plan defaults to
 > `deepseek-v4-pro`.
 
+> **Volcengine Plan usage restriction:** Volcengine documents Coding Plan and Agent Plan quota as
+> valid only inside supported AI coding tools, and warns that using a plan key for general API
+> calls may suspend the subscription or ban the account. Routing Codex or Claude Code through
+> opencodex is the documented use; pointing other automation at a plan key is not. The
+> pay-as-you-go `volcengine` route carries no such restriction.
+
 **DeepInfra discovery.** The key-based `deepinfra` OpenAI Chat Completions provider uses the
 `openai-chat` adapter with a Bearer API key. Its registry-owned model-list URL keeps only rows tagged
 `chat`, preserves slash-containing native model ids, and caps live discovery at 512 KiB and 512 raw

src/providers/registry.ts

@@ -104,8 +104,6 @@ export interface ProviderRegistryEntry {
   adapter: string;
   baseUrl: string;
   apiKeyTransport?: OcxProviderConfig["apiKeyTransport"];
-  /** Relative Responses resource for key-auth openai-responses gateways with versioned bases. */
-  responsesPath?: string;
   authKind: ProviderAuthKind;
   codexAccountMode?: CodexAccountMode;
   /** OAuth preset may explicitly honor a persisted API-key billing mode. */
@@ -405,6 +403,17 @@ const VOLCENGINE_PLAN_INPUT_MODALITIES: Record<string, string[]> = {
   "kimi-k2.6": ["text", "image"],
   "minimax-m3": ["text", "image"],
 };
+// Every other Plan model is text-only. Declaring this explicitly keeps the vision
+// sidecar from advertising image input for models that cannot accept it — the same
+// treatment tencent-coding-plan gives its (entirely text-only) plan catalog.
+const VOLCENGINE_PLAN_TEXT_ONLY_MODELS = [
+  "ark-code-latest",
+  "doubao-seed-2.0-code",
+  "deepseek-v4-pro",
+  "deepseek-v4-flash",
+  "glm-5.2",
+  "doubao-seed-2.0-pro",
+];
 const ALIBABA_INTL_TOKEN_PLAN_INPUT_MODALITIES: Record<string, string[]> = {
   "qwen3.8-max-preview": ["text", "image"],
   "qwen3.7-max": ["text", "image"],
@@ -1146,14 +1155,15 @@ export const PROVIDER_REGISTRY: readonly ProviderRegistryEntry[] = [
     models: VOLCENGINE_CODING_PLAN_MODELS,
     liveModels: false,
     modelInputModalities: VOLCENGINE_PLAN_INPUT_MODALITIES,
+    noVisionModels: VOLCENGINE_PLAN_TEXT_ONLY_MODELS,
     modelReasoningEfforts: Object.fromEntries(
       DEEPSEEK_THINKING_MODELS.map(id => [id, DEEPSEEK_THINKING_EFFORTS]),
     ),
     modelReasoningEffortMap: Object.fromEntries(
       DEEPSEEK_THINKING_MODELS.map(id => [id, DEEPSEEK_THINKING_REASONING_MAP]),
     ),
     preserveReasoningContentModels: DEEPSEEK_THINKING_MODELS,
-    note: "Coding Plan subscription endpoint with plan-scoped model aliases. Use the plan key issued by the Ark console.",
+    note: "Coding tools only. Volcengine restricts Coding Plan quota to supported AI coding tools and warns that using this key for general API calls may suspend the subscription or ban the account. Use the plan key issued by the Ark console.",
   },
   {
     id: "volcengine-agent-plan",
@@ -1168,7 +1178,8 @@ export const PROVIDER_REGISTRY: readonly ProviderRegistryEntry[] = [
     models: VOLCENGINE_AGENT_PLAN_MODELS,
     liveModels: false,
     modelInputModalities: VOLCENGINE_PLAN_INPUT_MODALITIES,
-    note: "Agent Plan subscription endpoint over the native Responses API with a static fallback catalog.",
+    noVisionModels: VOLCENGINE_PLAN_TEXT_ONLY_MODELS,
+    note: "Coding tools only. Agent Plan is a subscription endpoint over the native Responses API with a static fallback catalog; Ark plan quota is intended for supported AI coding and agent tools, so avoid using this key as a general-purpose API key.",
   },
   // 2026-07-10: docs unverified; model data frozen. Evidence: devlog/_plan/260710_provider_hardening/002_research_cn.md.
   { id: "qianfan", label: "Qianfan (Baidu)", baseUrl: "https://qianfan.baidubce.com/v2", adapter: "openai-chat", authKind: "key", dashboardUrl: "https://console.bce.baidu.com/iam/#/iam/apikey/list" },
@@ -1439,6 +1450,32 @@ export function providerMatchesRegistryTransport(
   return normalizedProviderEndpoint(provider.baseUrl) === normalizedProviderEndpoint(entry.baseUrl);
 }
 
+/**
+ * Resolve the registry entry a configured provider actually points at, by TRANSPORT
+ * rather than by name.
+ *
+ * `providerMatchesRegistryTransport` answers "does the row named X still point at X's
+ * documented destination", which is the right question for routing but the wrong one
+ * for user-facing metadata: the GUI lets a preset be saved under any name, and a
+ * renamed row would silently lose a usage restriction it still needs to display.
+ *
+ * Only fixed key destinations are matched. Entries with an overridable or templated
+ * base URL are skipped, because their configured URL cannot identify one vendor route.
+ */
+export function registryEntryForProviderDestination(
+  provider: Pick<OcxProviderConfig, "baseUrl" | "adapter"> & Partial<Pick<OcxProviderConfig, "authMode">>,
+): ProviderRegistryEntry | undefined {
+  if (typeof provider.baseUrl !== "string" || !provider.baseUrl) return undefined;
+  if (provider.authMode !== undefined && provider.authMode !== "key") return undefined;
+  const endpoint = normalizedProviderEndpoint(provider.baseUrl);
+  return PROVIDER_REGISTRY.find(entry =>
+    entry.authKind === "key"
+    && !entry.allowBaseUrlOverride
+    && !/\{[^}]*\}/.test(entry.baseUrl)
+    && entry.adapter === provider.adapter
+    && normalizedProviderEndpoint(entry.baseUrl) === endpoint);
+}
+
 /**
  * Resolve a registry-only default for a mixed-wire provider. Defaults only move a provider
  * between the two OpenAI-shaped adapters and never override a provider configured on another

src/server/auth-cors.ts

@@ -12,7 +12,7 @@ import {
   reasoningSummaryDeliveryRecordConfigError,
 } from "../config";
 import { providerDestinationConfigError } from "../lib/destination-policy";
-import { getProviderRegistryEntry, providerCodexAccountMode, providerMatchesRegistryTransport } from "../providers/registry";
+import { getProviderRegistryEntry, providerCodexAccountMode, providerMatchesRegistryTransport, registryEntryForProviderDestination } from "../providers/registry";
 import { providerConfigSeed } from "../providers/derive";
 import type { OcxConfig, OcxProviderConfig } from "../types";
 import { openRouterRoutingConfigError } from "../providers/openrouter-routing";
@@ -504,9 +504,13 @@ export function safeConfigDTO(config: OcxConfig): unknown {
     ] as const) {
       copyIfDefined(dto, provider, key);
     }
-    const registryNote = providerMatchesRegistryTransport(name, provider)
-      ? getProviderRegistryEntry(name)?.note
-      : undefined;
+    // Resolve the note by DESTINATION, not by name. A preset saved under a custom name is
+    // still pointed at the same vendor route, and a usage restriction the user needs to see
+    // must not disappear because the row was renamed. Prefer the same-name entry so an
+    // unrenamed provider keeps its exact registry note.
+    const registryNote = (providerMatchesRegistryTransport(name, provider)
+      ? getProviderRegistryEntry(name)
+      : registryEntryForProviderDestination(provider))?.note;
     if (typeof registryNote === "string" && registryNote.trim()) dto.note = registryNote;
     const codexAccountMode = providerCodexAccountMode(name, provider);
     if (codexAccountMode) dto.codexAccountMode = codexAccountMode;

tests/volcengine-providers.test.ts

@@ -5,6 +5,7 @@ import { applyProviderConfigHints, buildCatalogEntries } from "../src/codex/cata
 import { KEY_LOGIN_PROVIDERS } from "../src/oauth/key-providers";
 import { deriveProviderPresets, providerConfigSeed } from "../src/providers/derive";
 import { PROVIDER_REGISTRY } from "../src/providers/registry";
+import { safeConfigDTO } from "../src/server/auth-cors";
 import { routeModel } from "../src/router";
 import type { OcxConfig } from "../src/types";
 import { buildProviderPostBody } from "../gui/src/provider-payload";
@@ -317,4 +318,77 @@ describe("Volcengine Ark providers", () => {
     expect(isCatalogProviderId("volcengine-coding-plan")).toBe(true);
     expect(isCatalogProviderId("volcengine-agent-plan")).toBe(true);
   });
+
+  // Volcengine documents Plan quota as valid only inside supported AI coding tools and warns
+  // that other API use of the key may suspend the subscription or ban the account. The note is
+  // the only surface that tells a user this, so both Plan presets must carry it and the
+  // pay-as-you-go route — which has no such restriction — must not.
+  test("both Plan presets disclose the coding-tools-only restriction", () => {
+    const codingPlan = PROVIDER_REGISTRY.find(provider => provider.id === "volcengine-coding-plan")!;
+    const agentPlan = PROVIDER_REGISTRY.find(provider => provider.id === "volcengine-agent-plan")!;
+    const payg = PROVIDER_REGISTRY.find(provider => provider.id === "volcengine")!;
+
+    expect(codingPlan.note).toContain("Coding tools only");
+    expect(codingPlan.note).toMatch(/suspend the subscription or ban the account/);
+    expect(agentPlan.note).toContain("Coding tools only");
+    expect(payg.note).not.toContain("Coding tools only");
+  });
+
+  test("Plan presets declare their text-only models so the vision sidecar cannot over-advertise", () => {
+    for (const id of ["volcengine-coding-plan", "volcengine-agent-plan"]) {
+      const entry = PROVIDER_REGISTRY.find(provider => provider.id === id)!;
+      const multimodal = Object.entries(entry.modelInputModalities ?? {})
+        .filter(([, modalities]) => modalities.includes("image"))
+        .map(([model]) => model);
+
+      // Every advertised model is either declared multimodal or declared text-only —
+      // nothing is left to the default.
+      for (const model of entry.models ?? []) {
+        const declared = multimodal.includes(model) || (entry.noVisionModels ?? []).includes(model);
+        expect(declared).toBe(true);
+      }
+      // A text-only model is never also advertised as accepting images.
+      for (const model of entry.noVisionModels ?? []) {
+        expect(multimodal).not.toContain(model);
+      }
+    }
+  });
+
+  // The dashboard lets a preset be saved under any name. Resolving the note by name alone
+  // silently dropped the usage restriction for a renamed row — the user kept the same
+  // credential destination but lost the warning about it.
+  test("the Plan restriction survives saving the preset under a custom name", () => {
+    const codingPlan = PROVIDER_REGISTRY.find(provider => provider.id === "volcengine-coding-plan")!;
+    const dto = safeConfigDTO({
+      port: 10100,
+      defaultProvider: "my-volc",
+      providers: {
+        "my-volc": {
+          adapter: codingPlan.adapter,
+          baseUrl: codingPlan.baseUrl,
+          authMode: "key",
+          apiKey: "sk-test-not-a-real-key",
+        },
+      },
+    } as unknown as OcxConfig) as { providers: Record<string, { note?: string }> };
+
+    expect(dto.providers["my-volc"].note).toContain("Coding tools only");
+  });
+
+  test("an unrelated destination does not inherit a Volcengine restriction", () => {
+    const dto = safeConfigDTO({
+      port: 10100,
+      defaultProvider: "somewhere-else",
+      providers: {
+        "somewhere-else": {
+          adapter: "openai-chat",
+          baseUrl: "https://api.example.test/v1",
+          authMode: "key",
+          apiKey: "sk-test-not-a-real-key",
+        },
+      },
+    } as unknown as OcxConfig) as { providers: Record<string, { note?: string }> };
+
+    expect(dto.providers["somewhere-else"].note).toBeUndefined();
+  });
 });