omp-llm-role 1.1.0 → 1.3.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
@@ -310,6 +313,19 @@ export type OpenRouterEndpointPages = Record<string, OpenRouterEndpointRecord[]>
 
 export type OrEnrichment = { tput: number; latency: number | null; price: number | null; thinking: boolean; routes: OpenRouterEndpointRecord[] };
 
+/** The route's input (prompt) $/M under an assumed cache-hit rate: the input term
+ * `routeEffectivePrice` blends into the billed price. A hit rate `h` blends the
+ * cache-read input in, `h·cacheRead + (1−h)·input`; with `h = 0` or no cache-read
+ * price this is the listed input price, and a route with no input price has none —
+ * missing data keeps the full input price, never a silent discount. The single
+ * accessor for the input term: the billed blend, the output-price inverse
+ * (`routeOutputPrice`) and the explorer's per-task price all read it. */
+export function routeInputPrice(route: OpenRouterEndpointRecord, cacheHitRate = 0): number | null {
+  if (route.weightPrice == null) return null;
+  if (cacheHitRate <= 0 || route.cacheReadPrice == null) return route.weightPrice;
+  return cacheHitRate * route.cacheReadPrice + (1 - cacheHitRate) * route.weightPrice;
+}
+
 /** The effective billed $/M of one route under an assumed cache-hit rate. The route's
  * billed 3:1 price is `price = (3·input + output)/4` on the listed input price; a hit
  * rate `h` blends the cache-read input into the input term,
@@ -317,15 +333,33 @@ export type OrEnrichment = { tput: number; latency: number | null; price: number
  * (the output term is unchanged). With `h = 0`, no cache-read price, or no input price
  * this is the route's listed `price` — missing data keeps the full input price, never a
  * silent discount. Shared by the blend (`blendRoutePool`), the pin path (`rankRole`) and
- * `roleMetricValue`. */
+ * `roleMetricValue`; the input term itself is `routeInputPrice`. */
 export function routeEffectivePrice(route: OpenRouterEndpointRecord, cacheHitRate = 0): number | null {
   if (route.price == null) return null;
   if (cacheHitRate <= 0 || route.cacheReadPrice == null || route.weightPrice == null) return route.price;
   const input = route.weightPrice;
-  const effInput = cacheHitRate * route.cacheReadPrice + (1 - cacheHitRate) * input;
+  const effInput = routeInputPrice(route, cacheHitRate) as number;
   return route.price + (3 * (effInput - input)) / 4;
 }
 
+/** The output (completion) $/M implied by a billed 3:1 blend and the input price
+ * behind it: the inverse of `billed = IO_PRICE_RATIO·(3·input + output)`, i.e.
+ * `output = billed/IO_PRICE_RATIO − (1−IO_PRICE_RATIO)/IO_PRICE_RATIO · input`.
+ * The 3:1 ratio lives here (and in `IO_PRICE_RATIO`), not in the callers; dividing
+ * by `IO_PRICE_RATIO` (2⁻²) is exact, so this is the plain `4·billed − 3·input`. */
+export function blendOutputPrice(billed: number, input: number): number {
+  return billed / IO_PRICE_RATIO - ((1 - IO_PRICE_RATIO) / IO_PRICE_RATIO) * input;
+}
+
+/** The route's output (completion) $/M: the inverse blend of its own billed and
+ * input prices (see `blendOutputPrice`). Null when either of them is missing. */
+export function routeOutputPrice(route: OpenRouterEndpointRecord, cacheHitRate = 0): number | null {
+  const billed = routeEffectivePrice(route, cacheHitRate);
+  const input = routeInputPrice(route, cacheHitRate);
+  if (billed === null || input === null) return null;
+  return blendOutputPrice(billed, input);
+}
+
 /** Expected price/throughput/latency of one request over a route pool under the
  * router's default price-based load balancing: P(route i) ∝ 1/input_price_i² — the
  * router sorts on the input (prompt) price alone, so the weight basis is
@@ -1060,39 +1094,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 +1281,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 +1298,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/boot.ts

@@ -13,10 +13,13 @@
 
 import { execFile } from "node:child_process";
 import type { Server } from "node:http";
-import { enrichThinkingLevels, type CatalogEntry, type KeyAvailability } from "../availability.ts";
+import { join } from "node:path";
+import { enrichThinkingLevels, type CatalogEntry, type KeyAvailability, type Tier } from "../availability.ts";
 import type { RankData } from "../engine.ts";
 import { DEFAULT_ROLES, PLUGIN_SETTINGS_PATH } from "../settings.ts";
 import { agentDir } from "../state.ts";
+import { readUsageRows, type TokenProfile } from "../usage-ledger.ts";
+import type { PoolInputs } from "./pool.ts";
 import { readScopeRoles, resolveScope, resolveScopes, type Scope, type ScopeInputs } from "./scopes.ts";
 import { createExplorerServer } from "./server.ts";
 
@@ -49,6 +52,25 @@ export type ExplorerBootOpts = {
   reload(refresh: boolean): Promise<RankData>;
   /** Re-derive the key-availability overlay for `POST /api/refresh` (best-effort). */
   reloadAvailability?: () => Promise<KeyAvailability>;
+  /**
+   * The as-written pool's inputs (spec #81): the key's tier and the account's
+   * allowed-providers whitelist. Both are best-effort — an absent tier reads as
+   * `billed` (the ordinary account), and an absent/null whitelist leaves every
+   * route in place, so a failed harvest degrades to the raw pool instead of
+   * breaking the explorer.
+   */
+  tier?: Tier;
+  allowedProviders?: ReadonlySet<string> | null;
+  /** Re-derive the whitelist for `POST /api/refresh` (best-effort: a throw or a
+   *  null result degrades the as-written pool to no route pruning). */
+  reloadAllowedProviders?: () => Promise<ReadonlySet<string> | null>;
+  /** The user-set token profile the per-task price falls back to (the
+   *  `tokenProfile` setting); absent = unset. */
+  tokenProfile?: TokenProfile | null;
+  /** Dir holding the user-level usage ledger the per-task price resolves its
+   *  profile from (default: `agentDir()`, beside the plugin's other state). A
+   *  project scope reads its own `<root>/.omp` ledger instead. */
+  usageDir?: string;
   port?: number;
   /** Open the URL in the default browser (macOS only). */
   open?: boolean;
@@ -93,6 +115,11 @@ export async function startExplorer(opts: ExplorerBootOpts): Promise<ExplorerHan
   const scopeInputs: ScopeInputs = { userLockPath, cwd, registryDir: opts.registryDir };
   let rank = opts.rank;
   let availability = opts.availability;
+  // The as-written pool's mutable half: the whitelist is re-derived on refresh,
+  // the catalog and tier are boot-time facts. `null` = no pruning.
+  let allowed = opts.allowedProviders ?? null;
+  const tier = opts.tier ?? "billed";
+  const usageDir = opts.usageDir ?? agentDir();
   enrichThinkingLevels(rank.models, opts.catalog);
 
   // Scope resolution is boot's job: the user-level scope, the registry's
@@ -117,7 +144,22 @@ export async function startExplorer(opts: ExplorerBootOpts): Promise<ExplorerHan
       rank = await opts.reload(true);
       enrichThinkingLevels(rank.models, opts.catalog);
       if (opts.reloadAvailability) availability = await opts.reloadAvailability();
+      // Best-effort: the whitelist is account state, so a failed re-harvest must
+      // leave the explorer usable (routes unpruned) rather than fail the refresh.
+      if (opts.reloadAllowedProviders) {
+        try {
+          allowed = await opts.reloadAllowedProviders();
+        } catch {
+          allowed = null;
+        }
+      }
     },
+    getPoolInputs: (): PoolInputs => ({ catalog: opts.catalog, tier, allowed }),
+    // The ledger follows the plugin's state location: a project scope keeps its
+    // usage in its own `<root>/.omp`, so its per-task column never mixes with
+    // the user-level profile.
+    getUsageRows: (scope) => readUsageRows(scope.kind === "project" && scope.root !== undefined ? join(scope.root, ".omp") : usageDir),
+    tokenProfile: opts.tokenProfile ?? null,
   });
   // Optional detach (extension only): never hold the host process open on the
   // server's account, so a short-lived `omp -p` run cannot hang.

package/src/explorer/explain.ts

@@ -15,8 +15,9 @@
 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, blendOutputPrice, blendRoutePool, CAPABILITY_FILL, cardinalMetric, endpointFilteredModel, paretoFrontier, pinnedRoute, rankRole, roleLambda, roleMetricValue, roleRoute, routeEffectivePrice, routeInputPrice, routeOutputPrice, routePassesEndpointFilters, thinkingAdjustedPrice, type Model, type OpenRouterEndpointRecord, type Ranked, type RoleDef, type SuffixLevel } from "../engine.ts";
 import { KNOWN_METRICS } from "../settings.ts";
+import { type TokenProfile } from "../usage-ledger.ts";
 
 // ---------------------------------------------------------------------------
 // Metric metadata (the UI's picklists and formula legends)
@@ -126,6 +127,79 @@ export function focusAssessments(
   return out;
 }
 
+// ---------------------------------------------------------------------------
+// Per-task price (display-only)
+// ---------------------------------------------------------------------------
+
+/** The per-task price of one model under a role: the role's priced route's input
+ * and output prices applied to the role's token profile, with the output term
+ * scaled by the role's thinking factor. Display-only — it never feeds the
+ * ranking's sort key, `value`, or the explanation's `cost` block. */
+export type PerTaskPrice = {
+  inputTokens: number;
+  outputTokens: number;
+  /** the route's input price, $/M (cache-adjusted by the role's cache-hit rate) */
+  inputPrice: number;
+  /** the route's output price, $/M (derived from the billed blend and the input price) */
+  outputPrice: number;
+  /** the role's thinking factor (1 for a bare role) */
+  thinkingFactor: number;
+  /** dollars per task */
+  total: number;
+};
+
+/** The model's blended input price: the 1/weightPrice²-weighted mean of the
+ * routes' cache-adjusted input prices (`routeInputPrice`) — the same weighting
+ * `blendRoutePool` uses (the router's sort key), so price each route at its input
+ * price and read the blend back. The cache-hit rate must reach this term too, or
+ * `p_out` would mix a cache-adjusted billed blend with an unadjusted input price. */
+function blendedInputPrice(routes: readonly OpenRouterEndpointRecord[], cacheHitRate: number): number | null {
+  const priced = routes.map((r) => ({ ...r, price: routeInputPrice(r, cacheHitRate) }));
+  return blendRoutePool(priced, 0).price;
+}
+
+/** The per-task price of `model` under `def` for a token profile: `p_in` is the
+ * role's priced route's input price (cache-adjusted), `p_out` its output price
+ * (the inverse 3:1 blend of the same route, `routeOutputPrice`), and the output
+ * term is scaled by the role's thinking factor. When the role prices on the
+ * 1/price² blend (`roleRoute` returns null) the model's billed blend and the input
+ * blend over the routes that survive the role's endpoint filters stand in — the
+ * same pool the ranking prices on, so `p_in` and the billed blend never mix two
+ * route pools. `null` when there is no usable route price (absent, never a silent
+ * zero). */
+export function perTaskPrice(model: Model, def: RoleDef, profile: TokenProfile): PerTaskPrice | null {
+  const cacheHitRate = def.cacheHitRate ?? 0;
+  // A role with endpoint filters prices on the routes that survive them; a model
+  // whose every route fails is ineligible (the ranking drops it), so its per-task
+  // price is absent, not the unfiltered blend.
+  const em = endpointFilteredModel(model, def.filters, cacheHitRate);
+  if (em === null) return null;
+  const route = roleRoute(model, def);
+  let inputPrice: number | null;
+  let outputPrice: number | null;
+  if (route !== null) {
+    // The role prices this model on one route: that route's own input and output
+    // prices, the same pair the billed blend comes from.
+    inputPrice = routeInputPrice(route, cacheHitRate);
+    outputPrice = routeOutputPrice(route, cacheHitRate);
+  } else {
+    // The 1/price² blend case: the billed blend `em` is priced on and the input
+    // blend over exactly the routes it blended — the endpoint-filtered pool, never
+    // the model's full route list (a dropped route's input price belongs to no
+    // route's output price).
+    const pool = (model.routes ?? []).filter((r) => routePassesEndpointFilters(r, def.filters));
+    inputPrice = blendedInputPrice(pool, cacheHitRate);
+    outputPrice = inputPrice === null || em.price === null ? null : blendOutputPrice(em.price, inputPrice);
+  }
+  if (inputPrice === null || outputPrice === null) return null;
+  // The same gated factor the ranking applies: `thinkingAdjustedPrice(model, def, 1)`
+  // is 1 unless the model actually runs at the role's level, so the per-task price
+  // and the row's `priceEff` can never disagree for a non-thinking model.
+  const thinkingFactor = thinkingAdjustedPrice(model, def, 1);
+  const total = (profile.inputTokens * inputPrice + profile.outputTokens * outputPrice * thinkingFactor) / 1e6;
+  return { inputTokens: profile.inputTokens, outputTokens: profile.outputTokens, inputPrice, outputPrice, thinkingFactor, total };
+}
+
 // ---------------------------------------------------------------------------
 // Rank rows (table data with baseline deltas)
 // ---------------------------------------------------------------------------
@@ -156,6 +230,9 @@ export type RankRow = {
   baselineRank: number | null;
   /** baselineRank − rank; positive = moved up */
   delta: number | null;
+  /** dollars per task under the role's token profile, or null when no profile
+   * was supplied or the model has no usable route price. Display-only. */
+  perTask: number | null;
 };
 
 /** The availability overlay verdict for one model id: `"usable"` when the keyed
@@ -172,8 +249,9 @@ function keyVerdict(availability: KeyAvailability | undefined, id: string): "usa
 /** Rank `models` under `def`, annotating each row with its rank delta against
  * `baseline` (the effective role's ranking, i.e. what the plugin does today) and
  * its keyed-catalog availability overlay. Ranking order, deltas, and every other
- * field are unaffected by `availability`. */
-export function rankRows(def: RoleDef, models: Model[], baseline: Ranked[], availability?: KeyAvailability): RankRow[] {
+ * field are unaffected by `availability` or `profile`; `profile` only fills the
+ * display-only `perTask` column. */
+export function rankRows(def: RoleDef, models: Model[], baseline: Ranked[], availability?: KeyAvailability, profile?: TokenProfile | null): RankRow[] {
   const ranked = rankRole(def, models);
   const frontier = paretoFrontier(ranked);
   const baselineRank = new Map<string, number>();
@@ -200,6 +278,7 @@ export function rankRows(def: RoleDef, models: Model[], baseline: Ranked[], avai
       rank,
       baselineRank: b,
       delta: b == null ? null : b - rank,
+      perTask: profile == null ? null : perTaskPrice(r.model, def, profile)?.total ?? null,
     };
   });
 }
@@ -264,13 +343,21 @@ 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 };
+      /** the per-task price breakdown under the role's token profile, or null
+       * when no profile was supplied or the model has no usable route price.
+       * Display-only — never part of `cost` or the ranking. */
+      perTask: PerTaskPrice | null;
       gapAbove: number | null;
       gapToTop: number;
       above: { id: string; name: string; value: number } | null;
@@ -280,8 +367,9 @@ export type Explanation =
 
 /** Full decomposition of one model's rank for a role, or the eligibility gates it
  * failed (same gates `rankRole` applies, listed in the same order). The eligible
- * branch also carries the keyed-catalog availability overlay (`key`/`keyReason`). */
-export function explainModel(def: RoleDef, models: Model[], modelId: string, roleName = "", availability?: KeyAvailability): Explanation {
+ * branch also carries the keyed-catalog availability overlay (`key`/`keyReason`)
+ * and, when a token `profile` is supplied, the display-only per-task price. */
+export function explainModel(def: RoleDef, models: Model[], modelId: string, roleName = "", availability?: KeyAvailability, profile?: TokenProfile | null): Explanation {
   const model = models.find((m) => m.id === modelId);
   if (!model) return { eligible: false, reasons: ["model not found in today's dataset"] };
 
@@ -294,18 +382,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,9 +504,11 @@ 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 },
+    perTask: profile == null ? null : perTaskPrice(model, def, profile),
     gapAbove,
     gapToTop,
     above,