Merge pull request #224 from MadAppGang/jack-rudenko/route-reasoning-mode-client-20260828

fix: consume per-route reasoning mode capability

Author: erudenko

packages/cli/src/adapters/model-catalog.ts

@@ -10,6 +10,7 @@
  * constraints, not model metadata.
  */
 
+import type { ReasoningModeCapabilities } from "../model-loader.js";
 import {
   type ModelEndpoint,
   type ReasoningCapability,
@@ -24,6 +25,7 @@ export type {
   ReasoningControl,
   RouteVariant,
 } from "../providers/all-models-cache.js";
+export type { ReasoningModeCapabilities } from "../model-loader.js";
 
 export interface ModelEntry {
   /** Model ID as stored in the slim catalog (not lowercased) */
@@ -117,6 +119,23 @@ export function lookupModelRouteVariant(
   return findCacheEntry(modelId, cachePath)?.routeVariant;
 }
 
+/**
+ * `reasoning.mode` support for the exact route selected by `provider`.
+ *
+ * The same base model can support the parameter on one host, reject it on a
+ * second, and remain unverified on a third. Never fall back to model-level
+ * reasoning metadata or another aggregator row.
+ */
+export function lookupRouteReasoningMode(
+  modelId: string,
+  provider: string,
+  cachePath?: string
+): ReasoningModeCapabilities | undefined {
+  return findCacheEntry(modelId, cachePath)?.aggregators?.find(
+    (aggregator) => aggregator.provider === provider
+  )?.reasoning?.mode;
+}
+
 /**
  * The default preset variant for a family on a given provider, if the catalog
  * knows one.

packages/cli/src/adapters/variant-presets.test.ts

@@ -3,7 +3,7 @@ import { mkdtempSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { writeAllModelsCache } from "../providers/all-models-cache.js";
-import { lookupVariantPresets } from "./model-catalog.js";
+import { lookupRouteReasoningMode, lookupVariantPresets } from "./model-catalog.js";
 
 const BASE_MODEL_ID = "gpt-5.6-sol";
 const VARIANT_MODEL_ID = "gpt-5.6-sol-pro";
@@ -19,6 +19,37 @@ beforeEach(() => {
   writeAllModelsCache(
     {
       entries: [
+        {
+          modelId: BASE_MODEL_ID,
+          aliases: ["openai/gpt-5.6-sol"],
+          sources: {},
+          aggregators: [
+            {
+              provider: "openai",
+              externalId: BASE_MODEL_ID,
+              confidence: "api_official",
+              reasoning: {
+                mode: {
+                  status: "supported",
+                  values: ["standard", "pro"],
+                  default: "standard",
+                },
+              },
+            },
+            {
+              provider: "openai-codex",
+              externalId: BASE_MODEL_ID,
+              confidence: "gateway_official",
+              reasoning: { mode: { status: "rejected" } },
+            },
+            {
+              provider: "opencode-zen",
+              externalId: BASE_MODEL_ID,
+              confidence: "gateway_official",
+              reasoning: { mode: { status: "unknown" } },
+            },
+          ],
+        },
         {
           modelId: VARIANT_MODEL_ID,
           aliases: [],
@@ -59,3 +90,20 @@ describe("lookupVariantPresets", () => {
     expect(lookupVariantPresets("openai/gpt-5.6-terra", PROVIDER, cachePath)).toEqual([]);
   });
 });
+
+describe("lookupRouteReasoningMode", () => {
+  test("returns the selected route's typed mode fact only", () => {
+    expect(lookupRouteReasoningMode("openai/gpt-5.6-sol", "openai", cachePath)).toEqual({
+      status: "supported",
+      values: ["standard", "pro"],
+      default: "standard",
+    });
+    expect(lookupRouteReasoningMode(BASE_MODEL_ID, "openai-codex", cachePath)).toEqual({
+      status: "rejected",
+    });
+    expect(lookupRouteReasoningMode(BASE_MODEL_ID, "opencode-zen", cachePath)).toEqual({
+      status: "unknown",
+    });
+    expect(lookupRouteReasoningMode(BASE_MODEL_ID, "openrouter", cachePath)).toBeUndefined();
+  });
+});

packages/cli/src/model-loader.ts

@@ -69,6 +69,20 @@ export type ConfidenceTier =
   | "gateway_official"
   | "api_official";
 
+export type ReasoningModeCapabilities =
+  | {
+      status: "supported";
+      values: string[];
+      default?: string;
+    }
+  | {
+      status: "rejected" | "unknown";
+    };
+
+export interface RouteReasoningCapabilities {
+  mode?: ReasoningModeCapabilities;
+}
+
 /**
  * CLI-friendly aggregator entry — flattened view of `sources` keyed by the
  * canonical CLI provider name. Mirrors `AggregatorEntry` in
@@ -105,6 +119,8 @@ export interface AggregatorEntry {
    * `contextWindow`.
    */
   contextWindow?: number;
+  /** Reasoning behavior verified for this exact serving provider/model route. */
+  reasoning?: RouteReasoningCapabilities;
 }
 
 /**

packages/cli/src/session-events/pro-injection.test.ts

@@ -4,6 +4,7 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import type { Context } from "hono";
 import { ComposedHandler } from "../handlers/composed-handler.js";
+import type { ReasoningModeCapabilities } from "../model-loader.js";
 import { type SlimModelEntry, writeAllModelsCache } from "../providers/all-models-cache.js";
 import type { ProviderTransport } from "../providers/transport/types.js";
 import { SessionEventRegistry } from "./index.js";
@@ -61,6 +62,22 @@ function variantEntry(
   };
 }
 
+function routeCapabilityEntry(provider: string, mode: ReasoningModeCapabilities): SlimModelEntry {
+  return {
+    modelId: BASE_MODEL_ID,
+    aliases: [`openai/${BASE_MODEL_ID}`],
+    sources: {},
+    aggregators: [
+      {
+        provider,
+        externalId: BASE_MODEL_ID,
+        confidence: provider === "openai" ? "api_official" : "gateway_official",
+        reasoning: { mode },
+      },
+    ],
+  };
+}
+
 function writeCatalog(entries: SlimModelEntry[] = [variantEntry()]): void {
   writeAllModelsCache({ entries }, cachePath);
 }
@@ -99,12 +116,46 @@ describe("resolveVariantPreset", () => {
 
     expect(resolveVariantPreset(BASE_MODEL_ID, PROVIDER, cachePath)).toEqual({
       params: { reasoning: { mode: "pro" } },
-      variantModelId: VARIANT_MODEL_ID,
       provider: PROVIDER,
       preset: PRESET,
+      sourceLabel: `variant ${VARIANT_MODEL_ID} @ ${PROVIDER}`,
+    });
+  });
+
+  test("prefers supported typed route capability over the legacy variant fallback", () => {
+    makeHome();
+    writeCatalog([
+      routeCapabilityEntry("openai", {
+        status: "supported",
+        values: ["standard", "pro"],
+        default: "standard",
+      }),
+      variantEntry("openai"),
+    ]);
+
+    expect(resolveVariantPreset(BASE_MODEL_ID, "openai", cachePath)).toEqual({
+      params: { reasoning: { mode: "pro" } },
+      provider: "openai",
+      preset: PRESET,
+      sourceLabel: "route capability @ openai",
     });
   });
 
+  test("does not weaken explicit rejected or unknown route facts with a legacy variant", () => {
+    makeHome();
+    for (const status of ["rejected", "unknown"] as const) {
+      writeCatalog([routeCapabilityEntry("openai", { status }), variantEntry("openai")]);
+      expect(resolveVariantPreset(BASE_MODEL_ID, "openai", cachePath)).toBeUndefined();
+    }
+  });
+
+  test("requires pro to be an exact supported native value", () => {
+    makeHome();
+    writeCatalog([routeCapabilityEntry("openai", { status: "supported", values: ["standard"] })]);
+
+    expect(resolveVariantPreset(BASE_MODEL_ID, "openai", cachePath)).toBeUndefined();
+  });
+
   test("returns undefined when the variant belongs to a different provider", () => {
     makeHome();
     writeCatalog([variantEntry("openrouter")]);
@@ -248,10 +299,10 @@ describe("applyProInjection", () => {
 // ─── ComposedHandler wiring (step 5a-pre) ────────────────────────────────────
 
 /** Fake transport; the stubbed global fetch captures the final wire payload. */
-function makeTransport(): ProviderTransport {
+function makeTransport(provider = PROVIDER): ProviderTransport {
   return {
-    name: PROVIDER,
-    displayName: "OpenRouter",
+    name: provider,
+    displayName: provider,
     streamFormat: "openai-sse",
     getEndpoint: () => "http://localhost/v1/chat/completions",
     getHeaders: async () => ({}),
@@ -295,12 +346,20 @@ function makeClaudePayload(): Record<string, unknown> {
 function makeHandler(options: {
   proOnUltracode?: boolean;
   modelParams?: Record<string, unknown>;
+  provider?: string;
 }): ComposedHandler {
-  return new ComposedHandler(makeTransport(), `${PROVIDER}@${BASE_MODEL_ID}`, BASE_MODEL_ID, 8080, {
-    ...options,
-    sessionEventRegistry: registry,
-    catalogCachePath: cachePath,
-  });
+  const { provider = PROVIDER, ...handlerOptions } = options;
+  return new ComposedHandler(
+    makeTransport(provider),
+    `${provider}@${BASE_MODEL_ID}`,
+    BASE_MODEL_ID,
+    8080,
+    {
+      ...handlerOptions,
+      sessionEventRegistry: registry,
+      catalogCachePath: cachePath,
+    }
+  );
 }
 
 describe("ComposedHandler step 5a-pre wiring", () => {
@@ -314,6 +373,25 @@ describe("ComposedHandler step 5a-pre wiring", () => {
     expect(wire.body().reasoning?.mode).toBe("pro");
   });
 
+  test("typed OpenAI route support puts reasoning.mode=pro on the wire", async () => {
+    makeHome(FIXTURE_EFFORT_ULTRACODE_STDOUT, FIXTURE_ULTRA_EFFORT_ENTER);
+    writeCatalog([
+      routeCapabilityEntry("openai", {
+        status: "supported",
+        values: ["standard", "pro"],
+        default: "standard",
+      }),
+    ]);
+    const wire = stubFetchCapture();
+
+    await makeHandler({ proOnUltracode: true, provider: "openai" }).handle(
+      makeContext(),
+      makeClaudePayload()
+    );
+
+    expect(wire.body().reasoning?.mode).toBe("pro");
+  });
+
   test("ORDERING INVARIANT: swapping 5a-pre after 5a would override explicit --model-params", async () => {
     makeHome(FIXTURE_EFFORT_ULTRACODE_STDOUT, FIXTURE_ULTRA_EFFORT_ENTER);
     writeCatalog();

packages/cli/src/session-events/pro-injection.ts

@@ -6,14 +6,13 @@
  * merge — precedence is positional, so an explicit user parameter always wins
  * over the injected one.
  *
- * WHAT IS INJECTED IS NOT HARDCODED. Both halves of the fact come from the slim
- * catalog's `routeVariant`: which models a preset applies to (`baseModelId`)
- * and what that preset sets (`preset`, e.g. `reasoning.mode=pro`). A name regex
- * would assert a fact the catalog already knows, and would go stale the moment
- * a vendor ships another pro SKU.
+ * WHAT IS INJECTED IS NOT HARDCODED. The selected slim-catalog aggregator route
+ * says whether `reasoning.mode` is supported and which values it accepts. The
+ * older `routeVariant` lookup remains a compatibility fallback for caches that
+ * predate route-level capability metadata.
  */
 
-import { lookupVariantPresets } from "../adapters/model-catalog.js";
+import { lookupRouteReasoningMode, lookupVariantPresets } from "../adapters/model-catalog.js";
 import { log } from "../logger.js";
 import { deepMergeParams, parseModelParams } from "../model-params.js";
 import { type SessionEventRegistry, sessionEvents } from "./index.js";
@@ -22,41 +21,53 @@ import { type SessionEventRegistry, sessionEvents } from "./index.js";
 export interface ResolvedPreset {
   /** The params the preset expands to, ready to deep-merge. */
   params: Record<string, unknown>;
-  /** The variant model id the preset was read from (e.g. `gpt-5.6-sol-pro`). */
-  variantModelId: string;
   /** The serving provider the catalog recorded the preset on. */
   provider?: string;
   /** The raw preset string, for the log line. */
   preset: string;
+  /** Human-readable catalog evidence used by the diagnostic log. */
+  sourceLabel: string;
 }
 
 /**
- * The provider-preset this model has on `provider`, if the catalog knows one.
+ * The pro-mode preset this model has on `provider`, if the catalog knows one.
  *
- * Replaces the v1 `/gpt-5.6/` name gate. Returns undefined for a cold cache, a
- * model with no variants, a variant recorded on a DIFFERENT provider, or a
- * preset string that is not parseable `k=v` — every one of which means "no
- * information", which the caller must treat as "do not inject".
+ * Typed route metadata is authoritative when present: only `supported` plus a
+ * literal `pro` value enables injection. `rejected` and `unknown` both stop;
+ * neither may be weakened by a sibling provider's variant row. If the cache is
+ * old and has no typed route fact, the legacy same-provider `routeVariant`
+ * lookup remains available for one compatibility release.
  *
  * `provider` is required rather than optional on purpose: a preset is an
- * observation about ONE provider's roster. `reasoning.mode=pro` is recorded
- * against OpenRouter; whether the same parameter reaches the model on another
- * host is unverified, and injecting it there would be a guess.
+ * observation about ONE provider's route, not a portable model fact.
  */
 export function resolveVariantPreset(
   bareModelName: string,
   provider: string,
   cachePath?: string
 ): ResolvedPreset | undefined {
+  const routeMode = lookupRouteReasoningMode(bareModelName, provider, cachePath);
+  if (routeMode) {
+    if (routeMode.status !== "supported" || !routeMode.values.includes("pro")) {
+      return undefined;
+    }
+    return {
+      params: { reasoning: { mode: "pro" } },
+      provider,
+      preset: "reasoning.mode=pro",
+      sourceLabel: `route capability @ ${provider}`,
+    };
+  }
+
   for (const variant of lookupVariantPresets(bareModelName, provider, cachePath)) {
     try {
       const params = parseModelParams(variant.preset);
       if (Object.keys(params).length === 0) continue;
       return {
         params,
-        variantModelId: variant.modelId,
         provider: variant.provider,
         preset: variant.preset,
+        sourceLabel: `variant ${variant.modelId} @ ${variant.provider}`,
       };
     } catch {
       // Unparseable preset vocabulary (not `k=v`) → no information, try the next.
@@ -127,7 +138,7 @@ export function applyProInjection(
     deepMergeParams(requestPayload, resolved.params);
     log(
       `[SessionEvents] ultracode active → preset ${resolved.preset} for ${opts.targetModel} ` +
-        `(catalog variant ${resolved.variantModelId} @ ${resolved.provider}, session ${opts.sessionId})`
+        `(catalog ${resolved.sourceLabel}, session ${opts.sessionId})`
     );
     return true;
   } catch {