@nebulesstech/opencode-9router 0.1.1

package/README.md

@@ -0,0 +1,211 @@
+# 9Router for OpenCode
+
+`@nebulesstech/opencode-9router` version **0.1.1** registers
+[9Router](https://github.com/decolua/9router) as an OpenCode provider, discovers
+models, and generates model-specific thinking variants. It does not run the gateway.
+
+## For Users
+
+### Install and Configure
+
+Run a trusted 9Router gateway and obtain its API key. The default API base URL is
+`http://localhost:20128/v1`.
+
+Add this to your project `opencode.json` or global
+`~/.config/opencode/opencode.json`, merging with existing settings:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": ["@nebulesstech/opencode-9router@0.1.1"],
+  "provider": {
+    "9router": {
+      "npm": "@ai-sdk/openai-compatible",
+      "name": "9Router",
+      "options": {
+        "baseURL": "http://localhost:20128/v1"
+      }
+    }
+  }
+}
+```
+
+OpenCode auto-installs npm plugins at startup. No separate `npm install`, clone,
+or build is required for users. This package ships ESM TypeScript for OpenCode's
+plugin loader, not a compiled JavaScript library for plain Node.js imports.
+The explicit provider block makes the endpoint visible; the plugin can register
+it without that block. No hand-written `models` block is needed for discovery.
+
+These instructions target the published `0.1.1` release. Package metadata alone
+does not establish that a release exists. A registry 404 can mean unpublished or
+inaccessible; confirm release availability with the maintainer.
+
+### Authenticate
+
+Start OpenCode, run `/connect`, select **9Router**, and provide the gateway API
+key. Restart OpenCode afterward so startup discovery sees the stored credential.
+The plugin reads the `9router` entry in
+`~/.local/share/opencode/auth.json` before OpenCode's auth loader runs.
+
+For environment-based setup, inject `NINE_ROUTER_API_KEY` securely before starting
+OpenCode (`ROUTER_API_KEY` is the fallback). Also add this to the provider's
+`options` for inference authentication:
+
+```json
+{
+  "baseURL": "http://localhost:20128/v1",
+  "apiKey": "{env:NINE_ROUTER_API_KEY}"
+}
+```
+
+Use `{env:ROUTER_API_KEY}` instead if using that fallback. Discovery resolves keys
+in this order: nonempty plugin tuple `apiKey`, `NINE_ROUTER_API_KEY`,
+`ROUTER_API_KEY`, stored credential. Provider `options.apiKey` is not read by the
+discovery resolver. The auth loader returns an empty object and relies on
+OpenCode to supply stored credentials for inference; discovery-only keys are
+not copied into provider options. Unset unused environment variables rather
+than leaving them empty, since empty values can mask lower-priority credentials.
+
+The `/connect` base URL prompt saves metadata, but this version does not read
+that metadata when resolving endpoints. Configure the URL explicitly below.
+
+### Base URL Precedence
+
+Startup discovery and the registered provider use the first configured value:
+
+1. `provider.9router.options.baseURL`.
+2. Nonempty plugin tuple option `baseURL`.
+3. `NINE_ROUTER_BASE_URL`, otherwise `ROUTER_BASE_URL`.
+4. `http://localhost:20128/v1`.
+
+The explicit provider URL in the installation example therefore overrides
+environment URLs. Remove that field if you want environment selection. Keep
+environment values unset when unused. For tuple-capable OpenCode versions:
+
+```json
+{
+  "plugin": [
+    ["@nebulesstech/opencode-9router@0.1.1", {"baseURL": "https://router.example.com/v1"}]
+  ]
+}
+```
+
+The separate `provider.models` hook uses tuple/environment/default precedence,
+not the provider option. Startup discovery uses the `config` hook for this
+config-only provider. Keep endpoint settings consistent if using both hooks.
+
+### Discovery and Thinking
+
+Discovery requests `GET <baseURL>/models`, for example
+`http://localhost:20128/v1/models`, with a bearer key. Do not append another `/v1`.
+Without a resolved key, discovery is skipped even if the gateway allows public
+model listing. Successful results are cached in memory for five minutes per
+base URL; this is not a background refresh timer. Restart after credential or
+configuration changes. Existing user-defined model entries win by model ID.
+Failures leave the provider registered with any manually configured models.
+
+Discovery maps reasoning, tools, vision, and context/output limits. Missing
+limits default to 200,000 context tokens and at most 32,000 output tokens.
+Reported costs are zero placeholders, not a promise of free usage. Combo models
+appear when returned by the gateway's model list.
+
+Thinking variants depend on capability metadata, format, and model-ID heuristics:
+
+| Format | Current request fields |
+| --- | --- |
+| OpenAI | `reasoning_effort`; `max` maps to `xhigh` |
+| Z.ai / GLM | `reasoning_effort: low` or `high`; higher levels clamp to `high` |
+| DeepSeek | Enabled `thinking` plus `reasoning_effort`; current mapping sends `high` for minimal/low/medium and `max` for high/xhigh/max |
+| Kimi | Enabled `thinking` plus low/medium/high `reasoning_effort` |
+| MiniMax | Adaptive `thinking`; some models have no selectable variants |
+| Qwen | `enable_thinking` and `thinking_budget` |
+| Budget-style | Enabled `thinking` with `budget_tokens` |
+
+Budget map: none 0, minimal 512, low 1,024, medium 8,192, high 24,576,
+xhigh 32,768, max 128,000. The resolver filters or clamps against advertised
+`thinkingRange`; it does not expose every named level for every model.
+`thinkingCanDisable: false` removes `none`. Identical bodies are deduplicated,
+keeping the first generated level. Missing format metadata uses reasoning and
+model-name heuristics; unknown formats may yield no variants. Variant labels
+are not guarantees of distinct upstream effort or quality.
+
+### Verify and Troubleshoot
+
+Restart OpenCode, open `/models`, and choose a discovered 9Router model. Run a
+small prompt using its exact ID, preserving any gateway prefix:
+
+```sh
+opencode run --model '9router/<model-id>' 'Say OK'
+```
+
+Replace `<model-id>` with an actual discovered ID. Check available variants in
+OpenCode and select one supported by that model. Successful listing verifies
+discovery; a successful response separately verifies inference authentication.
+
+| Symptom | Check |
+| --- | --- |
+| npm 404 / plugin not installed | Confirm package/version publication and registry access; do not substitute a raw source URL |
+| No models | Confirm resolved key, endpoint reachability, and a JSON `data` array from `/models`; startup discovery failures are swallowed |
+| HTTP 401/403 | Check gateway key and separate discovery/inference key configuration |
+| HTTP 404 from gateway | Use API base URL ending in `/v1`, not `/v1/models` or `/v1/v1` |
+| Wrong endpoint | Check provider URL first; `/connect` URL metadata is not used |
+| Missing thinking variants | Check capabilities, range filtering, deduplication, and adaptive models with nothing to vary |
+| Old models or changed key ignored | Restart; cache is keyed by URL, not credential |
+
+### Security
+
+API keys MUST NOT enter source files or committed configuration. Use `/connect`
+or environment substitution, protect the auth file, and redact keys from logs
+and issue reports. Rotate any exposed credential. Only configure trusted
+gateways: discovery sends the bearer key to the resolved URL, and inference
+sends prompts and model traffic to the provider endpoint. Use HTTPS for remote
+gateways; keep plain HTTP limited to trusted local development. Review plugins
+before installing because they execute inside OpenCode.
+
+## For Maintainers
+
+Work from `plugins/9router`. `package.json` defines public scoped package
+`@nebulesstech/opencode-9router@0.1.1`, Node.js `>=20`, and zero-build ESM export
+`./index.ts`. OpenCode supplies the TypeScript-capable loader; the Node engine
+does not imply native Node can resolve the current extensionless TS imports.
+
+Published files are `index.ts`, `thinking.ts`, `README.md`, and npm's mandatory
+`package.json`. `selfcheck.ts` and local `opencode.json` stay in the repository.
+`@opencode-ai/plugin` is development-only because its source import is type-only;
+its pinned version matches this repository's SDK dependency. No build tooling
+or runtime dependencies are bundled. No license is asserted by this manifest.
+
+### Checks and Local Loading
+
+With Bun installed and a suitable live gateway, run:
+
+```sh
+npm run selfcheck -- http://localhost:20128/v1
+npm run pack:check
+```
+
+The self-check makes a live `/models` request and checks resolver invariants;
+it is not an authenticated end-to-end inference test. It sends no authorization
+header and does not read API-key variables. Use a trusted test endpoint that
+permits model listing without authentication; do not disable production auth.
+Always pass the URL: its fallback is `NINE_ROUTER_BASE_URL`, then the existing
+development address `http://zo-computer:20128/v1`, not the plugin default.
+`pack:check` runs `npm pack --dry-run`; inspect its file list for unexpected files
+or secrets. It does not publish or prove OpenCode compatibility.
+
+For a local smoke test, replace the npm plugin entry in a separate OpenCode
+configuration with `file:///absolute/path/to/Opencode-Workflows/plugins/9router/index.ts`.
+Keep `thinking.ts` alongside it. Repeat the user verification flow against a test
+gateway. Do not load local and npm copies together.
+
+### Release Flow
+
+1. Review runtime changes and publication rights. Resolve licensing deliberately; do not invent a license field.
+2. Run the live self-check and OpenCode smoke test above. Record actual results and any limitations.
+3. Confirm npm account `nebulesstech` has scope access. Check registry state; a 404 alone does not prove name availability.
+4. Set the intended version in `package.json` and update README installation pins. Run `npm run pack:check` and review the exact payload.
+5. Only after explicit release approval, an authorized maintainer publishes from this directory with public access. `publishConfig.access` is already `public`.
+6. Verify the published name/version and clean OpenCode startup installation, discovery, and inference before announcing the release.
+
+This guide describes a release procedure, not evidence that publishing or live
+verification has occurred. npm versions are immutable; fixes require a new version.

package/index.ts

@@ -0,0 +1,256 @@
+import { readFileSync } from "node:fs"
+import { homedir as osHomedir } from "node:os"
+import type { Plugin } from "@opencode-ai/plugin"
+import {
+  classifyFormat,
+  buildVariants,
+  type Format,
+  type Capabilities,
+  type Body,
+} from "./thinking"
+
+const PROVIDER_ID = "9router"
+const DEFAULT_BASE_URL = "http://localhost:20128/v1"
+const CACHE_TTL_MS = 5 * 60 * 1000
+
+type NineRouterCapabilities = {
+  vision?: boolean
+  tools?: boolean
+  reasoning?: boolean
+  thinkingFormat?: string | null
+  thinkingCanDisable?: boolean
+  thinkingEffortSupported?: boolean
+  thinkingRange?: [number, number] | null
+  contextWindow?: number
+  maxOutput?: number
+}
+
+type NineRouterModel = {
+  id: string
+  owned_by?: string
+  capabilities?: NineRouterCapabilities
+  context_length?: number
+  max_completion_tokens?: number
+}
+
+type ConfigModel = {
+  id?: string
+  name?: string
+  reasoning?: boolean
+  tool_call?: boolean
+  attachment?: boolean
+  temperature?: boolean
+  cost?: Record<string, unknown>
+  limit?: { context?: number; output?: number; input?: number }
+  options?: Record<string, unknown>
+  variants?: Record<string, Body | { disabled?: boolean }>
+}
+
+export const NineRouter: Plugin = async (input, options) => {
+  // Plugin-level options come from the tuple form: ["file://…", { baseURL }]
+  const pluginOptions = (options ?? {}) as Record<string, unknown>
+
+  const resolveBaseURL = (): string => {
+    const fromEnv =
+      process.env.NINE_ROUTER_BASE_URL ??
+      process.env.ROUTER_BASE_URL ??
+      undefined
+    return (
+      (typeof pluginOptions.baseURL === "string" && pluginOptions.baseURL) ||
+      fromEnv ||
+      DEFAULT_BASE_URL
+    )
+  }
+
+  const resolveKey = (): string | undefined => {
+    const fromOptions =
+      typeof pluginOptions.apiKey === "string" && pluginOptions.apiKey
+        ? pluginOptions.apiKey
+        : undefined
+    return (
+      fromOptions ??
+      process.env.NINE_ROUTER_API_KEY ??
+      process.env.ROUTER_API_KEY ??
+      storedKey() ??
+      undefined
+    )
+  }
+
+  // The config() hook runs before opencode's auth loader, so the stored
+  // /connect credential is read straight from the auth database file.
+  function storedKey(): string | undefined {
+    try {
+      const p = `${osHomedir()}/.local/share/opencode/auth.json`
+      const auth = JSON.parse(readFileSync(p, "utf8")) as Record<
+        string,
+        { type?: string; key?: string; access?: string }
+      >
+      const entry = auth[PROVIDER_ID]
+      if (!entry) return undefined
+      return entry.type === "api" ? entry.key : entry.type === "oauth" ? entry.access : entry.key
+    } catch {
+      return undefined
+    }
+  }
+
+  let cache: { at: number; models: Record<string, unknown> } | undefined
+  let cacheKey: string | undefined
+
+  async function fetchModels(baseURL: string, key?: string) {
+    if (cache && cacheKey === baseURL && Date.now() - cache.at < CACHE_TTL_MS) {
+      return cache.models
+    }
+    const url = baseURL.replace(/\/$/, "") + "/models"
+    const resp = await fetch(url, {
+      headers: key ? { Authorization: `Bearer ${key}` } : {},
+    })
+    if (!resp.ok) throw new Error(`9router: GET ${url} -> ${resp.status}`)
+    const json = (await resp.json()) as { data?: NineRouterModel[] }
+    const list = Array.isArray(json.data) ? json.data : []
+    const models: Record<string, unknown> = {}
+    for (const m of list) {
+      if (!m?.id) continue
+      models[m.id] = toConfigModel(m)
+    }
+    cache = { at: Date.now(), models }
+    cacheKey = baseURL
+    return models
+  }
+
+  function toConfigModel(m: NineRouterModel) {
+    const caps = m.capabilities ?? {}
+    const reasoning = caps.reasoning === true
+    const context = caps.contextWindow ?? m.context_length ?? 200_000
+    const output = caps.maxOutput ?? m.max_completion_tokens ?? Math.min(context, 32_000)
+    const pretty = prettyName(m.id)
+    const model: Record<string, unknown> = {
+      name: pretty,
+      reasoning: reasoning === true,
+      tool_call: caps.tools !== false,
+      attachment: caps.vision === true,
+      temperature: true,
+      release_date: "",
+      limit: { context, output },
+      // 9Router does not expose per-model pricing; zero cost keeps the
+      // usage math defined without inventing numbers.
+      cost: { input: 0, output: 0, cache_read: 0, cache_write: 0 },
+    }
+    const variants = buildVariants(
+      classifyFormat(caps.thinkingFormat, m.id, caps.reasoning === true),
+      {
+        reasoning,
+        canDisable: caps.thinkingCanDisable !== false,
+        effortSupported: caps.thinkingEffortSupported === true,
+        range: (caps.thinkingRange as [number, number] | null) ?? null,
+      },
+      m.id,
+    )
+    if (Object.keys(variants).length > 0) model.variants = variants
+    return model
+  }
+
+  return {
+    // Register the provider and inject discovered models. The provider.models
+    // hook is only consulted for providers that exist in the models.dev
+    // catalog, so for a config-only provider the discovery must happen here:
+    // config() runs before opencode parses cfg.provider into the database.
+    config: async (cfg) => {
+      cfg.provider ??= {}
+      const existing = cfg.provider[PROVIDER_ID] ?? {}
+      const baseURL = existing.options?.baseURL ?? resolveBaseURL()
+      const key = resolveKey()
+      cfg.provider[PROVIDER_ID] = {
+        npm: "@ai-sdk/openai-compatible",
+        name: existing.name ?? "9Router",
+        options: {
+          ...(existing.options ?? {}),
+          baseURL,
+        },
+        models: existing.models ?? {},
+      }
+      if (!key) return
+      try {
+        const discovered = await fetchModels(baseURL, key)
+        const merged = { ...(cfg.provider[PROVIDER_ID].models as object) }
+        for (const [id, model] of Object.entries(discovered)) {
+          if (!merged[id]) merged[id] = model
+        }
+        cfg.provider[PROVIDER_ID].models = merged
+      } catch {
+        // unreachable router: provider stays registered with whatever the
+        // user hand-wrote; opencode will error on that model, not at boot
+      }
+    },
+
+    auth: {
+      provider: PROVIDER_ID,
+      // Return {} and let opencode inject options.apiKey from the stored key.
+      loader: async () => ({}),
+      methods: [
+        {
+          type: "api",
+          label: "9Router API key",
+          prompts: [
+            {
+              key: "baseURL",
+              type: "text" as const,
+              message: "9Router base URL (leave blank for http://localhost:20128/v1)",
+              placeholder: "http://localhost:20128/v1",
+            },
+          ],
+          async authorize(inputs) {
+            const key = inputs?.["apiKey"] ?? ""
+            if (!key.trim()) return { type: "failed" as const }
+            const baseURL = inputs?.["baseURL"]?.trim()
+            const metadata: Record<string, string> = {}
+            if (baseURL) metadata.baseURL = baseURL
+            return {
+              type: "success" as const,
+              key,
+              provider: PROVIDER_ID,
+              metadata,
+            }
+          },
+        },
+      ],
+    },
+
+    provider: {
+      id: PROVIDER_ID,
+      models: async (_provider, ctx) => {
+        const key = resolveKey() ?? keyFromAuth(ctx.auth)
+        if (!key) return {}
+        const baseURL = resolveBaseURL()
+        try {
+          return await fetchModels(baseURL, key)
+        } catch {
+          // unreachable router: expose nothing rather than a broken provider
+          return {}
+        }
+      },
+    },
+  }
+}
+
+function keyFromAuth(auth: unknown): string | undefined {
+  if (!auth || typeof auth !== "object") return undefined
+  const a = auth as { type?: string; key?: string; access?: string }
+  if (a.type === "api") return a.key
+  if (a.type === "oauth") return a.access
+  if (a.type === "wellknown") return a.key
+  return undefined
+}
+
+function prettyName(id: string): string {
+  const tail = id.includes("/") ? id.slice(id.lastIndexOf("/") + 1) : id
+  return tail
+    .replace(/[:_]/g, " ")
+    .replace(/-/g, " ")
+    .replace(/\s+/g, " ")
+    .trim()
+    .split(" ")
+    .map((w) => (w.length <= 3 ? w.toUpperCase() : w[0].toUpperCase() + w.slice(1)))
+    .join(" ")
+}
+
+export type { ConfigModel }

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@nebulesstech/opencode-9router",
+  "version": "0.1.1",
+  "description": "OpenCode provider plugin for 9Router model discovery and thinking variants",
+  "type": "module",
+  "exports": "./index.ts",
+  "files": [
+    "index.ts",
+    "thinking.ts",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Nebuless/Opencode-Workflows.git",
+    "directory": "plugins/9router"
+  },
+  "keywords": [
+    "opencode",
+    "opencode-plugin",
+    "9router",
+    "ai",
+    "provider",
+    "reasoning"
+  ],
+  "scripts": {
+    "selfcheck": "bun run selfcheck.ts",
+    "pack:check": "npm pack --dry-run"
+  },
+  "devDependencies": {
+    "@opencode-ai/plugin": "1.18.31"
+  }
+}

package/thinking.ts

@@ -0,0 +1,284 @@
+// 9Router thinking-level resolution.
+//
+// Levels and budgets mirror 9Router's own source of truth:
+// open-sse/translator/concerns/thinking.js (decolua/9router)
+//   EFFORT_LEVELS = minimal|low|medium|high|xhigh|max
+//   LEVEL_TO_BUDGET = none:0, minimal:512, low:1024, medium:8192,
+//                     high:24576, xhigh:32768, max:128000
+//
+// A "thinking format" describes the request-body shape 9Router expects for a
+// model. 9Router normalizes the body itself per format (thinkingUnified.js),
+// so variants only need to emit the right top-level keys.
+
+/** Ordered low -> high. */
+export const EFFORT_LEVELS = [
+  "none",
+  "minimal",
+  "low",
+  "medium",
+  "high",
+  "xhigh",
+  "max",
+] as const
+
+export type EffortLevel = (typeof EFFORT_LEVELS)[number]
+
+/** Web-standard level -> budget_tokens (Anthropic/Gemini docs, via 9router). */
+export const LEVEL_TO_BUDGET: Record<EffortLevel, number> = {
+  none: 0,
+  minimal: 512,
+  low: 1024,
+  medium: 8192,
+  high: 24576,
+  xhigh: 32768,
+  max: 128000,
+}
+
+/** Request-body patch a variant contributes. Applied as providerOptions["9router"]. */
+export type Body = Record<string, unknown>
+
+export type Capabilities = {
+  reasoning: boolean
+  /** Model cannot disable thinking: clamp "none" instead of emitting a disable body. */
+  canDisable: boolean
+  /** Server advertises a discrete-effort ladder. */
+  effortSupported: boolean
+  /** [min, max] budget when known, else null. */
+  range: [number, number] | null
+}
+
+export type Format =
+  | "openai"
+  | "zai"
+  | "deepseek"
+  | "kimi"
+  | "minimax"
+  | "qwen"
+  | "budget" // claude/gemini/hunyuan-style { thinking: { type, budget_tokens } }
+  | "none"
+
+/** Clamp a budget into an optional thinkingRange. */
+function clampBudget(budget: number, range: [number, number] | null): number {
+  if (!range) return budget
+  const [min, max] = range
+  if (Number.isFinite(min) && budget < min) budget = min
+  if (Number.isFinite(max) && budget > max) budget = max
+  return budget
+}
+
+/**
+ * Resolve which effort levels a model exposes.
+ *
+ * 1. thinkingEffortSupported -> full ladder
+ * 2. thinkingRange present   -> levels whose budget fits the range
+ * 3. format/family heuristics
+ */
+export function resolveLevels(
+  format: Format,
+  caps: Capabilities,
+  modelId: string,
+): EffortLevel[] {
+  const id = modelId.toLowerCase()
+
+  const noneFirst: EffortLevel[] = caps.canDisable ? ["none"] : []
+
+  if (caps.effortSupported) {
+    // zai GLM-5.3+: discrete low|high (+ effort pass-through); openai-style full.
+    if (format === "zai") return [...noneFirst, "low", "high", "xhigh", "max"]
+    return [...noneFirst, "low", "medium", "high", "xhigh", "max"]
+  }
+
+  if (caps.range) {
+    const [min, max] = caps.range
+    const fits = (lvl: EffortLevel) => {
+      const b = LEVEL_TO_BUDGET[lvl]
+      return b >= (Number.isFinite(min) ? min : 0) && b <= (Number.isFinite(max) ? max : Infinity)
+    }
+    const set = [...noneFirst, "low", "medium", "high", "xhigh", "max"].filter(
+      (l) => l === "none" || fits(l),
+    )
+    return set as EffortLevel[]
+  }
+
+  // Family first: some ids carry their own thinking interface regardless of format.
+  if (id.includes("nemotron")) {
+    // Nemotron 3 has no discrete thinking controls on this gateway: one shot.
+    return caps.canDisable ? ["none", "high"] : []
+  }
+
+  switch (format) {
+    case "openai":
+      // gpt families: xhigh is top; "max" is not a native openai enum.
+      return [...noneFirst, "low", "medium", "high", "xhigh"]
+    case "zai":
+      // GLM without effort support: enable/disable + low|high effort (5.2 reads reasoning_effort).
+      return [...noneFirst, "low", "high"]
+    case "deepseek":
+      // deepseek maps low/medium -> high upstream; v4 adds native max.
+      return id.includes("deepseek-v4")
+        ? [...noneFirst, "high", "max"]
+        : [...noneFirst, "high"]
+    case "kimi":
+      return [...noneFirst, "low", "medium", "high"]
+    case "minimax":
+      // Adaptive: one on/off toggle is all the format can express.
+      return caps.canDisable ? ["none", "high"] : []
+    case "qwen":
+      return [...noneFirst, "high"]
+    case "budget":
+      return [...noneFirst, "low", "medium", "high", "xhigh", "max"]
+    case "none":
+      return []
+  }
+}
+
+/**
+ * Map a resolved level to the request-body keys for the model's format.
+ * Must match 9Router's applyThinking switch (thinkingUnified.js) so the
+ * upstream provider receives exactly what it expects.
+ */
+export function levelToBody(
+  format: Format,
+  level: EffortLevel,
+  caps: Capabilities,
+  modelId: string,
+): Body {
+  const id = modelId.toLowerCase()
+  const budget = clampBudget(LEVEL_TO_BUDGET[level], caps.range)
+  const disable: Body = { thinking: { type: "disabled" } }
+
+  switch (format) {
+    case "openai":
+      // openai enum: none|minimal|low|medium|high|xhigh (no "max")
+      if (level === "none") return { reasoning_effort: "none" }
+      if (level === "max") return { reasoning_effort: "xhigh" }
+      return { reasoning_effort: level }
+
+    case "zai": {
+      // z.ai reads reasoning_effort from GLM-5.2 onward; disable only when allowed.
+      if (level === "none") return caps.canDisable ? disable : { reasoning_effort: "low" }
+      if (level === "low") return { reasoning_effort: "low" }
+      if (level === "medium") return { reasoning_effort: "low" } // zai has no medium
+      if (level === "high") return { reasoning_effort: "high" }
+      return { reasoning_effort: "high" } // xhigh/max clamp: zai caps at high
+    }
+
+    case "deepseek": {
+      // low/medium -> high, xhigh/max -> max (9router mapping)
+      if (level === "none") return caps.canDisable ? disable : enabledHigh()
+      if (level === "minimal" || level === "low" || level === "medium")
+        return enabledHigh()
+      return { thinking: { type: "enabled" }, reasoning_effort: "max" }
+    }
+
+    case "kimi": {
+      if (level === "none") return caps.canDisable ? disable : enabledKimi()
+      // kimi accepts low|medium|high; higher levels clamp to high
+      const effort =
+        level === "minimal" || level === "low" ? "low" : level === "medium" ? "medium" : "high"
+      return { thinking: { type: "enabled" }, reasoning_effort: effort }
+    }
+
+    case "minimax":
+      // M2.x/M3 are adaptive; budget fields are ignored upstream.
+      if (level === "none") return caps.canDisable ? disable : { thinking: { type: "adaptive" } }
+      return { thinking: { type: "adaptive" } }
+
+    case "qwen":
+      if (level === "none") return caps.canDisable ? { enable_thinking: false } : high()
+      return { enable_thinking: true, thinking_budget: budget || undefined }
+
+    case "budget":
+      if (level === "none") return caps.canDisable ? disable : budgetBody(-1)
+      return budgetBody(budget)
+
+    case "none":
+      return {}
+  }
+
+  function enabledHigh(): Body {
+    return { thinking: { type: "enabled" }, reasoning_effort: "high" }
+  }
+  function enabledKimi(): Body {
+    return { thinking: { type: "enabled" }, reasoning_effort: "high" }
+  }
+  function high(): Body {
+    return { enable_thinking: true, thinking_budget: LEVEL_TO_BUDGET.high }
+  }
+  function budgetBody(b: number): Body {
+    return b === -1
+      ? { thinking: { type: "enabled" } }
+      : { thinking: { type: "enabled", budget_tokens: b } }
+  }
+}
+
+/**
+ * Build the variants record for one model.
+ * Dedup invariant: if two levels produce byte-identical bodies, keep the
+ * higher-level name so /models never shows two identical variants.
+ */
+export function buildVariants(
+  format: Format,
+  caps: Capabilities,
+  modelId: string,
+): Record<string, Body> {
+  const levels = resolveLevels(format, caps, modelId)
+  if (levels.length === 0) return {}
+  const out: Record<string, Body> = {}
+  const seen = new Map<string, EffortLevel>()
+  for (const level of levels) {
+    const body = levelToBody(format, level, caps, modelId)
+    const key = JSON.stringify(body)
+    const dup = seen.get(key)
+    if (dup !== undefined) {
+      // identical body already emitted at a lower level -> drop this one
+      continue
+    }
+    seen.set(key, level)
+    out[level] = body
+  }
+  return out
+}
+
+/** Classify a 9Router model id + thinkingFormat into our Format union. */
+export function classifyFormat(
+  thinkingFormat: string | null | undefined,
+  modelId: string,
+  reasoning = false,
+): Format {
+  switch (thinkingFormat) {
+    case "openai":
+      return "openai"
+    case "zai":
+      return "zai"
+    case "deepseek":
+      return "deepseek"
+    case "kimi":
+      return "kimi"
+    case "minimax":
+      return "minimax"
+    case "qwen":
+      return "qwen"
+    default: {
+      // null format + reasoning: upstream is OpenAI-compatible (ollama,
+      // generic gateways) and reads reasoning_effort. Non-reasoning models
+      // must stay "none" or buildVariants would emit thinking bodies for
+      // models that reject them.
+      if (!thinkingFormat || !reasoning) {
+        if (!reasoning) return "none"
+        const id = modelId.toLowerCase()
+        if (
+          id.includes("claude") ||
+          id.includes("gemini") ||
+          id.includes("o1") ||
+          id.includes("o3") ||
+          id.includes("o4")
+        ) {
+          return "budget"
+        }
+        return "openai"
+      }
+      return "none"
+    }
+  }
+}