@genee/omp-opsx-addon 0.1.0

package/lib/usage-resolver.ts

@@ -0,0 +1,477 @@
+/**
+ * Provider usage health resolver.
+ *
+ * Wraps `ctx.modelRegistry.authStorage.fetchUsageReports` and (optionally) a
+ * list of direct fetchers (mirroring `omp-plan-usage`) into a normalized
+ * `Map<provider, ProviderHealth>` so the model-selector can filter / rank by
+ * quota state without knowing the OMP auth-storage API.
+ *
+ * Direct fetchers are injected so the plugin stays decoupled from
+ * `omp-plan-usage`'s internal list. If none are provided, the resolver falls
+ * back to whatever `fetchUsageReports` returns (which already includes
+ * OMP-managed providers).
+ */
+
+import type { UsageReport, UsageStatus } from '@oh-my-pi/pi-ai';
+
+export type ApiKeyResolver = (provider: string) => Promise<string | undefined>;
+
+/**
+ * A provider-bound key resolver: the caller (gatherReports) has already bound a
+ * fetcher's `provider`, so each fetcher asks for "my key" with no argument.
+ * This keeps provider id strings out of fetcher bodies — a fetcher's identity
+ * lives only in its `DIRECT_FETCHERS` registration, never hardcoded inside it.
+ */
+export type BoundApiKeyResolver = () => Promise<string | undefined>;
+
+export interface DirectFetcher {
+    provider: string;
+    fetch(signal?: AbortSignal, getApiKey?: BoundApiKeyResolver): Promise<UsageReport | null>;
+    /**
+     * Sync, local-only credential probe. When true, this provider is treated as
+     * logged-in for gather/widget even if absent from authStorage.list().
+     */
+    credentialsPresent?: () => boolean;
+}
+
+/**
+ * Provider id aliases (currently empty). All fetchers and reports use the same
+ * provider id as the auth/model registry (e.g. `zhipu-coding-plan`,
+ * `minimax-code-cn`), so no canonicalization is needed.
+ */
+const PROVIDER_ALIAS: Record<string, string> = {};
+
+/** Normalize a provider id to its canonical form (no-op if already canonical). */
+export function canonicalizeProvider(id: string): string {
+    return PROVIDER_ALIAS[id] ?? id;
+}
+
+/** Providers whose direct fetcher reports locally-detectable credentials (no network). */
+export function listDetectableProviders(directFetchers: readonly DirectFetcher[]): string[] {
+    const out: string[] = [];
+    for (const f of directFetchers) {
+        try {
+            if (f.credentialsPresent?.()) out.push(canonicalizeProvider(f.provider));
+        } catch {
+            /* ignore probe errors */
+        }
+    }
+    return [...new Set(out)];
+}
+
+export type QuotaPolicy = 'conjunctive' | 'bucket' | 'balance';
+
+export interface WindowHealth {
+    id: string;
+    remaining?: number;
+    exhausted: boolean;
+    status: UsageStatus;
+}
+
+export interface ProviderHealth {
+    provider: string;
+    policy: QuotaPolicy;
+    /** Provider-wide shortcut: conjunctive any required window; bucket no usable bucket; balance remaining ≤ 0. */
+    exhausted: boolean;
+    windows: WindowHealth[];
+    autoBucketModels?: string[];
+    /** Best (lowest) usedFraction across all limit windows. 0..1+. Undefined = unknown. */
+    bestUsedFraction?: number;
+    /**
+     * Conjunctive/balance: min remaining. Cursor: max remaining among still-usable buckets.
+     */
+    worstRemainingFraction?: number;
+    /** Overall status: ok / warning / exhausted / unknown. */
+    status: UsageStatus;
+    /** Window labels whose status is exhausted. */
+    exhaustedWindows: string[];
+    fetchedAt: number;
+    notes?: string[];
+}
+
+const HEALTHY_REMAINING_THRESHOLD = 0.1;
+
+const REQUIRED_WINDOWS: Record<string, { policy: QuotaPolicy; required?: readonly string[] }> = {
+    'zhipu-coding-plan': { policy: 'conjunctive', required: ['5h', '1w'] },
+    'minimax-code-cn': { policy: 'conjunctive', required: ['5h', '1w'] },
+    'opencode-go': { policy: 'conjunctive', required: ['5h', '1w', '1mo'] },
+    kimi: { policy: 'conjunctive' },
+    'openai-codex': { policy: 'conjunctive' },
+    cursor: { policy: 'bucket' },
+    deepseek: { policy: 'balance' },
+};
+
+export function quotaPolicyFor(provider: string): QuotaPolicy {
+    return REQUIRED_WINDOWS[provider]?.policy ?? 'conjunctive';
+}
+
+function extractFraction(amount: {
+    usedFraction?: number;
+    remainingFraction?: number;
+    used?: number;
+    limit?: number;
+    remaining?: number;
+}): number | undefined {
+    if (typeof amount.usedFraction === 'number') return amount.usedFraction;
+    if (typeof amount.remainingFraction === 'number') return 1 - amount.remainingFraction;
+    if (typeof amount.used === 'number' && typeof amount.limit === 'number' && amount.limit > 0) {
+        return amount.used / amount.limit;
+    }
+    return undefined;
+}
+
+function inferCursorBucket(limit: UsageReport['limits'][number]): 'builtin' | 'other' | 'ondemand' | undefined {
+    const hay = `${limit.id ?? ''} ${limit.label ?? ''} ${limit.window?.id ?? ''} ${limit.scope?.windowId ?? ''}`.toLowerCase();
+    if (
+        hay.includes('ondemand') ||
+        hay.includes('on-demand') ||
+        hay.includes('spendlimit') ||
+        hay.includes('按需')
+    ) {
+        return 'ondemand';
+    }
+    if (
+        hay.includes('cursor models') ||
+        hay.includes('planusage') ||
+        hay.includes('autopercent') ||
+        hay.includes('builtin') ||
+        hay.includes('内置')
+    ) {
+        return 'builtin';
+    }
+    if (
+        hay.includes('other models') ||
+        hay.includes('named') ||
+        hay.includes('apipercent') ||
+        hay.includes(':api') ||
+        hay.includes('其他')
+    ) {
+        return 'other';
+    }
+    return undefined;
+}
+
+function inferWindowId(limit: UsageReport['limits'][number]): string {
+    const cursorBucket = inferCursorBucket(limit);
+    if (cursorBucket) return cursorBucket;
+
+    const raw = limit.window?.id;
+    if (raw) {
+        if (raw === 'auto') return 'builtin';
+        if (raw === 'api') return 'other';
+        if (raw === 'rolling-5h' || raw === 'rolling') return '5h';
+        if (raw === 'weekly' || raw === 'week') return '1w';
+        if (raw === 'monthly') return '1mo';
+        if (raw === 'daily' || raw === 'day') return '1d';
+    }
+    // Opaque ids with a recognizable duration (OpenCode Go reports its weekly
+    // window as "7d"): classify by duration so conjunctive required-window
+    // matching sees the same canonical id the 周 chip renders — otherwise an
+    // exhausted "7d" window is invisible to the health check and the column
+    // keeps showing chips instead of the reset countdown.
+    const dur = limit.window?.durationMs;
+    if (dur === 18_000_000) return '5h';
+    if (dur === 86_400_000) return '1d';
+    if (dur === 604_800_000) return '1w';
+    if (dur === 2_592_000_000) return '1mo';
+    if (raw) return raw;
+    const id = limit.id ?? '';
+    const after = id.includes(':') ? id.slice(id.indexOf(':') + 1) : id;
+    const known = new Set(['5h', '1w', '1mo', '1d', 'builtin', 'other', 'ondemand', 'default', 'auto', 'api']);
+    if (known.has(after)) {
+        if (after === 'auto') return 'builtin';
+        if (after === 'api') return 'other';
+        return after;
+    }
+    const label = (limit.label ?? '').toLowerCase();
+    if (label.includes('5h') || label.includes('5小时')) return '5h';
+    if (label.includes('周') || label.includes('week')) return '1w';
+    if (label.includes('月') || label.includes('month')) return '1mo';
+    return after || 'default';
+}
+
+export function parseAutoBucketModels(notes?: string[]): string[] | undefined {
+    if (!notes) return undefined;
+    for (const n of notes) {
+        if (n.startsWith('autoBucketModels=')) {
+            const ids = n
+                .slice('autoBucketModels='.length)
+                .split(',')
+                .map((s) => s.trim())
+                .filter(Boolean);
+            return ids.length > 0 ? ids : undefined;
+        }
+    }
+    return undefined;
+}
+
+function windowIsExhausted(limit: UsageReport['limits'][number], frac: number | undefined): boolean {
+    if (limit.status === 'warning') return false;
+    if (limit.status === 'exhausted') return true;
+    if (frac !== undefined && frac >= 1) return true;
+    const remaining = (limit.amount as { remaining?: number }).remaining;
+    if (typeof remaining === 'number' && remaining <= 0 && frac === undefined) return true;
+    return false;
+}
+
+export function summarizeReport(report: UsageReport): ProviderHealth {
+    const policy = quotaPolicyFor(report.provider);
+    const windows: WindowHealth[] = [];
+    const exhaustedWindows: string[] = [];
+    let bestUsed: number | undefined;
+    let status: UsageStatus = report.limits.length === 0 ? 'unknown' : 'ok';
+
+    for (const limit of report.limits) {
+        const frac = extractFraction(limit.amount);
+        const remaining =
+            frac !== undefined
+                ? 1 - frac
+                : typeof (limit.amount as { remainingFraction?: number }).remainingFraction === 'number'
+                  ? (limit.amount as { remainingFraction: number }).remainingFraction
+                  : undefined;
+        const winExhausted = windowIsExhausted(limit, frac);
+        const winId = inferWindowId(limit);
+        windows.push({
+            id: winId,
+            remaining,
+            exhausted: winExhausted,
+            status: (limit.status ?? (winExhausted ? 'exhausted' : 'ok')) as UsageStatus,
+        });
+        if (frac !== undefined) {
+            if (frac >= 1 - HEALTHY_REMAINING_THRESHOLD && !winExhausted && status === 'ok') {
+                status = 'warning';
+            }
+            if (bestUsed === undefined || frac < bestUsed) bestUsed = frac;
+        }
+        if (winExhausted) exhaustedWindows.push(limit.label);
+        else if (limit.status === 'warning' && status === 'ok') status = 'warning';
+    }
+
+    let exhausted = false;
+    let worstRemaining: number | undefined;
+
+    if (policy === 'bucket') {
+        const byId = new Map(windows.map((w) => [w.id, w]));
+        const builtin = byId.get('builtin');
+        const other = byId.get('other');
+        const ondemand = byId.get('ondemand');
+        const builtinDead = !builtin || builtin.exhausted;
+        const otherDead = !other || other.exhausted;
+        const ondemandOk = ondemand && !ondemand.exhausted;
+        exhausted = builtinDead && otherDead && !ondemandOk;
+        const usable = windows.filter((w) => !w.exhausted && (w.id === 'builtin' || w.id === 'other' || w.id === 'ondemand'));
+        for (const w of usable) {
+            if (w.remaining === undefined) continue;
+            if (worstRemaining === undefined || w.remaining > worstRemaining) worstRemaining = w.remaining;
+        }
+    } else if (policy === 'balance') {
+        const win = windows[0];
+        exhausted = windows.some((w) => w.exhausted) || (win?.remaining !== undefined && win.remaining <= 0);
+        worstRemaining = windows.reduce<number | undefined>((min, w) => {
+            if (w.remaining === undefined) return min;
+            return min === undefined ? w.remaining : Math.min(min, w.remaining);
+        }, undefined);
+    } else {
+        const spec = REQUIRED_WINDOWS[report.provider];
+        const required = spec?.required;
+        const relevant = required ? windows.filter((w) => required.includes(w.id)) : windows;
+        exhausted = relevant.some((w) => w.exhausted);
+        worstRemaining = relevant.reduce<number | undefined>((min, w) => {
+            if (w.remaining === undefined) return min;
+            return min === undefined ? w.remaining : Math.min(min, w.remaining);
+        }, undefined);
+        if (worstRemaining === undefined) {
+            worstRemaining = windows.reduce<number | undefined>((min, w) => {
+                if (w.remaining === undefined) return min;
+                return min === undefined ? w.remaining : Math.min(min, w.remaining);
+            }, undefined);
+        }
+    }
+
+    if (exhausted) status = 'exhausted';
+
+    return {
+        provider: report.provider,
+        policy,
+        exhausted,
+        windows,
+        autoBucketModels: parseAutoBucketModels(report.notes),
+        bestUsedFraction: bestUsed,
+        worstRemainingFraction: worstRemaining,
+        status,
+        exhaustedWindows,
+        fetchedAt: report.fetchedAt,
+        notes: report.notes,
+    };
+}
+
+/** Stable key for selection cache invalidation. */
+export function healthCacheKey(health: Map<string, ProviderHealth> | null | undefined): string {
+    if (!health || health.size === 0) return '';
+    return [...health.keys()]
+        .sort()
+        .map((p) => {
+            const h = health.get(p)!;
+            const wins = h.windows.map((w) => `${w.id}:${w.exhausted ? 1 : 0}:${w.remaining ?? ''}`).join(',');
+            const ab = (h.autoBucketModels ?? []).join('+');
+            return `${p}=${h.exhausted ? 1 : 0};${wins};${ab}`;
+        })
+        .join('|');
+}
+
+/** Build a provider → health map from a list of reports, preserving the most recent. */
+export function buildHealthMap(reports: UsageReport[]): Map<string, ProviderHealth> {
+    const map = new Map<string, ProviderHealth>();
+    for (const r of reports) {
+        const next = summarizeReport(r);
+        const prev = map.get(r.provider);
+        if (!prev || next.fetchedAt > prev.fetchedAt) {
+            map.set(r.provider, next);
+        }
+    }
+    return map;
+}
+
+/** Minimal interface for the auth-storage call site we depend on. */
+
+export interface AuthStorageLike {
+    fetchUsageReports?: (params?: { signal?: AbortSignal }) => Promise<UsageReport[] | undefined | null>;
+    /** List all providers with credentials configured. */
+    list?: () => string[];
+    /** Check if a specific provider has any auth configured. */
+    hasAuth?: (provider: string) => boolean;
+}
+
+/**
+ * Resolve usage for all configured providers.
+ *
+ * @param authStorage AuthStorage-like (in practice `ctx.modelRegistry.authStorage`).
+ * @param directFetchers Optional list of direct fetchers (mirrors omp-plan-usage's
+ *   `DIRECT_FETCHERS`). Useful when the host plugin does not register them.
+ * @param signal Optional abort signal forwarded to all fetches.
+ * @param getApiKey Optional provider→apiKey resolver (from `modelRegistry.getApiKeyForProvider`).
+ */
+export async function resolveProviderHealth(
+    authStorage: AuthStorageLike | undefined,
+    directFetchers: DirectFetcher[] = [],
+    signal?: AbortSignal,
+    getApiKey?: ApiKeyResolver,
+    providers?: readonly string[],
+): Promise<Map<string, ProviderHealth>> {
+    const reports = await gatherReports(authStorage, directFetchers, signal, getApiKey, providers);
+    return buildHealthMap(reports);
+}
+
+export interface ProviderReports {
+    reports: UsageReport[];
+    health: Map<string, ProviderHealth>;
+}
+
+/** Like resolveProviderHealth but also returns the raw UsageReport[]. */
+export async function resolveProviderReports(
+    authStorage: AuthStorageLike | undefined,
+    directFetchers: DirectFetcher[] = [],
+    signal?: AbortSignal,
+    getApiKey?: ApiKeyResolver,
+    providers?: readonly string[],
+): Promise<ProviderReports> {
+    const reports = await gatherReports(authStorage, directFetchers, signal, getApiKey, providers);
+    return { reports, health: buildHealthMap(reports) };
+}
+
+/**
+ * Gather raw reports (shared impl).
+ *
+ * Providers are split by whether a direct fetcher covers them:
+ *  - direct providers (covered by `directFetchers`) are fetched individually via
+ *    their fetcher — fully per-provider independent, never touching the bulk API.
+ *  - non-direct providers fall back to OMP's bulk `fetchUsageReports` (OAuth
+ *    providers like anthropic/openai). Bulk runs at most once per call.
+ *
+ * `providers?` (canonical ids) narrows the scope: only those providers are
+ * fetched, the rest skipped. When omitted, all logged-in providers are fetched.
+ * Logged-in providers come from `authStorage.list()` (canonicalized); when
+ * authStorage is unavailable the direct fetchers' providers are used as the
+ * fallback universe (for tests / offline mode).
+ */
+async function gatherReports(
+    authStorage: AuthStorageLike | undefined,
+    directFetchers: DirectFetcher[],
+    signal?: AbortSignal,
+    getApiKey?: ApiKeyResolver,
+    providers?: readonly string[],
+): Promise<UsageReport[]> {
+    const reports: UsageReport[] = [];
+    // Map direct fetchers by their CANONICAL provider id (PROVIDER_ALIAS merges a
+    // login-name registration like `zhipu-coding-plan` with the canonical id
+    // `zai-coding-cn` a fetcher returns, so dedup/override keys are stable).
+    const directFetcherByProvider = new Map(directFetchers.map((f) => [canonicalizeProvider(f.provider), f]));
+    const directIds = new Set(directFetcherByProvider.keys());
+    const loggedInSet = authStorage?.list ? new Set(authStorage.list().map(canonicalizeProvider)) : null;
+
+    // Classify target providers into direct (have a fetcher) vs bulk (need
+    // fetchUsageReports). `bulkTargets === null` means "discover via bulk" — used
+    // when no provider list is available, so fetchUsageReports is the only way to
+    // surface non-direct providers (OAuth providers like anthropic/openai).
+    let directTargets: string[];
+    let bulkTargets: string[] | null;
+    if (providers && providers.length > 0) {
+        // Per-provider mode: classify each requested provider directly.
+        const canonical = [...new Set(providers.map(canonicalizeProvider))];
+        directTargets = canonical.filter((p) => directFetcherByProvider.has(p));
+        bulkTargets = canonical.filter((p) => !directFetcherByProvider.has(p));
+    } else if (loggedInSet) {
+        for (const p2 of listDetectableProviders(directFetchers)) loggedInSet.add(p2);
+        directTargets = [...loggedInSet].filter((p) => directFetcherByProvider.has(p));
+        bulkTargets = [...loggedInSet].filter((p) => !directFetcherByProvider.has(p));
+    } else {
+        // No list (tests / offline): direct fetchers are known; bulk discovers the rest.
+        directTargets = [...directIds];
+        bulkTargets = null;
+    }
+
+    // Step 1: bulk fetchUsageReports — ONLY when there are bulk targets to fetch.
+    // A direct-fetcher provider never triggers this. Discovery mode (null) calls
+    // bulk unconditionally but excludes providers that have direct fetchers.
+    if (authStorage?.fetchUsageReports && (bulkTargets === null || bulkTargets.length > 0)) {
+        const filterSet = bulkTargets ? new Set(bulkTargets) : null;
+        try {
+            const fetched = await authStorage.fetchUsageReports({ signal });
+            if (Array.isArray(fetched)) {
+                for (const r of fetched) {
+                    // Canonicalize BEFORE filtering so a login-name id merges
+                    // with the canonical id under the same account.
+                    const c = canonicalizeProvider(r.provider);
+                    r.provider = c;
+                    // filterSet mode: only keep requested bulk providers.
+                    // null (discovery) mode: keep all except direct-fetcher providers
+                    // (they'll be fetched directly and would be overridden anyway).
+                    if (filterSet ? filterSet.has(c) : !directIds.has(c)) reports.push(r);
+                }
+            }
+        } catch {
+            /* ignore */
+        }
+    }
+
+    // Step 2: direct fetchers — each provider fetched independently. With no
+    // providers filter this is the full direct set; with a filter it is just the
+    // requested direct provider(s), enabling per-provider turn_end refresh.
+    for (const provider of directTargets) {
+        const fetcher = directFetcherByProvider.get(provider)!;
+        // Bind the key resolver to this fetcher's own provider so fetchers don't
+        // hardcode their id — they just ask for "my key" via the bound resolver.
+        const direct = await fetcher.fetch(signal, getApiKey ? () => getApiKey(fetcher.provider) : undefined);
+        if (direct) {
+            // Dedup against the canonical id: a fetcher registered under a login
+            // alias must still override the built-in report for the same account.
+            const canonical = canonicalizeProvider(direct.provider);
+            direct.provider = canonical;
+            const idx = reports.findIndex((r) => r.provider === canonical);
+            if (idx >= 0) reports[idx] = direct;
+            else reports.push(direct);
+        }
+    }
+
+    return reports;
+}

package/lib/usage-sampler.ts

@@ -0,0 +1,77 @@
+/**
+ * Module-level per-provider ring buffers of recent consumption increments,
+ * driving each usage widget column's own Braille mini waveform (design
+ * Decision 5, revised: per-provider charts, usage-RATE scale, sessionUsage
+ * source).
+ *
+ * Each sample is the provider's consumption DELTA over the sampling interval,
+ * not its stock level — a stock-mapped chart barely moves (quota drains slowly)
+ * or pins at full the moment a window is exhausted, which carries no signal.
+ * The stock the deltas are taken against is the SHARED CACHE's aggregated
+ * `sessionUsage` total for the provider (assistant `usage.totalTokens` summed
+ * across every session and process — subagents included via cache backflow;
+ * see usage-poller.ts / session-usage.ts). The sampler records
+ * `max(0, stock - prevStock)` so a counter reset reads as 0, never a spike.
+ * Each provider keeps an independent ring buffer. The buffers are strictly
+ * read-only wrt selection state: they never touch `selection`, role overrides,
+ * or the primary model.
+ */
+
+/**
+ * Max samples retained per provider. 40 samples = 40 seconds = the full
+ * 40-pixel waveform window (`WAVEFORM_COLS` × 2 half-columns), so the ring
+ * is exactly one window: every appended second shifts the chart 1px left,
+ * keeping the slide uniform and the strip filled edge to edge.
+ */
+export const RING_SIZE = 40;
+
+const buffers = new Map<string, number[]>();
+/** Last observed cumulative-consumption stock per provider (for delta math). */
+const prevStock = new Map<string, number>();
+
+/**
+ * Record one consumption increment for `provider`.
+ * - `stock === undefined` → skip entirely (unknown this tick; baseline unchanged,
+ *   so a later value deltas across the whole gap).
+ * - first observation → increment 0 (no interval yet).
+ * - stock decrease (window reset) → increment 0, never a spike.
+ */
+export function sampleConsumption(provider: string, stock: number | undefined): void {
+    if (stock === undefined) return;
+    const prev = prevStock.get(provider);
+    const increment = prev === undefined ? 0 : Math.max(0, stock - prev);
+    prevStock.set(provider, stock);
+    const arr = buffers.get(provider) ?? [];
+    arr.push(increment);
+    buffers.set(provider, arr.length > RING_SIZE ? arr.slice(-RING_SIZE) : arr);
+}
+
+/**
+ * Append one per-second increment (newest last). The caller is responsible
+ * for sampling EVERY elapsed second — including zeros for seconds with no
+ * consumption and for ticks the timer skipped — so all providers' buffers
+ * stay aligned on the same 1px-per-second time axis.
+ */
+export function appendSample(provider: string, increment: number): void {
+    if (!Number.isFinite(increment)) return;
+    const arr = buffers.get(provider) ?? [];
+    arr.push(increment);
+    buffers.set(provider, arr.length > RING_SIZE ? arr.slice(-RING_SIZE) : arr);
+}
+
+/** Recent consumption increments for a provider, newest last. Read-only. */
+export function getConsumptionSamples(provider: string): readonly number[] {
+    return buffers.get(provider) ?? [];
+}
+
+
+/** Clear every provider's ring buffer and stock baseline. */
+export function clearConsumptionSamples(): void {
+    buffers.clear();
+    prevStock.clear();
+}
+
+/** Test seam: fully reset module state. Production code never calls this. */
+export function _resetForTest(): void {
+    clearConsumptionSamples();
+}

package/lib/usage-widget.ts

@@ -0,0 +1,112 @@
+import { truncateToWidth, type Component } from "@oh-my-pi/pi-tui";
+import type { ExtensionUiComponentFactory } from "@oh-my-pi/pi-coding-agent";
+import type { UsageReport } from "@oh-my-pi/pi-ai";
+import { buildColumn, renderUsageReports, themePainter, type Painter, type ConsumptionTrack } from "./usage-render.js";
+
+/**
+ * A single provider rendered as a standalone, reusable pi-tui `Component`.
+ *
+ * `render(width)` returns the compact 2-line column (header + horizontal
+ * window chips / reset countdown), each clamped to ≤ `width` via
+ * `truncateToWidth`. Today the host drives the whole status strip through
+ * `UsageTable`, which reuses the shared `renderUsageReports` flex-wrap kernel
+ * rather than assembling cards directly — but this seam lets a future
+ * per-provider overlay (expand / detail / quick action) build on a unit that
+ * already renders in isolation, without reweaving the render tree.
+ *
+ * No keyboard interaction is implemented this round: `handleInput` / `dispose`
+ * are kept as empty extension points per the design non-goal.
+ */
+export class ProviderCard implements Component {
+    readonly #report: UsageReport;
+    readonly #painter: Painter;
+
+    constructor(report: UsageReport, painter: Painter) {
+        this.#report = report;
+        this.#painter = painter;
+    }
+
+    render(width: number): readonly string[] {
+        const lines = buildColumn(this.#report, this.#painter);
+        if (!lines) return [];
+        const w = Math.max(0, Math.trunc(width));
+        return lines.map((l) => truncateToWidth(l, w, ""));
+    }
+
+    /** Placeholder for future overlay interaction — intentionally a no-op. */
+    handleInput(_data: string): void {}
+
+    /** Placeholder for future overlay teardown — intentionally a no-op. */
+    dispose(): void {}
+}
+
+/**
+ * Root pi-tui `Component` the host mounts in its hook-widget tree. A single
+ * `UsageTable` owns the whole multi-provider layout (header + window rows for
+ * every report): the host only vertically stacks hook widgets, so per-provider
+ * widgets would collapse into a vertical list and lose the compact flex-wrap
+ * columns. The layout brain is the validated `renderUsageReports` kernel — the
+ * same code the RPC/print `string[]` fallback runs — only the `Painter` differs.
+ */
+export class UsageTable implements Component {
+    readonly #reports: UsageReport[];
+    readonly #painter: Painter;
+    readonly #placeholderIds?: readonly string[];
+    readonly #loadingProviders?: ReadonlySet<string>;
+    readonly #consumptionTracks?: Map<string, ConsumptionTrack>;
+    readonly #usageEstimates?: Map<string, string>;
+
+    constructor(
+        reports: UsageReport[],
+        painter: Painter,
+        placeholderIds?: readonly string[],
+        loadingProviders?: ReadonlySet<string>,
+        consumptionTracks?: Map<string, ConsumptionTrack>,
+        usageEstimates?: Map<string, string>,
+    ) {
+        this.#reports = reports;
+        this.#painter = painter;
+        this.#placeholderIds = placeholderIds;
+        this.#loadingProviders = loadingProviders;
+        this.#consumptionTracks = consumptionTracks;
+        this.#usageEstimates = usageEstimates;
+    }
+
+    render(width: number): readonly string[] {
+        // Per-provider consumption tracks are threaded into the layout kernel,
+        // which embeds each chart inside its own provider column.
+        return renderUsageReports(
+            this.#reports,
+            Math.max(1, Math.trunc(width)),
+            this.#painter,
+            this.#placeholderIds,
+            this.#loadingProviders,
+            this.#consumptionTracks,
+            this.#usageEstimates,
+        );
+    }
+
+    /** No cached state to release; provided so the host can propagate teardown. */
+    dispose(): void {}
+}
+
+/**
+ * Build the `ExtensionUiComponentFactory` the interactive host mounts. Colors are
+ * resolved lazily against the theme the host passes at mount time, so the widget
+ * follows the active palette; a later poll/resize re-runs `setWidget` with the
+ * current reports (mirroring the dashboard precedent), which re-injects the then-
+ * current theme. Returns a `Container`-free `UsageTable` directly: the validated
+ * layout already yields per-line `visibleWidth ≤ width`, and wrapping each row in
+ * `pi-tui`'s `Text` would both drop the flex-wrap blank separators (Text renders
+ * empty input as `[]`) and repad every line to the full width — losing byte
+ * parity with the RPC/print path for zero structural benefit.
+ */
+export function createUsageWidget(
+    reports: UsageReport[],
+    placeholderIds?: readonly string[],
+    loadingProviders?: ReadonlySet<string>,
+    consumptionTracks?: Map<string, ConsumptionTrack>,
+    usageEstimates?: Map<string, string>,
+): ExtensionUiComponentFactory {
+    return (_tui, theme) => new UsageTable(reports, themePainter(theme), placeholderIds, loadingProviders, consumptionTracks, usageEstimates);
+}