Skip to content

A local-first multi-agent app development platform, built on PenguinHarness

32.3 KB
Raw Blame
/**
 * Usage statistics query.
 *
 * Cost is **fixed when a Request completes**: every usage_records row carries the cost the
 * recorder computed from the rates in force at that moment, and nothing here re-prices it — a
 * price edited, synced or discounted later only changes what later Requests cost. The repo
 * returns sums broken down by `(provider, model_id)` paired reference, and this service folds
 * them into cost / hasUncosted (a row whose model had no price is excluded from cost and flags
 * hasUncosted).
 * Summary cards (today / last 7 days / cumulative), grouped aggregation (date /
 * agent / model / session, with the session dimension supporting agentId drill-down
 * filtering), and the zero-filled time series the cost center's charts draw.
 * Server-side error statistics (error_records) ride along on the same response:
 * the statistics center fetches everything in one request, and filters are
 * naturally shared; unattributed errors (login failures, process crashes, and other
 * errors with no Project context) are visible only to admins, see the ErrorsRepo
 * file header.
 */
import type {
  UsageAgentSeries,
  UsageBucket,
  UsageErrorIgnoreAdded,
  UsageErrorIgnoreRule,
  UsageErrorIgnoreWrite,
  UsageErrors,
  UsageErrorsPage,
  UsageGranularity,
  UsageGroupBy,
  UsageGroupRow,
  UsageModelSeries,
  UsageModelTotals,
  UsageResponse,
  UsageSessionDay,
  UsageSeriesPoint,
} from "../api/types.js";
import type { ErrorFilter, ErrorIgnoreRule } from "../db/repos/errors.js";
import type {
  UsageModelSums,
  UsageGroupModelSums,
  UsageSeriesModelSums,
  UsageAgentBucketCount,
  UsageFilter,
} from "../db/repos/usage.js";
import {
  enumerateBuckets,
  enumerateTsBuckets,
  formatLocalDate,
  localDateMinusDays,
} from "../internal/dates.js";
import { badRequest } from "../http/validate.js";
import { Component, Use } from "@adelie/core/kernel";
import type { Clock } from "../hmr/capabilities.js";
import type { ErrorLog, UsageQueries, UsageStore } from "../mechanisms/observability.js";
import type { ProjectConfigStore } from "../mechanisms/projects.js";

/**
 * Number of most-recent rows kept in the error detail table. Also the page size the whole
 * feature runs on, but nothing needs to hard-code it: `errors.recent` is exactly this many rows
 * whenever a second page exists, so the client derives its page size from the response instead
 * of holding a constant that could drift out of step with this one.
 */
const ERROR_RECENT_N = 10;

/** The three pricing buckets (usd_per_mtok convention), returned by the pricing lookup callback. */
export interface PricingRates {
  cacheRead: number;
  cacheWrite: number;
  output: number;
}

/**
 * The price a Project stores for a paired reference — what a Request on it is billed at when
 * it completes at `at` (the Project's list price for the row, less its promotion, at the tier
 * in force then); undefined = the Project stores no price for it.
 */
export type PricingLookup = (
  projectId: string,
  provider: string,
  modelId: string,
  at: Date,
) => Promise<PricingRates | undefined>;

export interface UsageQuery {
  from?: string;
  to?: string;
  groupBy: UsageGroupBy;
  /** Top-level filter: view by Agent (also used for groupBy=session drill-down). */
  agentId?: string;
  /** Top-level filter: view by Model (paired with modelId; the dropdown always sends them as a pair). */
  provider?: string;
  modelId?: string;
  /** Whether to include unattributed errors: admin only (the route passes user.isAdmin), defaults to false. */
  includeGlobalErrors?: boolean;
  /** Time-series precision for `series` / `byAgentSeries` / `byModelSeries`; defaults to day. The route validates the value; the bucket count is capped here. */
  granularity?: UsageGranularity;
  /**
   * Timestamp window bounds (ISO UTC), for the trailing "last hour" / "last 24
   * hours" ranges whose edges are instants rather than calendar dates: they
   * refine every range-scoped aggregate down to the window, and minute/hour
   * series buckets are enumerated between them. `minute` requires them.
   */
  fromTs?: string;
  toTs?: string;
  /**
   * The viewer's offset east of UTC, in minutes: the calendar day the error table folds a
   * day's repeats by (see ErrorsRepo.recent). Nothing else in the response reads it; absent,
   * the day is the server's own.
   */
  utcOffsetMinutes?: number;
}

/** One page of the error detail table (see {@link UsageService.queryErrors}). */
export interface UsageErrorsQuery {
  offset: number;
  limit: number;
  from?: string;
  to?: string;
  /** The trailing window narrowing those dates (see {@link UsageQuery}); both or neither. */
  fromTs?: string;
  toTs?: string;
  agentId?: string;
  /** Narrow to one category — `unexpected` (500s / runtime exceptions) or `expected`; absent counts both. */
  kind?: string;
  /**
   * Which side of the ignore rules to read: true = only the records a rule covers (the panel's
   * "ignored" view), absent = only the records no rule covers, which is every other view. One more
   * narrowing of the same filter, so a page never widens what the summary above it counted.
   */
  ignored?: boolean;
  /** Admin only: include errors with no Project attribution (see the ErrorsRepo file header). */
  includeGlobalErrors?: boolean;
  /** The viewer's offset east of UTC, in minutes (see {@link UsageQuery}). */
  utcOffsetMinutes?: number;
}

/**
 * What a clear removes (see {@link UsageService.clearErrors}): the panel's own range — dates,
 * and the trailing window when one is on — Agent, and the category the panel is narrowed to,
 * read with the same admin visibility the panel has. `kind` is here because the panel has the
 * control: a reader looking at one category must not lose the other to a button that said
 * "clear", so what the row offers and what this removes stay the same set.
 *
 * `until` is the boundary the confirmation counted: the newest record the dialog's own read
 * could see. The delete stops there, so the sentence's number is the number that goes even
 * when a record arrives between the two requests (loading the cost center records one itself).
 */
export interface UsageErrorsClearQuery {
  from?: string;
  to?: string;
  fromTs?: string;
  toTs?: string;
  until?: string;
  agentId?: string;
  /** Narrow to one category, the value the caller's reads carry; absent counts both. */
  kind?: string;
  /** The ignore side the caller's reads carry: true clears the rows a rule covers (the "ignored" view's own table), absent clears the rows no rule covers. */
  ignored?: boolean;
  /** Admin only, the value the caller's reads carry: an admin's clear takes the unattributed rows an admin's panel shows. */
  includeGlobalErrors?: boolean;
}

/** The "model price" formula: the three buckets at the given rates (USD per million Tokens), in USD. */
export function requestCostUsd(
  counts: { cacheRead: number; cacheWrite: number; output: number },
  rates: PricingRates,
): number {
  return (
    (counts.cacheRead * rates.cacheRead +
      counts.cacheWrite * rates.cacheWrite +
      counts.output * rates.output) /
    1e6
  );
}

/** In-process Map key for a paired reference (\0-separated, the same style as session-manager's agentKey; never persisted). */
function refKey(provider: string, modelId: string): string {
  return `${provider}\0${modelId}`;
}

/**
 * What {@link UsageService.addErrorIgnore} takes: the caller's own input plus the owner the route
 * resolved from the session. `createdBy` is deliberately not part of the wire type — a body that
 * could name its own author would let one Project's owner file a rule under someone else's name.
 */
export interface ErrorIgnoreAddInput extends UsageErrorIgnoreWrite {
  createdBy: string;
}

/**
 * The range half of a clear or ignore query, as the repo's filter. The two writes share it because
 * both answer for the range the caller was looking at: what a clear removes, and what a new rule
 * takes off the screen.
 */
function rangeFilter(
  q: Omit<UsageErrorsClearQuery, "until" | "kind" | "includeGlobalErrors">,
): Omit<ErrorFilter, "ignored"> {
  return {
    ...(q.agentId !== undefined ? { agentId: q.agentId } : {}),
    ...(q.from !== undefined ? { from: q.from } : {}),
    ...(q.to !== undefined ? { to: q.to } : {}),
    ...(q.fromTs !== undefined ? { fromTs: q.fromTs } : {}),
    ...(q.toTs !== undefined ? { toTs: q.toTs } : {}),
  };
}

/** The repo's rule row as the API contract spells it. The contract is a separate declaration because it is what the frontend imports; the shape is the repo's. */
function toIgnoreRuleDto(rule: ErrorIgnoreRule): UsageErrorIgnoreRule {
  return { ...rule };
}

@Component()
export class UsageService implements UsageQueries {
  @Use() private readonly usage!: UsageStore;
  @Use() private readonly errors!: ErrorLog;
  @Use() private readonly projectConfig!: ProjectConfigStore;
  @Use() private readonly clock!: Clock;
  private lookupPricing: PricingLookup = (projectId, provider, modelId, at) =>
    this.projectConfig.getPricing(projectId, provider, modelId, at);

  /**
   * COMPATIBILITY — remove two releases after the one that fixes costs at record time, together
   * with the `cost_settled` column. Fixes the cost of every usage record that has none yet: rows
   * written before costs were fixed at record time, and rows an older build wrote after a hot
   * update rolled back to it. Each is priced at the price its Project stores now, at the tier the
   * record's own timestamp fell in — the read-time cost center's promotion, with the tier pinned
   * to the row rather than to the hour the page happened to be opened. That is the one figure
   * which moves at the upgrade (a row the old page showed in the other tier corrects itself) and
   * never again after it. Idempotent — a settled row is never touched again — and safe beside the
   * recorder, whose rows are settled when written. Returns how many rows it settled.
   */
  async settleUnsettledCosts(): Promise<number> {
    let settled = 0;
    for (const ref of this.usage.unsettledRefs()) {
      const rows = this.usage.unsettledRows(ref.projectId, ref.provider, ref.modelId);
      const costs: Array<{ id: number; cost: number | null }> = [];
      for (const r of rows) {
        const rates = await this.lookupPricing(
          ref.projectId,
          ref.provider,
          ref.modelId,
          new Date(r.ts),
        );
        costs.push({ id: r.id, cost: rates === undefined ? null : requestCostUsd(r, rates) });
      }
      this.usage.settle(costs);
      settled += rows.length;
    }
    return settled;
  }

  /**
   * Period cost per session, for company mode's attribution by the sessions an organization
   * owns: the recorded costs summed per session. `unpriced` says some usage ran on a model
   * without pricing, so the numbers are a lower bound.
   */
  async costBySession(
    projectId: string,
    sessionIds: readonly string[],
    fromTs: string,
    toTs: string,
  ): Promise<{ bySession: Map<string, number>; unpriced: boolean }> {
    const bySession = new Map<string, number>();
    if (sessionIds.length === 0) return { bySession, unpriced: false };
    const rows = this.usage.groupsByModel(projectId, "session", { sessionIds, fromTs, toTs });
    let unpriced = false;
    for (const r of rows) {
      if (r.uncosted > 0) unpriced = true;
      if (r.cost !== null) bySession.set(r.key, (bySession.get(r.key) ?? 0) + r.cost);
    }
    return { bySession, unpriced };
  }

  /** Daily cost of a set of sessions over a window (the organization finance trend). */
  async dailyCostForSessions(
    projectId: string,
    sessionIds: readonly string[],
    fromTs: string,
    toTs: string,
  ): Promise<Array<{ date: string; cost: number }>> {
    if (sessionIds.length === 0) return [];
    const rows = this.usage.seriesByModel(projectId, "day", { sessionIds, fromTs, toTs });
    const byDate = new Map<string, number>();
    for (const r of rows) {
      if (r.cost !== null) byDate.set(r.key, (byDate.get(r.key) ?? 0) + r.cost);
    }
    return [...byDate.entries()]
      .sort(([a], [b]) => a.localeCompare(b))
      .map(([date, cost]) => ({ date, cost }));
  }

  async query(projectId: string, q: UsageQuery): Promise<UsageResponse> {
    const today = formatLocalDate(this.clock.now());
    // Top-level filter: agent + model (the cost center switches views by agent/model; the model filter is always sent as a pair).
    const base: UsageFilter = {};
    if (q.agentId !== undefined) base.agentId = q.agentId;
    if (q.provider !== undefined) base.provider = q.provider;
    if (q.modelId !== undefined) base.modelId = q.modelId;

    const win = (from?: string, to?: string): UsageFilter => ({
      ...base,
      ...(from !== undefined ? { from } : {}),
      ...(to !== undefined ? { to } : {}),
    });

    // Timestamp window bounds ride alongside the date range wherever the
    // selected range applies; the calendar-fixed today / last-7-days cards
    // deliberately stay date-only.
    const ts: UsageFilter = {
      ...(q.fromTs !== undefined ? { fromTs: q.fromTs } : {}),
      ...(q.toTs !== undefined ? { toTs: q.toTs } : {}),
    };
    const todayRows = this.usage.bucketByModel(projectId, win(today, today));
    const last7dRows = this.usage.bucketByModel(
      projectId,
      win(localDateMinusDays(this.clock.now(), 6)),
    );
    const totalRows = this.usage.bucketByModel(projectId, { ...win(q.from, q.to), ...ts });
    const groupRows = this.usage.groupsByModel(projectId, q.groupBy, {
      ...win(q.from, q.to),
      ...ts,
    });
    // Time series at the requested precision, zero-filled over the requested
    // range, defaulting to the last 30 days when no range is given.
    const granularity = q.granularity ?? "day";
    const seriesFrom = q.from ?? localDateMinusDays(this.clock.now(), 29);
    const seriesTo = q.to ?? today;
    // The series is zero-filled over the whole effective range: cap the bucket
    // count so an arbitrary range × precision combination cannot materialize an
    // unbounded response. 500 comfortably covers every range the Web App offers
    // (90 days daily = 90, 14 days hourly = 336, a trailing hour by minute = 61).
    // Minute buckets only make sense inside a timestamp window — the trailing
    // ranges — and hour buckets switch to the window when one is given.
    let bucketKeys: string[];
    if (granularity === "minute" || (granularity === "hour" && ts.fromTs !== undefined)) {
      if (ts.fromTs === undefined || ts.toTs === undefined) {
        throw badRequest(
          "fromTs and toTs must be given together, and minute granularity requires them.",
        );
      }
      bucketKeys = enumerateTsBuckets(new Date(ts.fromTs), new Date(ts.toTs), granularity, 500);
    } else {
      bucketKeys = enumerateBuckets(seriesFrom, seriesTo, granularity, 500);
    }
    if (bucketKeys.length > 500) {
      throw badRequest(
        "Date range too wide for this granularity; narrow the range or coarsen the granularity.",
      );
    }
    const seriesRows = this.usage.seriesByModel(projectId, granularity, {
      ...win(seriesFrom, seriesTo),
      ...ts,
    });
    // Per-Agent and per-Model series: each drops its own dimension's filter (its
    // chart draws that dimension's whole breakdown) but honors the other
    // dimension plus the selected range.
    const agentFree: UsageFilter = {
      ...(q.provider !== undefined ? { provider: q.provider } : {}),
      ...(q.modelId !== undefined ? { modelId: q.modelId } : {}),
      ...(q.from !== undefined ? { from: q.from } : {}),
      ...(q.to !== undefined ? { to: q.to } : {}),
      ...ts,
    };
    const agentBucketRows = this.usage.agentSeries(projectId, granularity, {
      ...agentFree,
      from: seriesFrom,
      to: seriesTo,
    });
    // With no model filter set, dropping the model filter leaves exactly the
    // query `seriesRows` already ran: reuse its rows instead of running the
    // heaviest query on this route (bucket x model) a second time.
    const modelFiltered = q.provider !== undefined || q.modelId !== undefined;
    const modelBucketRows = modelFiltered
      ? this.usage.seriesByModel(projectId, granularity, {
          ...(q.agentId !== undefined ? { agentId: q.agentId } : {}),
          from: seriesFrom,
          to: seriesTo,
          ...ts,
        })
      : seriesRows;
    // Error statistics: likewise not affected by the model filter (HTTP / process errors have no Model dimension), but still affected by the date + agent filter — and by the trailing window, like every other range-scoped aggregate.
    const errorFilter: ErrorFilter = {
      ...(q.agentId !== undefined ? { agentId: q.agentId } : {}),
      ...(q.from !== undefined ? { from: q.from } : {}),
      ...(q.to !== undefined ? { to: q.to } : {}),
      ...(q.fromTs !== undefined ? { fromTs: q.fromTs } : {}),
      ...(q.toTs !== undefined ? { toTs: q.toTs } : {}),
      // Unattributed errors are visible only to admins (regular members only see errors within their own Project, see the ErrorsRepo file header).
      ...(q.includeGlobalErrors === true ? { includeGlobal: true } : {}),
    };

    return {
      summary: {
        today: this.foldBucket(todayRows),
        last7d: this.foldBucket(last7dRows),
        total: this.foldBucket(totalRows),
      },
      groupBy: q.groupBy,
      groups: this.foldGroups(groupRows, q.groupBy),
      granularity,
      series: this.foldSeries(bucketKeys, seriesRows),
      byAgentSeries: foldAgentSeries(bucketKeys, agentBucketRows),
      byModelSeries: foldModelSeries(bucketKeys, modelBucketRows),
      errors: this.foldErrors(projectId, errorFilter, q.utcOffsetMinutes),
      agentIds: this.usage.distinctAgentIds(projectId),
      models: this.usage.distinctModels(projectId),
    };
  }

  /**
   * One page of the error detail table, newest first. The dashboard's own response already
   * carries the first page (`errors.recent`); this serves the "show me earlier ones" paging,
   * where refetching the whole aggregate to move one page would be wasteful. `rows` is the
   * filtered row count, so the caller knows when it has reached the end; `total` counts the
   * records behind those rows, the occurrences the badge reports.
   *
   * Takes the same filter the dashboard applies — date + agent, and admin-only visibility of
   * unattributed errors — so a page never widens what the summary above it counted.
   *
   * Paging is by offset into a newest-first table that grows at its head, so errors recorded
   * between two page requests shift every row down and a page can re-show rows already seen.
   * Accepted deliberately: this is a diagnostic table read at a moment in time, not a feed to
   * be walked exhaustively, and keying off the newest row's id would cost a cursor the caller
   * has no other use for.
   */
  queryErrors(projectId: string, q: UsageErrorsQuery): UsageErrorsPage {
    const f: ErrorFilter = {
      ...(q.agentId !== undefined ? { agentId: q.agentId } : {}),
      ...(q.from !== undefined ? { from: q.from } : {}),
      ...(q.to !== undefined ? { to: q.to } : {}),
      ...(q.fromTs !== undefined ? { fromTs: q.fromTs } : {}),
      ...(q.toTs !== undefined ? { toTs: q.toTs } : {}),
      ...(q.kind !== undefined ? { kind: q.kind } : {}),
      ...(q.ignored === true ? { ignored: true } : {}),
      ...(q.includeGlobalErrors === true ? { includeGlobal: true } : {}),
    };
    return {
      items: this.errors.recent(projectId, f, q.limit, q.offset, q.utcOffsetMinutes),
      total: this.errors.summary(projectId, f).total,
      rows: this.errors.rowCount(projectId, f, q.utcOffsetMinutes),
    };
  }

  /**
   * Empties the error table for the filter the panel is showing, and answers how many rows went.
   *
   * The filter is the same range (dates, and the trailing window when one is on), Agent and
   * category the dashboard and the paged route take, read with the same admin visibility, so a
   * clear removes exactly the set the caller was looking at and never a row outside it: a
   * reader who has narrowed to one Agent, one week or one category does not lose the rest to a
   * button that said "clear", and an admin whose panel showed unattributed rows is not left
   * holding them after clearing it (see ErrorsRepo.deleteFiltered).
   */
  clearErrors(projectId: string, q: UsageErrorsClearQuery): number {
    return this.errors.deleteFiltered(projectId, {
      ...(q.agentId !== undefined ? { agentId: q.agentId } : {}),
      ...(q.from !== undefined ? { from: q.from } : {}),
      ...(q.to !== undefined ? { to: q.to } : {}),
      ...(q.fromTs !== undefined ? { fromTs: q.fromTs } : {}),
      ...(q.toTs !== undefined ? { toTs: q.toTs } : {}),
      ...(q.until !== undefined ? { until: q.until } : {}),
      ...(q.kind !== undefined ? { kind: q.kind } : {}),
      ...(q.ignored === true ? { ignored: true } : {}),
      ...(q.includeGlobalErrors === true ? { includeGlobal: true } : {}),
    });
  }

  /** The Project's ignore rules, oldest first, each with what it currently covers. */
  errorIgnores(projectId: string): UsageErrorIgnoreRule[] {
    return this.errors.ignoreRules(projectId).map(toIgnoreRuleDto);
  }

  /**
   * Silences one class of errors for this Project. Records are not touched — the rule only changes
   * which ones the reads select — so this is undoable and answers with how many records it covers
   * in the range the caller was looking at, which is what a caller reports having just hidden.
   *
   * `null` when the Project already has a rule for that class: the same (source, code, fragment)
   * is one rule, and re-adding it is a refusal rather than a second row covering the same records.
   */
  addErrorIgnore(
    projectId: string,
    input: ErrorIgnoreAddInput,
    range: Omit<UsageErrorsClearQuery, "until" | "kind" | "includeGlobalErrors"> = {},
  ): UsageErrorIgnoreAdded | null {
    const fragment = input.messageLike?.trim() ? input.messageLike.trim() : null;
    const rule = this.errors.addIgnoreRule(projectId, {
      source: input.source,
      code: input.code,
      messageLike: fragment,
      note: input.note ?? null,
      createdBy: input.createdBy,
      createdAt: this.clock.now().toISOString(),
    });
    if (rule === null) return null;
    return {
      rule: toIgnoreRuleDto(rule),
      hidden: this.errors.ignoreRuleMatches(
        projectId,
        { source: rule.source, code: rule.code, messageLike: rule.messageLike },
        rangeFilter(range),
      ),
    };
  }

  /** Removes one rule, re-exposing the records it covered (they were never deleted); false when this Project has no such rule. */
  removeErrorIgnore(projectId: string, id: number): boolean {
    return this.errors.removeIgnoreRule(projectId, id);
  }

  /** Error statistics: summary info (total / unexpected / most common error code) + the table's first N rows and its row count, all filtered by the selected range. */
  private foldErrors(projectId: string, f: ErrorFilter, utcOffsetMinutes?: number): UsageErrors {
    const { total, unexpected } = this.errors.summary(projectId, f);
    return {
      total,
      unexpected,
      // The other side of the same filter, so the panel can report what its rules hold back rather
      // than showing a bare zero: counted under the caller's range, on the ignored side of the axis.
      ignored: this.errors.summary(projectId, { ...f, ignored: true }).total,
      topCode: this.errors.topCode(projectId, f),
      recent: this.errors.recent(projectId, f, ERROR_RECENT_N, 0, utcOffsetMinutes),
      rows: this.errors.rowCount(projectId, f, utcOffsetMinutes),
    };
  }

  /**
   * Lifetime Token totals per Model — one grouped scan of `usage_records`, no filters. The
   * models page shows each configured model what it has actually spent, and that figure is not
   * scoped to a range the way the cost center's is; a model with no records is simply absent,
   * so the caller renders nothing rather than a zero.
   */
  modelTotals(projectId: string): UsageModelTotals {
    return {
      totals: this.usage.bucketByModel(projectId).map((r) => ({
        provider: r.provider,
        modelId: r.modelId,
        tokens: r.total,
        requests: r.requests,
      })),
    };
  }

  /**
   * Usage by calendar day, each day split by Session — the account menu's "会话运行记录":
   * which conversations spent the Tokens, day by day. One grouped scan over the last `days`
   * calendar days (today included), folded here into days and Sessions; both levels sum the
   * same rows, so a day's figure is the sum of its Sessions' and the window's is the sum of
   * the days'.
   *
   * Days with no records are left out rather than drawn as zeros — a day nobody used the app
   * is not a row worth reading — but today is always answered, at zero when nothing has run,
   * because "今天花了多少" is the one figure the list is opened for. Within a day, Sessions
   * are ordered by Token total, descending.
   */
  sessionDays(projectId: string, opts: { days?: number } = {}): UsageSessionDay[] {
    const days = Math.min(Math.max(opts.days ?? 7, 1), 90);
    const now = this.clock.now();
    const today = formatLocalDate(now);
    const rows = this.usage.sessionDayByModel(projectId, {
      from: localDateMinusDays(now, days - 1),
      to: today,
    });
    const byDate = new Map<string, UsageSessionDay>();
    for (const r of rows) {
      let day = byDate.get(r.date);
      if (!day) {
        day = {
          date: r.date,
          cacheRead: 0,
          cacheWrite: 0,
          output: 0,
          total: 0,
          requests: 0,
          cost: null,
          hasUncosted: false,
          sessions: [],
        };
        byDate.set(r.date, day);
      }
      let session = day.sessions.find((s) => s.sessionId === r.sessionId);
      if (!session) {
        session = {
          sessionId: r.sessionId,
          agentId: r.agentId,
          cacheRead: 0,
          cacheWrite: 0,
          output: 0,
          total: 0,
          requests: 0,
          cost: null,
          hasUncosted: false,
        };
        day.sessions.push(session);
      }
      for (const target of [day, session]) {
        target.cacheRead += r.cacheRead;
        target.cacheWrite += r.cacheWrite;
        target.output += r.output;
        target.total += r.total;
        target.requests += r.requests;
        if (r.cost !== null) target.cost = (target.cost ?? 0) + r.cost;
        if (r.uncosted > 0) target.hasUncosted = true;
      }
    }
    const out = [...byDate.values()];
    for (const day of out) day.sessions.sort((a, b) => b.total - a.total);
    out.sort((a, b) => b.date.localeCompare(a.date));
    if (!byDate.has(today)) {
      out.unshift({
        date: today,
        cacheRead: 0,
        cacheWrite: 0,
        output: 0,
        total: 0,
        requests: 0,
        cost: null,
        hasUncosted: false,
        sessions: [],
      });
    }
    return out;
  }

  /**
   * The Project's lifetime cost — one unfiltered grouped scan, the same one `modelTotals` runs,
   * summing the costs fixed when the rows were written. Its consumer is a per-account figure
   * (the admin user backend's cost column), so there is exactly one number: `cost` stays null
   * while nothing could be priced rather than reporting a zero the caller cannot tell from "ran
   * for free", and `unpriced` marks a lower bound.
   */
  async lifetimeCost(projectId: string): Promise<{ cost: number | null; unpriced: boolean }> {
    const { cost, hasUncosted } = this.foldBucket(this.usage.bucketByModel(projectId));
    return { cost, unpriced: hasUncosted };
  }

  private foldBucket(rows: UsageModelSums[]): UsageBucket {
    let total = 0;
    let requests = 0;
    let cost: number | null = null;
    let hasUncosted = false;
    for (const r of rows) {
      total += r.total;
      requests += r.requests;
      if (r.cost !== null) cost = (cost ?? 0) + r.cost;
      if (r.uncosted > 0) hasUncosted = true;
    }
    return { total, requests, cost, hasUncosted };
  }

  private foldGroups(rows: UsageGroupModelSums[], groupBy: UsageGroupBy): UsageGroupRow[] {
    // The model dimension folds by paired reference (a shared model_id name across providers is split into separate rows); other dimensions fold by their group key.
    const keyOf = (r: UsageGroupModelSums): string =>
      groupBy === "model" ? refKey(r.provider, r.key) : r.key;
    const byKey = new Map<string, UsageGroupRow>();
    for (const r of rows) {
      const acc = byKey.get(keyOf(r)) ?? {
        key: r.key,
        ...(groupBy === "model" ? { provider: r.provider } : {}),
        cacheRead: 0,
        cacheWrite: 0,
        output: 0,
        total: 0,
        requests: 0,
        cost: null as number | null,
        hasUncosted: false,
      };
      acc.cacheRead += r.cacheRead;
      acc.cacheWrite += r.cacheWrite;
      acc.output += r.output;
      acc.total += r.total;
      acc.requests += r.requests;
      if (r.cost !== null) acc.cost = (acc.cost ?? 0) + r.cost;
      if (r.uncosted > 0) acc.hasUncosted = true;
      byKey.set(keyOf(r), acc);
    }
    const out = [...byKey.values()];
    // The date dimension sorts by key descending (most recent first); other dimensions sort by total Token count descending.
    if (groupBy === "date") out.sort((a, b) => b.key.localeCompare(a.key));
    else out.sort((a, b) => b.total - a.total);
    return out;
  }

  /**
   * Fold the per-Model series rows onto the zero-filled bucket skeleton: every
   * enumerated bucket appears exactly once, in order, so line charts never
   * connect across a silent gap. A row whose key falls outside the skeleton
   * cannot happen for day/week/month (keys derive from the filtered date
   * column) and is dropped defensively for minute/hour, whose keys come from
   * `ts` and can therefore fall outside a skeleton built from `date` if a row
   * was recorded under a different clock.
   */
  private foldSeries(keys: string[], rows: UsageSeriesModelSums[]): UsageSeriesPoint[] {
    const byKey = new Map<string, UsageSeriesPoint>(
      keys.map((bucket) => [
        bucket,
        {
          bucket,
          cacheRead: 0,
          cacheWrite: 0,
          output: 0,
          total: 0,
          cost: null,
          requests: 0,
          completed: 0,
          denominator: 0,
        },
      ]),
    );
    for (const r of rows) {
      const acc = byKey.get(r.key);
      if (!acc) continue;
      acc.cacheRead += r.cacheRead;
      acc.cacheWrite += r.cacheWrite;
      acc.output += r.output;
      acc.total += r.total;
      acc.requests += r.requests;
      acc.completed += r.completed;
      acc.denominator += r.denominator;
      if (r.cost !== null) acc.cost = (acc.cost ?? 0) + r.cost;
    }
    return keys.map((k) => byKey.get(k)!);
  }
}

const sumOf = (a: number[]) => a.reduce((s, v) => s + v, 0);

const zeros = (n: number) => new Array<number>(n).fill(0);

/**
 * Per-Agent counts aligned index-for-index with the bucket skeleton, sorted by
 * total requests descending (the requests chart takes the head and folds the
 * tail into an "other" series client-side).
 */
function foldAgentSeries(keys: string[], rows: UsageAgentBucketCount[]): UsageAgentSeries[] {
  const idx = new Map(keys.map((k, i) => [k, i]));
  const byAgent = new Map<string, UsageAgentSeries>();
  for (const r of rows) {
    const i = idx.get(r.key);
    if (i === undefined) continue;
    let s = byAgent.get(r.agentId);
    if (!s) {
      s = {
        agentId: r.agentId,
        requests: zeros(keys.length),
        completed: zeros(keys.length),
        denominator: zeros(keys.length),
      };
      byAgent.set(r.agentId, s);
    }
    s.requests[i]! += r.requests;
    s.completed[i]! += r.completed;
    s.denominator[i]! += r.denominator;
  }
  return [...byAgent.values()].sort((a, b) => sumOf(b.requests) - sumOf(a.requests));
}

/** Per-Model counts aligned with the bucket skeleton (entity identity is the (provider, modelId) pair), sorted by total requests descending. */
function foldModelSeries(keys: string[], rows: UsageSeriesModelSums[]): UsageModelSeries[] {
  const idx = new Map(keys.map((k, i) => [k, i]));
  const byModel = new Map<string, UsageModelSeries>();
  for (const r of rows) {
    const i = idx.get(r.key);
    if (i === undefined) continue;
    const key = refKey(r.provider, r.modelId);
    let s = byModel.get(key);
    if (!s) {
      s = {
        provider: r.provider,
        modelId: r.modelId,
        requests: zeros(keys.length),
        completed: zeros(keys.length),
        denominator: zeros(keys.length),
      };
      byModel.set(key, s);
    }
    s.requests[i]! += r.requests;
    s.completed[i]! += r.completed;
    s.denominator[i]! += r.denominator;
  }
  return [...byModel.values()].sort((a, b) => sumOf(b.requests) - sumOf(a.requests));
}