omp-llm-role 1.1.0 → 1.3.0

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);
+  }
+}

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}`] = {
@@ -359,7 +374,7 @@ export function deriveSettingsSchema(): Record<string, PluginSettingSchema> {
     }
     schema[`${p}.preferOwnProvider`] = {
       type: "boolean",
-      description: `Price ${name} models on their own lab's route where one exists (soft preference; never drops a model)`,
+      description: `Bind ${name} requests to each model's best provider route (soft preference; never drops a model)`,
       default: false,
     };
     schema[`${p}.required`] = {
@@ -395,6 +410,12 @@ export function deriveSettingsSchema(): Record<string, PluginSettingSchema> {
       default: def.filters?.maxPriceUsdPerM ?? 0,
       min: 0,
     };
+    schema[`${p}.filters.preferredMinThroughput`] = {
+      type: "number",
+      description: `Soft throughput floor for ${name} routes (tok/s; 0 = off) — a below-floor route sorts last but is never dropped`,
+      default: def.filters?.preferredMinThroughput ?? 0,
+      min: 0,
+    };
     schema[`${p}.lambda`] = {
       type: "number",
       description: `Explicit λ ($ per quality point) override for ${name}`,
@@ -567,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.
@@ -647,7 +684,7 @@ export function resolveSettings(raw: Record<string, unknown>): { settings: Resol
         if (rdef.filters.tools !== undefined && typeof rdef.filters.tools !== "boolean") {
           errors.push(`role ${name}: filters.tools must be a boolean`);
         }
-        for (const key of ["minContextTokens", "minOutputTokens", "maxPriceUsdPerM"] as const) {
+        for (const key of ["minContextTokens", "minOutputTokens", "maxPriceUsdPerM", "preferredMinThroughput"] as const) {
           const v = rdef.filters[key];
           if (v !== undefined && (typeof v !== "number" || !Number.isFinite(v) || v < 0)) {
             errors.push(`role ${name}: filters.${key} must be a number ≥ 0`);

package/src/updater.ts

@@ -15,8 +15,8 @@
 
 import { readFileSync, statSync } from "node:fs";
 import { dirname, join } from "node:path";
-import { computeRankings, endpointFilterDrops, loadRankData, META_LEVELS, providerPinDrops, type Ranked, type RankData } from "./engine.ts";
-import { currentRankingId, enrichThinkingLevels, fetchKeyAvailability, fetchKeyMeta, filterCatalog, probeModel, resolveVariant, THINKING_LEVELS, tierGate, type CatalogEntry, type KeyAvailability, type KeyMeta, type ProbeVerdict } from "./availability.ts";
+import { autoPinApplies, bestRoute, computeRankings, endpointFilterDrops, loadRankData, META_LEVELS, providerPinDrops, rankedRoutes, type Ranked, type RankData, type RoleDef } from "./engine.ts";
+import { currentRankingId, enrichThinkingLevels, fetchAllowedProviders, fetchKeyAvailability, fetchKeyMeta, filterCatalog, probeModel, providerAllowed, resolveVariant, THINKING_LEVELS, tierGate, type CatalogEntry, type KeyAvailability, type KeyMeta, type ProbeVerdict } from "./availability.ts";
 import { ConfigEditError, parseConfig, patchConfig, writeConfigAtomic, type ConfigPatch } from "./config-edit.ts";
 import { PLUGIN_SETTINGS_PATH, projectLockPath, readPluginSettingsMap, resolveSettings, roleUniverse, type ResolvedSettings } from "./settings.ts";
 import { discoverAgentPins } from "./agent-pins.ts";
@@ -68,6 +68,11 @@ export type Trigger = "session-start" | "manual";
 /** A ranked model resolved to a concrete catalog id. */
 type Candidate = { ranked: Ranked; catalogId: string };
 
+/** Per managed role: its bare chain key, role suffix, provider pin, the pool it
+ * was chosen from, and the inputs the auto-pin chain builder needs (the expanded
+ * def for `rankedRoutes`, and whether the pin was auto-derived). */
+type ChainPlan = { key: string; suffix: string | undefined; pin: string; pool: Candidate[]; chosenIdx: number; def: RoleDef; autoPin: boolean };
+
 export type Deps = {
   getToken(): Promise<string>;
   getCatalog(): Promise<CatalogEntry[]>;
@@ -80,6 +85,13 @@ export type Deps = {
   probeModel?(token: string, catalogId: string): Promise<ProbeVerdict>;
   /** DI seam like `getKeyMeta`/`probeModel`; production defaults to `fetchKeyAvailability` (never throws). */
   getKeyAvailability?(token: string): Promise<KeyAvailability>;
+  /**
+   * DI seam like `getKeyAvailability`; production defaults to
+   * `fetchAllowedProviders` (never throws). Returns the account's
+   * allowed-providers privacy whitelist, or null when there is none (or the
+   * harvest failed) — a null result leaves every route pool untouched.
+   */
+  getAllowedProviders?(token: string, modelId: string): Promise<Set<string> | null>;
   /**
    * Host coupling (extension only): apply a concrete selector to the live
    * session model. Receives the final `default` selector (with thinking
@@ -200,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;
@@ -319,9 +336,38 @@ export async function runUpdater(trigger: Trigger, deps: Deps, opts?: { force?:
         `omp-llm-role: OpenRouter keyed catalog ${availability.reason === "no-filter" ? "not filtering" : "unavailable"} — enable OpenRouter → Settings → "Filter the model catalog for API keys" to skip probing key-blocked models; the probe walk is still in use`,
       );
     }
+
+    // Allowed-providers privacy whitelist (spec #65): harvested once per run
+    // with a valid catalog model id (the canary 404s, so it bills no tokens).
+    // The whitelist is invisible to /api/v1/key and the catalog endpoints, so a
+    // route on a provider outside it would be written into config.yml and 404
+    // at request time. Pruning every model's route pool to allowed providers
+    // before ranking makes the soft basis, the auto-pin and the fallback chains
+    // whitelist-aware through the single `m.routes` seam. A null result (no
+    // whitelist set / harvest failed) leaves the pools untouched.
+    const canaryModelId = eligible[0]?.id;
+    const allowed =
+      canaryModelId === undefined
+        ? null
+        : await (deps.getAllowedProviders ? deps.getAllowedProviders(token, canaryModelId) : fetchAllowedProviders(token, canaryModelId));
+    if (allowed !== null) {
+      let prunedCount = 0;
+      const pruned = rank.models.map((m) => {
+        const routes = m.routes;
+        if (routes === undefined) return m;
+        const kept = routes.filter((r) => providerAllowed(allowed, r.providerSlug));
+        prunedCount += routes.length - kept.length;
+        return { ...m, routes: kept };
+      });
+      rank = { ...rank, models: pruned };
+      notes.push(
+        `omp-llm-role: OpenRouter allowed-providers whitelist active — ${allowed.size} providers; ${prunedCount} routes pruned`,
+      );
+    } else {
+      notes.push(`omp-llm-role: OpenRouter allowed-providers whitelist: no whitelist`);
+    }
     const poolByRole: Record<string, Candidate[]> = {};
-    /** Per managed role: its bare chain key, role suffix, provider pin, and the pool it was chosen from. */
-    const chainPlanByRole: Record<string, { key: string; suffix: string | undefined; pin: string; pool: Candidate[]; chosenIdx: number }> = {};
+    const chainPlanByRole: Record<string, ChainPlan> = {};
     /** Roles whose `providerPin` matched no route: left unchanged, their current chain preserved. */
     const pinUnmatched: string[] = [];
     const probe = deps.probeModel ?? probeModel;
@@ -436,7 +482,16 @@ export async function runUpdater(trigger: Trigger, deps: Deps, opts?: { force?:
       // thinking level (`openrouter/<id>@<slug>:<level>`) — omp's
       // `splitUpstreamRouting` parses the trailing `@<slug>` and applies
       // `compat.openRouterRouting = { only: [slug] }`.
-      const pin = def.providerPin !== undefined ? `@${def.providerPin}` : "";
+      //
+      // Auto-pin (spec #58): with the soft `preferOwnProvider` capability on and
+      // no manual pin, the chosen model's best route by the role's own value
+      // rides as that suffix, so the price the ranking assumed is the price the
+      // request pays. A manual `providerPin` is a hard gate and always wins; a
+      // model with no candidate route keeps default routing (bare selector).
+      const manualPin = def.providerPin;
+      const autoRoute = autoPinApplies(def) ? bestRoute(chosen.ranked.model, def) : null;
+      const pinSlug = manualPin ?? autoRoute?.providerSlug;
+      const pin = pinSlug !== undefined ? `@${pinSlug}` : "";
       const chosenRow = rowById.get(chosen.catalogId);
       // Append only a level the model's catalog thinking[] actually supports —
       // omp clamps unsupported levels, so an unsupported pin would run at a
@@ -463,7 +518,7 @@ export async function runUpdater(trigger: Trigger, deps: Deps, opts?: { force?:
       // came from. Values are built after the loop, once every key claim is known.
       if (settings.writeFallbackChains) {
         const key = suffix !== undefined && finalSelector.endsWith(`:${suffix}`) ? finalSelector.slice(0, -(suffix.length + 1)) : finalSelector;
-        chainPlanByRole[role] = { key, suffix, pin, pool, chosenIdx: pool.indexOf(chosen) };
+        chainPlanByRole[role] = { key, suffix, pin, pool, chosenIdx: pool.indexOf(chosen), def, autoPin: autoRoute !== null };
       }
     }
 
@@ -492,13 +547,41 @@ export async function runUpdater(trigger: Trigger, deps: Deps, opts?: { force?:
         const cheaper = after.filter((p) => p.ranked.priceEff <= chosenPrice);
         const pricier = after.filter((p) => p.ranked.priceEff > chosenPrice);
         const chainPool = [...cheaper, ...pricier].slice(0, settings.fallbackChainDepth);
-        chainUpserts[plan.key] = [
-          ...new Set(chainPool.map((p) => {
-            const row = rowById.get(p.catalogId);
-            const level = suffix !== undefined && row !== undefined && (META_LEVELS[suffix] === true || row.thinking.includes(suffix)) ? `:${suffix}` : "";
-            return `openrouter/${p.catalogId}${plan.pin}${level}`;
-          })),
-        ].filter((v) => v !== plan.key);
+        // A chain value's thinking level is appended only when the target's
+        // catalog entry advertises support (or the level is a meta level).
+        const levelFor = (catalogId: string): string => {
+          const row = rowById.get(catalogId);
+          return suffix !== undefined && row !== undefined && (META_LEVELS[suffix] === true || row.thinking.includes(suffix)) ? `:${suffix}` : "";
+        };
+        const values: string[] = [];
+        if (plan.autoPin) {
+          // Auto-pin chain (spec #58, expanded by #69): every gate-passing route
+          // of the primary model (all but the pinned best), then every
+          // gate-passing route of each fallback model, in the role's
+          // value-for-money score order (`rankedRoutes`, spec #71) — every entry
+          // bound to its route's provider, so a down primary
+          // provider falls back to the same model on another provider rather
+          // than a different model. `rankedRoutes` already applies every gate
+          // (non-degraded, endpoint filters, usable billed price, the
+          // maxPriceUsdPerM cap, the allowed-providers whitelist), so the chain
+          // carries exactly the routes the role can use. The dedup below
+          // collapses two routes that share a provider slug (same chain value),
+          // so the chain length is (R_primary − 1) + Σ R_fallback over distinct
+          // gate-passing provider slugs.
+          const chosenCandidate = plan.pool[plan.chosenIdx];
+          for (const r of rankedRoutes(chosenCandidate.ranked.model, plan.def).slice(1)) {
+            values.push(`openrouter/${chosenCandidate.catalogId}@${r.providerSlug}${levelFor(chosenCandidate.catalogId)}`);
+          }
+          for (const p of chainPool) {
+            for (const r of rankedRoutes(p.ranked.model, plan.def)) {
+              values.push(`openrouter/${p.catalogId}@${r.providerSlug}${levelFor(p.catalogId)}`);
+            }
+          }
+        } else {
+          // Manual pin (every value carries it) or no pin (bare values).
+          for (const p of chainPool) values.push(`openrouter/${p.catalogId}${plan.pin}${levelFor(p.catalogId)}`);
+        }
+        chainUpserts[plan.key] = [...new Set(values)].filter((v) => v !== plan.key);
         referenced.add(plan.key);
       }
       // Locked roles keep their current chain: the plugin neither rewrites nor

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;
+}