@kabmo-labs/kabmo 0.0.0-stage → 0.0.1

package/src/shared/lib/dictation/protocol.ts

@@ -0,0 +1,110 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Dictation WebSocket frames: the contract between the composer's mic button
+ * and Kabmo's dictation route.
+ *
+ * One utterance per socket, and the audio travels in a SINGLE frame. The
+ * alternative — streaming chunks while the user speaks — buys nothing here:
+ * omp's STT is not incremental (its own TUI inserts text on release), so a
+ * chunked transport would only add reordering and reassembly for a result the
+ * final decode replaces. The socket exists for the other direction: the server
+ * pushes model download progress while the decode waits on a first-run fetch.
+ */
+
+import { isRecord } from '@/shared/lib/util/guards';
+
+export const DICTATION_SAMPLE_RATE = 16000;
+export const DICTATION_BITS = 16;
+export const DICTATION_CHANNELS = 1;
+export const DICTATION_FORMAT = `audio/pcm;rate=${DICTATION_SAMPLE_RATE};bits=${DICTATION_BITS}`;
+
+/** Cap on one utterance, so a stuck client cannot post an unbounded buffer. */
+export const DICTATION_MAX_AUDIO_BYTES = 32 * 1024 * 1024;
+
+/** Client → Server: the whole utterance, PCM16LE mono @16 kHz, base64. */
+export interface DictationTranscribeFrame {
+  type: 'transcribe';
+  audio: string;
+  modelKey?: string;
+  language?: string;
+}
+
+export type DictationClientFrame = DictationTranscribeFrame;
+
+/** Server → Client: the socket is open and ready for an utterance. */
+export interface DictationReadyFrame {
+  type: 'ready';
+}
+
+/** Server → Client: the model is being fetched or loaded. */
+export interface DictationProgressFrame {
+  type: 'progress';
+  /** 0..100 while downloading, null once it is decoding. */
+  percent: number | null;
+  file?: string;
+  decoding: boolean;
+}
+
+/** Server → Client: the transcript of the utterance just sent. */
+export interface DictationFinalFrame {
+  type: 'final';
+  text: string;
+}
+
+/** Server → Client: the utterance could not be transcribed. */
+export interface DictationErrorFrame {
+  type: 'error';
+  error: string;
+  retryable: boolean;
+}
+
+export type DictationServerFrame =
+  | DictationReadyFrame
+  | DictationProgressFrame
+  | DictationFinalFrame
+  | DictationErrorFrame;
+
+export function encodeDictationFrame(frame: DictationClientFrame | DictationServerFrame): string {
+  return JSON.stringify(frame);
+}
+
+function tryParse(text: string): unknown {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Decode an inbound frame from whatever the socket delivered.
+ *
+ * Elysia hands the `message` callback an ALREADY-PARSED object when no `body`
+ * schema is declared — verified: `typeof raw` is `object` and `String(raw)` is
+ * `[object Object]`. Routing that through `new TextDecoder().decode(raw)`
+ * yields an empty string, so a `JSON.parse` of it throws and the frame is
+ * silently dropped: the client sees `ready` and then nothing, with no error on
+ * either side. The terminal protocol's decoder takes the same three shapes for
+ * the same reason.
+ */
+export function decodeDictationClientFrame(raw: unknown): DictationClientFrame | null {
+  const value =
+    typeof raw === 'string'
+      ? tryParse(raw)
+      : raw instanceof Uint8Array
+        ? tryParse(new TextDecoder().decode(raw))
+        : raw;
+  if (!isRecord(value)) return null;
+  if (value.type !== 'transcribe') return null;
+  if (typeof value.audio !== 'string') return null;
+  return {
+    type: 'transcribe',
+    audio: value.audio,
+    ...(typeof value.modelKey === 'string' ? { modelKey: value.modelKey } : {}),
+    ...(typeof value.language === 'string' ? { language: value.language } : {}),
+  };
+}

package/src/shared/lib/fonts/NOTICE.md

@@ -0,0 +1,44 @@
+# Bundled font: Symbols Nerd Font Mono
+
+`symbols-nerd-font-mono.woff2` is a subset of **SymbolsNerdFontMono-Regular.ttf**
+from [Nerd Fonts](https://github.com/ryanoasis/nerd-fonts) **v3.5.1**, built by
+`scripts/nerd-symbols-font.mjs`. It is the fallback face for the terminal's
+private-use glyphs (powerline separators, devicons, Font Awesome, Material
+Design icons); see `nerd-symbols.css` for why it is needed and how it is scoped.
+
+Subset coverage — the private-use areas plus the handful of Nerd-specific
+codepoints outside them:
+
+    U+E000-F8FF      BMP private use
+    U+F0000-FFFFD    Supplementary private use area-A (Material Design Icons)
+    U+23FB-23FE, U+2630, U+2665, U+26A1, U+276C-2771, U+2B58
+
+## Licences
+
+The font is a patched build combining several upstream icon sets. Each is
+redistributed here under its own licence, unchanged in substance (the subset
+keeps the glyph outlines verbatim; only `layout-features` and hinting are
+dropped, which are not licence terms).
+
+| Icon set                 | Upstream                                              | Licence     |
+|--------------------------|-------------------------------------------------------|-------------|
+| Codicons                 | https://github.com/microsoft/vscode-codicons          | CC BY 4.0   |
+| Devicons                 | https://github.com/devicons/devicon                   | MIT         |
+| extraglyphs              | https://github.com/source-foundry/Hack                | MIT         |
+| Font Awesome             | https://github.com/FortAwesome/Font-Awesome           | CC BY 4.0   |
+| Font Awesome Extension   | https://github.com/AndreLZGava/font-awesome-extension | MIT         |
+| Font Logos               | https://github.com/lukas-w/font-logos                 | unlicensed  |
+| Material Design Icons    | https://github.com/Templarian/MaterialDesign-Font     | Apache 2.0  |
+| Octicons                 | https://github.com/primer/octicons                    | MIT         |
+| Seti and original        | https://github.com/jesseweed/seti-ui                  | MIT         |
+| Pomicons                 | https://github.com/gabrielelana/pomicons              | OFL 1.1 RFN |
+| Powerline Extra Symbols  | https://github.com/ryanoasis/powerline-extra-symbols  | MIT         |
+| Powerline Symbols        | https://github.com/powerline/powerline                | MIT         |
+
+The Nerd Fonts project itself (the patching, the font metadata and the
+non-icon glyphs) is MIT, Copyright (c) 2014 Ryan L McIntyre. Its licence text
+accompanies the upstream release at
+https://github.com/ryanoasis/nerd-fonts/blob/master/LICENSE.
+
+"Font Logos" is marked unlicensed upstream; it ships inside the Nerd Fonts
+release that this subset is taken from, and is redistributed on that basis.

package/src/shared/lib/fonts/nerd-symbols.css

@@ -0,0 +1,55 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/*
+ * The bundled Nerd Font symbols face.
+ *
+ * A shell prompt is drawn with private-use symbols — powerline separators,
+ * devicons, Font Awesome, Material Design icons — that no coding webfont
+ * contains. `@fontsource/fira-code`'s latin subset maps 226 codepoints and not
+ * one of them is above U+FFFF, so the terminal's stack can only reach them
+ * through a Nerd Font. Until now the stack named installed families only
+ * (`XTERM_GLYPH_FALLBACKS`), which means the glyphs appeared on the machine
+ * that had one installed and were hollow tofu boxes on every other device — a
+ * phone, a second laptop, a colleague's browser.
+ *
+ * This face closes that gap without taking the choice away: it is declared LAST
+ * in the stack, after every installed Nerd Font family, so a machine that
+ * already has one renders from it and never fetches these bytes.
+ *
+ * `unicode-range` is what makes "never fetches" true rather than aspirational.
+ * A face whose range no laid-out glyph falls in is never downloaded, so a page
+ * that renders only Latin text (or a desktop where an installed family wins)
+ * issues no request at all. Verified: a latin-only document with this
+ * stylesheet loaded fetched only `fira-code-latin-400-normal.woff2` and left
+ * this face `unloaded`; a document laying out U+E0B0 with an installed family
+ * ahead of it fetched nothing.
+ *
+ * `font-display: block` rather than `swap`, unlike the text faces beside it: a
+ * swapped symbol paints a tofu box first and repaints, and in a terminal that
+ * box is exactly the artifact this face exists to remove. `mount.ts` awaits the
+ * face before opening xterm for the same reason — see `ensureNerdGlyphs`.
+ *
+ * Generated by `bun run scripts/nerd-symbols-font.mjs` from
+ * `SymbolsNerdFontMono-Regular.ttf` (Nerd Fonts v3.5.1). See NOTICE.md in this
+ * directory for the icon-set licences.
+ */
+
+@font-face {
+  font-family: 'Kabmo Nerd Symbols';
+  font-style: normal;
+  font-weight: 400;
+  font-display: block;
+  unicode-range:
+    U+E000-F8FF,
+    U+F0000-FFFFD,
+    U+23FB-23FE,
+    U+2630,
+    U+2665,
+    U+26A1,
+    U+276C-2771,
+    U+2B58;
+  src: url('./symbols-nerd-font-mono.woff2') format('woff2');
+}

package/src/shared/lib/fonts/nerd-symbols.test.ts

@@ -0,0 +1,176 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The terminal's Nerd Font coverage is one contract split across three files,
+ * and every way it can break is silent at runtime:
+ *
+ * - The bundled face's family name is written twice — in the stack
+ *   (`XTERM_FONT_FAMILY`) and in the `@font-face` (`nerd-symbols.css`). If they
+ *   drift, the face loads and nothing uses it: prompts render as tofu boxes
+ *   with no error anywhere.
+ * - The face must stay LAST in the stack. Moved ahead of the installed families
+ *   it would win on every machine, which both changes the glyph shapes a user
+ *   with a Nerd Font already sees AND makes every desktop download 1.1 MB it
+ *   never needed. That is a bandwidth regression with no visible symptom on the
+ *   developer's own laptop.
+ * - The font file and its `unicode-range` must agree. A range that names
+ *   codepoints the subset dropped leaves those glyphs as tofu even though the
+ *   face is loaded and "working".
+ *
+ * These assertions are cheap and each one pins a failure this change was made
+ * to prevent, so they are permanent rather than throwaway.
+ */
+
+import { describe, expect, test } from 'bun:test';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import {
+  NERD_SYMBOLS_FAMILY,
+  XTERM_FONT_FAMILY,
+  XTERM_GLYPH_FALLBACKS,
+} from '@/client/data/theme/terminal';
+
+const FONT_DIR = import.meta.dir;
+const CSS = readFileSync(join(FONT_DIR, 'nerd-symbols.css'), 'utf8');
+const WOFF2 = join(FONT_DIR, 'symbols-nerd-font-mono.woff2');
+/** The app's UI stack (`--font-sans`), which paints the session-title card icon. */
+const TAILWIND = readFileSync(join(FONT_DIR, '../../../client/tailwind.css'), 'utf8');
+
+/** Parse `unicode-range: a, b, c;` into codepoint intervals. */
+function declaredRanges(css: string): Array<[number, number]> {
+  const block = css.match(/unicode-range:\s*([^;]+);/);
+  if (!block) throw new Error('nerd-symbols.css declares no unicode-range');
+  return block[1]
+    .split(',')
+    .map((entry) => entry.trim())
+    .filter(Boolean)
+    .map((entry) => {
+      const [start, end] = entry.split('-');
+      const lo = Number.parseInt(start.replace(/^U\+/i, ''), 16);
+      const hi = end ? Number.parseInt(end.replace(/^U\+/i, ''), 16) : lo;
+      return [lo, hi] as [number, number];
+    });
+}
+
+describe('bundled Nerd Font symbols face', () => {
+  test('the stylesheet declares the family the terminal stack names', () => {
+    const declared = CSS.match(/font-family:\s*'([^']+)'/)?.[1];
+    expect(declared).toBe(NERD_SYMBOLS_FAMILY);
+  });
+
+  test('the face is LAST in the stack, after every installed family', () => {
+    // A local Nerd Font must win, so the bundled face is only reached on a
+    // machine that has none — which is also what keeps the desktop from
+    // downloading it (its unicode-range is PUA-only, so it is never fetched
+    // when another family supplies the glyph).
+    expect(XTERM_FONT_FAMILY.indexOf(NERD_SYMBOLS_FAMILY)).toBeGreaterThan(
+      XTERM_FONT_FAMILY.indexOf('PowerlineSymbols'),
+    );
+    // Only the generic fallbacks may follow it.
+    const after = XTERM_FONT_FAMILY.slice(XTERM_FONT_FAMILY.indexOf(NERD_SYMBOLS_FAMILY));
+    expect(after).not.toMatch(/Nerd Font Mono'/);
+  });
+
+  test('every installed family is still offered before the bundled one', () => {
+    for (const family of ['FiraCode Nerd Font Mono', 'JetBrainsMono Nerd Font', 'Symbols Nerd Font Mono']) {
+      expect(XTERM_GLYPH_FALLBACKS).toContain(family);
+      expect(XTERM_FONT_FAMILY.indexOf(family)).toBeLessThan(
+        XTERM_FONT_FAMILY.indexOf(NERD_SYMBOLS_FAMILY),
+      );
+    }
+  });
+
+  test('the subset actually covers the ranges the stylesheet claims', () => {
+    // Reading the cmap needs fonttools, which is not a project dependency. The
+    // absence is a legitimate skip; a *failure* of the probe is not, so the two
+    // are told apart rather than both being swallowed as "no fonttools".
+    //
+    // The availability check gets its own bounded budget, and the test gets room
+    // for it: on a Windows runner `python3` resolves to a slow launcher that took
+    // the whole default 5s test budget just to answer "no fonttools", so the test
+    // was reported as TIMED OUT after it had correctly decided to skip (measured
+    // on windows-latest: 5009ms, with the skip message already printed). An
+    // interpreter that cannot answer inside this budget counts as unavailable —
+    // the skip this test already documents — rather than as a hang.
+    const PYTHON_PROBE_TIMEOUT_MS = 5_000;
+    const available = Bun.spawnSync({
+      cmd: ['python3', '-c', 'import fontTools, brotli'],
+      timeout: PYTHON_PROBE_TIMEOUT_MS,
+    });
+    if (available.exitCode !== 0) {
+      console.warn('skipping font coverage check: python3 fonttools/brotli unavailable');
+      return;
+    }
+
+    const probe = Bun.spawnSync([
+      'python3',
+      '-c',
+      `
+import json
+from fontTools.ttLib import TTFont
+
+cmap = set(TTFont(${JSON.stringify(WOFF2)}).getBestCmap())
+ranges = ${JSON.stringify(declaredRanges(CSS))}
+uncovered = [r for r in ranges if not any(cp in cmap for cp in range(r[0], r[1] + 1))]
+# The prompt glyphs this face exists for.
+required = [0xE0B0, 0xE0B4, 0xE0B6, 0xE606, 0xE7A8, 0xE718, 0xF015, 0xF03E, 0xF121B, 0xF0001]
+print(json.dumps({ "codepoints": len(cmap), "uncovered": uncovered, "missing": [c for c in required if c not in cmap] }))
+`,
+    ]);
+
+    // fonttools is known to be importable here, so a non-zero exit is a real
+    // failure (a corrupt subset, a bad path) and must not read as a skip.
+    expect(probe.stderr.toString()).toBe('');
+
+    const result = JSON.parse(probe.stdout.toString()) as {
+      codepoints: number;
+      uncovered: Array<[number, number]>;
+      missing: number[];
+    };
+    expect(result.uncovered).toEqual([]);
+    expect(result.missing).toEqual([]);
+    expect(result.codepoints).toBeGreaterThan(10_000);
+    // Room for the bounded availability probe above plus the cmap read; the
+    // default 5s is what a slow Windows launcher consumed on its own.
+  }, 20_000);
+
+  test('the face file is present and non-trivial', async () => {
+    const file = Bun.file(WOFF2);
+    expect(await file.exists()).toBe(true);
+    expect(file.size).toBeGreaterThan(100_000);
+  });
+
+  /**
+   * The UI stack is the SECOND consumer of this face, and it was missing one.
+   * omp heads a session title with a card icon — a PUA glyph
+   * (`title.icons: nf+emoji`) that no Latin face contains — so a stack without
+   * a Nerd Font renders it as tofu wherever the device has none (a phone). The
+   * desktop only looked correct because Chromium's OS fallback found the
+   * developer's installed Nerd Font; there is no such fallback on a phone.
+   *
+   * The order is what keeps it from being a bandwidth regression: the installed
+   * families must precede the bundled face, or Chromium prefers the named
+   * webfont over the system fallback and every machine downloads 1.1 MB.
+   */
+  test('the UI stack names a Nerd Font, with the bundled face LAST', () => {
+    const stack = TAILWIND.match(/--font-sans:\s*([^;]+);/)?.[1];
+    expect(stack).toBeDefined();
+    // A title card must have SOME Nerd Font in the UI stack, or it is tofu on a phone.
+    expect(stack!).toContain(NERD_SYMBOLS_FAMILY);
+    // Installed families first, bundled face last: the terminal's own contract,
+    // for the same reason (a machine that has one never fetches these bytes).
+    // Both must be PRESENT (`indexOf` alone lets a missing name through, since
+    // `-1 < anyPositive` is true).
+    for (const family of ['FiraCode Nerd Font Mono', 'Symbols Nerd Font Mono']) {
+      expect(stack!).toContain(family);
+      expect(stack!.indexOf(family)).toBeLessThan(stack!.indexOf(NERD_SYMBOLS_FAMILY));
+    }
+    // Nothing may follow the bundled face — a later generic would be dead code.
+    const after = stack!.slice(stack!.indexOf(NERD_SYMBOLS_FAMILY) + NERD_SYMBOLS_FAMILY.length);
+    expect(after.replace(/["'\s,]/g, '')).toBe('');
+  });
+});

package/src/shared/lib/format/number.test.ts

@@ -0,0 +1,127 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * The Kabmo's shared number formatters.
+ *
+ * These decide what a token count, a cost, a byte size and a per-1M price look
+ * like on every surface, so the boundaries are the contract: `formatCompactTokens`
+ * switches at 1000 and 1_000_000 with decimal units (1500 → "1.5K", 1048576 →
+ * "1.0M"), passes preformatted strings through untouched, and returns undefined
+ * for non-positive/non-finite input so callers can apply their own fallback.
+ * `formatCost`/`formatBytes`/`formatPrice` must return an EMPTY string — not
+ * "$0.00"/"0 B" — for missing values, except that a real price of 0 is a valid
+ * "$0.00". Pinning the empty-vs-zero split stops a "nicer default" from
+ * inventing a cost the model never charged.
+ */
+
+import { describe, expect, test } from 'bun:test';
+
+import { formatBytes, formatCompactTokens, formatCost, formatPrice } from '@/shared/lib/format/number';
+
+describe('formatCompactTokens', () => {
+  test('passes already-formatted strings through, including the empty string', () => {
+    expect(formatCompactTokens('1.5K')).toBe('1.5K');
+    expect(formatCompactTokens('')).toBe('');
+  });
+
+  test('returns undefined for null, undefined and invalid numbers', () => {
+    expect(formatCompactTokens(null)).toBeUndefined();
+    expect(formatCompactTokens(undefined)).toBeUndefined();
+    expect(formatCompactTokens(0)).toBeUndefined();
+    expect(formatCompactTokens(-5)).toBeUndefined();
+    expect(formatCompactTokens(Number.NaN)).toBeUndefined();
+    expect(formatCompactTokens(Number.POSITIVE_INFINITY)).toBeUndefined();
+  });
+
+  test('keeps small counts verbatim', () => {
+    expect(formatCompactTokens(1)).toBe('1');
+    expect(formatCompactTokens(999)).toBe('999');
+    expect(formatCompactTokens(1.5)).toBe('1.5');
+  });
+
+  test('switches to K at exactly 1000, with a trailing zero only when needed', () => {
+    expect(formatCompactTokens(1000)).toBe('1K');
+    expect(formatCompactTokens(1500)).toBe('1.5K');
+    expect(formatCompactTokens(131_072)).toBe('131.1K');
+    expect(formatCompactTokens(999_999)).toBe('1000.0K');
+  });
+
+  test('switches to M at exactly 1_000_000', () => {
+    expect(formatCompactTokens(1_000_000)).toBe('1M');
+    expect(formatCompactTokens(1_048_576)).toBe('1.0M');
+    expect(formatCompactTokens(2_000_000)).toBe('2M');
+    expect(formatCompactTokens(1_000_000_000)).toBe('1000M');
+  });
+});
+
+describe('formatCost', () => {
+  test('renders two decimals by default', () => {
+    expect(formatCost(1.234)).toBe('$1.23');
+    expect(formatCost(2)).toBe('$2.00');
+    expect(formatCost(0.5)).toBe('$0.50');
+  });
+
+  test('honours a raised fraction-digit count for sub-cent costs', () => {
+    expect(formatCost(0.001, 4)).toBe('$0.0010');
+    expect(formatCost(12.6, 0)).toBe('$13');
+  });
+
+  test('an empty string marks a missing or non-positive cost', () => {
+    expect(formatCost(0)).toBe('');
+    expect(formatCost(-1)).toBe('');
+    expect(formatCost(Number.NaN)).toBe('');
+    expect(formatCost(undefined)).toBe('');
+    expect(formatCost(null)).toBe('');
+    expect(formatCost('1' as unknown as number)).toBe('');
+  });
+});
+
+describe('formatBytes', () => {
+  test('renders bytes below 1 KiB as rounded whole bytes', () => {
+    expect(formatBytes(0)).toBe('0 B');
+    expect(formatBytes(512)).toBe('512 B');
+    expect(formatBytes(1.5)).toBe('2 B');
+    expect(formatBytes(1023.4)).toBe('1023 B');
+  });
+
+  test('switches to KB at exactly 1024', () => {
+    expect(formatBytes(1024)).toBe('1.0 KB');
+    expect(formatBytes(1536)).toBe('1.5 KB');
+    expect(formatBytes(1_048_575)).toBe('1024.0 KB');
+  });
+
+  test('switches to MB at exactly 1 MiB', () => {
+    expect(formatBytes(1_048_576)).toBe('1.00 MB');
+    expect(formatBytes(2 * 1024 * 1024)).toBe('2.00 MB');
+  });
+
+  test('an empty string marks missing, non-finite or negative sizes', () => {
+    expect(formatBytes(-1)).toBe('');
+    expect(formatBytes(Number.NaN)).toBe('');
+    expect(formatBytes(Number.POSITIVE_INFINITY)).toBe('');
+    expect(formatBytes(undefined)).toBe('');
+    expect(formatBytes(null)).toBe('');
+  });
+});
+
+describe('formatPrice', () => {
+  test('renders a per-1M price with two decimals', () => {
+    expect(formatPrice(3)).toBe('$3.00');
+    expect(formatPrice(3.5)).toBe('$3.50');
+    expect(formatPrice(1.239)).toBe('$1.24');
+  });
+
+  test('zero is a valid free price, not a missing one', () => {
+    expect(formatPrice(0)).toBe('$0.00');
+  });
+
+  test('an empty string marks a missing or negative price', () => {
+    expect(formatPrice(-1)).toBe('');
+    expect(formatPrice(Number.NaN)).toBe('');
+    expect(formatPrice(Number.POSITIVE_INFINITY)).toBe('');
+    expect(formatPrice(undefined)).toBe('');
+  });
+});

package/src/shared/lib/format/number.ts

@@ -0,0 +1,69 @@
+/**
+ * @license
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * Shared number formatters. Every compact-label / cost / byte / price display
+ * in Kabmo funnels through here so the wire format stays identical
+ * everywhere.
+ *
+ * `formatCompactTokens` absorbs the former `formatContextWindow` (the most
+ * complete of the token formatters — it accepts a raw number, an already
+ * formatted string, or null/undefined). Call sites that always need a string
+ * pass a `?? '0'` fallback.
+ */
+
+/**
+ * Compact token/context label using decimal (1000-based) units:
+ * 1500 → "1.5K", 1048576 → "1.0M", 131072 → "131.1K". Strings pass through
+ * unchanged (already formatted); non-finite or non-positive numbers return
+ * `undefined`.
+ */
+export function formatCompactTokens(value: number | string | undefined | null): string | undefined {
+  if (value === undefined || value === null) return undefined;
+  if (typeof value === 'string') return value;
+  if (!Number.isFinite(value) || value <= 0) return undefined;
+
+  if (value >= 1_000_000) {
+    const m = value / 1_000_000;
+    return `${Number.isInteger(m) ? m : m.toFixed(1)}M`;
+  }
+  if (value >= 1_000) {
+    const k = value / 1_000;
+    return `${Number.isInteger(k) ? k : k.toFixed(1)}K`;
+  }
+  return String(value);
+}
+
+/**
+ * Dollar amount (`$1.23`). Non-finite or non-positive values return an empty
+ * string so call sites can omit the cost entirely; callers that need a zero
+ * label (chart axes) fall back with `|| '$0.00'`. `fractionDigits` defaults to
+ * the 2-decimal display and is raised by subagent rows that report sub-cent
+ * costs.
+ */
+export function formatCost(value: number | undefined | null, fractionDigits = 2): string {
+  if (typeof value !== 'number' || !Number.isFinite(value) || value <= 0) return '';
+  return `$${value.toFixed(fractionDigits)}`;
+}
+
+/**
+ * Byte size label: 0 → "0 B", 512 → "512 B", 2048 → "2.0 KB", 2 MiB → "2.00 MB".
+ * Undefined, non-finite, or negative values return an empty string.
+ */
+export function formatBytes(bytes: number | undefined | null): string {
+  if (typeof bytes !== 'number' || !Number.isFinite(bytes) || bytes < 0) return '';
+  if (bytes < 1024) return `${Math.round(bytes)} B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+  return `${(bytes / (1024 * 1024)).toFixed(2)} MB`;
+}
+
+/**
+ * Per-1M-token price label (`$3.00`). Undefined/non-finite/negative values
+ * return an empty string so a partially specified model renders one side blank.
+ */
+export function formatPrice(value: number | undefined): string {
+  if (typeof value !== 'number' || !Number.isFinite(value) || value < 0) return '';
+  return `$${value.toFixed(2)}`;
+}