omp-llm-role 1.2.0 → 1.3.0

package/src/extension.ts

@@ -20,7 +20,8 @@ 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 { catalogFromOmpModelsJson, fetchKeyAvailability, splitThinkingSuffix, type KeyAvailability } from "./availability.ts";
+import { catalogFromOmpModelsJson, currentRankingId, fetchAllowedProviders, fetchKeyAvailability, fetchKeyMeta, filterCatalog, splitThinkingSuffix, tierGate, type KeyAvailability, type Tier } from "./availability.ts";
+import { parseConfig } from "./config-edit.ts";
 import { loadRankData, rankRole, type Model } from "./engine.ts";
 import { defaultErrorReportDeps, reportUnexpectedError, type ErrorReportInput } from "./error-report.ts";
 import { formatFeatures } from "./features.ts";
@@ -30,7 +31,9 @@ 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";
+import { agentDir } from "./state.ts";
+import { resolveProjectDir, runUpdater, type Deps } from "./updater.ts";
+import { appendUsageRow, readUsageRows, type UsageRow } from "./usage-ledger.ts";
 
 /** SPA directory shipped beside this extension (repo `web/`). */
 const WEB_DIR = fileURLToPath(new URL("../web", import.meta.url));
@@ -109,6 +112,93 @@ function applyProviderDisplayFor(ctx: ExtContext, selector?: string): void {
   }
 }
 
+/**
+ * Append one usage-ledger row per assistant turn in the session's branch
+ * (spec #81). The branch is the session's own record — the same entries the
+ * session jsonl persists — so each row carries the model, the provider, and the
+ * usage block omp billed. Rows already in the ledger (same timestamp + model)
+ * are skipped, so firing this on several events cannot double-record a turn.
+ *
+ * The ledger follows the plugin's state location: a project session records into
+ * `<cwd>/.omp`, so a project's usage stays separate from the user-level profile
+ * (the same dir the updater writes config/state/history to, and the same dir the
+ * role map is read from).
+ *
+ * Best-effort: a recording failure never breaks a session (and `appendUsageRow`
+ * never throws either).
+ */
+function recordUsage(ctx: ExtContext): void {
+  try {
+    const branch = ctx.sessionManager?.getBranch();
+    if (branch === undefined) return;
+    const dir = resolveProjectDir() ?? agentDir();
+    const roleByModel = configuredRoles(dir);
+    const seen = new Set(readUsageRows(dir).map((row) => `${row.ts}|${row.model}`));
+    for (const entry of branch) {
+      const row = usageRowOf(entry, roleByModel);
+      if (row === null) continue;
+      const key = `${row.ts}|${row.model}`;
+      if (seen.has(key)) continue;
+      seen.add(key);
+      appendUsageRow(dir, row);
+    }
+  } catch {
+    // best-effort: the ledger never owns a session's fate
+  }
+}
+
+/**
+ * The config's role→selector map inverted to model slug → role: a turn's
+ * `message.model` names the selector's ranking id, and `currentRankingId`
+ * strips the provider prefix, the `@pin`, and the `:level` from the configured
+ * selector, so the two join. The first role wins when two share a model; an
+ * unreadable config maps nothing, so every row's role is "".
+ */
+function configuredRoles(dir: string): Map<string, string> {
+  const byModel = new Map<string, string>();
+  let text: string;
+  try {
+    text = readFileSync(join(dir, "config.yml"), "utf8");
+  } catch {
+    return byModel;
+  }
+  for (const [role, selector] of Object.entries(parseConfig(text).modelRoles)) {
+    const id = currentRankingId(selector);
+    if (id !== "" && !byModel.has(id)) byModel.set(id, role);
+  }
+  return byModel;
+}
+
+/**
+ * The ledger row for one session branch entry: an assistant message carrying a
+ * usage block. Null for every other entry (user turns, tool results, custom
+ * entries) and for a message with no usage to record.
+ */
+function usageRowOf(entry: unknown, roleByModel: ReadonlyMap<string, string>): UsageRow | null {
+  if (!isRecord(entry) || entry.type !== "message") return null;
+  const message = entry.message;
+  if (!isRecord(message) || message.role !== "assistant" || typeof message.model !== "string") return null;
+  const usage = message.usage;
+  if (!isRecord(usage)) return null;
+  const cost = isRecord(usage.cost) ? usage.cost.total : 0;
+  return {
+    ts: typeof entry.timestamp === "string" ? entry.timestamp : new Date().toISOString(),
+    role: roleByModel.get(currentRankingId(message.model)) ?? "",
+    model: message.model,
+    provider: typeof message.provider === "string" ? message.provider : "",
+    input: usageNumber(usage.input),
+    output: usageNumber(usage.output),
+    cacheRead: usageNumber(usage.cacheRead),
+    cacheWrite: usageNumber(usage.cacheWrite),
+    cost: usageNumber(cost),
+  };
+}
+
+/** A usage field as a finite number; an absent field records 0. */
+function usageNumber(value: unknown): number {
+  return typeof value === "number" && Number.isFinite(value) ? value : 0;
+}
+
 /**
  * Apply a concrete selector (with thinking suffix) to the live session model
  * via the ExtensionAPI surface (`pi.setModel`/`pi.setThinkingLevel` — probed
@@ -461,6 +551,14 @@ export default function (pi: ExtensionAPI) {
     applyProviderDisplayFor(ctx);
   });
 
+  // Usage ledger (spec #81): one row per assistant turn, read from the session
+  // branch. turn_end records the turn that just finished; session_shutdown is
+  // the backstop for a headless one-turn run (a short-lived `omp -p` may exit
+  // before another turn_end). The file-side dedupe makes the second hook
+  // harmless.
+  pi.on("turn_end", async (_event, ctx: ExtContext) => recordUsage(ctx));
+  pi.on("session_shutdown", async (_event, ctx: ExtContext) => recordUsage(ctx));
+
   pi.registerCommand("refresh-roles", {
     description: "Refresh model roles from today's llm-stats/OpenRouter rankings",
     handler: async (_args, ctx: ExtContext) => {
@@ -508,6 +606,31 @@ export default function (pi: ExtensionAPI) {
             ? fetchKeyAvailability(token)
             : { active: false, reason: "unavailable", allowed: new Set(), blocked: new Set(), publicCount: 0, keyedCount: 0, fetchedAt: new Date().toISOString() };
         };
+        // Best-effort account-scoped inputs for the as-written pool: the key's
+        // tier gates the catalog, and the allowed-providers whitelist prunes the
+        // routes the account cannot call. The canary must be a CATALOG slug
+        // (`eligible[0].id`) — a ranking id 400s before the whitelist body, so
+        // the harvest would silently return nothing. Any failure (no key, an
+        // unreachable endpoint, no whitelist) degrades the pool to the raw
+        // dataset instead of blocking Explorer boot.
+        const loadPoolInputs = async (): Promise<{ tier: Tier; allowed: ReadonlySet<string> | null }> => {
+          const token = await ctx.modelRegistry.getApiKeyForProvider("openrouter").catch(() => undefined);
+          if (!token) return { tier: "billed", allowed: null };
+          let tier: Tier = "billed";
+          try {
+            tier = tierGate(await fetchKeyMeta(token));
+          } catch {
+            // an unreachable key endpoint leaves the ordinary account's tier
+          }
+          const canary = filterCatalog(catalog, tier)[0]?.id;
+          if (canary === undefined) return { tier, allowed: null };
+          try {
+            return { tier, allowed: await fetchAllowedProviders(token, canary) };
+          } catch {
+            return { tier, allowed: null };
+          }
+        };
+        const pool = await loadPoolInputs();
         explorer = await startExplorer({
           webDir: WEB_DIR,
           cwd: ctx.cwd,
@@ -515,6 +638,13 @@ export default function (pi: ExtensionAPI) {
           catalog,
           availability: await loadAvailability(),
           reloadAvailability: loadAvailability,
+          tier: pool.tier,
+          allowedProviders: pool.allowed,
+          reloadAllowedProviders: async () => (await loadPoolInputs()).allowed,
+          tokenProfile: resolveSettings(readPluginSettingsMap({ global: PLUGIN_SETTINGS_PATH, project: projectLockPath(ctx.cwd) })).settings.tokenProfile,
+          // The user-level ledger (the project scopes read their own
+          // `<root>/.omp` ledger, so the per-task column follows the scope).
+          usageDir: agentDir(),
           reload: (refresh) => loadRankData({ refresh, roles: explorerRoles(), extraMetrics: Object.keys(KNOWN_METRICS) }),
           port,
           open,

package/src/settings.ts

@@ -16,6 +16,7 @@ import { dirname, join } from "node:path";
 import { SUFFIX_LEVELS, type RoleDef } from "./engine.ts";
 import { FEATURES, expandFeatures, featureById } from "./features.ts";
 import { isRecord } from "./guards.ts";
+import type { TokenProfile } from "./usage-ledger.ts";
 
 /** User-level plugin settings lock file (the explorer's read/export target and
  * the default source for `readPluginSettingsMap`). */
@@ -244,6 +245,9 @@ export type ResolvedSettings = {
   /** Global capability flags (`features.<id>`); a role's `features.<id>` overrides
    * the global in either direction. Expanded per role by `resolveSettings`. */
   features: Record<string, boolean>;
+  /** Per-task token mix for the per-task price, used when the role has no
+   *  recorded usage. `null` = no profile (the per-task price is absent). */
+  tokenProfile: TokenProfile | null;
 };
 
 export const DEFAULT_SETTINGS: ResolvedSettings = {
@@ -255,6 +259,7 @@ export const DEFAULT_SETTINGS: ResolvedSettings = {
   activateDefaultOnEmptySession: true,
   errorReporting: "off",
   features: {},
+  tokenProfile: null,
 };
 
 /** One row of the plugin's settings schema (omp's `PluginSettingSchema`): the
@@ -312,6 +317,16 @@ export function deriveSettingsSchema(): Record<string, PluginSettingSchema> {
       default: DEFAULT_SETTINGS.errorReporting,
       values: ["off", "ask", "auto"],
     },
+    "tokenProfile.inputTokens": {
+      type: "number",
+      description: "Input tokens per task for the per-task price (used when the role has no recorded usage)",
+      min: 0,
+    },
+    "tokenProfile.outputTokens": {
+      type: "number",
+      description: "Output tokens per task for the per-task price (used when the role has no recorded usage)",
+      min: 0,
+    },
   };
   for (const row of FEATURES) {
     schema[`features.${row.id}`] = {
@@ -573,6 +588,22 @@ export function resolveSettings(raw: Record<string, unknown>): { settings: Resol
     errors.push(`errorReporting: must be one of off, ask, auto, got ${JSON.stringify(merged.errorReporting)}`);
   }
 
+  // The per-task token profile: null (no profile), or a record whose two counts
+  // are finite numbers >= 0. One error string per violation.
+  const tokenProfile: unknown = merged.tokenProfile;
+  if (tokenProfile !== null) {
+    if (!isRecord(tokenProfile)) {
+      errors.push(`tokenProfile: must be null or an object with inputTokens/outputTokens, got ${JSON.stringify(tokenProfile)}`);
+    } else {
+      for (const key of ["inputTokens", "outputTokens"] as const) {
+        const v = tokenProfile[key];
+        if (typeof v !== "number" || !Number.isFinite(v) || v < 0) {
+          errors.push(`tokenProfile.${key}: must be a number >= 0, got ${JSON.stringify(v)}`);
+        }
+      }
+    }
+  }
+
   // Global capability flags (`features.<id>`): an unknown id or a non-boolean
   // value aborts the run (a typo must never silently do nothing). A non-record
   // `features` is reset so the per-role expansion below always gets a map.

package/src/updater.ts

@@ -212,8 +212,13 @@ function writePatch(configPath: string, dir: string, patch: ConfigPatch): { stat
  * behavior applies. omp resolves the project dir as `<cwd>/.omp` with no
  * walk-up, so the plugin's project-scope read must use the same dir (not the
  * walk-up anchor `findProjectAnchor` returns).
+ *
+ * Exported as the one home for "where this session's plugin state lives": the
+ * updater scopes config/state/history/lock to it, and the extension records the
+ * usage ledger there too, so a project's usage is separate from the user-level
+ * profile.
  */
-function resolveProjectDir(): string | null {
+export function resolveProjectDir(): string | null {
   const projectDir = join(process.cwd(), ".omp");
   const raw = readPluginSettingsMap({ global: join(projectDir, "plugins", "omp-plugins.lock.json"), project: null });
   return Object.keys(raw).length > 0 ? projectDir : null;

package/src/usage-ledger.ts

@@ -0,0 +1,127 @@
+/**
+ * The per-role usage ledger — an append-only jsonl file beside the plugin's
+ * state, one row per recorded assistant turn, and the token profile derived
+ * from it.
+ *
+ * - `llm-role-usage.jsonl` — one row per turn (role, model, provider, token
+ *   counts, cost). Bounded to `USAGE_LEDGER_CAP` rows: the normal path is a
+ *   single append; an over-cap file is compacted to its newest rows via a temp
+ *   file + atomic rename, so a crash mid-compaction leaves the original intact.
+ * - Recording is best-effort: a failure never breaks a session.
+ *
+ * The per-task price resolves its token profile from the recorded usage first
+ * (the role's median per-turn counts), then the user-set `tokenProfile` setting.
+ */
+
+import { appendFileSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { quantile } from "./agent-create.ts";
+import { isRecord } from "./guards.ts";
+
+export type UsageRow = {
+  ts: string;
+  role: string;
+  model: string;
+  provider: string;
+  input: number;
+  output: number;
+  cacheRead: number;
+  cacheWrite: number;
+  cost: number;
+};
+
+export type TokenProfile = { inputTokens: number; outputTokens: number };
+
+export const USAGE_LEDGER_FILE = "llm-role-usage.jsonl";
+export const USAGE_LEDGER_CAP = 2000;
+
+const STRING_FIELDS = ["ts", "role", "model", "provider"] as const;
+const NUMBER_FIELDS = ["input", "output", "cacheRead", "cacheWrite", "cost"] as const;
+
+/** A parsed line is a row only when every field is present with the right type;
+ *  anything else is a malformed line the reader skips. */
+function toUsageRow(v: unknown): UsageRow | null {
+  if (!isRecord(v)) return null;
+  for (const k of STRING_FIELDS) if (typeof v[k] !== "string") return null;
+  for (const k of NUMBER_FIELDS) if (typeof v[k] !== "number" || !Number.isFinite(v[k])) return null;
+  return {
+    ts: v.ts as string,
+    role: v.role as string,
+    model: v.model as string,
+    provider: v.provider as string,
+    input: v.input as number,
+    output: v.output as number,
+    cacheRead: v.cacheRead as number,
+    cacheWrite: v.cacheWrite as number,
+    cost: v.cost as number,
+  };
+}
+
+/** Keep the newest `USAGE_LEDGER_CAP` rows: temp file + atomic rename, so a
+ *  crash mid-compaction leaves the original file intact. */
+function compactIfOverCap(dir: string, path: string): void {
+  const lines = readFileSync(path, "utf8")
+    .split("\n")
+    .filter((l) => l.length > 0);
+  if (lines.length <= USAGE_LEDGER_CAP) return;
+  const tmp = join(dir, `${USAGE_LEDGER_FILE}.tmp`);
+  writeFileSync(tmp, `${lines.slice(-USAGE_LEDGER_CAP).join("\n")}\n`);
+  renameSync(tmp, path);
+}
+
+/** Append one row; best-effort — a recording failure never throws. */
+export function appendUsageRow(dir: string, row: UsageRow): void {
+  try {
+    mkdirSync(dir, { recursive: true });
+    const path = join(dir, USAGE_LEDGER_FILE);
+    appendFileSync(path, `${JSON.stringify(row)}\n`);
+    compactIfOverCap(dir, path);
+  } catch {
+    // best-effort: never break a session over a ledger write
+  }
+}
+
+/** Tolerant read: a missing, unreadable, or malformed file degrades to []; an
+ *  unparseable or wrongly-shaped line is skipped. */
+export function readUsageRows(dir: string): UsageRow[] {
+  let text: string;
+  try {
+    text = readFileSync(join(dir, USAGE_LEDGER_FILE), "utf8");
+  } catch {
+    return [];
+  }
+  const rows: UsageRow[] = [];
+  for (const line of text.split("\n")) {
+    if (line.length === 0) continue;
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    const row = toUsageRow(parsed);
+    if (row) rows.push(row);
+  }
+  return rows;
+}
+
+/** The role's median per-turn input/output counts, or null when it has no rows.
+ *  The median is `agent-create.ts`'s `quantile(values, 0.5)` — the repo's one
+ *  quantile convention (linear interpolation), not a second implementation. */
+export function roleTokenProfile(rows: readonly UsageRow[], role: string): TokenProfile | null {
+  const mine = rows.filter((r) => r.role === role);
+  if (mine.length === 0) return null;
+  return {
+    inputTokens: quantile(mine.map((r) => r.input), 0.5),
+    outputTokens: quantile(mine.map((r) => r.output), 0.5),
+  };
+}
+
+/** Precedence: the recorded usage, then the user-set setting, then null. */
+export function resolveTokenProfile(
+  role: string,
+  rows: readonly UsageRow[],
+  setting: TokenProfile | null,
+): TokenProfile | null {
+  return roleTokenProfile(rows, role) ?? setting;
+}

package/web/app.js

@@ -23,6 +23,11 @@ const state = {
   lockPath: "",
   scopes: [],
   activeScope: "",
+  // The ranked pool the server is serving (raw | as-written) and the user-set
+  // token profile the per-task price falls back to (null = unset). Both come
+  // from the bootstrap payload, so a refresh keeps them.
+  poolMode: "raw",
+  tokenProfile: null,
   features: {},
   featureRegistry: [],
   filter: "",
@@ -82,6 +87,26 @@ function fmtCtx(value) {
   return value >= 1000 ? Math.round(value / 1000) + "K" : String(value);
 }
 
+/** Dollars per task, at a precision that keeps the small values readable: a
+ * per-task price spans roughly $0.0001 (a cheap model, a short task) to $1+. */
+function fmtUsd(value) {
+  if (value === null || value === undefined) return "—";
+  const abs = Math.abs(value);
+  if (abs >= 1) return "$" + value.toFixed(2);
+  if (abs >= 0.01) return "$" + value.toFixed(3);
+  if (abs > 0) return "$" + value.toFixed(4);
+  return "$0";
+}
+
+/** Token counts, compact: 20000 → "20K", 1500 → "1.5K", 800 → "800". */
+function fmtTokens(value) {
+  if (value >= 1000) {
+    const k = value / 1000;
+    return (k >= 10 ? Math.round(k) : Math.round(k * 10) / 10) + "K";
+  }
+  return String(value);
+}
+
 function deltaText(delta) {
   if (delta === null || delta === undefined || delta === 0) return "·";
   return delta > 0 ? "+" + delta : "−" + Math.abs(delta);
@@ -121,6 +146,7 @@ const TIPS = {
   hideBlocked: "Drop rows your OpenRouter key cannot run (key = blocked). Applied after the text filter and the top-n slice.",
   lock: "Plugin settings lock file that Export writes to (the active scope's lock file).",
   scope: "Role-config source: the user-level scope, or a project where /project-roles was used. Switching re-reads that scope's roles and universe from disk and points Export at its lock file. A project whose lock file is gone is unavailable.",
+  pool: "Ranked pool. raw = the full cached dataset (account-agnostic). as-written = the same catalog/tier gate and allowed-providers whitelist prune the updater applies before writing, so the leader you see is the model you will get. Best-effort: a failed whitelist fetch degrades to the raw pool. Export is unaffected — it always writes the authored role.",
   refresh: "Refetch llm-stats and OpenRouter data (hits the network).",
   rank: "Rank among this role's eligible models, by value, descending.",
   delta: "Rank change against the role's saved (effective) definition: + means this definition ranks the model higher than the plugin does today.",
@@ -128,6 +154,7 @@ const TIPS = {
   value: "Sort key: value = q − λ·$/M on the thinking-adjusted effective price. λ is the price of one quality point, in $/M.",
   q: "Quality q = Σ (wᵢ/(1−w_price))·tᵢ over the weighted quality metrics. Price is not blended in — it is the penalty axis.",
   price: "Effective price in $/M: OpenRouter standard-route blend (3:1 in:out) scaled by the role's thinking factor when the model supports thinking; unadjusted for bare/off roles.",
+  perTask: "Dollars per task: your own token mix (the role's recorded usage, else the tokenProfile setting) × the role's priced route, thinking-adjusted. Display-only — the ranking still sorts on $/M. — when no token profile is available (no recorded usage and no tokenProfile set).",
   throughput: "Output throughput in tok/s (OpenRouter p50 when matched, else llm-stats).",
   context: "Context window in tokens.",
   explainSub: "value = q − λ·$/M (effective price), where q is the weighted quality sum and λ the price of one quality point.",
@@ -141,6 +168,9 @@ const TIPS = {
   whyNotHigher: "The value gap to the model ranked above, and the per-metric raw target that would close it (inverse of the cardinal transform).",
   dominated: "Models that are both cheaper and at least as good on q.",
   lambda: "λ = price of one quality point, in $/M. Derived as " + LAMBDA_DERIVATION + " unless the role overrides lambda.",
+  leaderFlip: "The price weight w* at which a cheaper challenger overtakes the value leader: λ* = min over cheaper challengers X of (q_L − q_X)/(pEff_L − pEff_X), then w* = 20λ*/(1+20λ*). Absent when no cheaper challenger exists. Exact for the 1/price² blend or a hard provider pin; a first-order estimate under the soft best-route basis (the route choice itself moves with the price weight).",
+  levers: "Two price-lever readouts, computed on the pool you are viewing: the leader-flip threshold (the price weight at which a cheaper challenger overtakes the leader) and the thinking level's effect on the leader. Each is absent when the server sends null — no cheaper challenger, or a bare role.",
+  thinkingLevels: "The leader at each thinking level, with the level's price factor (3ρ+1+T)/(3ρ+1). The factor multiplies the price axis, so it penalizes expensive models more in absolute λ-units — that is why auto favours the cheap model. Absent for a bare role (no thinking level).",
   sum: "Weights must sum to 1.0 (±0.01) or the plugin rejects the role.",
   required: "Eligibility gate, not a weight: a model missing this metric is not ranked at all for the role.",
   focus: "Nine-axis audit of each weighted benchmark/percentile metric, over the same pool the updater ranks on. A below-bar axis is warned; unknown means the metric's scores were not loaded (never a silent ok).",
@@ -267,6 +297,20 @@ function scopeSelect() {
   return sel;
 }
 
+/** The pool selector: the raw dataset (account-agnostic) or the as-written pool
+ * (the catalog/tier gate + allowed-providers prune the updater ranks on). The
+ * value is the server's mode, so the header always names the active pool. */
+function poolSelect() {
+  const sel = el("select", { id: "pool", "data-tip": TIPS.pool });
+  sel.append(
+    el("option", { value: "raw", text: "raw pool" }),
+    el("option", { value: "as-written", text: "as-written pool" }),
+  );
+  sel.value = state.poolMode;
+  sel.addEventListener("change", onPoolChange);
+  return sel;
+}
+
 function renderMeta(data) {
   const meta = document.getElementById("meta");
   meta.textContent = "";
@@ -275,6 +319,8 @@ function renderMeta(data) {
     el("span", { class: "sep", text: "·" }),
     scopeSelect(),
     el("span", { class: "sep", text: "·" }),
+    poolSelect(),
+    el("span", { class: "sep", text: "·" }),
     el("span", { "data-tip": TIPS.models, text: data.modelCount + " models" }),
     el("span", { class: "sep", text: "·" }),
     el("span", { "data-tip": TIPS.fetched, text: "fetched " + data.fetchedAt.slice(0, 10) }),
@@ -426,6 +472,7 @@ function renderTable() {
       el("th", { class: "num", "data-tip": TIPS.value, text: "value" }),
       el("th", { class: "num", "data-tip": TIPS.q, text: "q" }),
       el("th", { class: "num", "data-tip": TIPS.price, text: "$/M" }),
+      el("th", { class: "num", "data-tip": TIPS.perTask, text: "$/task" }),
       el("th", { class: "num", "data-tip": TIPS.throughput, text: "tok/s" }),
       el("th", { class: "num", "data-tip": TIPS.context, text: "ctx" }),
     ])),
@@ -450,6 +497,7 @@ function renderTable() {
         el("td", { class: "num", text: fmt(r.value, 3) }),
         el("td", { class: "num", text: fmt(r.q, 3) }),
         el("td", { class: "num", text: fmt(r.priceEff, 2) }),
+        el("td", { class: "num", text: fmtUsd(r.perTask) }),
         el("td", { class: "num", text: r.throughput === null ? "—" : fmt(r.throughput, 0) }),
         el("td", { class: "num", text: r.context === null ? "—" : fmtCtx(r.context) }),
       ]),
@@ -562,6 +610,23 @@ function renderExplain() {
   const ownNote = ex.ownProvider ? " · best route" : "";
   panel.append(el("p", { class: "cost", "data-tip": TIPS.costPenalty, text: "eff price $" + fmt(ex.cost.priceEff, 2) + "/M" + (ex.cost.priceEff !== ex.cost.billedPrice ? " (billed $" + fmt(ex.cost.billedPrice, 2) + " × " + thinkNote + ")" : " (" + thinkNote + ")") + cacheNote + ownNote + " · penalty = λ·price = " + fmt(ex.cost.penalty, 4) + " · value = q − penalty = " + fmt(ex.cost.value, 4) }));
 
+  // The per-task price breakdown: display-only, so it sits apart from the
+  // ranking's cost line. A muted note when no token profile resolved (never a
+  // silent zero).
+  panel.append(el("h3", { "data-tip": TIPS.perTask, text: "Per-task price" }));
+  if (ex.perTask) {
+    const p = ex.perTask;
+    panel.append(
+      el("p", {
+        class: "cost",
+        "data-tip": TIPS.perTask,
+        text: "per task: " + fmtTokens(p.inputTokens) + " in × $" + fmt(p.inputPrice, 3) + "/M + " + fmtTokens(p.outputTokens) + " out × $" + fmt(p.outputPrice, 3) + "/M × " + p.thinkingFactor.toFixed(3) + " = " + fmtUsd(p.total),
+      }),
+    );
+  } else {
+    panel.append(el("p", { class: "cost muted", "data-tip": TIPS.perTask, text: "per task: — (no token profile — record usage or set tokenProfile)" }));
+  }
+
   panel.append(el("h3", { "data-tip": TIPS.whyNotHigher, text: "Why not higher" }));
   if (ex.gapAbove === null) {
     panel.append(el("p", { class: "muted", text: "Already #1 for this role." }));
@@ -593,6 +658,53 @@ function renderExplain() {
     for (const d of ex.dominators) ul.append(el("li", { text: d.name + " — $" + fmt(d.priceEff, 2) + "/M, q " + fmt(d.q, 3) }));
     panel.append(ul);
   }
+
+  // The two price-lever readouts are role-level (computed on the pool the
+  // ranking above uses), so they close the panel. Each is absent when the
+  // server sends null: no cheaper challenger, or a bare role.
+  const flip = ex.leaderFlip;
+  const levels = ex.thinkingLevels;
+  if (flip || levels) {
+    panel.append(el("h3", { "data-tip": TIPS.levers, text: "Price levers" }));
+    if (flip) {
+      const ratio = flip.wPrice > 0 ? (flip.flipW / flip.wPrice).toFixed(2) + "×" : "—";
+      panel.append(
+        el("p", {
+          class: "cost",
+          "data-tip": TIPS.leaderFlip,
+          text: "leader flip: w* = " + flip.flipW.toFixed(3) + " · now " + flip.wPrice.toFixed(3) + " · distance " + (flip.distance >= 0 ? "+" : "−") + Math.abs(flip.distance).toFixed(3) + " (" + ratio + ")",
+        }),
+      );
+      panel.append(
+        el("p", {
+          class: "cost",
+          text: "challenger: " + flip.challenger.name + " — $" + fmt(flip.challenger.priceEff, 2) + "/M, value " + fmt(flip.challenger.value, 3),
+        }),
+      );
+    }
+    if (levels) {
+      const t = el("table", { class: "comp" });
+      t.append(
+        el("thead", {}, el("tr", {}, [
+          el("th", { text: "level" }),
+          el("th", { class: "num", "data-tip": TIPS.thinking, text: "×price" }),
+          el("th", { "data-tip": TIPS.thinkingLevels, text: "leader" }),
+        ])),
+      );
+      const tb = el("tbody");
+      for (const row of levels) {
+        tb.append(
+          el("tr", { class: row.level === ex.role.thinking ? "active-level" : "" }, [
+            el("td", { text: row.level }),
+            el("td", { class: "num", text: "×" + row.factor.toFixed(3) }),
+            el("td", { text: row.leader ? row.leader.name + " (" + fmt(row.leader.value, 3) + ")" : "—" }),
+          ]),
+        );
+      }
+      t.append(tb);
+      panel.append(t);
+    }
+  }
 }
 
 // ---------------------------------------------------------------------------
@@ -1185,6 +1297,24 @@ async function onScopeChange(event) {
   }
 }
 
+/** Switch the ranked pool (raw ↔ as-written). Unsaved edits are confirmed first
+ * (mirroring the scope switcher); the returned payload rebuilds every panel, so
+ * the header's model count and the table describe the new pool. */
+async function onPoolChange(event) {
+  const mode = event.target.value;
+  if (mode === state.poolMode) return;
+  if (Object.keys(dirtyRoles()).length > 0 && !confirm("Discard unsaved role edits and switch pool?")) {
+    event.target.value = state.poolMode;
+    return;
+  }
+  try {
+    applyBootstrap(await api("/api/pool", { mode }));
+  } catch (err) {
+    alert("Pool switch failed: " + err.message);
+    event.target.value = state.poolMode;
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Boot
 // ---------------------------------------------------------------------------
@@ -1196,6 +1326,8 @@ function applyBootstrap(data) {
   const previousRole = state.role;
   state.scopes = data.scopes || [];
   state.activeScope = data.activeScope;
+  state.poolMode = data.poolMode || "raw";
+  state.tokenProfile = data.tokenProfile ?? null;
   state.universe = data.universe;
   state.effective = {};
   for (const [name, entry] of Object.entries(state.universe)) state.effective[name] = entry.def;

package/web/style.css

@@ -39,6 +39,7 @@ body {
 #meta .sep { color: var(--line); }
 #meta .lock { color: var(--muted); font-family: var(--mono); font-size: 11px; }
 #meta #scope { max-width: 340px; }
+#meta #pool { max-width: 200px; }
 #meta button { margin-left: auto; }
 
 #roles {
@@ -189,6 +190,8 @@ table.comp th { text-align: left; color: var(--muted); font-weight: 500; font-si
 table.comp td.num, table.comp th.num { text-align: right; font-family: var(--mono); font-variant-numeric: tabular-nums; }
 table.comp tr.missing-row td { color: var(--muted); }
 table.comp tr.note-row td { border-bottom: none; font-size: 11px; padding-top: 0; }
+/* The thinking-level readout: the role's current level is the row that matters. */
+table.comp tr.active-level td { color: var(--accent); }
 
 /* Focus-metric audit: one row per weighted benchmark/percentile metric, four
    signal cells. ok = up, below-bar = warn + glyph, unknown = muted (never ok). */