model-compare-opencode-plugin 0.5.0 → 0.6.0

package/README.md

@@ -10,7 +10,7 @@ Each priority is a live alias inside the existing OpenRouter provider — no new
 | `openrouter/model-compare/price` | best price pick |
 | `openrouter/model-compare/quality` | best quality pick |
 
-The alias re-points at the current pick while OpenCode runs (refresh every 30 minutes, data cache 6 hours). OpenCode's model picker shows it as `Model Compare: <priority> → <pick>`, with `(fallback)` or `(unavailable)` when the fallback is serving or the alias is disabled.
+The alias re-points at the current pick while OpenCode runs (refresh every 30 minutes, data cache 6 hours). It also pins the catalog's scored reasoning effort on each request, so the model runs at the depth its `quality` score was measured at. OpenCode's model picker shows it as `Model Compare: <priority> → <pick> · <effort> [alt <effort> <index>]`, with `(fallback)` while the fallback is serving, `(unavailable)` when the alias is disabled, and the `alt` part naming the best measured effort above the current one that OpenRouter can actually select.
 
 
 ## Install
@@ -69,7 +69,7 @@ opencode run --model "openrouter/model-compare/price" "msg"
 Commands:
 
 - `/use-best [priority]` — switch the session to `openrouter/model-compare/<p>` (defaults to `defaultPriority`). Refuses a disabled alias.
-- `/model-compare` — top 5 per priority with scores and data age; priorities whose `weights` override actually takes effect are labelled `(custom weights)` with recomputed scores, and each alias's current pick is marked `← current pick`. The output is a synthetic message (`resume: false`): it costs no model turn and, in a headless session, surfaces in the transcript at the next turn. In the TUI it opens the report dialog instead.
+- `/model-compare` — top 5 per priority with scores and data age; each line also shows the reasoning effort behind `quality` (`· high`) and the best selectable measured alternative (`· alt max 56.0`). Priorities whose `weights` override actually takes effect are labelled `(custom weights)` with recomputed scores, and each alias's current pick is marked `← current pick`. The output is a synthetic message (`resume: false`): it costs no model turn and, in a headless session, surfaces in the transcript at the next turn. In the TUI it opens the report dialog instead, with `effort` and `alt` columns.
 
 
 ### Keyboard shortcuts
@@ -85,7 +85,7 @@ Commands:
 
 Both dialogs open anywhere — including the opening screen, where no session exists yet. There, picking a row (a priority in the picks dialog, a model in the report) creates a new session already bound to that model and opens it; merely opening a dialog never creates a session. With a session open, a pick switches that session as before. The TUI has no `/use-best` keybinding: the slash command already covers switching.
 
-Status: the footer shows `MC: balanced → <pick>` (balanced only — `disabled`/`unavailable`/`(fallback)` as applicable; all three priorities live in the picks dialog). Toasts announce `/use-best` outcomes and pick changes (never for the first observation after load), the `alt+e` served endpoint, and the cannot-steer notice — see [Steering and served endpoints](#steering-and-served-endpoints). Headless, command feedback is synthetic transcript messages at the next turn; the steering toasts have no headless surface.
+Status: the footer shows `MC: balanced → <pick>` (balanced only — `disabled`/`unavailable`/`(fallback)` as applicable; all three priorities live in the picks dialog). The picker's alias name carries the effort and alternative; the footer stays a compact served-model line. Toasts announce `/use-best` outcomes and pick changes (never for the first observation after load), the `alt+e` served endpoint, and the cannot-steer notice — see [Steering and served endpoints](#steering-and-served-endpoints). Headless, command feedback is synthetic transcript messages at the next turn; the steering toasts have no headless surface.
 
 
 ## Configuration
@@ -155,18 +155,18 @@ The alt+e capture is best-effort by design, and alias-scoped: only a session who
 
 The last validated catalog is persisted, so ranking and `/model-compare` work offline after a restart. The cache is keyed by source (URL or script path), so changing the source never serves the previous source's data. Script exit code 2 means "no candidates" *or* an argparse usage error — never read it as "no candidates" alone.
 
-**Vendored pin:** `vendor/model_compare.py` is byte-identical to upstream `v0.5.0` (`vendor/UPSTREAM.json` records repo, tag, commit, sha256). The catalog is schema v4 (since upstream 0.5.0): v3's `pricing` tier/schedule structure and published ranking `parameters.weights` are unchanged, and v4 adds per-model quality provenance (`quality_as_of`, `quality_drift`) plus a reshaped `sources.aa` block — nothing `validateCatalog` reads changed shape. The plugin accepts schema v4 ONLY — `validateCatalog` rejects anything else — and releases are gated on the live remote serving v4 (the release-gate check pipes `https://model-compare.dev/catalog.json` through `scripts/canary-check.mjs`, which fails closed when the served document is not the expected schema). Effective-tier pricing semantics still apply: `pricing` scalars hold effective-tier values — the tier in effect at 1M-token prompts — so models with OpenRouter price overrides are ranked at what a long session actually pays.
+**Vendored pin:** `vendor/model_compare.py` is byte-identical to upstream `v0.6.0` (`vendor/UPSTREAM.json` records repo, tag, commit, sha256). The catalog is schema v5 (since upstream 0.6.0): `quality` is the AA intelligence index at the model's effective OpenRouter default reasoning effort, and every entry carries `quality_effort` plus a `reasoning` block (`default_effort`, the expanded `supported_efforts`, the raw flags, and the measured `depths` with AA `$/task`). The plugin accepts schema v5 ONLY — `validateCatalog` rejects anything else — and releases are gated on the live remote serving v5 (the release-gate check pipes `https://model-compare.dev/catalog.json` through `scripts/canary-check.mjs`, which fails closed when the served document is not the expected schema). Each alias request pins exactly the pick's `quality_effort` in its body (`reasoning: { effort }`), so the alias runs at the depth its score represents; an explicit `#variant` selection, or a body that already sets `reasoning`/`reasoning_effort`, wins and is never overwritten. The catalog's `reasoning` sentinel is display-only and never sent to the gateway. Effective-tier pricing semantics still apply: `pricing` scalars hold effective-tier values — the tier in effect at 1M-token prompts — so models with OpenRouter price overrides are ranked at what a long session actually pays.
 
-**Vendored 0.5.0 cold-cache network profile:** since 0.4.0 the vendored script performs per-model endpoint-pricing fetches when building a fresh catalog (74 candidates in the recorded run). Each fetch fails closed per model — after the script's internal retries, a failed endpoint fetch drops that model and the catalog shrinks silently (429-class responses raise without retry) — so a degraded network costs pool coverage, not pricing correctness. Since 0.5.0, unkeyed runs also hydrate quality from the published catalog (one fetch of `https://model-compare.dev/catalog.json`, cached under `published-catalog`; keyed runs consult the AA API — now the primary quality source — and never fetch the published catalog); every quality hydration fails closed to "no quality data" per model. A cold cache under a slow network can exceed the plugin's 60-second local budget, in which case the plugin warns and falls back (`auto` → remote, `local` → its cached document).
+**Vendored 0.6.0 cold-cache network profile:** since 0.4.0 the vendored script performs per-model endpoint-pricing fetches when building a fresh catalog (76 candidates in the recorded run). Each fetch fails closed per model — after the script's internal retries, a failed endpoint fetch drops that model and the catalog shrinks silently (429-class responses raise without retry) — so a degraded network costs pool coverage, not pricing correctness. Unkeyed runs hydrate quality from the published catalog (one fetch of `https://model-compare.dev/catalog.json`, cached under `published-catalog`; keyed runs consult the AA API — the primary quality source — and never fetch the published catalog); every quality hydration fails closed to "no quality data" per model, and a missing record at the selected effort shows `-` rather than borrowing another effort's score. A cold cache under a slow network can exceed the plugin's 60-second local budget, in which case the plugin warns and falls back (`auto` → remote, `local` → its cached document).
 
 **Upgrading the pin** — reviewed PRs only; nothing merges automatically:
 
 1. `node scripts/sync-vendor.mjs <tag>` — fetches the script at that commit, reports the sha256 change, re-pins `UPSTREAM.json`, prints the matching CHANGELOG section (`--check` verifies offline).
-2. Conformance tests check `--version`, schema v4, required fields, recomputed `overall` scores, and the standard-library-only import allowlist.
+2. Conformance tests check `--version`, schema v5, required fields, recomputed `overall` scores, and the standard-library-only import allowlist.
 3. The upgrade PR body lists script lines touching imports, URLs, environment variables, subprocess calls and file writes, for reviewer attention.
 4. Release with a changelog line naming the upstream tag; users run `opencode plugin update` (OpenCode checks but doesn't apply).
 
-A scheduled workflow opens a draft upgrade PR when upstream publishes a newer release (never a downgrade); a nightly canary exercises the vendored script against live upstream data and asserts the generated catalog is schema v4 (`scripts/canary-check.mjs` pins `EXPECTED_SCHEMA_VERSION = 4` and exits nonzero on any other version); releases additionally gate on the live remote itself (see the publishing gates below); a weekly drift check compares the vendored sha256 against upstream's pinned commit and the published rankings against the published scores.
+A scheduled workflow opens a draft upgrade PR when upstream publishes a newer release (never a downgrade); a nightly canary exercises the vendored script against live upstream data and asserts the generated catalog is schema v5 (`scripts/canary-check.mjs` pins `EXPECTED_SCHEMA_VERSION = 5` and exits nonzero on any other version); releases additionally gate on the live remote itself (see the publishing gates below); a weekly drift check compares the vendored sha256 against upstream's pinned commit and the published rankings against the published scores.
 
 
 ## Troubleshooting
@@ -210,7 +210,7 @@ MC_INTEGRATION=1 npx vitest run tests/integration/    # live-server suite (opt-i
 - The integration files skip unless `MC_INTEGRATION=1`, so plain `npm test` stays hermetic. The suite drives a real `opencode serve` on 127.0.0.1:14721 and needs the `opencode` CLI and `python3` (skips cleanly when either is missing); one case needs network access and the `sqlite3` CLI.
 - `node scripts/pack-smoke.mjs` (also in CI, after `node scripts/build-tui.mjs`) packs the plugin and checks the tarball against the packaging list (files, `exports`, relative imports, and that the TUI artifact is precompiled — no react import). It does **not** load the package in OpenCode — install the tarball into a scratch project and confirm OpenCode loads it before publishing.
 - Publishing: cut a GitHub release tagged `vX.Y.Z` and `.github/workflows/release.yaml` stages the package on npm through trusted publishing (tokenless OIDC — no token secret; the npmjs.com trusted-publisher entry must name `release.yaml`, the `canonical/model-compare-opencode-plugin` repository and the `release` environment, with "Allow npm publish" and "Allow npm dist-tag" unchecked — stage-only, npm's recommended posture). Nothing goes live until a maintainer approves it with 2FA on npmjs.com (package page → Staged Packages) or via `npm stage approve`. The workflow fails closed when the tag does not match `package.json`'s version, and the gates (build, typecheck, tests, pack-smoke, live-remote canary) run before staging.
-- `fixtures/catalog-v0.5.0.json` is the sole contract fixture — a recorded schema-v4 catalog; `fixtures/catalog-no-quality.json` is derived from it by `scripts/make-no-quality-fixture.py` (the vendored script's own quality-blind weights, so its scores are internally consistent). No pre-v4 fixture exists; the v4-only gate rejects one. `node scripts/sync-vendor.mjs --check` verifies the pin's sha256 offline.
+- `fixtures/catalog-v0.6.0.json` is the sole contract fixture — a recorded schema-v5 catalog; `fixtures/catalog-no-quality.json` is derived from it by `scripts/make-no-quality-fixture.py` (the vendored script's own quality-blind weights, so its scores are internally consistent). No pre-v5 fixture exists; the v5-only gate rejects one. `node scripts/sync-vendor.mjs --check` verifies the pin's sha256 offline.
 - Repo layout: `src/core/` (pure ranking/pinning), `src/sources/` (local + remote acquisition), `src/opencode/` (aliases, guard, commands, storage, refresh), `dist/` (generated `tui.js` artifact, gitignored), `vendor/` (pinned upstream script), `tests/{unit,conformance,integration}`.
 
 

package/dist/tui.js

@@ -157,6 +157,8 @@ function toReportEntries(raw) {
       value: entry.value,
       score: typeof entry.score === "string" ? entry.score : "-",
       quality: typeof entry.quality === "string" ? entry.quality : "-",
+      effort: typeof entry.effort === "string" ? entry.effort : "",
+      alternative: typeof entry.alternative === "string" ? entry.alternative : "",
       price: typeof entry.price === "string" ? entry.price : "-",
       current: entry.current === true,
       fromFallback: entry.fromFallback === true
@@ -708,8 +710,15 @@ export default Plugin.define({
       const labels = data.entries.map(entry => `${entry.rank === null ? "·" : entry.rank}. ${entry.id}${entry.fromFallback ? " (fallback)" : ""}`);
       const labelOf = new Map(data.entries.map((entry, index) => [entry, labels[index]]));
       const colW = (values, floor, cap) => Math.min(cap, Math.max(floor, ...values.map(value => value.length)));
-      const qualW = colW(data.entries.map(entry => entry.quality), "qual".length, 8);
-      const priceW = colW(data.entries.map(entry => entry.price), "$ in/out".length, 16);
+      // Quality is a one-decimal AA index (max "100.0"); the caps leave the
+      // 52-char row budget intact (see `fixed` below) while fitting real
+      // values: "minimal" (effort), "minimal 100.0" (alt), "10.00/100.00".
+      const qualW = colW(data.entries.map(entry => entry.quality), "qual".length, 5);
+      // Catalog v5: the effort the quality was measured at and the best
+      // selectable measured alternative ("max 56.0"). A missing value is "-".
+      const effortW = colW(data.entries.map(entry => entry.effort || "-"), "effort".length, 7);
+      const altW = colW(data.entries.map(entry => entry.alternative || "-"), "alt".length, 13);
+      const priceW = colW(data.entries.map(entry => entry.price), "$ in/out".length, 13);
       // A cell wider than its clamped column is truncated to fit.
       const cell = (value, width) => value.length > width ? value.slice(0, width - 1) + "…" : value;
       // Prices use padEnd (not padStart): padded to a common width the
@@ -717,10 +726,13 @@ export default Plugin.define({
       // stays exactly 2 (padStart pushed each value right by its slack).
       // The default dialog is 60 wide: 2 list insets + 6 row insets leave 52
       // for row content; the header shares that budget (plus its 3-indent).
-      const fixed = 2 + qualW + 2 + priceW;
-      const nameW = Math.max(8, Math.min(52 - fixed, Math.max(...labels.map(label => label.length))));
+      // Column caps keep the budget even for hostile strings: 5+7+13+13 plus
+      // the four 2-char paddings and the 2-char row indent = 46, leaving the
+      // name floor of 6 (the name column shrinks first for real content).
+      const fixed = 2 + qualW + 2 + effortW + 2 + altW + 2 + priceW;
+      const nameW = Math.max(6, Math.min(52 - fixed, Math.max(...labels.map(label => label.length))));
       const trim = label => label.length > nameW ? label.slice(0, nameW - 1) + "…" : label;
-      const headerLine = "   " + " ".repeat(nameW) + "  " + "qual".padStart(qualW) + "  " + "$ in/out".padEnd(priceW);
+      const headerLine = "   " + " ".repeat(nameW) + "  " + "qual".padStart(qualW) + "  " + "effort".padStart(effortW) + "  " + "alt".padEnd(altW) + "  " + "$ in/out".padEnd(priceW);
       const rows = [{
         label: "",
         headerLine
@@ -735,7 +747,7 @@ export default Plugin.define({
         for (const entry of section) {
           rows.push({
             label: trim(labelOf.get(entry) ?? "").padEnd(nameW),
-            columns: "  " + cell(entry.quality, qualW).padStart(qualW) + "  " + cell(entry.price, priceW).padEnd(priceW),
+            columns: "  " + cell(entry.quality, qualW).padStart(qualW) + "  " + cell(entry.effort || "-", effortW).padStart(effortW) + "  " + cell(entry.alternative || "-", altW).padEnd(altW) + "  " + cell(entry.price, priceW).padEnd(priceW),
             // F-20 id split: the row DISPLAYS the sanitized id (in `label`)
             // but picks `value`, the raw catalog id switchToModel needs.
             value: entry.value,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "model-compare-opencode-plugin",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "OpenCode plugin that switches OpenRouter model aliases to the best value-for-money pick from canonical/model-compare's ranking (balanced, price, quality).",
   "keywords": [
     "opencode",

package/src/core/catalog.ts

@@ -1,9 +1,16 @@
 // src/core/catalog.ts
-// Catalog document validation (design §5). Accepts schema v4 documents (only) from
+// Catalog document validation (design §5). Accepts schema v5 documents (only) from
 // either source (vendored script or remote catalog) and projects them onto
 // the plugin's Catalog type. Validation only — ranking lives elsewhere.
 
-import type { Catalog, ModelEntry, Priority, Weights } from "./types"
+import type {
+  Catalog,
+  ModelEntry,
+  Priority,
+  Reasoning,
+  ReasoningDepth,
+  Weights,
+} from "./types"
 
 const PRIORITIES: readonly Priority[] = ["balanced", "price", "quality"]
 const SCORE_KEYS = ["quality", "price", "context", "age"] as const
@@ -44,18 +51,67 @@ function steer(raw: unknown): ModelEntry["steering"] {
   return steering
 }
 
+function finiteOrNull(value: unknown): number | null {
+  return typeof value === "number" && Number.isFinite(value) ? value : null
+}
+
+function stringOrNull(value: unknown): string | null {
+  return typeof value === "string" ? value : null
+}
+
+function boolOrNull(value: unknown): boolean | null {
+  return typeof value === "boolean" ? value : null
+}
+
+// The v5 reasoning block (display + request injection). Field-by-field
+// projection, never a spread of the raw object: a hostile catalogURL serves
+// arbitrary JSON here, and only the fields the plugin reads survive. A
+// non-object block reads as absent; a malformed field reads as its neutral
+// value (empty list / null) rather than rejecting the whole catalog — the
+// block is advisory metadata, not ranking input. Depth records without a
+// non-empty string effort are dropped; every other depth field is nullable.
+function projectReasoning(raw: unknown): Reasoning | undefined {
+  if (!isObject(raw)) return undefined
+  const supported =
+    Array.isArray(raw.supported_efforts) && raw.supported_efforts.every((effort) => typeof effort === "string")
+      ? [...(raw.supported_efforts as string[])]
+      : []
+  const depths: ReasoningDepth[] = []
+  if (Array.isArray(raw.depths)) {
+    for (const record of raw.depths) {
+      if (!isObject(record)) continue
+      if (typeof record.effort !== "string" || record.effort === "") continue
+      depths.push({
+        effort: record.effort,
+        index: finiteOrNull(record.index),
+        cost_per_task_usd: finiteOrNull(record.cost_per_task_usd),
+        source: stringOrNull(record.source),
+        as_of: stringOrNull(record.as_of),
+      })
+    }
+  }
+  return {
+    default_effort: stringOrNull(raw.default_effort),
+    supported_efforts: supported,
+    default_enabled: boolOrNull(raw.default_enabled),
+    mandatory: boolOrNull(raw.mandatory),
+    supports_max_tokens: boolOrNull(raw.supports_max_tokens),
+    depths,
+  }
+}
+
 export function validateCatalog(
   raw: unknown,
 ): { ok: true; catalog: Catalog } | { ok: false; reason: string } {
   if (!isObject(raw)) return { ok: false, reason: "catalog must be a JSON object" }
 
-  // Supported schema: v4 only — upstream's current contract (0.5.0's
-  // schema_version 4). The v4 changes are additive provenance (per-model
-  // quality_as_of/quality_drift, a reshaped sources.aa block) and change
-  // nothing this validator reads; every other version is rejected with the
-  // reason string the canary and the stored-document path rely on.
-  if (raw.schema_version !== 4) {
-    return { ok: false, reason: `schema_version must be 4, got ${JSON.stringify(raw.schema_version)}` }
+  // Supported schema: v5 only — upstream's current contract (0.6.0's
+  // schema_version 5). v5 changes the meaning of `quality` (the AA score at
+  // the selected/default reasoning effort) and adds per-model
+  // `quality_effort` and `reasoning`; every other version is rejected with
+  // the reason string the canary and the stored-document path rely on.
+  if (raw.schema_version !== 5) {
+    return { ok: false, reason: `schema_version must be 5, got ${JSON.stringify(raw.schema_version)}` }
   }
   if (typeof raw.generated_at !== "string") {
     return { ok: false, reason: "generated_at must be a string" }
@@ -160,12 +216,17 @@ export function validateCatalog(
     const input = pricing.input_per_1m
     const output = pricing.output_per_1m
     // The steering block projects (or reads as absent) per the steer() rules.
-    // The assignment sits AFTER the spread so it explicitly overrides the raw
-    // block that `...entry` would otherwise carry through verbatim — a
-    // hostile steering block must never survive onto the projected entry.
+    // The v5 quality_effort/reasoning fields project the same way: strip the
+    // raw keys before the spread so the camelCase projection is the only
+    // representation on the entry (a hostile block never survives verbatim).
+    const { steering: _rawSteering, quality_effort: _rawQualityEffort, reasoning: _rawReasoning, ...passthrough } =
+      entry
     const steering = steer(entry.steering)
+    const qualityEffort =
+      typeof entry.quality_effort === "string" && entry.quality_effort !== "" ? entry.quality_effort : null
+    const reasoning = projectReasoning(entry.reasoning)
     models.push({
-      ...entry,
+      ...passthrough,
       id: entry.id,
       name: entry.name,
       pricing: {
@@ -177,6 +238,8 @@ export function validateCatalog(
       context: entry.context,
       scores: { ...components, overall },
       quality,
+      qualityEffort,
+      reasoning,
       steering,
     })
   }
@@ -220,14 +283,33 @@ export function validateStoredCatalog(
   stored: unknown,
 ): { ok: true; catalog: Catalog } | { ok: false; reason: string } {
   if (!isObject(stored)) return { ok: false, reason: "stored catalog must be an object" }
+  // v5 projections always carry qualityEffort (null or a string). A record
+  // written by a pre-v5 plugin lacks it: accepting it would mix v4's max-row
+  // quality with v5's default-effort semantics, so it is a cache miss.
+  if (Array.isArray(stored.models)) {
+    for (const [i, entry] of stored.models.entries()) {
+      if (isObject(entry) && !Object.hasOwn(entry, "qualityEffort")) {
+        return { ok: false, reason: `models[${i}].qualityEffort is missing (not a v5 catalog)` }
+      }
+    }
+  }
   const models = Array.isArray(stored.models)
     ? stored.models.map((entry) => {
-        if (!isObject(entry) || entry.steering === undefined) return entry
-        return { ...entry, steering: { model: entry.id, provider: entry.steering } }
+        if (!isObject(entry)) return entry
+        // The projection renamed quality_effort to qualityEffort and unwrapped
+        // steering; rebuild the raw v5 shape. A hand-edited record re-projects
+        // (or reads as absent) exactly like a raw one would.
+        const raw: Record<string, unknown> = {
+          ...entry,
+          quality_effort: entry.qualityEffort ?? null,
+        }
+        if (entry.reasoning !== undefined) raw.reasoning = entry.reasoning
+        if (entry.steering !== undefined) raw.steering = { model: entry.id, provider: entry.steering }
+        return raw
       })
     : stored.models
   return validateCatalog({
-    schema_version: 4,
+    schema_version: 5,
     generated_at: stored.generatedAt,
     parameters: { weights: stored.weights },
     models,

package/src/core/reasoning.ts

@@ -0,0 +1,96 @@
+// src/core/reasoning.ts
+// Reasoning-depth helpers (catalog v5): gateway-effort validation, the
+// selectable-depth rule, and the best measured alternative to the effort a
+// model was scored at. Pure functions over a projected ModelEntry — no I/O,
+// no OpenCode imports.
+//
+// The selectable rule is upstream's site rule (web/site/app.js depthRows):
+// OpenRouter can select an effort only when the model's expanded
+// `supported_efforts` lists it (or the model is a single-state toggle that
+// exposes `#none`). An AA row for an unlisted effort is display-only and is
+// never advertised as an alternative. The catalog's `reasoning` sentinel is a
+// producer label for a single-state reasoning model, not a gateway value.
+
+import type { ModelEntry, Reasoning } from "./types"
+
+// What OpenRouter accepts as a discrete effort. Mirrors upstream's
+// REASONING_GATEWAY_EFFORTS. Deliberately excludes the catalog sentinels
+// "reasoning" and "default".
+export const GATEWAY_EFFORTS = ["max", "xhigh", "high", "medium", "low", "minimal", "none"] as const
+
+// Deepest-first display order, mirroring upstream's AA_EFFORT_ORDER.
+const EFFORT_ORDER: readonly string[] = [...GATEWAY_EFFORTS, "reasoning"]
+
+export function gatewayEffort(value: string | null | undefined): string | null {
+  return value !== null && value !== undefined && (GATEWAY_EFFORTS as readonly string[]).includes(value)
+    ? value
+    : null
+}
+
+function effortOrder(effort: string): number {
+  const index = EFFORT_ORDER.indexOf(effort)
+  return index === -1 ? EFFORT_ORDER.length : index
+}
+
+// Upstream's v5 non-reasoning rule (the producer's is_reasoning flag is not
+// published): no reasoning metadata at all, so the bare id is the only form.
+function isNonReasoningBlock(reasoning: Reasoning): boolean {
+  return (
+    reasoning.default_effort === "none" &&
+    reasoning.default_enabled !== false &&
+    reasoning.mandatory !== true &&
+    reasoning.supports_max_tokens !== true
+  )
+}
+
+// A single-state reasoning model with reasoning off by default exposes only
+// the "#none" toggle.
+function isSingleStateToggle(reasoning: Reasoning): boolean {
+  return reasoning.mandatory !== true && reasoning.default_enabled === false
+}
+
+export function isSelectableDepth(model: ModelEntry, effort: string): boolean {
+  if (effort === "reasoning") return false
+  const reasoning = model.reasoning
+  if (reasoning === undefined) return false
+  if (reasoning.supported_efforts.includes(effort)) return true
+  if (effort !== "none" || reasoning.supported_efforts.length > 0) return false
+  if (isNonReasoningBlock(reasoning)) return false
+  return isSingleStateToggle(reasoning)
+}
+
+export type DepthAlternative = {
+  effort: string
+  index: number
+  cost: number | null
+}
+
+// The best measured, selectable effort that scores strictly higher than the
+// effort `quality` already represents. Unselectable rows never qualify; ties
+// resolve to the deeper effort (the display order).
+export function bestDepthAlternative(model: ModelEntry): DepthAlternative | null {
+  const base = model.quality
+  const selected = model.qualityEffort
+  const reasoning = model.reasoning
+  if (base == null || selected == null || reasoning === undefined) return null
+
+  const depths = [...reasoning.depths].sort((a, b) => effortOrder(a.effort) - effortOrder(b.effort))
+  let best: DepthAlternative | null = null
+  for (const depth of depths) {
+    if (depth.index === null || depth.effort === selected) continue
+    if (!isSelectableDepth(model, depth.effort)) continue
+    if (depth.index <= base) continue
+    if (best === null || depth.index > best.index) {
+      best = { effort: depth.effort, index: depth.index, cost: depth.cost_per_task_usd }
+    }
+  }
+  return best
+}
+
+// The report's compact alternative label: "<effort> <index>" ("max 56.0"),
+// the same shape upstream's site shows under QUAL. Empty when there is none.
+export function formatDepthAlternative(model: ModelEntry | undefined): string {
+  if (model === undefined) return ""
+  const best = bestDepthAlternative(model)
+  return best === null ? "" : `${best.effort} ${best.index.toFixed(1)}`
+}

package/src/core/steering.ts

@@ -12,6 +12,7 @@
 // and the steeringFor cases here); a semantic change to one must be mirrored
 // in the other.
 
+import { gatewayEffort } from "./reasoning"
 import type { ModelEntry, Priority } from "./types"
 
 // A model reference as the hook event carries it (`event.model`), mirroring
@@ -75,6 +76,30 @@ export function steeringFor(
   return models.get(pick.id)?.steering ?? null
 }
 
+// The reasoning effort an alias request must pin, or null when it must not:
+// the same alias/body/pick/model gates as steeringFor, plus the explicit
+// variant rule. `#variant` is OpenCode's per-request selection (the event
+// carries it on `model.variant`); "default" is the no-selection sentinel
+// OpenCode stamps on `--model` refs (spike fact 1), so it does NOT count as an
+// explicit variant. The catalog's `quality_effort` is the effort the score was
+// measured at; the "reasoning" sentinel is a producer label and is never sent
+// to the gateway.
+export function reasoningEffortFor(
+  eventModel: ModelRef,
+  variant: string | undefined,
+  bodyModel: string | undefined,
+  picks: Partial<Record<Priority, AliasTarget>>,
+  models: Map<string, ModelEntry>,
+): string | null {
+  const p = aliasPriority(eventModel)
+  if (p === null) return null
+  if (variant !== undefined && variant !== "default") return null
+  const pick = picks[p]
+  if (pick === undefined || pick.id === null) return null
+  if (bodyModel !== undefined && bodyModel !== pick.id) return null
+  return gatewayEffort(models.get(pick.id)?.qualityEffort)
+}
+
 function isPlainObject(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null && !Array.isArray(value)
 }
@@ -103,6 +128,17 @@ export function injectSteering(body: unknown, steering: Steering): unknown {
   }
 }
 
+// The body with `reasoning: { effort }` added — or the input untouched when
+// it already carries `reasoning` or the legacy `reasoning_effort` field (an
+// explicit #variant, user config or another plugin wins; the plugin never
+// clobbers a reasoning choice it did not make) or is not a JSON object.
+// Reference inequality is the wiring's "re-create the Request" signal.
+export function injectReasoning(body: unknown, effort: string): unknown {
+  if (!isPlainObject(body)) return body
+  if (Object.hasOwn(body, "reasoning") || Object.hasOwn(body, "reasoning_effort")) return body
+  return { ...body, reasoning: { effort } }
+}
+
 // normalize_provider (vendor/model_compare.py): casefold the name and strip
 // ALL non-alphanumeric characters — "Z.AI", "z-ai" and "z ai" all normalize
 // to "zai". JS toLowerCase stands in for Python's casefold (provider display

package/src/core/types.ts

@@ -6,6 +6,31 @@ export type Priority = "balanced" | "price" | "quality"
 
 export type Weights = { quality: number; price: number; context: number; age: number }
 
+// One measured reasoning effort (catalog v5): the AA intelligence index at
+// that effort, AA's reference-price benchmark cost per task (display-only,
+// never scored), and the record's provenance. `null` marks a missing value;
+// the record itself survives so the effort can still be offered as a variant.
+export type ReasoningDepth = {
+  effort: string
+  index: number | null
+  cost_per_task_usd: number | null
+  source: string | null
+  as_of: string | null
+}
+
+// The v5 per-model reasoning block. `supported_efforts` is what OpenRouter
+// accepts as a discrete effort (expanded upstream, never null); `depths` is
+// what some source measured (empty when nothing did). The raw flags are kept
+// for provenance and for the single-state/non-reasoning display rules.
+export type Reasoning = {
+  default_effort: string | null
+  supported_efforts: string[]
+  default_enabled: boolean | null
+  mandatory: boolean | null
+  supports_max_tokens: boolean | null
+  depths: ReasoningDepth[]
+}
+
 export type ModelEntry = {
   id: string
   name: string
@@ -20,6 +45,14 @@ export type ModelEntry = {
   }
   context: number
   quality: number | null
+  // The effort `quality` was measured at (catalog v5 `quality_effort`). The
+  // alias request pins exactly this effort; the sentinel "reasoning" is a
+  // catalog label, never a gateway value. Optional only for hand-built /
+  // legacy projected entries: validateCatalog always writes it (null or a
+  // string), and validateStoredCatalog requires it on cached records.
+  qualityEffort?: string | null
+  // Present when the raw block projects cleanly (absent stays absent).
+  reasoning?: Reasoning
   // The steering block (F-11/F-12): upstream records the provider's
   // endpoint-routing hints as { model, provider: { order, ignore,
   // quantizations?, allow_fallbacks } }; the projection unwraps the provider
@@ -47,7 +80,7 @@ export type Catalog = {
   models: ModelEntry[]
 }
 
-// Upstream.s PRIORITY_WEIGHTS at the pinned tag (v0.5.0; unchanged since v0.3.0). Used when a
+// Upstream's PRIORITY_WEIGHTS at the pinned tag (v0.6.0; unchanged since v0.3.0). Used when a
 // document carries no `parameters.weights` at all (design §5); individual
 // missing keys fall back to weight 0 instead.
 export const DEFAULT_WEIGHTS: Record<Priority, Weights> = {

package/src/index.ts

@@ -19,7 +19,13 @@ import { parseConfig } from "./config"
 import { pinKey, type Pin } from "./core/pins"
 import { effectiveWeights, rankModels } from "./core/rank"
 import type { Catalog, EndpointCapture, ModelEntry, Priority, Sourced } from "./core/types"
-import { captureEndpoint, injectSteering, steeringFor } from "./core/steering"
+import {
+  captureEndpoint,
+  injectReasoning,
+  injectSteering,
+  reasoningEffortFor,
+  steeringFor,
+} from "./core/steering"
 import { formatReport, humanizeAge, reportEntries, steeringNote } from "./opencode/commands"
 import { ModelCompare } from "./rpc"
 import { planAlias, type AliasTarget } from "./opencode/aliases"
@@ -329,7 +335,11 @@ function applyAliases(state: WireState, editor: AliasEditor): void {
     // plan: planAlias only checks for undefined (it never reads model
     // internals — the applier does, below).
     const source = target.id === null ? undefined : editor.get(ALIAS_PROVIDER, target.id)
-    const plan = planAlias(p, target, source as unknown as ModelEntry | undefined)
+    // The concrete editor model proves presence; the catalog entry supplies
+    // the v5 effort/alternative labels (the editor model has no ranking data).
+    const catalogModel =
+      target.id === null ? undefined : state.sourced?.doc.models.find((entry) => entry.id === target.id)
+    const plan = planAlias(p, target, source as unknown as ModelEntry | undefined, catalogModel)
 
     if (plan.enabled && plan.modelID !== null && source !== undefined) {
       editor.update(ALIAS_PROVIDER, aliasId(p), (model) => {
@@ -558,21 +568,36 @@ export async function wire(ctx: PluginCtx, deps: WireDeps = {}): Promise<() => v
         state.appliedSteering[event.sessionID] = null
         return
       }
-      const steering = steeringFor(
+      const byId = new Map(
+        state.sourced.doc.models.map((entry): [string, ModelEntry] => [entry.id, entry]),
+      )
+      const bodyModel = bodyModelOf(body)
+      const steering = steeringFor(event.model, bodyModel, state.picks, byId)
+      // Two independent injections share one re-created Request: the
+      // provider-routing block and the catalog's scored reasoning effort.
+      // Each helper preserves a value the body already sets, so an explicit
+      // #variant (either signalled by the event's variant or by the body's
+      // own reasoning field) wins without withholding the other block.
+      let modified: unknown = body
+      let providerApplied = false
+      if (steering !== null) {
+        const next = injectSteering(modified, steering)
+        if (next !== modified) {
+          modified = next
+          providerApplied = true
+        }
+      }
+      const effort = reasoningEffortFor(
         event.model,
-        bodyModelOf(body),
+        event.model.variant,
+        bodyModel,
         state.picks,
-        new Map(state.sourced.doc.models.map((entry): [string, ModelEntry] => [entry.id, entry])),
+        byId,
       )
-      if (steering === null) {
-        // No steering data for the pick: untouched, fail open.
-        state.appliedSteering[event.sessionID] = null
-        return
-      }
-      const modified = injectSteering(body, steering)
+      if (effort !== null) modified = injectReasoning(modified, effort)
       if (modified === body) {
-        // The body already carries a `provider` key (or is not an object):
-        // never clobber routing the user or a provider configured.
+        // Neither block had anything to add: no steering data, no scored
+        // effort, or the body already carries the corresponding field.
         state.appliedSteering[event.sessionID] = null
         return
       }
@@ -592,7 +617,9 @@ export async function wire(ctx: PluginCtx, deps: WireDeps = {}): Promise<() => v
       })
       // Record the order actually applied — the response hook reads it as
       // captureEndpoint's order (the `!` flag fires only on a non-empty one).
-      state.appliedSteering[event.sessionID] = steering.order
+      // A reasoning-only injection (or a body that already carried routing)
+      // applies no routing, so the record is null.
+      state.appliedSteering[event.sessionID] = providerApplied ? steering!.order : null
     } catch {
       // Fail open: any error leaves the original request proceeding
       // untouched, and records that nothing was injected.