A local-first multi-agent app development platform, built on PenguinHarness
/**
* Cost and usage center:
* top filters for Agent / Model + a date-range preset (trailing last hour /
* last 24 hours, calendar 7/30/90 days, or a custom pair of date inputs);
* the range alone decides the time-series precision, so there is no second
* control for it (controls have no external title — the explanation is
* written into the dropdown options themselves);
* three summary cards (today / last 7 days / cumulative, each stat on its own row);
* a 2x2 grid of time-series charts over the shared range and precision —
* requests + success rate broken down by Agent and, beside it, the same by
* Model (requests stacked on the left axis, one rate line per entity on a
* right 0–100% axis), then Token buckets (stacked bars + a dashed
* cache-hit-rate curve in front) and cost (line + points + area). Charts
* always fit their card — nothing scrolls; below them is a full-width
* "errors" panel (stats + a paged errors table). Currency follows the user's
* settings.
*
* Every chart draws the same buckets: compactSeries runs **once**, here, and
* all four are fed its result, so the grid keeps one shared x axis. It drops
* only the buckets where nothing at all was recorded — emptiness is a
* property of the interval, not of one entity in it, so a bucket any entity
* ran in stays and the idle entities show their zeros and dashes there. The
* per-entity counts arrive index-aligned with `series`, so they are
* re-indexed through the same `kept` list (compactCounts); one list for all
* of them is what keeps an entity's history from sliding onto the wrong
* intervals. Each chart marks the skipped intervals on its own axis.
*/
import { useCallback, useEffect, useMemo, useRef, useState } from "react";
import { useSearchParams } from "react-router";
import type { ModelRefDto, UsageBucket, UsageResponse } from "@adelie/server/api";
import { Input, PageFrame, PageHeader, Select, Skeleton, TodoNotice } from "@adelie/ui";
import * as api from "../../api/endpoints";
import { S } from "../../lib/strings";
import { apiErrorText } from "../../lib/api-error";
import { useDocumentTitle } from "../../lib/use-document-title";
import { useUpdateBadges } from "../../lib/use-update-badges";
import { dismissTodo } from "../../lib/todo-dismissals";
import { refreshProjectTodos } from "../../lib/use-project-todos";
import { formatMoney, humanizeTokens } from "../../lib/format";
import { catalogEntryFor } from "@adelie/core/model-catalog";
import { scoped, scopedValue, type Scoped } from "../../lib/project-scope";
import { useOpenedInProject } from "../../lib/use-opened-in-project";
import { useProject } from "../../state/project";
import { useTheme } from "../../state/theme";
import { TrendChart } from "./trend-chart";
import { RequestsChart, TokenBarChart, TokenLegend, type TokenLegendKey } from "./usage-charts";
import {
compactCounts,
compactSeries,
presetDefaultGranularity,
presetRange,
presetTsWindow,
rangeDays,
type EntityCounts,
type RangePreset,
} from "./usage-controls";
import { ErrorsPanel } from "./errors-panel";
/** A summary card's stat row: name on the left, value on the right — each item on its own row, so a narrow card no longer crams them into one wrapping line. */
function SummaryRow({
label,
value,
muted,
sup,
}: {
label: string;
value: string;
muted?: boolean;
/** Show a superscript marker (the cost row's "includes unpriced records" asterisk sits next to the **name**, not stuck after the number). */
sup?: boolean;
}) {
const tone = muted ? "text-gray-500 dark:text-gray-400" : "text-gray-900 dark:text-gray-100";
return (
<div className="flex items-baseline justify-between gap-2">
<span className="shrink-0 text-xs text-gray-500 dark:text-gray-400">
{label}
{sup && <sup className="ml-px">*</sup>}
</span>
<span className={`min-w-0 truncate font-mono text-sm font-semibold tabular-nums ${tone}`}>
{value}
</span>
</div>
);
}
/** Usage summary card: a title + Token / request count / cost each on their own row. */
function SummaryCard({
title,
bucket,
currency,
}: {
title: string;
bucket: UsageBucket;
currency: "USD" | "CNY";
}) {
return (
<div className="rounded-md border border-gray-200 bg-white p-3 dark:border-gray-800 dark:bg-gray-900">
<p className="mb-1.5 text-xs font-medium text-gray-500 dark:text-gray-400">{title}</p>
<div className="space-y-1">
<SummaryRow label={S.usage.tokens} value={humanizeTokens(bucket.total)} />
<SummaryRow label={S.usage.requests} value={String(bucket.requests)} muted />
{/* The unpriced-records asterisk sits on the word "cost" (superscript), keeping the number clean and readable; see the footer for the explanation */}
<SummaryRow
label={S.common.cost}
value={formatMoney(bucket.cost, currency)}
sup={bucket.hasUncosted}
/>
</div>
</div>
);
}
/** Chart card container: title + content (bounded height, avoiding stretching the whole page and triggering extra scroll). */
function ChartCard({
title,
extra,
children,
}: {
title: string;
extra?: React.ReactNode;
children: React.ReactNode;
}) {
return (
<div className="rounded-md border border-gray-200 bg-white p-3 dark:border-gray-800 dark:bg-gray-900">
<div className="mb-2 flex flex-wrap items-center justify-between gap-x-2 gap-y-1">
<p className="text-xs font-medium text-gray-500 dark:text-gray-400">{title}</p>
{extra}
</div>
{children}
</div>
);
}
/**
* The range the dashboard last read: the preset and the bounds it resolved to at load time —
* the two trailing presets add their instant pair (see `loaded` in the page).
*/
interface LoadedRange {
preset: RangePreset;
from: string;
to: string;
fromTs?: string;
toTs?: string;
}
/** The `?agentId=` deep link as a filter of the Project the page was opened in; none without either. */
function linkedAgentFilter(
agentId: string | null,
projectId: string | null,
): Scoped<string> | null {
return agentId === null || agentId === "" || projectId === null
? null
: scoped(projectId, agentId);
}
export function UsagePage() {
useDocumentTitle(S.usage.title);
const { currency } = useTheme();
const { currentProject } = useProject();
/** The Cost Center trail's raised badge, or undefined — the errors panel's notice clears it. */
const todo = useUpdateBadges().todos.errors;
const projectId = currentProject?.projectId ?? null;
// ?agentId= deep link (from the Agents page's "cost" entry point): the URL
// parameter is the single source of truth for this filter — including
// clearing it (/usage?agentId=A → clicking nav to /usage doesn't remount,
// so the filter must be reset); manually changing the filter doesn't write
// back to the URL (consistent with the existing convention that the model
// / date filters likewise don't enter the URL — the effect never overrides a manual selection when the parameter is unchanged).
const [searchParams] = useSearchParams();
const paramAgentId = searchParams.get("agentId");
// The filter names an Agent of the Project it was chosen in — the deep link's belongs to the
// Project the page was opened in — and is read only under that Project (lib/project-scope.ts):
// after a Project switch the page is unfiltered, rather than asking the new Project about an
// Agent of the old one.
const openedIn = useOpenedInProject(projectId);
const [agentFilterRead, setAgentFilterRead] = useState<Scoped<string> | null>(() =>
linkedAgentFilter(paramAgentId, openedIn),
);
// The deep link is applied again when it changes, and once the Project it belongs to is known
// — in the render that sees the change, so no read goes out with the filter it replaces.
const [linkSeen, setLinkSeen] = useState({ paramAgentId, openedIn });
if (linkSeen.paramAgentId !== paramAgentId || linkSeen.openedIn !== openedIn) {
setLinkSeen({ paramAgentId, openedIn });
setAgentFilterRead(linkedAgentFilter(paramAgentId, openedIn));
}
const agentFilter = scopedValue(agentFilterRead, projectId) ?? "";
const setAgentFilter = (agentId: string) =>
setAgentFilterRead(agentId === "" || projectId === null ? null : scoped(projectId, agentId));
// Model filtering is a **paired reference** (the same model_id can coexist
// under multiple providers); the dropdown's option value uses the
// candidate's index rather than a concatenated string — the reference is always passed as a pair, never concatenated into an id.
const [modelFilter, setModelFilter] = useState<ModelRefDto | null>(null);
// Date range: a trailing window (last hour / last 24 hours), a calendar
// preset (7/30/90 days), or a custom from/to pair — plus the time-series
// precision. A range change keeps the precision when the new preset still
// offers it, otherwise snaps to the preset's default.
const [preset, setPreset] = useState<RangePreset>("7d");
const [from, setFrom] = useState(() => presetRange("7d", new Date()).from);
const [to, setTo] = useState(() => presetRange("7d", new Date()).to);
const applyRange = (nextPreset: RangePreset, nextFrom: string, nextTo: string) => {
setPreset(nextPreset);
setFrom(nextFrom);
setTo(nextTo);
};
/** The dashboard's answer, tagged with the Project it was read for. */
const [dataRead, setData] = useState<Scoped<UsageResponse> | null>(null);
const data = scopedValue(dataRead, projectId);
/**
* The range the dashboard actually READ, which is not always the one the picker holds. A
* trailing preset computes its window at load time and deliberately leaves `from`/`to` on
* whatever the last calendar preset put there, so the two diverge the moment "last hour" is
* chosen. The error panel pages against this range and, for an owner, DELETES against it —
* so it has to be the range whose rows are on screen, never the stale pair behind them. The
* memo below reads its primitives one by one so it holds its identity across a reload that
* changes nothing (the panel's fetch effect depends on that identity).
*/
const [loaded, setLoaded] = useState<LoadedRange>(() => ({ preset, from, to }));
const [error, setError] = useState<string | null>(null);
// The legend / control state that lives in the card headers (ChartCard's
// extra) while the marks live inside the cards, lifted to this level.
const [tokenBucket, setTokenBucket] = useState<TokenLegendKey | null>(null);
/** Dashboard reads so far: only the newest one's answer is applied. */
const asked = useRef(0);
const load = useCallback(async () => {
if (!projectId) return;
const ask = ++asked.current;
// The notice must acknowledge the errors fetched for this visit, not the timestamp
// cached when the app started; otherwise those errors return as unread after a reload.
refreshProjectTodos(projectId);
setError(null);
try {
// The trailing presets recompute their window at load time, so a reload
// keeps trailing "now"; the calendar presets use the stored date pair.
const range =
preset === "1h" || preset === "1d" ? presetTsWindow(preset, new Date()) : { from, to };
const res = await api.getUsage(projectId, {
...range,
// The detail table has been removed, superseded by the charts above; groupBy is still a required query parameter, fixed to group by date.
groupBy: "date",
// The range picks the precision — there is no separate control, and this
// is the only place the choice is made (see presetDefaultGranularity).
granularity: presetDefaultGranularity(preset, rangeDays(from, to)),
...(agentFilter ? { agentId: agentFilter } : {}),
...(modelFilter ? { provider: modelFilter.provider, modelId: modelFilter.modelId } : {}),
});
// A late answer — for the Project just left, or for filters changed since — is dropped.
if (ask !== asked.current) return;
setData(scoped(projectId, res));
setLoaded({ preset, ...range });
} catch (e) {
if (ask === asked.current) setError(apiErrorText(e));
}
}, [projectId, preset, from, to, agentFilter, modelFilter?.provider, modelFilter?.modelId]);
useEffect(() => {
setData(null);
void load();
}, [load]);
// The error panel pages against this filter and depends on the object's identity, so it is
// built once per filter value rather than fresh on every render — a new object each render
// would refetch the current page on any unrelated state change (hovering a chart bucket).
// Built from the range the dashboard read (see `loaded`), not from the picker's state: the
// panel's rows, its later pages and its clear all have to name one same set. The model
// filter is deliberately absent: it never applied to errors.
const errorFilters = useMemo(
() => ({
from: loaded.from,
to: loaded.to,
...(loaded.fromTs !== undefined && loaded.toTs !== undefined
? { fromTs: loaded.fromTs, toTs: loaded.toTs }
: {}),
...(agentFilter ? { agentId: agentFilter } : {}),
}),
[loaded.from, loaded.to, loaded.fromTs, loaded.toTs, agentFilter],
);
if (!projectId) return null;
// Model filter candidates and the currently selected item's index (the option value uses the index, avoiding concatenating an id as the key).
const modelOptions = data?.models ?? [];
const selectedModelIndex = modelFilter
? modelOptions.findIndex(
(m) => m.provider === modelFilter.provider && m.modelId === modelFilter.modelId,
)
: -1;
const modelFilterIndex = selectedModelIndex >= 0 ? String(selectedModelIndex) : "";
const summary = data?.summary;
const hasUncostedRows =
(summary?.today.hasUncosted ?? false) ||
(summary?.last7d.hasUncosted ?? false) ||
(summary?.total.hasUncosted ?? false);
// One compaction for the whole page (see the file header): every chart draws
// these buckets, and every per-entity series is re-indexed through the same
// kept list, so nothing can drift out of alignment with the axis.
const plotted = compactSeries(data?.series ?? []);
// The two requests charts each get one dimension's entity list, already
// sorted by total requests descending and arriving index-aligned with the
// full `series` (the server's contract) — compactCounts moves it onto the
// drawn buckets; the charts fold their own tails.
const agentEntities: EntityCounts[] = (data?.byAgentSeries ?? []).map((s) => ({
label: s.agentId,
...compactCounts(s, plotted.kept),
}));
const modelEntities: EntityCounts[] = (data?.byModelSeries ?? []).map((s) => ({
label: catalogEntryFor(s.provider, s.modelId)?.displayName ?? s.modelId,
...compactCounts(s, plotted.kept),
}));
return (
<PageFrame contentClassName="space-y-4">
{/* The filters are the header's actions: they carry no external title (the explanation is
written into the "all …" option), so they sit centred on the title row. */}
<PageHeader
title={S.usage.title}
actions={
<>
<div className="w-32">
<Select
size="sm"
value={agentFilter}
onChange={(e) => setAgentFilter(e.target.value)}
>
<option value="">{S.usage.filterAllAgents}</option>
{/* The deep-linked agent must still show as the selected option even if it has no usage records yet (not in agentIds) */}
{agentFilter && !(data?.agentIds ?? []).includes(agentFilter) && (
<option value={agentFilter}>{agentFilter}</option>
)}
{(data?.agentIds ?? []).map((a) => (
<option key={a} value={a}>
{a}
</option>
))}
</Select>
</div>
<div className="w-32">
<Select
size="sm"
value={modelFilterIndex}
onChange={(e) => {
const i = e.target.value;
setModelFilter(i === "" ? null : (modelOptions[Number(i)] ?? null));
}}
>
<option value="">{S.usage.filterAllModels}</option>
{modelOptions.map((m, i) => (
<option key={`${m.provider}:${m.modelId}`} value={String(i)}>
{catalogEntryFor(m.provider, m.modelId)?.displayName ?? m.modelId}
</option>
))}
</Select>
</div>
{/* Date range: trailing windows and quick presets, with "custom" revealing the two date inputs */}
<div className="w-28">
<Select
size="sm"
value={preset}
aria-label={S.usage.rangeLabel}
onChange={(e) => {
const next = e.target.value as RangePreset;
if (next === "7d" || next === "30d" || next === "90d") {
const r = presetRange(next, new Date());
applyRange(next, r.from, r.to);
} else {
// Trailing windows compute their bounds at load time; custom keeps the dates already picked.
applyRange(next, from, to);
}
}}
>
<option value="1h">{S.usage.rangeHour}</option>
<option value="1d">{S.usage.rangeDay}</option>
<option value="7d">{S.usage.range7d}</option>
<option value="30d">{S.usage.range30d}</option>
<option value="90d">{S.usage.range90d}</option>
<option value="custom">{S.usage.rangeCustom}</option>
</Select>
</div>
{preset === "custom" && (
/* A dash between the two inputs stands in for a "from/to" label */
<div className="flex items-center gap-1.5">
<Input
size="sm"
type="date"
aria-label={S.usage.from}
value={from}
onChange={(e) => applyRange("custom", e.target.value, to)}
/>
<span className="shrink-0 text-gray-400" aria-hidden>
–
</span>
<Input
size="sm"
type="date"
aria-label={S.usage.to}
value={to}
onChange={(e) => applyRange("custom", from, e.target.value)}
/>
</div>
)}
</>
}
/>
{/* Last stop on the Cost Center trail, in the one shape all four dismissible trails
use: directly under the title, not down against the errors table. It counts the
probe's own trailing window (use-project-todos.ts), which is not the filters above
it, so it states what the badge is about rather than what any one panel is showing.
"Read", not "done" — nothing is being updated here, the user has simply looked, and
this is the one of the four that offers no bulk action: a past error cannot be
updated, so the block renders the dismiss control alone. */}
{todo && (
<TodoNotice
text={S.todo.unexpectedErrors(todo.count)}
dismissLabel={S.todo.markRead}
onDismiss={() => dismissTodo(projectId, "errors", todo.signature)}
/>
)}
{/* Summary cards (today / last 7 days / cumulative) */}
{data ? (
<div className="grid grid-cols-1 gap-3 sm:grid-cols-3">
<SummaryCard title={S.usage.today} bucket={data.summary.today} currency={currency} />
<SummaryCard title={S.usage.last7d} bucket={data.summary.last7d} currency={currency} />
<SummaryCard title={S.usage.total} bucket={data.summary.total} currency={currency} />
</div>
) : (
<div className="grid grid-cols-1 gap-3 sm:grid-cols-3">
<Skeleton className="h-24" />
<Skeleton className="h-24" />
<Skeleton className="h-24" />
</div>
)}
{/* Time-series charts, all over the shared range + precision: requests +
success rate by Agent and by Model on the first row, Token buckets +
cache hit rate and cost on the second. Charts always fit their card — nothing scrolls. */}
{data ? (
<div className="grid grid-cols-1 gap-3 lg:grid-cols-2">
<ChartCard title={S.usage.chartRequestsByAgent}>
<RequestsChart
series={plotted.points}
entities={agentEntities}
granularity={data.granularity}
breaks={plotted.breaks}
/>
</ChartCard>
<ChartCard title={S.usage.chartRequestsByModel}>
<RequestsChart
series={plotted.points}
entities={modelEntities}
granularity={data.granularity}
breaks={plotted.breaks}
/>
</ChartCard>
{/* The Token legend lives in its card header while its marks live inside the card, so that state is lifted to this level */}
<ChartCard
title={S.usage.chartTokenTrend}
extra={<TokenLegend active={tokenBucket} onHover={setTokenBucket} />}
>
<TokenBarChart
series={plotted.points}
granularity={data.granularity}
legend={tokenBucket}
breaks={plotted.breaks}
/>
</ChartCard>
<ChartCard title={S.usage.chartCostTrend}>
<TrendChart
series={plotted.points}
granularity={data.granularity}
currency={currency}
breaks={plotted.breaks}
/>
</ChartCard>
</div>
) : (
<Skeleton className="h-64" />
)}
{/* Errors (a single full-width panel: stats + a recent-errors table) */}
{data && (
<ChartCard title={S.usage.errors}>
<ErrorsPanel
errors={data.errors}
projectId={projectId}
filters={errorFilters}
preset={loaded.preset === "custom" ? undefined : loaded.preset}
// Clearing the log is a Project-level management operation, gated on the owner
// by the route; a member reads the panel without the action.
canClear={currentProject?.role === "owner"}
// The ignore rules draw the same line, and for the same reason: a rule changes what
// everyone reading this Project sees.
canIgnore={currentProject?.role === "owner"}
// Reload the table, its stats and its notice: after clearing the log, and when
// the clear confirmation opens (so the panel behind it agrees with its sentence).
onReload={() => {
void load();
}}
/>
</ChartCard>
)}
{hasUncostedRows && <p className="text-xs text-gray-400">{S.usage.uncostedNote}</p>}
{error && <p className="text-xs text-red-600 dark:text-red-400">{error}</p>}
</PageFrame>
);
}