pi-pignon 0.1.1

package/src/policy.ts

@@ -0,0 +1,215 @@
+/**
+ * Pure routing policy.
+ *
+ * No I/O, no Pi dependencies — the only thing to unit-test.
+ */
+
+import { DEFAULT_CONFIG, DEFAULT_THRESHOLDS } from "./config/defaults.js";
+import {
+  type Form,
+  type ModelSpec,
+  type PolicyInput,
+  type PolicyOutput,
+  type Price,
+  type Profile,
+  type RoutingDecision,
+  type RoutingTable,
+  FORMS,
+} from "./types.js";
+
+/** Derive the task form from a decision. */
+export function formOf(
+  decision: RoutingDecision,
+  minConfidenceForm = DEFAULT_THRESHOLDS.minConfidenceForm,
+): Form {
+  if (!decision.needsExploration && decision.explorationConfidence >= minConfidenceForm) {
+    return "direct";
+  }
+  return "exploration";
+}
+
+/**
+ * Given a Laya decision, the current profile, and context metadata,
+ * decide whether to switch models and to which profile.
+ *
+ * Upgrades are quality-driven: only tier confidence gates them. Every other
+ * switch (downgrade, lateral, or moving in from a model outside the table)
+ * must also get past the cooldown and the switch-cost check, because it
+ * throws away the current prompt cache.
+ *
+ * Fail-open: any missing or ambiguous signal keeps the current model.
+ */
+export function decide(input: PolicyInput): PolicyOutput {
+  const { decision, current, contextTokens, promptsSinceSwitch, config = DEFAULT_CONFIG } = input;
+  const { table, thresholds } = config;
+
+  // Fail-open : no usable decision -> do nothing.
+  if (!decision || decision.tier === null) {
+    return { target: null, reason: "no decision" };
+  }
+
+  const form = formOf(decision, thresholds.minConfidenceForm);
+  let rank = rankOf(table, decision.tier);
+  if (rank < 0) {
+    return { target: null, reason: `unknown tier ${decision.tier}` };
+  }
+
+  // Some tiers (typically the cheapest) are too weak for the long tool loop
+  // of an exploration task, whatever its reasoning demand: move up to the
+  // first tier that takes it.
+  if (form === "exploration" && !table[rank]!.explorationAllowed) {
+    const next = table.findIndex((t, i) => i > rank && t.explorationAllowed);
+    if (next >= 0) rank = next;
+  }
+
+  const tier = table[rank]!.id;
+  const target: Profile = { tier, form };
+  const targetSpec = table[rank]!.models[form];
+
+  const currentRank = current ? rankOf(table, current.tier) : -1;
+  const currentSpec = currentRank >= 0 ? table[currentRank]!.models[current!.form] : undefined;
+
+  // Several cells may share a model: compare what would actually run.
+  if (currentSpec && sameSpec(currentSpec, targetSpec)) {
+    return { target: null, reason: "already on target model" };
+  }
+
+  const move = currentRank < 0
+    ? "enter"
+    : rank > currentRank
+      ? "upgrade"
+      : rank < currentRank
+        ? "downgrade"
+        : "lateral";
+  const label = current ? `${current.tier} -> ${tier} (${form})` : `${tier}/${form}`;
+
+  if (move === "upgrade") {
+    if (decision.tierConfidence < thresholds.minConfidenceUpgrade) {
+      return {
+        target: null,
+        reason: `confidence ${decision.tierConfidence.toFixed(2)} < upgrade threshold`,
+      };
+    }
+    return { target, reason: `upgrade ${label}` };
+  }
+
+  // Moving in from an unrouted model may be an upgrade or a downgrade: apply
+  // the stricter (downgrade) threshold.
+  if (move !== "lateral" && decision.tierConfidence < thresholds.minConfidenceDowngrade) {
+    const threshold = move === "enter" ? "entry" : "downgrade";
+    return {
+      target: null,
+      reason: `confidence ${decision.tierConfidence.toFixed(2)} < ${threshold} threshold`,
+    };
+  }
+
+  // Hysteresis: do not flap between models on consecutive prompts.
+  if (promptsSinceSwitch !== undefined && promptsSinceSwitch < thresholds.minPromptsBetweenSwitches) {
+    return {
+      target: null,
+      reason: `cooldown: ${promptsSinceSwitch} prompt(s) since last switch`,
+    };
+  }
+
+  const contextK = `${Math.round(contextTokens / 1_000)}k`;
+
+  // Lateral switches are about fit, not price: only the flat guard applies.
+  if (move === "lateral") {
+    if (contextTokens > thresholds.cacheGuardTokens) {
+      return { target: null, reason: `lateral blocked: context ${contextK}` };
+    }
+    return { target, reason: `lateral ${current!.form} -> ${form}` };
+  }
+
+  const currentPrice = knownPrice(input.currentPrice);
+  const targetPrice = knownPrice(input.priceOf?.(targetSpec));
+
+  if (currentPrice && targetPrice) {
+    const payback = paybackRequests(
+      currentPrice,
+      targetPrice,
+      contextTokens,
+      thresholds.assumedOutputTokensPerRequest,
+    );
+    if (payback > thresholds.maxPaybackRequests) {
+      const detail = Number.isFinite(payback)
+        ? `pays back in ${payback.toFixed(1)} requests > ${thresholds.maxPaybackRequests}`
+        : "target is not cheaper";
+      return { target: null, reason: `context ${contextK}: ${detail}` };
+    }
+    return { target, reason: `${move} ${label}, pays back in ${payback.toFixed(1)} requests` };
+  }
+
+  // Prices unknown: fall back to the flat context guard.
+  if (contextTokens > thresholds.cacheGuardTokens) {
+    return { target: null, reason: `context ${contextK}: cache protected` };
+  }
+  return {
+    target,
+    reason: move === "enter" ? `enter ${label} from unrouted model` : `downgrade ${label}`,
+  };
+}
+
+/**
+ * How many LLM requests a switch takes to pay for itself.
+ *
+ * The first request on the new model reads the whole context uncached (or
+ * writes it to cache, whichever is dearer) instead of at the cache-read rate.
+ * Each later request saves the difference in cache-read price on the context
+ * plus the difference in output price. Returns Infinity when nothing is saved.
+ */
+export function paybackRequests(
+  current: Price,
+  target: Price,
+  contextTokens: number,
+  outputTokensPerRequest: number,
+): number {
+  const missPrice = Math.max(target.input, target.cacheWrite);
+  const premium = contextTokens * (missPrice - target.cacheRead);
+  const savingPerRequest =
+    contextTokens * (current.cacheRead - target.cacheRead) +
+    outputTokensPerRequest * (current.output - target.output);
+  if (savingPerRequest <= 0) return Infinity;
+  return premium / savingPerRequest;
+}
+
+/** Treat an all-zero price (common for unpriced registry entries) as unknown. */
+function knownPrice(price: Price | undefined): Price | undefined {
+  if (!price) return undefined;
+  return price.input > 0 || price.output > 0 ? price : undefined;
+}
+
+function sameSpec(a: ModelSpec, b: ModelSpec): boolean {
+  return a.provider === b.provider && a.modelId === b.modelId && a.thinking === b.thinking;
+}
+
+/** Position of a tier in the table (its rank), or -1 when it is not there. */
+function rankOf(table: RoutingTable, tier: string): number {
+  return table.findIndex((t) => t.id === tier);
+}
+
+/** The model a profile runs on, or undefined when its tier is not in the table. */
+export function specOf(table: RoutingTable, profile: Profile): ModelSpec | undefined {
+  return table.find((t) => t.id === profile.tier)?.models[profile.form];
+}
+
+/**
+ * Resolve a (provider, modelId) pair to a Profile by scanning the routing
+ * table. When several cells share the model, the first match is returned;
+ * `decide` compares specs, so which of those cells is picked does not matter.
+ */
+export function profileFromModel(
+  provider: string,
+  modelId: string,
+  table: RoutingTable,
+): Profile | null {
+  for (const tier of table) {
+    for (const form of FORMS) {
+      const spec = tier.models[form];
+      if (spec.provider === provider && spec.modelId === modelId) {
+        return { tier: tier.id, form };
+      }
+    }
+  }
+  return null;
+}

package/src/report.ts

@@ -0,0 +1,171 @@
+/**
+ * One-shot reports (`/pignon doctor`, `config`, `log`, `/pignon-stats`).
+ *
+ * In the TUI a report opens in a dismissible overlay: no line cap (a
+ * string-array widget keeps only 10 lines) and nothing left above the editor
+ * once it is closed. RPC clients get a notification, print/JSON mode stderr.
+ *
+ * The overlay scrolls by itself: Pi composites overlays by calling
+ * `render(width)` and slicing to `maxHeight`, so a pi-tui `ScrollView` inside
+ * one never receives a viewport and would be cut off like the widget was.
+ */
+
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { Key, matchesKey, truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+
+/** The subset of Pi's theme the overlay uses. */
+export interface ReportTheme {
+  fg(color: "accent" | "border" | "muted" | "dim", text: string): string;
+  bold(text: string): string;
+}
+
+/** Share of the terminal height the overlay may use. */
+const HEIGHT_SHARE = 0.7;
+/** Top and bottom border rows. */
+const CHROME_ROWS = 2;
+/** Border and padding columns around each line. */
+const CHROME_COLUMNS = 4;
+/** Overlay width while the lines are still computing, when they cannot be measured yet. */
+const PENDING_WIDTH = "90%";
+
+export class ReportOverlay {
+  private body: string[];
+  private offset = 0;
+  /** Body rows shown by the last render; paging moves by this much. */
+  private visibleRows = 1;
+
+  constructor(
+    readonly title: string,
+    lines: string[],
+    private readonly theme: ReportTheme,
+    /** Terminal height, read on every render so a resize is picked up. */
+    private readonly terminalRows: () => number,
+    private readonly requestRender: () => void,
+    private readonly close: () => void,
+  ) {
+    this.body = lines;
+  }
+
+  get lines(): readonly string[] {
+    return this.body;
+  }
+
+  setLines(lines: string[]): void {
+    this.body = lines;
+    this.offset = 0;
+    this.requestRender();
+  }
+
+  handleInput(data: string): void {
+    const page = Math.max(1, this.visibleRows - 1);
+    if (matchesKey(data, Key.escape) || matchesKey(data, Key.enter) || matchesKey(data, "q")) {
+      this.close();
+      return;
+    }
+    if (matchesKey(data, Key.up) || matchesKey(data, "k")) this.scrollTo(this.offset - 1);
+    else if (matchesKey(data, Key.down) || matchesKey(data, "j")) this.scrollTo(this.offset + 1);
+    else if (matchesKey(data, Key.pageUp)) this.scrollTo(this.offset - page);
+    else if (matchesKey(data, Key.pageDown) || matchesKey(data, Key.space)) this.scrollTo(this.offset + page);
+    else if (matchesKey(data, Key.home) || matchesKey(data, "g")) this.scrollTo(0);
+    else if (matchesKey(data, Key.end) || matchesKey(data, "shift+g")) this.scrollTo(Number.MAX_SAFE_INTEGER);
+  }
+
+  render(width: number): string[] {
+    const { theme } = this;
+    const border = (s: string) => theme.fg("border", s);
+    const inner = Math.max(1, width - CHROME_COLUMNS);
+
+    const maxRows = Math.max(1, Math.floor(this.terminalRows() * HEIGHT_SHARE) - CHROME_ROWS);
+    this.visibleRows = Math.min(this.body.length, maxRows);
+    this.offset = this.clamp(this.offset);
+    const shown = this.body.slice(this.offset, this.offset + this.visibleRows);
+
+    const scrolls = this.body.length > this.visibleRows;
+    const position = scrolls ? `${this.offset + 1}–${this.offset + shown.length}/${this.body.length}` : "";
+    const hint = scrolls ? "↑↓ PgUp/PgDn scroll · Esc close" : "Esc close";
+
+    return [
+      this.rule("╭", "╮", this.title && theme.fg("accent", theme.bold(this.title)), "", width),
+      ...shown.map((line) => `${border("│")} ${truncateToWidth(line, inner, "…", true)} ${border("│")}`),
+      this.rule("╰", "╯", theme.fg("dim", hint), position && theme.fg("dim", position), width),
+    ];
+  }
+
+  invalidate(): void {}
+
+  /** `╭─ left ───── right ─╮`, with the labels dropped if they do not fit. */
+  private rule(open: string, close: string, left: string, right: string, width: number): string {
+    const border = (s: string) => this.theme.fg("border", s);
+    const labelled = (s: string) => (s ? ` ${s} ` : "");
+    let l = labelled(left);
+    let r = labelled(right);
+    if (visibleWidth(l) + visibleWidth(r) + CHROME_COLUMNS > width) r = "";
+    if (visibleWidth(l) + CHROME_COLUMNS > width) l = "";
+    const fill = Math.max(0, width - CHROME_COLUMNS - visibleWidth(l) - visibleWidth(r));
+    return border(`${open}─`) + l + border("─".repeat(fill)) + r + border(`─${close}`);
+  }
+
+  private scrollTo(offset: number): void {
+    const next = this.clamp(offset);
+    if (next === this.offset) return;
+    this.offset = next;
+    this.requestRender();
+  }
+
+  private clamp(offset: number): number {
+    return Math.max(0, Math.min(offset, this.body.length - this.visibleRows));
+  }
+}
+
+/**
+ * Columns that show the widest line (or the title) whole. Pi resolves overlay
+ * options once, when the overlay opens, and clamps them to the terminal.
+ */
+export function reportWidth(title: string, lines: readonly string[]): number {
+  return Math.max(visibleWidth(title) + 6, ...lines.map(visibleWidth)) + CHROME_COLUMNS;
+}
+
+/**
+ * Show a report until the user closes it. `lines` may still be computing
+ * (doctor probes the deciders): the overlay opens at once and fills in.
+ */
+export async function showReport(
+  ctx: ExtensionContext,
+  title: string,
+  lines: string[] | Promise<string[]>,
+): Promise<void> {
+  const settled = Promise.resolve(lines).catch((err: unknown) => [
+    `  ✗ ${err instanceof Error ? err.message : String(err)}`,
+  ]);
+
+  if (ctx.mode !== "tui") {
+    const text = [title, ...(await settled)].join("\n");
+    if (ctx.hasUI) ctx.ui.notify(text, "info"); // RPC: custom components are not forwarded
+    else process.stderr.write(`${text}\n`); // keeps stdout parseable in JSON mode
+    return;
+  }
+
+  await ctx.ui.custom<void>(
+    (tui, theme, _keybindings, done) => {
+      const overlay = new ReportOverlay(
+        title,
+        Array.isArray(lines) ? lines : ["  running checks…"],
+        theme,
+        () => tui.terminal.rows,
+        () => tui.requestRender(),
+        () => done(undefined),
+      );
+      if (!Array.isArray(lines)) void settled.then((result) => overlay.setLines(result));
+      return overlay;
+    },
+    {
+      overlay: true,
+      overlayOptions: {
+        width: Array.isArray(lines) ? reportWidth(title, lines) : PENDING_WIDTH,
+        minWidth: 40,
+        anchor: "center",
+        margin: 1,
+      },
+    },
+  );
+}

package/src/router.ts

@@ -0,0 +1,215 @@
+/**
+ * Per-prompt routing: ask the decider, run the policy, apply the verdict.
+ *
+ * Pi-free: everything it needs from the host (current model, registry, model
+ * switching, UI feedback) goes through `RouterHost`, so it can be tested with
+ * plain fakes.
+ */
+
+import { createHash } from "node:crypto";
+
+import { parseDecision } from "./deciders/parse.js";
+import { buildQuestions } from "./deciders/questions.js";
+import type { Decider } from "./deciders/types.js";
+import { decide, formOf, profileFromModel, specOf } from "./policy.js";
+import type {
+  DeciderAttempt,
+  PolicyOutput,
+  Price,
+  Profile,
+  RouterConfig,
+  RouterLogEntry,
+  RouterMode,
+  RoutingDecision,
+  ThinkingLevel,
+} from "./types.js";
+
+/**
+ * Laya reads at most ~320 tokens of the prompt (512-token window minus the
+ * question header) from the start and ignores the rest, so sending more only
+ * costs tokenization time (and, for remote deciders, money and privacy).
+ */
+export const MAX_PROMPT_CHARS = 4_000;
+
+/** The part of a host model the router reads. */
+export interface HostModel {
+  provider: string;
+  id: string;
+  cost?: Price;
+}
+
+/** What the router needs from the agent it runs in (Pi, or a test fake). */
+export interface RouterHost<M extends HostModel = HostModel> {
+  /** Model the prompt would run on now. */
+  readonly model: M | undefined;
+  readonly contextTokens: number;
+  /** Cancellation of the current agent run. */
+  readonly signal: AbortSignal | undefined;
+  findModel(provider: string, modelId: string): M | undefined;
+  /** Switch model without the switch being taken for a manual pin. Resolves false without auth. */
+  switchModel(model: M): Promise<boolean>;
+  setThinkingLevel(level: ThinkingLevel): void;
+  status(text: string): void;
+  notify(text: string, level: "info" | "warning" | "error"): void;
+  showDeciding(deciderModel: string): void;
+  hideDeciding(): void;
+}
+
+export interface RoutePromptOptions {
+  decider: Decider;
+  config: RouterConfig;
+  mode: Exclude<RouterMode, "off">;
+  /** Prompts since the router last switched models; undefined if it never has. */
+  promptsSinceSwitch: number | undefined;
+}
+
+export interface RouteResult {
+  /** Whether the model was switched. */
+  applied: boolean;
+  entry: RouterLogEntry;
+}
+
+/** Ask the decider about one prompt and apply the verdict. Never throws. */
+export async function routePrompt<M extends HostModel>(
+  host: RouterHost<M>,
+  options: RoutePromptOptions,
+  prompt: string,
+): Promise<RouteResult> {
+  const { decider, config, mode, promptsSinceSwitch } = options;
+  const { table, thresholds } = config;
+  const model = host.model;
+  const current = model ? profileFromModel(model.provider, model.id, table) : null;
+  const contextTokens = host.contextTokens;
+  const currentModel = model ? `${model.provider}/${model.id}` : undefined;
+  const entryBase = { mode, config, decider, currentModel, prompt, current, contextTokens };
+
+  try {
+    host.status("pignon is deciding...");
+    host.showDeciding(decider.model ?? "unknown");
+    let result;
+    try {
+      result = await decider.decide(
+        { text: prompt.slice(0, MAX_PROMPT_CHARS), questions: buildQuestions(config) },
+        host.signal,
+      );
+    } finally {
+      host.hideDeciding();
+    }
+    const decision = parseDecision(result.answers, result.latencyMs, config);
+
+    const verdict = decide({
+      decision,
+      current,
+      contextTokens,
+      promptsSinceSwitch,
+      currentPrice: model?.cost,
+      priceOf: (spec) => host.findModel(spec.provider, spec.modelId)?.cost,
+      config,
+    });
+
+    let applied = false;
+    if (mode === "live" && verdict.target) {
+      const spec = specOf(table, verdict.target)!;
+      const target = host.findModel(spec.provider, spec.modelId);
+      if (!target) {
+        host.notify(`pignon: ${spec.provider}/${spec.modelId} is not in the model registry`, "warning");
+      } else if (await host.switchModel(target)) {
+        host.setThinkingLevel(spec.thinking);
+        applied = true;
+      } else {
+        host.notify(`pignon: no auth for ${spec.provider}/${spec.modelId}`, "warning");
+      }
+    }
+
+    const entry = buildLogEntry({
+      ...entryBase,
+      deciderId: result.deciderId,
+      remote: result.remote ?? decider.remote,
+      deciderModel: result.model,
+      ...(result.costUsd !== undefined ? { costUsd: result.costUsd } : {}),
+      ...(result.attempts ? { attempts: result.attempts } : {}),
+      decision,
+      verdict,
+      applied,
+    });
+
+    const badge = mode === "live" ? (applied ? "⚡" : "·") : "👁";
+    const label = `${decision.tier ?? "?"}/${formOf(decision, thresholds.minConfidenceForm)} p=${decision.tierConfidence.toFixed(2)}`;
+    host.status(`pignon ${badge} ${label} — ${verdict.reason}`);
+    return { applied, entry };
+  } catch (err) {
+    const error = err instanceof Error ? err.message : String(err);
+    host.status(`pignon ✗ ${error.slice(0, 80)}`);
+    const entry = buildLogEntry({
+      ...entryBase,
+      deciderModel: decider.model ?? "unknown",
+      decision: null,
+      verdict: { target: null, reason: "error" },
+      applied: false,
+      error,
+    });
+    return { applied: false, entry };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Log entries
+// ---------------------------------------------------------------------------
+
+/** Short, stable fingerprint of a prompt; the text itself is never stored. */
+export function hashPrompt(prompt: string): string {
+  return createHash("sha256").update(prompt).digest("hex").slice(0, 16);
+}
+
+interface LogEntryInput {
+  mode: RouterMode;
+  config: RouterConfig;
+  decider: Decider;
+  /** Decider that answered, when it differs from `decider` (a strategy). */
+  deciderId?: string;
+  remote?: boolean;
+  costUsd?: number;
+  attempts?: DeciderAttempt[];
+  currentModel: string | undefined;
+  deciderModel: string;
+  prompt: string;
+  decision: RoutingDecision | null;
+  current: Profile | null;
+  contextTokens: number;
+  verdict: PolicyOutput;
+  applied: boolean;
+  error?: string;
+}
+
+function buildLogEntry(input: LogEntryInput): RouterLogEntry {
+  const { decision, current, verdict } = input;
+  const spec = verdict.target ? specOf(input.config.table, verdict.target) : undefined;
+  return {
+    ts: Date.now(),
+    mode: input.mode,
+    decider: input.deciderId ?? input.decider.id,
+    remote: input.remote ?? input.decider.remote,
+    ...(input.costUsd !== undefined ? { costUsd: input.costUsd } : {}),
+    ...(input.attempts ? { attempts: input.attempts } : {}),
+    deciderModel: input.deciderModel,
+    questionsVersion: input.config.questions.version,
+    promptHash: hashPrompt(input.prompt),
+    promptLength: input.prompt.length,
+    tier: decision?.tier ?? null,
+    tierConfidence: decision?.tierConfidence ?? null,
+    needsExploration: decision?.needsExploration ?? null,
+    explorationConfidence: decision?.explorationConfidence ?? null,
+    form: decision ? formOf(decision, input.config.thresholds.minConfidenceForm) : null,
+    latencyMs: decision?.latencyMs ?? null,
+    currentTier: current?.tier ?? null,
+    currentForm: current?.form ?? null,
+    ...(input.currentModel !== undefined ? { currentModel: input.currentModel } : {}),
+    contextTokens: input.contextTokens,
+    targetTier: verdict.target?.tier ?? null,
+    targetForm: verdict.target?.form ?? null,
+    ...(spec ? { targetModel: `${spec.provider}/${spec.modelId}`, targetThinking: spec.thinking } : {}),
+    reason: verdict.reason,
+    applied: input.applied,
+    ...(input.error !== undefined ? { error: input.error } : {}),
+  };
+}

package/src/stats.ts

@@ -0,0 +1,55 @@
+/**
+ * `/pignon-stats`: tier x form x confidence histogram over a session's decisions.
+ */
+
+import { DEFAULT_CONFIG } from "./config/defaults.js";
+import { type RouterLogEntry, type RoutingTable, FORMS } from "./types.js";
+
+/** Rows follow the table; decisions for tiers no longer in it are not counted. */
+export function buildStatsLines(rows: RouterLogEntry[], table: RoutingTable = DEFAULT_CONFIG.table): string[] {
+  const buckets = ["<0.5", "0.5-0.7", "0.7-0.85", "0.85-0.95", ">=0.95"];
+  const bucketOf = (c: number) =>
+    c < 0.5 ? 0 : c < 0.7 ? 1 : c < 0.85 ? 2 : c < 0.95 ? 3 : 4;
+
+  const grid: Record<string, number[]> = {};
+  for (const { id } of table) {
+    for (const form of FORMS) {
+      grid[`${id}/${form}`] = [0, 0, 0, 0, 0];
+    }
+  }
+
+  let applied = 0;
+  const latencies: number[] = [];
+  const byDecider = new Map<string, number>();
+  let cost = 0;
+
+  for (const row of rows) {
+    const cell = row.tier && row.form ? `${row.tier}/${row.form}` : null;
+    if (cell && grid[cell]) grid[cell][bucketOf(row.tierConfidence ?? 0)]++;
+    // Failed decisions have no latency; counting them as 0 ms skews the mean.
+    if (typeof row.latencyMs === "number") latencies.push(row.latencyMs);
+    if (row.applied) applied++;
+    if (row.decider) byDecider.set(row.decider, (byDecider.get(row.decider) ?? 0) + 1);
+    cost += row.costUsd ?? 0;
+  }
+
+  const avgLatency = latencies.length
+    ? `${Math.round(latencies.reduce((a, b) => a + b, 0) / latencies.length)} ms`
+    : "n/a";
+
+  return [
+    `pignon — ${rows.length} decisions, ${applied} applied`,
+    `${"profile".padEnd(22)}${buckets.map((b) => b.padStart(9)).join("")}`,
+    ...Object.entries(grid).map(
+      ([cell, counts]) =>
+        `${cell.padEnd(22)}${counts.map((n) => String(n).padStart(9)).join("")}`,
+    ),
+    `avg latency ${avgLatency}`,
+    ...(byDecider.size > 0
+      ? [
+          `deciders ${[...byDecider].map(([id, n]) => `${id} ${n}`).join(" · ")}` +
+            (cost > 0 ? ` · cost $${cost.toFixed(5)}` : ""),
+        ]
+      : []),
+  ];
+}