opencode-usage-insights 0.0.0-stage → 0.1.0

package/dist/panel-data.d.ts

@@ -0,0 +1,212 @@
+import { type LineFields, type LineIdentity, type LineLabels, type TurnStats, type TurnTotalsView } from "./core";
+import type { CacheDropRow, LatencyReport, ModelUsage, Overview, Range, SessionUsage, TurnUsage, TtlEvidenceRow } from "./stats/queries";
+import type { DbInfo } from "./stats/maintenance";
+import type { AffinityReport, CacheStats, CoverageReport, EndpointRow, EndpointSummary, GapReport, LatencyGroupRow, PeriodGranularity, PeriodRow } from "./stats/aggregates";
+/**
+ * View models and formatting for the stats panel. Everything here is pure:
+ * the panel component feeds query results in and renders the lines out, which
+ * keeps the layout testable without a terminal. Lines may carry a `row`, the
+ * identity the cursor selects and Enter drills into.
+ */
+export declare const PANEL_NAME = "usage-insights";
+export declare const PANEL_VIEWS: readonly ["overview", "models", "endpoints", "affinity", "cache", "periods", "latency", "sessions", "turns", "db"];
+export type PanelView = (typeof PANEL_VIEWS)[number];
+export declare const RANGE_KEYS: readonly ["session", "today", "7d", "30d", "all"];
+export type RangeKey = (typeof RANGE_KEYS)[number];
+export declare const GRANULARITIES: readonly ["day", "week", "month"];
+export type Granularity = (typeof GRANULARITIES)[number];
+export type PanelTone = "base" | "muted" | "warning" | "accent";
+/** What a selectable line stands for; Enter drills into it. */
+export type PanelRow = {
+    kind: "model" | "session" | "period" | "endpoint" | "provider" | "turn" | "prune";
+    value: string;
+    variant?: string | undefined;
+};
+export type PanelLine = {
+    text: string;
+    tone?: PanelTone;
+    row?: PanelRow | undefined;
+};
+/** The views and ranges, as the command and the panel header understand them. */
+export declare function parseArgs(input: string | undefined): {
+    view?: PanelView;
+    range?: RangeKey;
+};
+export declare function rangeFor(key: RangeKey, now: number, sessionStart?: number | undefined): Range | undefined;
+export declare function rangeLabel(key: RangeKey): string;
+export declare function nextIn<Value>(values: readonly Value[], current: Value, step: number): Value;
+/** Which turns the `turns` view lists: the open session, or every session. */
+export type TurnsScope = "session" | "all";
+/**
+ * Everything the panel remembers between openings. Stored through the host's
+ * durable storage, so the panel reopens where the user left it.
+ */
+export type PanelSettings = {
+    view: PanelView;
+    range: RangeKey;
+    sort: string;
+    sortDesc: boolean;
+    granularity: Granularity;
+    turnsScope: TurnsScope;
+    /** Empty string means "no filter". */
+    modelID: string;
+    /** The routing endpoint that served the request. */
+    routerID: string;
+};
+export declare const DEFAULT_SETTINGS: PanelSettings;
+/** Merge persisted state with the defaults, dropping anything unrecognized. */
+export declare function sanitizeSettings(raw: Partial<PanelSettings> | undefined): PanelSettings;
+export declare function formatPercent(value: number | undefined, digits?: number): string;
+export declare function formatCount(value: number): string;
+export declare function formatMs(value: number | undefined): string;
+export declare function formatTps(value: number | undefined): string;
+/** A rate that has to fit a sidebar: whole numbers from 10 up. */
+export declare function formatTpsCompact(value: number | undefined): string;
+/** Idle gaps are read at a glance: seconds, minutes, hours, days. */
+export declare function formatGap(value: number | undefined): string;
+/** Cut a value to the width, dropping control characters first. */
+export declare function truncate(value: string, width: number): string;
+/** Keep both ends of a long id: the family reads first, the `#variant` last. */
+export declare function truncateMiddle(value: string, width: number): string;
+/**
+ * Pick the widest column layout that fits the panel. A table that overflows
+ * wraps and stops reading as a table, so the columns are chosen, not squeezed.
+ */
+export declare function tableWidths(width: number, layouts: readonly (readonly number[])[]): number[];
+/**
+ * A model cell keeps the variant visible: two rows of the same family must not
+ * read alike after truncation.
+ */
+export declare function modelCell(modelID: string, variant: string | undefined, width: number): string;
+export declare function padCell(value: string, width: number, align?: "left" | "right"): string;
+export declare function formatTableRow(cells: readonly string[], widths: readonly number[], aligns?: readonly ("left" | "right")[]): string;
+export declare function count(n: number, singular: string, plural?: string): string;
+/** Two label/value pairs per row, collapsed to one pair on narrow panels. */
+export declare function kvGrid(pairs: readonly (readonly [string, string])[], width: number): PanelLine[];
+/** Fold a series into at most `maxBars` summed buckets, so a sparkline stays a line. */
+export declare function reduceSeries(values: readonly number[], maxBars?: number): number[];
+/** Text sparkline: trends at a glance without a chart renderable. */
+export declare function sparkline(values: readonly number[], maxBars?: number): string;
+/**
+ * The live line's buckets, so every aggregate the panel shows reconciles with
+ * it: `in` is the uncached prompt (fresh input *and* cache writes), `prompt` is
+ * what the provider saw, `out` is everything generated (visible *and*
+ * reasoning). `write` and `reasoning` are the parts of `in` and `out`.
+ */
+export type UsageBuckets = {
+    steps: number;
+    input: number;
+    prompt: number;
+    cached: number;
+    cacheWrite: number;
+    output: number;
+    reasoning: number;
+    cost: number;
+    hit: number | undefined;
+};
+export declare function usageBuckets(usage: {
+    steps: number;
+    input: number;
+    cached: number;
+    cacheWrite: number;
+    output: number;
+    reasoning: number;
+    cost: number;
+}): UsageBuckets;
+/**
+ * The view tabs. The active one is bracketed so a single tone still reads
+ * clearly; on a narrow panel the names shorten instead of wrapping, and the
+ * active view always keeps its full name.
+ */
+export declare function viewBar(view: PanelView, width?: number): PanelLine;
+export declare function keysFor(of: PanelView): string;
+export declare function filterSummary(filters: {
+    modelID?: string | undefined;
+    routerID?: string | undefined;
+}): string | undefined;
+export declare function granularityLabel(granularity: PeriodGranularity): string;
+/** Help overlay: the keys and the exact meaning of every number. */
+export declare function helpLines(width: number): PanelLine[];
+export declare function overviewLines(data: {
+    usage: Overview;
+    session: Overview | undefined;
+    /** Child sessions of the open session, when it has any. */
+    subagents?: readonly SessionUsage[] | undefined;
+    range: RangeKey;
+    activity?: readonly number[] | undefined;
+    coverage?: CoverageReport | undefined;
+}, width: number): PanelLine[];
+export type ModelExtras = {
+    /** Reuse stats per `modelKey`, computed from the step facts. */
+    cache?: Map<string, CacheStats> | undefined;
+    /** Identity changes per `modelKey`, from the affinity report. */
+    changes?: Map<string, number> | undefined;
+};
+/**
+ * Usage per model with the cache it actually got, where it was served from and
+ * how often its identity changed. One line per model; `providers` keeps the
+ * per-provider detail.
+ */
+export declare function modelsLines(rows: readonly ModelUsage[], width: number, extras?: ModelExtras, limit?: number): PanelLine[];
+/** One row per endpoint, over every model it served. */
+export declare function endpointSummaryLines(rows: readonly EndpointSummary[], width: number, limit?: number): PanelLine[];
+/** One row per model × endpoint: the endpoints that served each model. */
+export declare function endpointsLines(rows: readonly EndpointRow[], width: number, limit?: number): PanelLine[];
+export declare function affinityLines(report: AffinityReport, width: number, limit?: number): PanelLine[];
+/** One model's reuse row, shared by the models and cache views. */
+export type CacheModelRow = {
+    usage: {
+        modelID: string;
+        variant: string | undefined;
+    };
+    cache: CacheStats;
+};
+export declare function cacheLines(data: {
+    drops: readonly CacheDropRow[];
+    evidence: readonly TtlEvidenceRow[];
+    gap?: GapReport | undefined;
+    models?: readonly CacheModelRow[] | undefined;
+}, width: number): PanelLine[];
+export declare function periodLines(rows: readonly PeriodRow[], width: number, granularity: PeriodGranularity, limit?: number): PanelLine[];
+export declare function latencyLines(report: LatencyReport, width: number, groups?: readonly LatencyGroupRow[] | undefined, limit?: number): PanelLine[];
+export declare function sessionsLines(rows: readonly SessionUsage[], width: number, options?: {
+    limit?: number | undefined;
+    rollup?: {
+        subagentSteps: number;
+        subagentCost: number;
+    } | undefined;
+}): PanelLine[];
+/** The database view: where it lives, what it holds, and the two cleanups. */
+export declare function dbLines(data: {
+    info: DbInfo;
+    busy?: boolean | undefined;
+    now: number;
+}, width: number): PanelLine[];
+export type LineFormatOptions = {
+    labels?: Partial<LineLabels> | undefined;
+    fields?: Partial<LineFields> | undefined;
+    turnTotals?: TurnTotalsView | undefined;
+    identity?: LineIdentity | undefined;
+};
+/** The line's own view of a recorded turn, so both render identically. */
+export declare function turnStats(turn: TurnUsage): TurnStats;
+/**
+ * Per-prompt history: one line per finished turn, rendered by the same
+ * formatter as the live line (without the session segment, which would repeat
+ * the same totals on every row).
+ */
+export declare function turnsLines(rows: readonly TurnUsage[], width: number, options?: LineFormatOptions & {
+    sessionTitles?: Map<string, string> | undefined;
+}): PanelLine[];
+/**
+ * The accumulated usage of one session, as compact lines for the sidebar. The
+ * buckets are the live line's, so the sidebar, the line and the panel agree.
+ */
+export declare function sessionSummaryLines(usage: Overview, budget?: number): PanelLine[];
+/**
+ * The sidebar history: two compact lines per turn — when and through which
+ * endpoint, then the prompt volumes — truncated to the sidebar budget.
+ */
+export declare function sidebarLines(rows: readonly TurnUsage[], options?: LineFormatOptions & {
+    budget?: number | undefined;
+}): PanelLine[];

package/dist/panel.d.ts

@@ -0,0 +1,39 @@
+/** @jsxImportSource @opentui/solid */
+import type { Database } from "bun:sqlite";
+import type { Context, PanelInput } from "@opencode/plugin/tui/context";
+import { type LineFormatOptions, type PanelSettings } from "./panel-data";
+/**
+ * The `/usage` panel. One read-only view over the stats database at a time,
+ * driven entirely from the keyboard: a cursor over the selectable lines,
+ * Enter drills into the row under it, and the views, range, sort, bucket and
+ * filters are part of the state the host persists between openings.
+ *
+ * The panel owns input while it is open, so every key lives in the layer this
+ * component registers — the prompt is not involved.
+ */
+export type PanelDeps = {
+    /** Lazily opened stats database; undefined when it cannot be opened. */
+    db: () => Database | undefined;
+    /** Where that database lives, for the `db` view. */
+    dbPath: () => string;
+    /**
+     * Short-lived write connection for maintenance (prune, compact). The panel
+     * itself only reads; opening a writer on demand is what keeps a read from
+     * ever taking the recorder's lock. Undefined when the write cannot be made.
+     */
+    withWrite?: (<Value>(run: (db: Database) => Value) => Value | undefined) | undefined;
+    /** Injectable clock, for tests. */
+    now: () => number;
+    /** Creation time of a session, used by the `session` range. */
+    sessionStart: (sessionID: string) => number | undefined;
+    /** Bumped by the TUI when a step or an execution ends, so views re-read. */
+    refresh?: (() => number) | undefined;
+};
+export declare function Panel(props: {
+    readonly input: PanelInput;
+    readonly ctx: Context;
+    readonly deps: PanelDeps;
+    readonly settings: PanelSettings;
+    readonly update: (mutation: (draft: PanelSettings) => void) => void;
+    readonly format?: LineFormatOptions | undefined;
+}): any;

package/dist/recorder.d.ts

@@ -0,0 +1,82 @@
+import type { Database } from "bun:sqlite";
+/**
+ * Event-driven recorder. Every handler is idempotent and defensive: the
+ * plugin must never break a session because an event arrived in an
+ * unexpected shape, so unknown events are ignored and malformed payloads are
+ * dropped rather than thrown.
+ *
+ * Pure with respect to its inputs (database plus events) so the whole
+ * recording policy can be unit-tested without the plugin runtime.
+ */
+export type SessionModelRef = {
+    id: string;
+    providerID: string;
+    variant?: string | undefined;
+};
+export type TokenUsageLike = {
+    input?: number | undefined;
+    output?: number | undefined;
+    reasoning?: number | undefined;
+    cache?: {
+        read?: number | undefined;
+        write?: number | undefined;
+    } | undefined;
+};
+export type RecorderEventData = {
+    sessionID?: string | undefined;
+    assistantMessageID?: string | undefined;
+    inboxID?: string | undefined;
+    item?: {
+        type?: string | undefined;
+    } | undefined;
+    started?: number | undefined;
+    model?: SessionModelRef | undefined;
+    previous?: SessionModelRef | undefined;
+    tokens?: TokenUsageLike | undefined;
+    cost?: number | undefined;
+    finish?: string | undefined;
+    rawFinish?: string | undefined;
+    reason?: string | undefined;
+    location?: {
+        directory?: string | undefined;
+    } | undefined;
+    parentID?: string | undefined;
+    title?: string | undefined;
+};
+export type RecorderEvent = {
+    type: string;
+    created?: number | undefined;
+    data?: RecorderEventData | undefined;
+};
+export type HttpResponseInput = {
+    sessionID?: string | undefined;
+    kind?: string | undefined;
+    model?: SessionModelRef | undefined;
+    request?: {
+        method?: string | undefined;
+        url?: string | undefined;
+    } | undefined;
+    response?: {
+        status?: number | undefined;
+        headers?: Headers | Record<string, string | undefined> | undefined;
+    } | undefined;
+};
+export type PendingStep = {
+    messageID: string;
+    sessionID: string;
+    started: number | undefined;
+    streamed: number | undefined;
+    model: SessionModelRef | undefined;
+};
+export type RecorderOptions = {
+    /** Clock override, for tests. */
+    now?: (() => number) | undefined;
+};
+export type Recorder = {
+    /** Apply one session event. Unknown or malformed events are ignored. */
+    handleEvent(event: RecorderEvent): void;
+    /** Learn the routing endpoint from one model response. */
+    handleHttpResponse(event: HttpResponseInput): void;
+    pendingFor(sessionID: string): PendingStep | undefined;
+};
+export declare function createRecorder(db: Database, options?: RecorderOptions): Recorder;

package/dist/sidebar.d.ts

@@ -0,0 +1,25 @@
+/** @jsxImportSource @opentui/solid */
+import type { Database } from "bun:sqlite";
+import type { Context } from "@opencode/plugin/tui/context";
+import { type LineFormatOptions } from "./panel-data";
+/**
+ * Sidebar history: the session's accumulated usage, then the last finished
+ * turns, two compact lines each (when + endpoint, then the prompt volumes).
+ * Reads the same database, the same buckets and the same formatter as the panel
+ * and the live line, and refreshes whenever a turn ends.
+ */
+export type TurnsSidebarDeps = {
+    db: () => Database | undefined;
+    /** Bumped by the TUI when a step or an execution ends. */
+    refresh: () => number;
+    /** How many turns to show. */
+    limit: number;
+    /** Column budget of the sidebar, shared with the summary. */
+    budget?: number | undefined;
+};
+export declare function TurnsSidebar(props: {
+    readonly sessionID: string;
+    readonly ctx: Context;
+    readonly deps: TurnsSidebarDeps;
+    readonly options?: LineFormatOptions | undefined;
+}): any;

package/dist/stats/aggregates.d.ts

@@ -0,0 +1,282 @@
+/**
+ * The analysis layer: the reports the panel and the CLI show.
+ *
+ * Two shapes, chosen by measurement rather than taste:
+ *
+ * 1. **Aggregates in SQLite** — totals, counts, distinct values. `coverageOf`
+ *    and the filter pickers never move a row into JavaScript.
+ * 2. **Narrow rows plus arithmetic in JS** — percentiles, pair rules, calendar
+ *    buckets. SQLite's window functions cost about 17 µs per row per report
+ *    here (a sort plus a materialisation), while reading the four to twelve
+ *    columns a report actually needs costs 1–4 µs per row. The percentiles and
+ *    the pair comparisons are therefore computed over lean projections: on the
+ *    audit's 120k-step database a whole view costs a few hundred milliseconds,
+ *    and on a normal one it is instant.
+ *
+ * The rules are not restated here. Cache reuse, idle gaps and the noise
+ * threshold come from `core.ts` — the same functions the live line uses — so
+ * the panel and the line can never disagree about what a cache loss is.
+ * `test/reports.test.ts` holds every report to those rules.
+ */
+import type { Database } from "bun:sqlite";
+import { type Filters, type LatencyStats, type Range, type Usage } from "./queries";
+/** The step's own clock, the expression the `steps_at` index covers. */
+export declare const STEP_AT = "COALESCE(created_at, recorded_at)";
+type Options = {
+    range?: Range | undefined;
+    filters?: Filters | undefined;
+};
+/** One recorded step, as the reports read it. */
+export type StepRow = {
+    messageID: string;
+    sessionID: string;
+    providerID: string | undefined;
+    modelID: string | undefined;
+    variant: string | undefined;
+    router: string | undefined;
+    input: number;
+    cached: number;
+    cacheWrite: number;
+    output: number;
+    reasoning: number;
+    cost: number;
+    createdAt: number | undefined;
+    streamedAt: number | undefined;
+    completedAt: number | undefined;
+    /** `COALESCE(created_at, recorded_at)`: the ordering time of the step. */
+    at: number;
+    /** Set on the single step loaded before the range, as a reference. */
+    boundary?: boolean | undefined;
+};
+/**
+ * A step as the pair reports read it. Their projection leaves the generated
+ * tokens out (nothing they compute sums them), and the type says so: an
+ * aggregate that reads `output` cannot be handed a pair row by mistake.
+ */
+export type PairRow = Omit<StepRow, "output" | "reasoning">;
+/** The steps of the range, narrow. Ordering is only paid for where it is read. */
+export declare function stepRows(db: Database, options?: Options): StepRow[];
+/**
+ * The steps of the range plus, for every session with a step inside it, the one
+ * step before the range: the pair reports compare a step with the one that
+ * preceded it, so the first step of a range has to see it.
+ *
+ * The boundary is one seek per session on the `(session_id, time)` index — a
+ * few milliseconds for a far wider history — never the whole history of the
+ * sessions in range.
+ */
+export declare function cachePairs(db: Database, options?: Options): PairRow[];
+export type CoverageReport = {
+    steps: number;
+    models: number;
+    endpoints: number;
+    missingModel: number;
+    missingEndpoint: number;
+    unsettled: number;
+    missingTps: number;
+    firstAt: number | undefined;
+    lastAt: number | undefined;
+};
+/**
+ * What the panel cannot answer honestly: how many steps lack a model or an
+ * observed endpoint, and how many never settled. A zero in the affinity view
+ * means "never changed" only when this coverage is complete.
+ */
+export declare function coverageOf(db: Database, options?: Options): CoverageReport;
+/** The steps a latency report is built from. It reads no generated tokens. */
+type GroupedRow = StepRow;
+export type LatencyReport = {
+    wall: LatencyStats;
+    stream: LatencyStats;
+    tps: LatencyStats;
+};
+/** The timings of the range: one read, shared by the overall report and the groups. */
+export declare function timingRows(db: Database, options?: Options): GroupedRow[];
+/** Overall wall time, streaming window and throughput percentiles. */
+export declare function latencyOf(rows: readonly StepRow[]): LatencyReport;
+export type LatencyGroupRow = {
+    key: string;
+    label: string;
+    count: number;
+    usage: Usage;
+    wall: LatencyStats;
+    stream: LatencyStats;
+    tps: LatencyStats;
+};
+export type Dimension = "model" | "provider" | "endpoint";
+/** Wall, streaming window and throughput percentiles per group. */
+export declare function latencyGroupsOf(rows: readonly StepRow[], by: Dimension): LatencyGroupRow[];
+export type CacheStats = {
+    steps: number;
+    input: number;
+    cached: number;
+    cacheWrite: number;
+    /** The whole prompt the provider saw: `cached + input + cache_write`. */
+    prompt: number;
+    /** Token-weighted reuse over the whole selection. */
+    hit: number | undefined;
+    /** Median of the per-step reuse ratios: a few huge steps cannot hide a split pattern. */
+    hitP50: number | undefined;
+};
+/** Reuse of the prompt cache over the range, as one row. */
+export declare function cacheStatsOf(db: Database, options?: Options): CacheStats;
+export type CacheModelRow = {
+    modelID: string;
+    variant: string | undefined;
+    cache: CacheStats;
+};
+/**
+ * Reuse of the prompt cache per model, most cached first, over the steps of the
+ * range. A boundary step is not part of the range, so it is left out.
+ */
+export declare function cacheStatsByModel(rows: readonly PairRow[]): CacheModelRow[];
+export type AffinityRow = {
+    modelID: string;
+    variant: string | undefined;
+    steps: number;
+    pairs: number;
+    changes: number;
+    modelChanges: number;
+    endpointChanges: number;
+    cacheLost: number;
+    cacheLostEvents: number;
+};
+export type AffinityTransition = {
+    dimension: "model" | "endpoint";
+    from: string;
+    to: string;
+    count: number;
+};
+export type AffinityReport = {
+    rows: AffinityRow[];
+    transitions: AffinityTransition[];
+    totals: {
+        pairs: number;
+        changes: number;
+        cacheLost: number;
+        cacheLostEvents: number;
+    };
+};
+/**
+ * Identity changes between consecutive steps of a session, by the two
+ * dimensions that decide where the work ran: the model and the routing
+ * endpoint. A change is not by itself a fault — a gateway may re-route
+ * deliberately — so the report pairs the count with the cache it actually cost.
+ */
+export declare function affinityOf(rows: readonly PairRow[]): AffinityReport;
+export type GapBucket = {
+    label: string;
+    samples: number;
+    /** Pairs that still reused the prompt cache. */
+    retained: number;
+    drops: number;
+    lostTokens: number;
+    retainedRatio: number | undefined;
+};
+export type EndpointReuseRow = {
+    /** The routing endpoint, or `(unknown)` when it was never observed. */
+    endpoint: string;
+    samples: number;
+    retained: number;
+    drops: number;
+    lostTokens: number;
+    retainedRatio: number | undefined;
+};
+export type GapReport = {
+    buckets: GapBucket[];
+    endpoints: EndpointReuseRow[];
+    samples: number;
+};
+/** Idle-gap buckets, coarse enough to read at a glance. */
+export declare const GAP_BUCKETS: ReadonlyArray<readonly [string, number, number | undefined]>;
+/**
+ * How long an idle gap the prompt cache survives, per gap bucket and per
+ * endpoint. Only pairs of the same model are comparable, which is exactly the
+ * set the cache rule already uses.
+ */
+export declare function gapReportOf(rows: readonly PairRow[]): GapReport;
+export type TtlEvidenceRow = {
+    providerID: string;
+    modelID: string;
+    samples: number;
+    /** Largest idle gap that still hit the cache. */
+    maxHitGapMs: number | undefined;
+    /** Smallest idle gap after which reuse was lost. */
+    minDropGapMs: number | undefined;
+};
+/**
+ * Empirical bounds on the provider cache TTL: the longest idle gap that still
+ * reused the cache, and the shortest gap that lost it. Comparing the two per
+ * provider turns TTL guesses into observations.
+ */
+export declare function ttlEvidenceOf(rows: readonly PairRow[]): TtlEvidenceRow[];
+export type DropReason = "compaction" | "expired" | "unknown";
+export type CacheDropRow = {
+    sessionID: string;
+    messageID: string;
+    providerID: string | undefined;
+    modelID: string | undefined;
+    variant: string | undefined;
+    at: number;
+    tokens: number;
+    gapMs: number | undefined;
+    prevCached: number;
+    reason: DropReason;
+};
+/**
+ * Cache reuse losses with a best-effort reason: a compaction in between, an
+ * idle gap long enough to be provider-side expiry, or unknown.
+ *
+ * Compactions come from the `events` table: one query for the sessions in
+ * play, never one per loss.
+ */
+export declare function cacheDropsOf(db: Database, rows: readonly PairRow[], options?: {
+    ttlHintMs?: number;
+}): CacheDropRow[];
+export type EndpointSummary = {
+    /** The routing endpoint, or undefined for requests whose destination was never observed. */
+    endpoint: string | undefined;
+    /** Models this endpoint served. */
+    models: string[];
+    share: number;
+    usage: Usage;
+    cache: CacheStats;
+    tps: number | undefined;
+    wall: number | undefined;
+    firstAt: number | undefined;
+    lastAt: number | undefined;
+};
+export type EndpointRow = EndpointSummary & {
+    modelID: string;
+    variant: string | undefined;
+};
+/** One row per endpoint, over every model it served. */
+export declare function endpointSummaryOf(rows: readonly StepRow[]): EndpointSummary[];
+/** One row per model × endpoint: where each model was served, and how much. */
+export declare function endpointBreakdownOf(rows: readonly StepRow[]): EndpointRow[];
+export type PeriodGranularity = "day" | "week" | "month";
+export type PeriodRow = {
+    key: string;
+    label: string;
+    /** Start of the bucket, local time. */
+    at: number;
+    steps: number;
+    sessions: number;
+    usage: Usage;
+    cache: CacheStats;
+};
+/** ISO-8601 week number and its Monday, in local time. */
+export declare function isoWeek(date: Date): {
+    year: number;
+    week: number;
+    monday: Date;
+};
+/** Key, label and local start of the period `at` falls in. */
+export declare function periodStart(at: number, granularity: PeriodGranularity): {
+    key: string;
+    label: string;
+    start: number;
+};
+/** Totals per local calendar day, week or month, oldest first. */
+export declare function periodsOf(rows: readonly StepRow[], granularity: PeriodGranularity): PeriodRow[];
+export {};