@adecore/agents-react 0.0.1 → 0.17.0-beta.1

package/src/usage/limit-groups.ts

@@ -0,0 +1,119 @@
+import i18next from 'i18next';
+import {
+    USAGE_PROVIDERS,
+    type ProviderAccounts,
+    type ProviderAccountStatus,
+    type UsageLimitsProvider,
+    type UsageLimitsSnapshot,
+    type UsageProvider,
+    type UsageWindow
+} from '@adecore/agent-contracts';
+import { limitsAccountId } from '../agents/account-limits';
+import { accountName, accountsOfKind, accountStatusLine } from '../agents/accounts';
+import { formatDuration } from '@adecore/ui/format';
+import { PROVIDER_LABELS } from './format';
+
+const MINUTE = 60_000;
+
+/* One account of a CLI as the limits draw it. */
+export interface LimitAccount {
+    id: string;
+    kind: UsageProvider;
+    name: string;
+    color: string | undefined;
+    /* Null for an account the machine does not read, which is one that is not signed in. */
+    entry: UsageLimitsProvider | null;
+    /* Null for a machine from before accounts, and for an account the machine has not described yet. */
+    status: ProviderAccountStatus | null;
+}
+
+export interface LimitGroup {
+    kind: UsageProvider;
+    accounts: LimitAccount[];
+}
+
+/*
+ * The plan numbers per CLI, one row per account. The machine only reads an account that is signed in,
+ * so an account that is on but signed out comes from the account list, where it can say why it has
+ * no numbers. An account that is off is left out, unless the machine still reads it (a CLI's default).
+ */
+export function limitGroups(snapshot: UsageLimitsSnapshot, accounts: ProviderAccounts | null): LimitGroup[] {
+    return USAGE_PROVIDERS.flatMap((kind) => {
+        const known = accountsOfKind(accounts, kind);
+        const read = snapshot.providers
+            .filter((entry) => entry.kind === kind)
+            .map((entry): LimitAccount => {
+                const id = limitsAccountId(entry);
+                const account = known.find((each) => each.id === id);
+                return {
+                    id,
+                    kind,
+                    name: account === undefined ? (entry.account?.label ?? PROVIDER_LABELS[kind]) : accountName(account, PROVIDER_LABELS[kind]),
+                    color: account === undefined ? entry.account?.color : account.account.color,
+                    entry,
+                    status: account?.status ?? null
+                };
+            });
+        const unread = known
+            .filter((account) => account.account.enabled !== false && !read.some((row) => row.id === account.id))
+            .map((account): LimitAccount => ({
+                id: account.id,
+                kind,
+                name: accountName(account, PROVIDER_LABELS[kind]),
+                color: account.account.color,
+                entry: null,
+                status: account.status
+            }));
+        const rows = [...read, ...unread];
+        return rows.length === 0 ? [] : [{ kind, accounts: rows }];
+    });
+}
+
+/* Whether any CLI has more than one account, which is when the limits name the account of every row. */
+export function hasSeveralAccounts(groups: readonly LimitGroup[]): boolean {
+    return groups.some((group) => group.accounts.length > 1);
+}
+
+export function isSignedOut(account: LimitAccount): boolean {
+    return account.status?.state === 'signed-out';
+}
+
+/* The window that resets first from now, the one reset a line per window has no room to repeat. */
+export function nextReset(windows: readonly UsageWindow[], now: number): (UsageWindow & { resetsAt: number }) | null {
+    let next: (UsageWindow & { resetsAt: number }) | null = null;
+    for (const window of windows) {
+        if (window.resetsAt !== null && window.resetsAt > now && (next === null || window.resetsAt < next.resetsAt)) {
+            next = { ...window, resetsAt: window.resetsAt };
+        }
+    }
+    return next;
+}
+
+/* When the numbers came in and from where: a read of the machine's own, or a turn that reported them. Null before the first read. */
+export function checkedLabel(entry: UsageLimitsProvider, now: number): string | null {
+    if (entry.checkedAt <= 0) {
+        return null;
+    }
+    const past = now - entry.checkedAt;
+    const when = past < MINUTE ? i18next.t('agent-usage:limits.checked.now') : i18next.t('agent-usage:limits.checked.ago', { duration: formatDuration(past) });
+    return entry.source === 'event' ? i18next.t('agent-usage:limits.checked.fromTurn', { when }) : when;
+}
+
+/* Why a read account has no bars, or null when it has them. */
+export function explain(provider: UsageLimitsProvider): string | null {
+    if (provider.unavailable === null) {
+        return provider.windows.length === 0 ? i18next.t('agent-usage:limits.none') : null;
+    }
+    if (provider.unavailable.reason === 'not-installed') {
+        return i18next.t('agent-usage:limits.notInstalled');
+    }
+    if (provider.unavailable.reason === 'no-subscription') {
+        return i18next.t('agent-usage:limits.noSubscription');
+    }
+    return provider.unavailable.message ?? i18next.t('agent-usage:limits.unreachable');
+}
+
+/* Why an account has no bars, or null when it has them. An account the machine does not read says what its login is doing. */
+export function accountNote(account: LimitAccount): string | null {
+    return account.entry === null ? accountStatusLine(account.status, true).text : explain(account.entry);
+}

package/src/usage/limits.ts

@@ -0,0 +1,71 @@
+import { useEffect, useMemo } from 'react';
+import type { UsageLimitsSnapshot } from '@adecore/agent-contracts';
+import { useChatScope, type ChatScope } from '../scope';
+import { useProviderAccountsStore } from '../state/provider-accounts';
+import { useUsage, useUsageStore } from '../state/usage';
+import { limitGroups, type LimitGroup } from './limit-groups';
+
+interface Hold {
+    /* How many things on screen show this host's plan windows; at zero it lets go. */
+    readers: number;
+    release(): void;
+}
+
+/* Asking the CLIs is expensive, so everything that shows the windows shares one read per host. */
+const holds = new Map<string, Hold>();
+
+/* On the scope's transport as it stands: reading the windows never makes the host connect, so they fill once it is connected for another reason. */
+function hold(scope: ChatScope): Hold {
+    const link = scope.transport;
+    const scopeId = scope.id;
+    const ask = (): void => {
+        link.request('usage.limits', {})
+            .then((snapshot) => useUsageStore.getState().setLimits(scopeId, snapshot))
+            .catch(() => undefined);
+    };
+    if (link.status === 'open') {
+        ask();
+    }
+    // A running turn reports its own numbers, which is what keeps a bar moving between reads.
+    const offChanged = link.on('usage.limitsChanged', (snapshot) => useUsageStore.getState().setLimits(scopeId, snapshot));
+    const offStatus = link.subscribeStatus((status) => {
+        if (status === 'open') {
+            ask();
+        }
+    });
+    return {
+        readers: 0,
+        release: () => {
+            offChanged();
+            offStatus();
+        }
+    };
+}
+
+/* The snapshot of the host in scope, kept fresh for as long as anything shows it. */
+export function useUsageLimits(): UsageLimitsSnapshot | null {
+    const limits = useUsage((s) => s.limits);
+    const scope = useChatScope();
+
+    useEffect(() => {
+        const held = holds.get(scope.id) ?? hold(scope);
+        held.readers += 1;
+        holds.set(scope.id, held);
+        return () => {
+            held.readers -= 1;
+            if (held.readers === 0) {
+                held.release();
+                holds.delete(scope.id);
+            }
+        };
+    }, [scope]);
+
+    return limits;
+}
+
+/* The snapshot per CLI and account, with the accounts of the same host it is read from. */
+export function useLimitGroups(limits: UsageLimitsSnapshot | null): LimitGroup[] {
+    const { id } = useChatScope();
+    const accounts = useProviderAccountsStore((s) => s.byScope[id]?.accounts ?? null);
+    return useMemo(() => (limits === null ? [] : limitGroups(limits, accounts)), [limits, accounts]);
+}

package/src/usage/money.ts

@@ -0,0 +1,14 @@
+import { useMemo } from 'react';
+import { useUsage } from '../state/usage';
+import { moneyFormat } from './format';
+
+/*
+ * The formatter every amount on the page goes through: the currency that was chosen, at the rate
+ * the summary on screen carries. It is a hook rather than a prop because every row wants it and
+ * none of them wants to know where the rate came from.
+ */
+export function useMoney(): (usd: number) => string {
+    const currency = useUsage((s) => s.currency);
+    const rate = useUsage((s) => s.summary?.rate ?? null);
+    return useMemo(() => moneyFormat(currency, rate), [currency, rate]);
+}

package/src/usage/summary.ts

@@ -0,0 +1,137 @@
+import type { UsageProvider, UsageSummaryResult, UsageTotals } from '@adecore/agent-contracts';
+import type { UsageMetric } from '../state/usage';
+import { EMPTY_TOTALS, USAGE_PROVIDERS, addTotals, totalTokensOf } from '@adecore/agent-contracts';
+
+/* One bar of the chart, what each provider put in this slot, and the height of the stack. */
+export interface ChartSlot {
+    slot: string;
+    byProvider: Partial<Record<UsageProvider, number>>;
+    total: number;
+}
+
+/* One row of the legend, which is also one provider's share of the period. */
+export interface ProviderTotal {
+    provider: UsageProvider;
+    costUsd: number;
+    totals: UsageTotals;
+}
+
+/* Three or four round numbers up the side. The one piece of arithmetic a chart library would bring. */
+export function niceScale(max: number, ticks = 4): { max: number; step: number } {
+    if (!Number.isFinite(max) || max <= 0) {
+        return { max: 1, step: 1 };
+    }
+    const rough = max / ticks;
+    const magnitude = 10 ** Math.floor(Math.log10(rough));
+    const normalized = rough / magnitude;
+    const step = (normalized <= 1 ? 1 : normalized <= 2 ? 2 : normalized <= 5 ? 5 : 10) * magnitude;
+    return { max: Math.ceil(max / step) * step, step };
+}
+
+export interface DerivedUsage {
+    slots: ChartSlot[];
+    providers: ProviderTotal[];
+    /* The providers that did anything, in the order the chart stacks them. */
+    active: UsageProvider[];
+    totals: UsageTotals;
+    costUsd: number;
+    cacheSavingsUsd: number;
+}
+
+function pad(value: number): string {
+    return String(value).padStart(2, '0');
+}
+
+/*
+ * Every slot the period has, whether anything happened in it or not: an empty day keeps its place on
+ * the axis, so a gap in the work reads as a gap and not as a shorter week.
+ */
+export function enumerateSlots(summary: Pick<UsageSummaryResult, 'from' | 'to' | 'resolution'>): string[] {
+    if (summary.resolution === 'hour') {
+        return Array.from({ length: 24 }, (_, hour) => `${summary.to}T${pad(hour)}`);
+    }
+    const slots: string[] = [];
+    const at = new Date(`${summary.from}T00:00:00`);
+    const end = new Date(`${summary.to}T00:00:00`);
+    // A calendar loop rather than adding milliseconds, since a day is 23 or 25 hours long twice a year.
+    while (at <= end && slots.length < 400) {
+        slots.push(`${at.getFullYear()}-${pad(at.getMonth() + 1)}-${pad(at.getDate())}`);
+        at.setDate(at.getDate() + 1);
+    }
+    return slots;
+}
+
+/* How often an x label fits: every third hour, every day, every week, every fortnight. */
+export function labelEveryFor(slots: number): number {
+    return slots <= 10 ? 1 : slots <= 24 ? 3 : slots <= 31 ? 7 : 15;
+}
+
+/*
+ * The buckets folded into what the page draws. The daemon sends one bucket per slot, provider and
+ * model, which is the smallest thing every part of the page can be summed out of.
+ */
+export function deriveUsage(summary: UsageSummaryResult, metric: UsageMetric): DerivedUsage {
+    const bySlot = new Map<string, ChartSlot>();
+    for (const slot of enumerateSlots(summary)) {
+        bySlot.set(slot, { slot, byProvider: {}, total: 0 });
+    }
+    const byProvider = new Map<UsageProvider, ProviderTotal>();
+    let totals = EMPTY_TOTALS;
+    let costUsd = 0;
+    let cacheSavingsUsd = 0;
+
+    for (const bucket of summary.buckets) {
+        const value = metric === 'cost' ? (bucket.costUsd ?? 0) : totalTokensOf(bucket.totals);
+        const slot = bySlot.get(bucket.slot);
+        if (slot !== undefined) {
+            slot.byProvider[bucket.provider] = (slot.byProvider[bucket.provider] ?? 0) + value;
+            slot.total += value;
+        }
+        const provider = byProvider.get(bucket.provider) ?? { provider: bucket.provider, costUsd: 0, totals: EMPTY_TOTALS };
+        provider.costUsd += bucket.costUsd ?? 0;
+        provider.totals = addTotals(provider.totals, bucket.totals);
+        byProvider.set(bucket.provider, provider);
+        totals = addTotals(totals, bucket.totals);
+        costUsd += bucket.costUsd ?? 0;
+        cacheSavingsUsd += bucket.cacheSavingsUsd;
+    }
+
+    const providers = [...byProvider.values()].sort((a, b) => b.costUsd - a.costUsd);
+    return {
+        slots: [...bySlot.values()],
+        providers,
+        active: USAGE_PROVIDERS.filter((provider) => byProvider.has(provider)),
+        totals,
+        costUsd,
+        cacheSavingsUsd
+    };
+}
+
+/* One row of the Day table, what each provider cost that day, and what the day moved in all. */
+export interface UsageDay {
+    /* `YYYY-MM-DD`, always a calendar day, whatever resolution the chart above it is drawn at. */
+    slot: string;
+    costByProvider: Partial<Record<UsageProvider, number>>;
+    costUsd: number;
+    tokens: number;
+}
+
+/*
+ * The same buckets the chart draws, written out as a table of calendar days, newest first. Today is
+ * drawn per hour but read per day, so an hour slot is folded onto the date it names. A day nothing
+ * happened in is left out, since the chart already shows the gap, and a quiet fortnight would otherwise
+ * be fourteen rows of zeroes between the days worth reading.
+ */
+export function deriveDays(summary: UsageSummaryResult): UsageDay[] {
+    const rows = new Map<string, UsageDay>();
+    for (const bucket of summary.buckets) {
+        const day = bucket.slot.slice(0, 10);
+        const row = rows.get(day) ?? { slot: day, costByProvider: {}, costUsd: 0, tokens: 0 };
+        const cost = bucket.costUsd ?? 0;
+        row.costByProvider[bucket.provider] = (row.costByProvider[bucket.provider] ?? 0) + cost;
+        row.costUsd += cost;
+        row.tokens += totalTokensOf(bucket.totals);
+        rows.set(day, row);
+    }
+    return [...rows.values()].sort((a, b) => b.slot.localeCompare(a.slot));
+}