omp-llm-role 1.1.0 → 1.2.0

package/src/engine.ts

@@ -181,6 +181,9 @@ export type RoleDef = {
     minOutputTokens?: number;
     /** drop the model when its role-priced blend exceeds this ($/M); 0 = off */
     maxPriceUsdPerM?: number;
+    /** soft throughput floor (tok/s); 0/absent = off. A route at or above the
+     * floor sorts before a route below it, but is never dropped. */
+    preferredMinThroughput?: number;
   };
   /** explicit λ override ($ per quality point); default derives from the price weight */
   lambda?: number;
@@ -205,9 +208,9 @@ export type RoleDef = {
   /** Opt-in capability flags (`roles.<role>.features.<id>`); expanded by
    * `expandFeatures` before ranking. `true`/`false` overrides the global flag. */
   features?: Record<string, boolean>;
-  /** Soft provider preference (issue #40): price a model on its own lab's route
-   * when the role's `providerPinning` feature is on, else the 1/price² blend.
-   * Unlike `providerPin` this NEVER drops a model. */
+  /** Soft provider preference (issue #40, re-based by #58): price a model on its
+   * best route by the role's own value when the role's `providerPinning` feature
+   * is on, else the 1/price² blend. Unlike `providerPin` this NEVER drops a model. */
   preferOwnProvider?: boolean;
   /** Locked role: the plugin still ranks it (so it stays in the universe and its
    * sources are fetched) but never rewrites its `modelRoles` selector or fallback
@@ -1060,39 +1063,144 @@ export function pinnedRoute(model: Model, providerPin: string | undefined): Open
   return (model.routes ?? []).find((r) => r.providerSlug === providerPin) ?? null;
 }
 
-/** The model's own-lab route (the soft `preferOwnProvider` basis): the first route
- * whose lowercased `providerSlug` equals the lowercased `orgId`, or starts with
- * `orgId.toLowerCase() + "/"` — route slugs are tiered (`xiaomi/fp8`), so a prefix
- * match is the lab's own endpoint. When the orgId prefix finds nothing, the
- * lowercased display `org` is tried the same way (`Meta` vs slug `meta`). First
- * match in the model's `routes` order; null when nothing matches. There is no
- * alias map in v1: an org whose lab slug differs (`zai-org` vs `z-ai`) falls back
- * to the blend rather than mis-pinning. */
-export function ownProviderRoute(model: Model, orgId: string, org: string): OpenRouterEndpointRecord | null {
-  const routes = model.routes ?? [];
-  const match = (key: string): OpenRouterEndpointRecord | null => {
-    const k = key.toLowerCase();
-    if (k.length === 0) return null;
-    return routes.find((r) => {
-      const slug = r.providerSlug.toLowerCase();
-      return slug === k || slug.startsWith(`${k}/`);
-    }) ?? null;
-  };
-  return match(orgId) ?? match(org);
+/** The role's thinking-adjusted billed price for a model at `basePrice`: the
+ * thinking factor applies only when the model actually runs the role's level
+ * (catalog `thinkingLevels` wins; without it the `supports_reasoning` flag
+ * gates). Mirrors the factor `rankRole` applies, so the route basis and the
+ * ranking can never disagree. */
+export function thinkingAdjustedPrice(model: Model, def: RoleDef, basePrice: number): number {
+  const levelFactor = def.thinking === undefined ? 1 : thinkingPriceFactor(def.thinking);
+  if (levelFactor === 1) return basePrice;
+  const levels = model.thinkingLevels;
+  const runsAtLevel = levels
+    ? levels.length > 0 && (def.thinking === undefined || META_LEVELS[def.thinking] === true || levels.includes(def.thinking))
+    : model.thinking;
+  return runsAtLevel ? basePrice * levelFactor : basePrice;
+}
+
+/** The role's value of a model priced on `route` (null = the 1/price² blend):
+ * the price-free quality composite q over the model's metrics with the route's
+ * p50 throughput and cache-adjusted billed price, minus λ·priceEff. Returns null
+ * when the model has no usable billed price. */
+function roleValueOnRoute(
+  em: Model,
+  def: RoleDef,
+  route: OpenRouterEndpointRecord | null,
+  cacheHitRate: number,
+  lambda: number,
+  levelFactor: number,
+  qW: number,
+): { q: number; priceEff: number; value: number; parts: Record<string, number> } | null {
+  const basePrice = route !== null ? routeEffectivePrice(route, cacheHitRate) : em.price;
+  if (basePrice == null) return null;
+  const priceEff = levelFactor === 1 ? basePrice : thinkingAdjustedPrice(em, def, basePrice);
+  let q = 0;
+  const parts: Record<string, number> = {};
+  for (const [metric, w] of Object.entries(def.weights)) {
+    if (metric === "price") continue; // cost enters as the λ·$ penalty, not the blend
+    const raw = roleMetricValue(em, metric, route, cacheHitRate);
+    if (raw == null) {
+      // Sparse capability metrics are capability-filled (below-median, not 0)
+      // so absence is not a coverage penalty; every other metric contributes
+      // nothing when missing.
+      const fill = CAPABILITY_FILL[metric];
+      if (fill === undefined) continue;
+      const contrib = (w / qW) * fill;
+      parts[metric] = contrib;
+      q += contrib;
+      continue;
+    }
+    const contrib = (w / qW) * cardinalMetric(metric, raw);
+    parts[metric] = contrib;
+    q += contrib;
+  }
+  return { q, priceEff, value: q - lambda * priceEff, parts };
+}
+
+/** The model's routes that are candidates for the role's soft best-route basis,
+ * sorted by the value-for-money score desc (ties: providerSlug asc, id asc). A
+ * candidate is non-degraded (status === 0), passes
+ * `routePassesEndpointFilters(route, def.filters)`, has a usable billed price,
+ * and (when `filters.maxPriceUsdPerM > 0`) a thinking-adjusted price at or below
+ * the cap.
+ *
+ * The score is `vfm = wT·tNorm − wP·pNorm`, where `tNorm`/`pNorm` are the
+ * route's p50 throughput and cache-adjusted billed price min/max-normalized over
+ * the candidate set, and `wT = wTput/(wPrice+wTput)`, `wP = wPrice/(wPrice+wTput)`.
+ * A route with no p50 uses the model's blended throughput (an absent p50 is
+ * unknown, not slow). `filters.preferredMinThroughput` is a SOFT floor: routes at
+ * or above it sort before routes below it, but are never dropped. */
+export function rankedRoutes(model: Model, def: RoleDef): OpenRouterEndpointRecord[] {
+  const cacheHitRate = def.cacheHitRate ?? 0;
+  const cap = def.filters?.maxPriceUsdPerM ?? 0;
+  const floor = def.filters?.preferredMinThroughput ?? 0;
+  const out = (model.routes ?? []).filter((r) => {
+    if (r.status !== 0) return false;
+    if (!routePassesEndpointFilters(r, def.filters)) return false;
+    const p = routeEffectivePrice(r, cacheHitRate);
+    if (p === null || p <= 0) return false;
+    if (cap > 0 && thinkingAdjustedPrice(model, def, p) > cap) return false;
+    return true;
+  });
+  if (out.length === 0) return [];
+  // A route with no p50 falls back to the model's blended throughput over the
+  // endpoint-filtered pool — the same basis `roleMetricValue` used before.
+  const em = endpointFilteredModel(model, def.filters, cacheHitRate) ?? model;
+  const wTput = def.weights.throughput ?? 0;
+  const wPrice = def.weights.price ?? 0;
+  const wSum = wTput + wPrice;
+  const wT = wSum > 0 ? wTput / wSum : 0;
+  const wP = wSum > 0 ? wPrice / wSum : 0;
+  // Decorate-sort-undecorate: the throughput/price lookups are not free, so
+  // compute each route's terms once.
+  const decorated = out.map((route) => ({
+    route,
+    tput: roleMetricValue(em, "throughput", route, cacheHitRate) ?? 0,
+    priceEff: routeEffectivePrice(route, cacheHitRate) as number,
+  }));
+  const tMin = Math.min(...decorated.map((d) => d.tput));
+  const tMax = Math.max(...decorated.map((d) => d.tput));
+  const pMin = Math.min(...decorated.map((d) => d.priceEff));
+  const pMax = Math.max(...decorated.map((d) => d.priceEff));
+  const tSpan = tMax - tMin;
+  const pSpan = pMax - pMin;
+  return decorated
+    .map((d) => {
+      const tNorm = tSpan > 0 ? (d.tput - tMin) / tSpan : 0;
+      const pNorm = pSpan > 0 ? (d.priceEff - pMin) / pSpan : 0;
+      return { route: d.route, score: wT * tNorm - wP * pNorm, aboveFloor: floor <= 0 || d.tput >= floor };
+    })
+    .sort((a, b) => {
+      if (a.aboveFloor !== b.aboveFloor) return a.aboveFloor ? -1 : 1;
+      if (a.score !== b.score) return b.score - a.score;
+      if (a.route.providerSlug !== b.route.providerSlug) return a.route.providerSlug < b.route.providerSlug ? -1 : 1;
+      return a.route.id < b.route.id ? -1 : a.route.id > b.route.id ? 1 : 0;
+    })
+    .map((d) => d.route);
+}
+
+/** `rankedRoutes(model, def)[0]` or null. The auto-pin slug and the soft basis. */
+export function bestRoute(model: Model, def: RoleDef): OpenRouterEndpointRecord | null {
+  return rankedRoutes(model, def)[0] ?? null;
+}
+
+/** True when the role's soft best-route basis applies: the `preferOwnProvider`
+ * capability is on and no manual `providerPin` overrides it. The soft basis the
+ * engine prices on and the auto-pin the updater writes share this predicate. */
+export function autoPinApplies(def: RoleDef): boolean {
+  return def.providerPin === undefined && def.preferOwnProvider === true;
 }
 
 /** The route a role prices a model on: the hard pin's route when the role is
- * pinned, else the model's own-lab route when the soft `preferOwnProvider`
- * preference is on and that route carries a usable billed price, else null (the
- * 1/price² blend). A preference never drops a model — an unmatched own route (or
- * one with no usable price) falls back to the blend. */
+ * pinned, else the model's best route by the role's own value when the soft
+ * `preferOwnProvider` preference is on, else null (the 1/price² blend). A
+ * preference never drops a model — a model with no candidate route keeps the
+ * blend. */
 export function roleRoute(model: Model, def: RoleDef): OpenRouterEndpointRecord | null {
   const pin = pinnedRoute(model, def.providerPin);
   if (pin !== null) return pin;
-  if (def.providerPin !== undefined || def.preferOwnProvider !== true) return null;
-  const own = ownProviderRoute(model, model.orgId, model.org);
-  if (own === null) return null;
-  return routeEffectivePrice(own, def.cacheHitRate ?? 0) !== null ? own : null;
+  if (!autoPinApplies(def)) return null;
+  return bestRoute(model, def);
 }
 
 /** The metric value a role sees for a model. A pinned role's throughput is its
@@ -1142,12 +1250,11 @@ export function rankRole(def: RoleDef, models: Model[]): Ranked[] {
     // the pin and is ineligible (recorded by `providerPinDrops`).
     const pinRoute = pinnedRoute(m, def.providerPin);
     if (def.providerPin !== undefined && pinRoute === null) continue;
-    // Soft own-provider preference (issue #40): with no hard pin, a role that
-    // prefers the model's own lab endpoint is priced on that route where one
-    // exists (the same route basis a pin uses), else on the 1/price² blend. This
-    // is a preference, never a gate: a model with no own-lab route — or one whose
-    // route carries no usable billed price — keeps the blend, so the eligible
-    // count is unchanged. `providerPinDrops`/`pinUnmatched` key on
+    // Soft best-route preference (issue #40, re-based by #58): with no hard pin,
+    // a role that prefers a bound route is priced on the model's best route by
+    // the role's own value, else on the 1/price² blend. This is a preference,
+    // never a gate: a model with no candidate route keeps the blend, so the
+    // eligible count is unchanged. `providerPinDrops`/`pinUnmatched` key on
     // `def.providerPin` only, so the preference never drops a model.
     const route = roleRoute(m, def);
     // Endpoint capability gate: a role that declares endpoint filters is priced on
@@ -1160,49 +1267,23 @@ export function rankRole(def: RoleDef, models: Model[]): Ranked[] {
     const em = endpointFilteredModel(m, def.filters, cacheHitRate);
     if (em === null) continue;
     // The required-metric gate keys on the hard pin only (null when unpinned), so
-    // the soft own-provider preference can never change eligibility — it only
+    // the soft best-route preference can never change eligibility — it only
     // re-prices a model that already passes every gate.
     if (def.required.some((k) => roleMetricValue(em, k, pinRoute, cacheHitRate) == null)) continue;
-    // The billed price the role actually pays: the pinned route's cache-adjusted
-    // price, else the role's route-pool blend. Value needs one.
-    const basePrice = route !== null ? routeEffectivePrice(route, cacheHitRate) : em.price;
-    if (basePrice == null) continue;
-
-    // The factor assumes the model runs at the role's level. omp clamps
-    // unsupported levels, so a model whose catalog thinking[] excludes the
-    // level is priced bare — matching the updater, which appends no suffix in
-    // that case. Catalog data wins when present; without it (standalone
-    // ranking), the OR supports_reasoning flag gates.
-    const levels = m.thinkingLevels;
-    const runsAtLevel = levels
-      ? levels.length > 0 && (def.thinking === undefined || META_LEVELS[def.thinking] === true || levels.includes(def.thinking))
-      : m.thinking;
-    const priceEff = levelFactor === 1 || !runsAtLevel ? basePrice : basePrice * levelFactor;
-    // maxPriceUsdPerM caps the role-priced price (the thinking-adjusted price the
-    // role actually pays — the pinned route's price when pinned); 0 = off.
-    if ((def.filters?.maxPriceUsdPerM ?? 0) > 0 && priceEff > (def.filters?.maxPriceUsdPerM as number)) continue;
-
-    let q = 0;
-    const parts: Record<string, number> = {};
-    for (const [metric, w] of Object.entries(def.weights)) {
-      if (metric === "price") continue; // cost enters as the λ·$ penalty, not the blend
-      const raw = roleMetricValue(em, metric, route, cacheHitRate);
-      if (raw == null) {
-        // Sparse capability metrics are capability-filled (below-median, not 0)
-        // so absence is not a coverage penalty; every other metric contributes
-        // nothing when missing.
-        const fill = CAPABILITY_FILL[metric];
-        if (fill === undefined) continue;
-        const contrib = (w / qW) * fill;
-        parts[metric] = contrib;
-        q += contrib;
-        continue;
-      }
-      const contrib = (w / qW) * cardinalMetric(metric, raw);
-      parts[metric] = contrib;
-      q += contrib;
+    // The role's value on its route basis (the pin's route, the soft best route,
+    // or the 1/price² blend). Null when the model has no usable billed price.
+    const rv = roleValueOnRoute(em, def, route, cacheHitRate, lambda, levelFactor, qW);
+    if (rv === null) continue;
+    // maxPriceUsdPerM caps the model's own price basis, never the soft best-route
+    // basis: with no hard pin the gate uses the model's blend price (thinking-
+    // adjusted), so enabling `preferOwnProvider` cannot change eligibility. A hard
+    // pin keeps gating its route price — the price the request actually pays. 0 = off.
+    const cap = def.filters?.maxPriceUsdPerM ?? 0;
+    if (cap > 0) {
+      const capBase = pinRoute !== null ? routeEffectivePrice(pinRoute, cacheHitRate) : em.price;
+      if (capBase != null && thinkingAdjustedPrice(em, def, capBase) > cap) continue;
     }
-    ranked.push({ model: em, value: q - lambda * priceEff, q, priceEff, parts });
+    ranked.push({ model: em, value: rv.value, q: rv.q, priceEff: rv.priceEff, parts: rv.parts });
   }
   ranked.sort((a, b) => b.value - a.value);
   return ranked;

package/src/explorer/explain.ts

@@ -15,7 +15,7 @@
 import { assessFocusMetric, type FocusMetricAssessment } from "../agent-create.ts";
 import { type KeyAvailability } from "../availability.ts";
 import { cachedSourceInfo, sourceForMetric, type SourceDeclaration } from "../benchmark-sources.ts";
-import { BENCHMARK_CHANCE, CAPABILITY_FILL, cardinalMetric, endpointFilteredModel, paretoFrontier, pinnedRoute, rankRole, roleLambda, roleMetricValue, roleRoute, routeEffectivePrice, type Model, type Ranked, type RoleDef, type SuffixLevel } from "../engine.ts";
+import { autoPinApplies, BENCHMARK_CHANCE, CAPABILITY_FILL, cardinalMetric, endpointFilteredModel, paretoFrontier, pinnedRoute, rankRole, roleLambda, roleMetricValue, roleRoute, routeEffectivePrice, thinkingAdjustedPrice, type Model, type Ranked, type RoleDef, type SuffixLevel } from "../engine.ts";
 import { KNOWN_METRICS } from "../settings.ts";
 
 // ---------------------------------------------------------------------------
@@ -264,10 +264,14 @@ export type Explanation =
       value: number;
       q: number;
       priceEff: number;
-      /** true when the model was priced on its own lab's route (the soft
+      /** true when the model was priced on the soft best route (the
        * `preferOwnProvider` preference, no hard pin) rather than the 1/price²
        * blend — the panel shows WHY the price is what it is. */
       ownProvider: boolean;
+      /** the automatic pin: the model's best route's provider slug when the role
+       * prefers a bound route and carries no manual pin, else null. Read-only in
+       * the UI; a manual `providerPin` overrides it. */
+      autoPin: string | null;
       role: { name: string; lambda: number; derivedLambda: number; wPrice: number; qW: number; thinking: SuffixLevel | undefined; cacheHitRate: number };
       contributions: Contribution[];
       cost: { priceEff: number; billedPrice: number; lambda: number; penalty: number; q: number; value: number };
@@ -294,18 +298,31 @@ export function explainModel(def: RoleDef, models: Model[], modelId: string, rol
   const cacheHitRate = def.cacheHitRate ?? 0;
   const em = endpointFilteredModel(model, def.filters, cacheHitRate);
   const eff = em ?? model;
-  // Soft own-provider preference (mirrors rankRole): with no hard pin, a role that
-  // prefers the model's own lab endpoint is priced on that route where one exists,
-  // else on the blend. Never a gate — a model with no own-lab route keeps the blend.
+  // Soft best-route preference (mirrors rankRole): with no hard pin, a role that
+  // prefers a bound route is priced on the model's best route by the role's own
+  // value, else on the blend. Never a gate — a model with no candidate route keeps
+  // the blend.
   const route = roleRoute(model, def);
-  // The model is priced on its own lab's route (not a hard pin, not the blend).
+  // The model is priced on the soft best route (not a hard pin, not the blend).
   const ownProvider = pinRoute === null && route !== null;
+  // The automatic pin the updater would write: the model's best route's slug,
+  // only when the role prefers a bound route and carries no manual pin. Reuses the
+  // already-computed `route` (the same best route) instead of recomputing it.
+  const autoPin = autoPinApplies(def) ? route?.providerSlug ?? null : null;
   const missingRequired = def.required.filter((k) => roleMetricValue(eff, k, pinRoute, cacheHitRate) == null);
   if (missingRequired.length > 0) reasons.push(`missing required metric(s): ${missingRequired.join(", ")}`);
   if (def.filters?.image && !model.multimodal) reasons.push("role requires image input; model is text-only");
   if (def.providerPin !== undefined && pinRoute === null) reasons.push("no route matches the role's provider pin");
   if (em === null) reasons.push("no standard-tier route satisfies the role's endpoint filters");
   if (eff.price == null) reasons.push("no billed OpenRouter route");
+  // maxPriceUsdPerM caps the model's own price basis, never the soft best-route
+  // basis (mirrors rankRole): with no hard pin the gate uses the blend price, so
+  // the soft basis cannot change eligibility; a hard pin gates its route price.
+  const cap = def.filters?.maxPriceUsdPerM ?? 0;
+  if (cap > 0) {
+    const capBase = pinRoute !== null ? routeEffectivePrice(pinRoute, cacheHitRate) : eff.price;
+    if (capBase != null && thinkingAdjustedPrice(eff, def, capBase) > cap) reasons.push(`price exceeds the role's maxPriceUsdPerM cap (${cap})`);
+  }
   if (reasons.length > 0) return { eligible: false, reasons };
 
   const ranked = rankRole(def, models);
@@ -403,6 +420,7 @@ export function explainModel(def: RoleDef, models: Model[], modelId: string, rol
     q: self.q,
     priceEff: self.priceEff,
     ownProvider,
+    autoPin,
     role: { name: roleName, lambda, derivedLambda, wPrice, qW, thinking: def.thinking, cacheHitRate },
     contributions,
     cost: { priceEff: self.priceEff, billedPrice: route !== null ? routeEffectivePrice(route, cacheHitRate) ?? eff.price : eff.price, lambda, penalty: lambda * self.priceEff, q: self.q, value: self.value },

package/src/explorer/server.ts

@@ -26,7 +26,7 @@ import { createServer, type IncomingMessage, type Server, type ServerResponse }
 import { extname, resolve, sep } from "node:path";
 import type { KeyAvailability } from "../availability.ts";
 import { loadDeclaredSources } from "../benchmark-sources.ts";
-import { SUFFIX_LEVELS, rankRole, roleLambda, thinkingPriceFactor, type RankData, type RoleDef, type SuffixLevel } from "../engine.ts";
+import { pinnedRoute, SUFFIX_LEVELS, rankRole, roleLambda, thinkingPriceFactor, type RankData, type RoleDef, type SuffixLevel } from "../engine.ts";
 import { expandFeatures, FEATURES } from "../features.ts";
 import { isRecord } from "../guards.ts";
 import { validateRole, writeRoleSettings } from "../role-settings.ts";
@@ -260,7 +260,20 @@ async function handleExport(req: IncomingMessage, res: ServerResponse, opts: Exp
   const body = await readJson(req);
   if (!isRecord(body) || !isRecord(body.roles)) throw new HttpError(400, "expected { roles: object }");
   const scope = activeScope(opts, session);
-  const result = writeRoleSettings(scope.lockPath, body.roles as unknown as Record<string, RoleDef>);
+  const dirty = body.roles as unknown as Record<string, RoleDef>;
+  // A manual provider pin must name a route the loaded dataset actually has, or
+  // the exported role would be unroutable. Validate before any write; the
+  // plugin's own validator (empty/@/:) still runs, so both error sets surface.
+  const state = opts.getState(scope);
+  const errors: string[] = [];
+  for (const [name, def] of Object.entries(dirty)) {
+    errors.push(...validateRole(name, def));
+    if (def.providerPin === undefined) continue;
+    const known = state.rank.models.some((m) => pinnedRoute(m, def.providerPin) !== null);
+    if (!known) errors.push(`role "${name}": provider pin "${def.providerPin}" matches no route in the loaded dataset`);
+  }
+  if (errors.length > 0) return sendJson(res, 200, { ok: false, errors });
+  const result = writeRoleSettings(scope.lockPath, dirty);
   if (!result.ok) return sendJson(res, 200, { ok: false, errors: result.errors });
   sendJson(res, 200, { ok: true, backupPath: result.backupPath, roles: result.roles, lockPath: scope.lockPath });
 }

package/src/extension.ts

@@ -20,13 +20,14 @@ import { generateAgentSpec, generateProjectProfile } from "./agent-architect.ts"
 import { authorBenchmarkSource } from "./benchmark-author.ts";
 import { applyBenchmarkScores, BENCHMARK_ENTRY_CAP, cachedSourceInfo, declarationToSource, declaredSourceForLink, dryRunDeclaration, fetchJson, loadBenchmarkCatalog, loadBenchmarkScores, loadDeclaredSources, resolveBenchmarkSource, saveDeclaredSource, sourceForMetric, validateDeclaration, type BenchmarkCatalogEntry, type BenchmarkPayloadMeta, type BenchmarkSource, type SourceDeclaration } from "./benchmark-sources.ts";
 import { judgeBenchmarkRelevance } from "./benchmark-discovery.ts";
-import { THINKING_LEVELS, catalogFromOmpModelsJson, fetchKeyAvailability, type KeyAvailability } from "./availability.ts";
+import { catalogFromOmpModelsJson, fetchKeyAvailability, splitThinkingSuffix, type KeyAvailability } from "./availability.ts";
 import { loadRankData, rankRole, type Model } from "./engine.ts";
 import { defaultErrorReportDeps, reportUnexpectedError, type ErrorReportInput } from "./error-report.ts";
 import { formatFeatures } from "./features.ts";
 import { startExplorer, type ExplorerHandle } from "./explorer/boot.ts";
 import { resolveScopes, unionRoles } from "./explorer/scopes.ts";
 import { isRecord } from "./guards.ts";
+import { applyProviderDisplay, providerPinOf, providerPinOfSelector } from "./provider-display.ts";
 import { applyProfileOverrides, formatProjectRolesReport, parseProjectRolesArgs, PROJECT_ROLES_USAGE, setupProject, type ProjectProfile } from "./project-setup.ts";
 import { DEFAULT_ROLES, findProjectAnchor, KNOWN_METRICS, PLUGIN_SETTINGS_PATH, projectLockPath, readPluginSettingsMap, resolveSettings } from "./settings.ts";
 import { runUpdater, type Deps } from "./updater.ts";
@@ -71,17 +72,41 @@ function hasEmptyConversation(ctx: ExtContext): boolean {
   return true;
 }
 
-/** True when the live session model resolves from the old default selector (same provider/id, any level). */
-function sessionBootedOnOldDefault(ctx: ExtContext, oldSelector: string): boolean {
+/**
+ * True when `selector` names the live session model: the selector's base
+ * (thinking suffix stripped) resolves to a model with the same `provider` and
+ * `id` as `ctx.models.current()`. Any thinking level or provider pin is
+ * ignored. Used both to detect a session booted on the old default role and to
+ * decide whether a fallback event's selector is authoritative for the session
+ * (advisor fallbacks emit the same events with the advisor's selector).
+ */
+function liveModelIsSelector(ctx: ExtContext, selector: string): boolean {
   const current = ctx.models?.current();
-  const colon = oldSelector.lastIndexOf(":");
-  const level = colon !== -1 && oldSelector.slice(colon + 1) in THINKING_LEVELS ? oldSelector.slice(colon + 1) : null;
-  const base = level === null ? oldSelector : oldSelector.slice(0, oldSelector.length - level.length - 1);
-  const oldModel = ctx.models?.resolve(base);
-  if (current === undefined || current === null || oldModel === undefined || oldModel === null) return false;
-  if (typeof current !== "object" || typeof oldModel !== "object") return false;
-  if (!("provider" in current) || !("id" in current) || !("provider" in oldModel) || !("id" in oldModel)) return false;
-  return current.provider === oldModel.provider && current.id === oldModel.id;
+  const { base } = splitThinkingSuffix(selector);
+  const target = ctx.models?.resolve(base);
+  if (current === undefined || current === null || target === undefined || target === null) return false;
+  if (typeof current !== "object" || typeof target !== "object") return false;
+  if (!("provider" in current) || !("id" in current) || !("provider" in target) || !("id" in target)) return false;
+  return current.provider === target.provider && current.id === target.id;
+}
+
+/**
+ * Apply the provider display suffix to the live session model (spec #77).
+ * `selector` is the event's authoritative selector string when the event
+ * carries one; the live model's routing block is the fallback. The event's
+ * selector is trusted only when it names the live session model — the fallback
+ * events are also emitted for advisor fallbacks, where only the advisor's model
+ * changes and the session model is untouched. Contained: a throw must not tear
+ * down the session or escape into omp's dispatch.
+ */
+function applyProviderDisplayFor(ctx: ExtContext, selector?: string): void {
+  try {
+    const live = ctx.models?.current();
+    const eventPin = typeof selector === "string" && liveModelIsSelector(ctx, selector) ? providerPinOfSelector(selector) : null;
+    applyProviderDisplay(live, eventPin ?? providerPinOf(live));
+  } catch {
+    // display-only; never let a failure escape into omp's dispatch
+  }
 }
 
 /**
@@ -97,10 +122,8 @@ function makeApplySessionModel(pi: ExtensionAPI, ctx: ExtContext, notify: (lines
     if (ctx.agent.kind !== "main") return;
     if (!hasEmptyConversation(ctx)) return;
     if (previous === null) return; // first run ever wrote a fresh default; the session predates no old role
-    if (!sessionBootedOnOldDefault(ctx, previous)) return;
-    const colon = selector.lastIndexOf(":");
-    const level = colon !== -1 && selector.slice(colon + 1) in THINKING_LEVELS ? selector.slice(colon + 1) : null;
-    const base = level === null ? selector : selector.slice(0, selector.length - level.length - 1);
+    if (!liveModelIsSelector(ctx, previous)) return;
+    const { base, level } = splitThinkingSuffix(selector);
     const model = ctx.models?.resolve(base);
     if (model === undefined || model === null) {
       notify([`omp-llm-role: session model not updated — "${base}" matches no available model`]);
@@ -418,6 +441,26 @@ export default function (pi: ExtensionAPI) {
     }
   });
 
+  // Provider display (spec #77): keep the live model's name suffixed with its
+  // provider pin. Never pi.setModel — that would wipe omp's in-flight fallback
+  // state and clobber the thinking level; mutate the live model's name only.
+  // Registered after the updater so the session-start pin reflects the model
+  // the run just selected.
+  pi.on("session_start", async (_event, ctx: ExtContext) => {
+    applyProviderDisplayFor(ctx);
+  });
+  pi.on("retry_fallback_applied", async (event, ctx: ExtContext) => {
+    applyProviderDisplayFor(ctx, event.to);
+  });
+  pi.on("retry_fallback_succeeded", async (event, ctx: ExtContext) => {
+    applyProviderDisplayFor(ctx, event.model);
+  });
+  // Self-healing hook: omp restores the primary after a fallback cooldown with
+  // no session event, so re-derive the pin from the live model before each turn.
+  pi.on("turn_start", async (_event, ctx: ExtContext) => {
+    applyProviderDisplayFor(ctx);
+  });
+
   pi.registerCommand("refresh-roles", {
     description: "Refresh model roles from today's llm-stats/OpenRouter rankings",
     handler: async (_args, ctx: ExtContext) => {

package/src/features.ts

@@ -19,7 +19,7 @@ export type FeatureRow = {
   description: string;
   /** The recommended settings the flag applies. A bundle value is either a
    * scalar knob or a per-model policy field (`preferOwnProvider`). */
-  recommended: { filters?: { tools?: boolean; minOutputTokens?: number; maxPriceUsdPerM?: number }; cacheHitRate?: number; preferOwnProvider?: true };
+  recommended: { filters?: { tools?: boolean; minOutputTokens?: number; maxPriceUsdPerM?: number; preferredMinThroughput?: number }; cacheHitRate?: number; preferOwnProvider?: true };
   /** What the flag buys, for `--list-features` and the docs. */
   buys: string;
 };
@@ -41,14 +41,14 @@ export const FEATURES: readonly FeatureRow[] = [
   },
   {
     id: "providerPinning",
-    label: "Prefer the model's own lab endpoint",
+    label: "Best-route provider pinning",
     // Per-model policy, not a scalar slug: the sensible pin differs per model,
     // so the bundle carries `preferOwnProvider` (evaluated against the model's
-    // own routes at rank time). It changes no eligibility — a model with no
-    // own-lab route keeps the default 1/price² blend.
-    description: "Price a model on its own lab's route where one exists (per-model policy; never drops a model)",
-    recommended: { preferOwnProvider: true },
-    buys: "a model is priced on its own lab's route where one exists (DeepSeek's own endpoint, 94.5 % cache hit), falling back to the default blend otherwise",
+    // best route at rank time). It changes no eligibility — a model with no
+    // candidate route keeps the default 1/price² blend.
+    description: "Bind each request to the model's best provider route (per-model policy; never drops a model) and prefer routes at or above 50 tok/s",
+    recommended: { preferOwnProvider: true, filters: { preferredMinThroughput: 50 } },
+    buys: "each request is bound to the model's best provider route — the selector gains @<slug> — and the fallback chain carries the same model on its next-best providers plus each fallback model on its best providers, so a down route fails over within the model's own routes; a soft 50 tok/s floor deprioritizes a pathologically slow route without dropping it",
   },
   {
     id: "costCap",
@@ -69,6 +69,7 @@ function formatBundle(rec: FeatureRow["recommended"]): string {
   if (rec.filters?.tools !== undefined) parts.push(`filters.tools=${rec.filters.tools}`);
   if (rec.filters?.minOutputTokens !== undefined) parts.push(`filters.minOutputTokens=${rec.filters.minOutputTokens}`);
   if (rec.filters?.maxPriceUsdPerM !== undefined) parts.push(`filters.maxPriceUsdPerM=${rec.filters.maxPriceUsdPerM}`);
+  if (rec.filters?.preferredMinThroughput !== undefined) parts.push(`filters.preferredMinThroughput=${rec.filters.preferredMinThroughput}`);
   if (rec.cacheHitRate !== undefined) parts.push(`cacheHitRate=${rec.cacheHitRate}`);
   if (rec.preferOwnProvider !== undefined) parts.push(`preferOwnProvider=${rec.preferOwnProvider}`);
   return parts.join(", ");
@@ -95,6 +96,7 @@ export function expandFeatures(authored: RoleDef, globalFlags: Record<string, bo
       if (rec.filters.tools !== undefined && f.tools === undefined) f.tools = rec.filters.tools;
       if (rec.filters.minOutputTokens !== undefined && f.minOutputTokens === undefined) f.minOutputTokens = rec.filters.minOutputTokens;
       if (rec.filters.maxPriceUsdPerM !== undefined && f.maxPriceUsdPerM === undefined) f.maxPriceUsdPerM = rec.filters.maxPriceUsdPerM;
+      if (rec.filters.preferredMinThroughput !== undefined && f.preferredMinThroughput === undefined) f.preferredMinThroughput = rec.filters.preferredMinThroughput;
     }
     if (rec.cacheHitRate !== undefined && out.cacheHitRate === undefined) out.cacheHitRate = rec.cacheHitRate;
     if (rec.preferOwnProvider !== undefined && out.preferOwnProvider === undefined) out.preferOwnProvider = rec.preferOwnProvider;

package/src/provider-display.ts

@@ -0,0 +1,67 @@
+/**
+ * Provider display: keep the live session model's `name` suffixed with its
+ * upstream provider pin, so omp's model segment renders e.g.
+ * `DeepSeek V4.1 Flash @coreweave/fp8`.
+ *
+ * omp's built-in model segment renders `state.model.name || state.model.id`
+ * only and exposes no extension hook to add to it; the only lever is the live
+ * model object's `name` (the exact object `ctx.models.current()` returns). This
+ * module is pure and dual-runtime (no `@oh-my-pi/*` import) — the extension
+ * wiring only calls it.
+ */
+import { splitThinkingSuffix } from "./availability.ts";
+import { isRecord } from "./guards.ts";
+
+/** The single upstream route of a compat routing block, or null. Mirrors omp's
+ * `getSingleRoutingOnly`: exactly one entry, a non-empty string. */
+function singleOnly(routing: unknown): string | null {
+  if (!isRecord(routing) || !Array.isArray(routing.only) || routing.only.length !== 1) return null;
+  const upstream = routing.only[0];
+  return typeof upstream === "string" && upstream ? upstream : null;
+}
+
+/**
+ * The provider pin carried by a model's compat routing block:
+ * `compat.openRouterRouting.only[0]`, else `compat.vercelGatewayRouting.only[0]`.
+ * Null when absent, when `only` is not exactly one entry, or when the entry is
+ * not a non-empty string.
+ */
+export function providerPinOf(model: unknown): string | null {
+  if (!isRecord(model) || !isRecord(model.compat)) return null;
+  const compat = model.compat;
+  return singleOnly(compat.openRouterRouting) ?? singleOnly(compat.vercelGatewayRouting);
+}
+
+/**
+ * The trailing `@<slug>` of a selector (`openrouter/<id>@<slug>:<level>`),
+ * after stripping a trailing thinking suffix (`:high`, `:auto`, …). Null when
+ * there is no `@` or the slug is empty. Strip order mirrors `currentRankingId`
+ * in `src/availability.ts`: level first, then `@`.
+ */
+export function providerPinOfSelector(selector: string): string | null {
+  const { base } = splitThinkingSuffix(selector);
+  const at = base.lastIndexOf("@");
+  if (at === -1) return null;
+  const slug = base.slice(at + 1);
+  return slug || null;
+}
+
+/**
+ * Strip any previous ` @<slug>` suffix from `name`, then append ` @<pin>` when
+ * `pin` is non-null. Idempotent; a null pin returns the base name (suffix
+ * stripped). Plain text only — no theme tokens, no ANSI.
+ */
+export function withProviderSuffix(name: string, pin: string | null): string {
+  const base = name.replace(/\s@\S+$/, "");
+  return pin === null ? base : `${base} @${pin}`;
+}
+
+/**
+ * Set `model.name` to `withProviderSuffix(model.name, pin)` when `model` is a
+ * record with a string `name`; a no-op otherwise.
+ */
+export function applyProviderDisplay(model: unknown, pin: string | null): void {
+  if (isRecord(model) && typeof model.name === "string") {
+    model.name = withProviderSuffix(model.name, pin);
+  }
+}