Skip to content

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

19.2 KB
Raw Blame
/**
 * Usage statistics routes:
 * GET /api/projects/:p/usage?from&to&fromTs&toTs&groupBy&granularity&agentId&provider&modelId
 * (model filter is paired: provider and modelId are given together; granularity
 * sets the time-series precision, defaulting to day; fromTs/toTs bound a
 * trailing window down to instants — required for minute — and must be given
 * together);
 * GET /api/projects/:p/usage/errors?offset&limit&from&to&fromTs&toTs&agentId&kind&ignored — one page
 * of the error detail table, for paging back past the first page the dashboard already
 * returns (both reads also take `utcOffsetMinutes`, the viewer's offset from UTC, whose
 * calendar day the table folds a day's repeats by; `ignored` reads the other side of the
 * Project's ignore rules);
 * DELETE /api/projects/:p/usage/errors?from&to&fromTs&toTs&until&agentId&kind&ignored — empties that table
 * for the filter the panel is showing (owner only; `from`/`to` are required, unlike on the
 * reads; an admin's clear also takes the unattributed rows an admin's read shows; `until`
 * stops at the newest record the confirmation counted);
 * GET /api/projects/:p/usage/errors/ignores — the Project's ignore rules, each with what it
 * covers (owner only);
 * POST /api/projects/:p/usage/errors/ignores?from&to&fromTs&toTs&agentId — adds one rule, and
 * answers how many records it covers in that range (owner only; `source` and `code` required,
 * `messageLike` narrows it to messages containing that fragment; 409 when the class is already
 * ignored);
 * DELETE /api/projects/:p/usage/errors/ignores/:id — removes one rule (owner only; 404 when this
 * Project has none);
 * GET /api/projects/:p/usage/model-totals — lifetime Token total per Model, unfiltered.
 * GET /api/projects/:p/usage/session-days?days= — usage by calendar day, each day split by
 * Session (the account menu's run record; days 1..90, default 7).
 */
import { Hono } from "hono";
import type { Context } from "hono";
import type {
  UsageErrorIgnoreAdded,
  UsageErrorIgnores,
  UsageErrorKind,
  UsageErrorsClearResponse,
  UsageGranularity,
  UsageGroupBy,
  UsageSessionDays,
} from "../../api/types.js";
import type { AppEnv } from "../../auth/middleware.js";
import {
  badRequest,
  optionalDateParam,
  paginationQuery,
  parseNonNegativeInt,
  requireValidId,
} from "../validate.js";
import { HttpError } from "../errors.js";
import type { UsageQueries } from "../../mechanisms/observability.js";
import type { SessionIndex } from "../../mechanisms/sessions.js";
import type { Access } from "../../mechanisms/projects.js";

/** What this route group reaches — bound by its module (src/modules). */
export interface UsageRouteDeps {
  access: Access;
  usageService: UsageQueries;
  /** The Session index, read only to name a Session's row in the day-by-Session breakdown (it holds no title of its own). */
  sessionsRepo: SessionIndex;
}

const GROUP_BYS: readonly UsageGroupBy[] = ["date", "agent", "model", "session"];

const GRANULARITIES: readonly UsageGranularity[] = ["minute", "hour", "day", "week", "month"];

/** The two categories `error_records.kind` is ever written with (ErrorRecorder's own vocabulary). */
const ERROR_KINDS: readonly UsageErrorKind[] = ["unexpected", "expected"];

/**
 * Parse an optional ISO-8601 timestamp parameter, normalized to the UTC ISO
 * form the rows record — string comparison against `usage_records.ts` and
 * `error_records.ts` only works with both sides in that one spelling.
 */
function optionalTsParam(value: string | undefined, label: string): string | undefined {
  if (value === undefined || value === "") return undefined;
  const ms = Date.parse(value);
  if (Number.isNaN(ms)) throw badRequest(`${label} must be an ISO-8601 timestamp.`);
  return new Date(ms).toISOString();
}

/** The widest offset from UTC a clock actually uses (UTC+14), which bounds `utcOffsetMinutes`. */
const UTC_OFFSET_MAX_MINUTES = 14 * 60;

/**
 * The optional viewer offset east of UTC, in minutes: whose calendar day the error table folds
 * a day's repeats by (see ErrorsRepo.recent). A signed whole number within the offsets clocks
 * use, and nothing else — a typo is a 400 rather than a quietly different day.
 */
function utcOffsetQuery(c: Context<AppEnv>): number | undefined {
  const raw = c.req.query("utcOffsetMinutes");
  if (raw === undefined || raw === "") return undefined;
  const minutes = /^-?\d{1,4}$/.test(raw) ? Number(raw) : Number.NaN;
  if (!(Math.abs(minutes) <= UTC_OFFSET_MAX_MINUTES)) {
    throw badRequest(
      `utcOffsetMinutes must be a whole number of minutes between -${UTC_OFFSET_MAX_MINUTES} and ${UTC_OFFSET_MAX_MINUTES}.`,
    );
  }
  return minutes;
}

/**
 * The optional trailing-window pair, normalized: both or neither, and in order. One parser
 * for the dashboard and the two error routes, so a window means the same thing to all three.
 */
function tsWindowQuery(c: Context<AppEnv>): { fromTs?: string; toTs?: string } {
  const fromTs = optionalTsParam(c.req.query("fromTs"), "fromTs");
  const toTs = optionalTsParam(c.req.query("toTs"), "toTs");
  if ((fromTs === undefined) !== (toTs === undefined)) {
    throw badRequest("fromTs and toTs must be given together.");
  }
  if (fromTs !== undefined && toTs !== undefined && fromTs > toTs) {
    throw badRequest("fromTs must not be after toTs.");
  }
  return { ...(fromTs !== undefined ? { fromTs } : {}), ...(toTs !== undefined ? { toTs } : {}) };
}

/**
 * The error panel's range: the dates, the trailing window and the Agent every error read and write
 * shares. One parser for all four, so "the range on screen" means the same thing to the reads, to a
 * clear, and to the count a new ignore rule reports having hidden.
 */
function errorRangeQuery(c: Context<AppEnv>): {
  from?: string;
  to?: string;
  fromTs?: string;
  toTs?: string;
  agentId?: string;
} {
  const from = optionalDateParam(c.req.query("from"), "from");
  const to = optionalDateParam(c.req.query("to"), "to");
  const agentId = c.req.query("agentId");
  return {
    ...(from !== undefined ? { from } : {}),
    ...(to !== undefined ? { to } : {}),
    ...tsWindowQuery(c),
    ...(agentId !== undefined && agentId !== "" ? { agentId } : {}),
  };
}

/**
 * Which side of the Project's ignore rules to read or clear: `1` the records a rule covers, `0`
 * (or nothing) the ones no rule covers. Validated like `kind` and for the same reason — a typo
 * that passed through would silently read the other side and report the wrong table as empty.
 */
function ignoredQuery(c: Context<AppEnv>): boolean | undefined {
  const raw = c.req.query("ignored");
  if (raw === undefined || raw === "" || raw === "0" || raw === "false") return undefined;
  if (raw === "1" || raw === "true") return true;
  throw badRequest("ignored must be 0 or 1.");
}

export function usageRoutes(deps: UsageRouteDeps): Hono<AppEnv> {
  const app = new Hono<AppEnv>();

  app.get("/", async (c) => {
    // Defensive id validation.
    const projectId = requireValidId(c, "projectId");
    deps.access.requireProjectAccess(c.var.user.userId, projectId);
    const groupByRaw = c.req.query("groupBy") ?? "date";
    if (!(GROUP_BYS as readonly string[]).includes(groupByRaw)) {
      throw badRequest(`groupBy must be one of ${GROUP_BYS.join(" / ")}.`);
    }
    const granularityRaw = c.req.query("granularity") ?? "day";
    if (!(GRANULARITIES as readonly string[]).includes(granularityRaw)) {
      throw badRequest(`granularity must be one of ${GRANULARITIES.join(" / ")}.`);
    }
    const granularity = granularityRaw as UsageGranularity;
    const from = optionalDateParam(c.req.query("from"), "from");
    const to = optionalDateParam(c.req.query("to"), "to");
    const window = tsWindowQuery(c);
    const utcOffsetMinutes = utcOffsetQuery(c);
    const agentId = c.req.query("agentId");
    const provider = c.req.query("provider");
    const modelId = c.req.query("modelId");
    return c.json(
      await deps.usageService.query(projectId, {
        groupBy: groupByRaw as UsageGroupBy,
        granularity,
        ...window,
        ...(utcOffsetMinutes !== undefined ? { utcOffsetMinutes } : {}),
        // Unattributed errors (login failures, process crashes, etc. with no Project
        // context) are visible only to admins: requireProjectAccess only guarantees
        // "is a member of this Project" — a regular member seeing another tenant's errors
        // would be a cross-tenant information leak.
        includeGlobalErrors: c.var.user.isAdmin,
        ...(from !== undefined ? { from } : {}),
        ...(to !== undefined ? { to } : {}),
        ...(agentId !== undefined && agentId !== "" ? { agentId } : {}),
        ...(provider !== undefined && provider !== "" ? { provider } : {}),
        ...(modelId !== undefined && modelId !== "" ? { modelId } : {}),
      }),
    );
  });

  // Lifetime Token total per Model, for the models page's per-card figure. Takes no filters at
  // all: the number answers "how much has this model been used", which has no range, and the
  // page showing it offers none. One grouped scan, so it stays a cheap second request rather
  // than a reason to widen the models response with telemetry.
  app.get("/model-totals", (c) => {
    const projectId = requireValidId(c, "projectId");
    deps.access.requireProjectAccess(c.var.user.userId, projectId);
    return c.json(deps.usageService.modelTotals(projectId));
  });

  // Usage by calendar day, each day split by Session — the account menu's "会话运行记录": one
  // request answers "which conversations spent the Tokens these days, and how much". The
  // Sessions' titles are added here from the Session index (the usage rows carry only ids), so
  // a reader recognises a conversation instead of decoding a session id; a Session deleted
  // since keeps its id and no title.
  app.get("/session-days", (c) => {
    const projectId = requireValidId(c, "projectId");
    deps.access.requireProjectAccess(c.var.user.userId, projectId);
    const raw = c.req.query("days");
    const parsed = raw === undefined || raw === "" ? 7 : /^\d{1,3}$/.test(raw) ? Number(raw) : NaN;
    if (!Number.isInteger(parsed) || parsed < 1 || parsed > 90) {
      throw badRequest("days must be a whole number between 1 and 90.");
    }
    const titles = new Map<string, string | undefined>();
    const days = deps.usageService.sessionDays(projectId, { days: parsed }).map((day) => ({
      ...day,
      sessions: day.sessions.map((row) => {
        if (!titles.has(row.sessionId)) {
          titles.set(row.sessionId, deps.sessionsRepo.findById(row.sessionId)?.title ?? undefined);
        }
        const title = titles.get(row.sessionId);
        return { ...row, ...(title !== undefined ? { title } : {}) };
      }),
    }));
    return c.json({ days } satisfies UsageSessionDays);
  });

  // One page of the error detail table, newest first. The dashboard response above already
  // carries the first page; this serves "show me earlier ones" without refetching the whole
  // aggregate. Takes the date/agent filter only — the model filter never applied to errors
  // (HTTP and process errors have no Model dimension), so accepting it here would imply a
  // narrowing the summary above does not do.
  app.get("/errors", (c) => {
    const projectId = requireValidId(c, "projectId");
    deps.access.requireProjectAccess(c.var.user.userId, projectId);
    const { offset, limit } = paginationQuery(c);
    const range = errorRangeQuery(c);
    const utcOffsetMinutes = utcOffsetQuery(c);
    const kindRaw = c.req.query("kind");
    // `kind` narrows to one of the two categories the panel's stats already separate. It is
    // validated against that closed set rather than passed through, so a typo asks for
    // nothing instead of silently matching no rows and reading as "no errors".
    if (
      kindRaw !== undefined &&
      kindRaw !== "" &&
      !(ERROR_KINDS as readonly string[]).includes(kindRaw)
    ) {
      throw badRequest(`kind must be one of ${ERROR_KINDS.join(" / ")}.`);
    }
    const ignored = ignoredQuery(c);
    return c.json(
      deps.usageService.queryErrors(projectId, {
        offset,
        limit,
        // Same admin-only rule as the dashboard: a regular member seeing another tenant's
        // unattributed errors would be a cross-tenant leak.
        includeGlobalErrors: c.var.user.isAdmin,
        ...range,
        ...(utcOffsetMinutes !== undefined ? { utcOffsetMinutes } : {}),
        ...(kindRaw !== undefined && kindRaw !== "" ? { kind: kindRaw } : {}),
        ...(ignored !== undefined ? { ignored } : {}),
      }),
    );
  });

  // Empties the error table for the filter the panel is showing. Takes the same date, window,
  // agent, category and ignore side as the two reads above and no other: a clear removes exactly
  // the rows the caller was looking at, never the Project's whole history behind a narrowed view —
  // the date range is required for that reason, where the reads leave it optional. `kind` and
  // `ignored` are accepted because the panel has those controls: its table and its button read the
  // same filter, so a reader narrowed to one category keeps the other one, and a reader standing
  // on the ignored view is the one person who may delete those rows.
  app.delete("/errors", (c) => {
    const projectId = requireValidId(c, "projectId");
    // Owner only, the rule Agent deletion applies to error rows already (it cascade-deletes
    // them): membership is enough to READ the panel, but these rows are the Project's shared
    // history and one member emptying them takes them from everyone.
    deps.access.requireProjectOwner(c.var.user.userId, projectId);
    const range = errorRangeQuery(c);
    // Both bounds are required here, unlike on the two reads: a missing bound reads as
    // unbounded on that side, and an unbounded clear is the Project's entire history — for an
    // admin, every unattributed row in the instance along with it, rows that sit in every
    // other Project's admin panel. The panel already withholds the action while either date
    // input is blank (see clearableFilter); this is that same rule where it can be enforced,
    // rather than a promise only the caller who uses the UI keeps.
    if (range.from === undefined || range.to === undefined) {
      throw badRequest("from and to are both required.");
    }
    // The boundary the confirmation counted, optional: without it the clear takes everything
    // the filter matches, which is what a caller that never showed a count is asking for. A
    // malformed instant is refused rather than dropped — a clear that quietly ignores its
    // boundary would remove rows the sentence said were kept.
    const until = optionalTsParam(c.req.query("until"), "until");
    const kindRaw = c.req.query("kind");
    // Validated against the same closed set the read uses: an unrecognized category would
    // otherwise match no rows, and a clear that silently matches nothing reads as "already
    // empty" while the rows are still there.
    if (
      kindRaw !== undefined &&
      kindRaw !== "" &&
      !(ERROR_KINDS as readonly string[]).includes(kindRaw)
    ) {
      throw badRequest(`kind must be one of ${ERROR_KINDS.join(" / ")}.`);
    }
    const ignored = ignoredQuery(c);
    // The same admin visibility the reads above carry, so a clear takes exactly the rows the
    // caller's panel showed. An admin's panel shows the unattributed rows (login failures,
    // process crashes) and so an admin's clear takes them; a member's never shows them, so a
    // clear can never become a way to remove a row its caller was not allowed to see.
    const deleted = deps.usageService.clearErrors(projectId, {
      includeGlobalErrors: c.var.user.isAdmin,
      ...range,
      ...(until !== undefined ? { until } : {}),
      ...(kindRaw !== undefined && kindRaw !== "" ? { kind: kindRaw } : {}),
      ...(ignored !== undefined ? { ignored } : {}),
    });
    return c.json({ deleted } satisfies UsageErrorsClearResponse);
  });

  // The Project's ignore rules: the error classes its owner has taken out of the panel's default
  // view. Owner only, the line the clear draws and for the same reason — a rule changes what
  // everyone reading this Project sees. The panel reports the count to members on its own (the
  // dashboard's `errors.ignored`), so reading the rules themselves is management, not disclosure.
  app.get("/errors/ignores", (c) => {
    const projectId = requireValidId(c, "projectId");
    deps.access.requireProjectOwner(c.var.user.userId, projectId);
    return c.json({ rules: deps.usageService.errorIgnores(projectId) } satisfies UsageErrorIgnores);
  });

  // Adds one rule. The records are not touched — the rule only decides which ones the reads select
  // — so this is undoable, and the answer carries how many records it covers in the range the
  // caller was looking at: what the caller says it just hid. The range is the same one the reads
  // and the clear take, so the number matches the table it came from.
  app.post("/errors/ignores", async (c) => {
    const projectId = requireValidId(c, "projectId");
    deps.access.requireProjectOwner(c.var.user.userId, projectId);
    const body = (await c.req.json().catch(() => null)) as {
      source?: unknown;
      code?: unknown;
      messageLike?: unknown;
      note?: unknown;
    } | null;
    // A rule with no source or no code covers nothing while reading as a rule, so both are
    // required rather than defaulted; the lengths are capped because they are matched against two
    // columns and the note is drawn in a list row.
    const source = typeof body?.source === "string" ? body.source.trim() : "";
    const code = typeof body?.code === "string" ? body.code.trim() : "";
    if (source === "" || code === "") throw badRequest("source and code are both required.");
    if (source.length > 64 || code.length > 200) {
      throw badRequest("source must be at most 64 characters and code at most 200.");
    }
    const messageLike = typeof body?.messageLike === "string" ? body.messageLike : null;
    const note = typeof body?.note === "string" ? body.note : null;
    if ((messageLike?.length ?? 0) > 200 || (note?.length ?? 0) > 200) {
      throw badRequest("messageLike and note must be at most 200 characters.");
    }
    const added = deps.usageService.addErrorIgnore(
      projectId,
      { source, code, messageLike, note, createdBy: c.var.user.userId },
      errorRangeQuery(c),
    );
    // Already ignored: the same (source, code, fragment) is one rule, and a second row covering the
    // same records would leave the list saying the same thing twice.
    if (added === null) {
      throw new HttpError(
        409,
        "ignore_rule_exists",
        `This Project already ignores [${source}] ${code}.`,
      );
    }
    return c.json(added satisfies UsageErrorIgnoreAdded, 201);
  });

  // Removes one rule, which re-exposes every record it covered — nothing was ever deleted, so this
  // is the whole of the undo.
  app.delete("/errors/ignores/:id", (c) => {
    const projectId = requireValidId(c, "projectId");
    deps.access.requireProjectOwner(c.var.user.userId, projectId);
    const id = parseNonNegativeInt(c.req.param("id") ?? "");
    if (id === null) throw badRequest("id must be a non-negative integer.");
    if (!deps.usageService.removeErrorIgnore(projectId, id)) {
      throw new HttpError(404, "ignore_rule_not_found", "No such ignore rule in this Project.");
    }
    return c.json({ removed: true });
  });

  return app;
}