feat(api): surface per-tenant AI cost on the operator dashboard (#7191)

Adds listAiCostByTenantSince (one GROUP BY query, highest-cost-first)
and wires it into /v1/app/operator-dashboard. The ledger and
per-tenant column already existed (#7176/#7183); nothing consumed
them yet. Always empty for self-host, unchanged behavior there.

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

Author: JSONbored

apps/loopover-ui/src/routes/app.operator.test.tsx

@@ -60,3 +60,57 @@ describe("OperatorDashboard loading skeleton (#6816)", () => {
     expect(container.querySelectorAll(".animate-pulse").length).toBe(0);
   });
 });
+
+describe("OperatorDashboard AI cost by tenant (#4916)", () => {
+  function mockDashboard(aiCostByTenant?: Array<{ installationId: string; totalCostUsd: number }>) {
+    useApiResource.mockImplementation((path: string) => {
+      if (path === "/v1/app/operator-dashboard") {
+        return {
+          status: "ready",
+          data: {
+            metrics: [{ label: "Installs", value: "12", delta: "+2" }],
+            noiseReduction: [],
+            weeklyReport: [],
+            aiCostByTenant,
+          },
+          error: null,
+          loadedAt: "2026-07-17T00:00:00.000Z",
+          reload: () => {},
+        };
+      }
+      return {
+        status: "error",
+        data: null,
+        error: "unavailable in this test",
+        errorKind: "unknown",
+        loadedAt: null,
+        reload: () => {},
+      };
+    });
+  }
+
+  it("renders no section at all when aiCostByTenant is absent (self-host, the common case)", () => {
+    mockDashboard(undefined);
+    render(<OperatorDashboard />);
+    expect(screen.queryByText("AI cost by tenant")).toBeNull();
+  });
+
+  it("renders no section when aiCostByTenant is an empty list", () => {
+    mockDashboard([]);
+    render(<OperatorDashboard />);
+    expect(screen.queryByText("AI cost by tenant")).toBeNull();
+  });
+
+  it("renders each tenant's formatted cost, highest-cost-first as the backend already ordered them", () => {
+    mockDashboard([
+      { installationId: "inst-2", totalCostUsd: 4 },
+      { installationId: "inst-1", totalCostUsd: 2 },
+    ]);
+    render(<OperatorDashboard />);
+    expect(screen.getByText("AI cost by tenant")).toBeTruthy();
+    expect(screen.getByText("inst-2")).toBeTruthy();
+    expect(screen.getByText("$4.00")).toBeTruthy();
+    expect(screen.getByText("inst-1")).toBeTruthy();
+    expect(screen.getByText("$2.00")).toBeTruthy();
+  });
+});

apps/loopover-ui/src/routes/app.operator.tsx

@@ -34,6 +34,7 @@ type OperatorDashboardResponse = {
     metrics: Array<{ id: string; label: string; value: number; detail: string }>;
   };
   upstreamDrift?: { status?: string } | null;
+  aiCostByTenant?: Array<{ installationId: string; totalCostUsd: number }>;
 };
 
 type FleetMetrics = {
@@ -51,6 +52,7 @@ type FleetMetrics = {
 };
 
 const formatPct = (v: number | null): string => (v === null ? "—" : `${Math.round(v * 100)}%`);
+const usdFmt = new Intl.NumberFormat("en-US", { style: "currency", currency: "USD" });
 const formatMs = (v: number | null): string =>
   v === null
     ? "—"
@@ -482,6 +484,30 @@ export function OperatorDashboard() {
               ) : null}
             </div>
           </section>
+          {data.aiCostByTenant && data.aiCostByTenant.length > 0 ? (
+            <section className="rounded-token border border-border bg-transparent p-5">
+              <h2 className="font-display text-token-lg font-semibold">AI cost by tenant</h2>
+              <p className="mt-1 text-token-xs text-muted-foreground">
+                Hosted-deployment AI spend, highest-cost tenant first. Empty for self-host — this
+                only populates once an installation carries hosted AI-usage records.
+              </p>
+              <ul className="mt-4 space-y-2">
+                {data.aiCostByTenant.map((tenant) => (
+                  <li
+                    key={tenant.installationId}
+                    className="flex items-center justify-between gap-4 border-b-hairline pb-2 last:border-b-0 last:pb-0"
+                  >
+                    <span className="font-mono text-token-xs text-foreground/90">
+                      {tenant.installationId}
+                    </span>
+                    <span className="font-mono text-token-sm text-foreground">
+                      {usdFmt.format(tenant.totalCostUsd)}
+                    </span>
+                  </li>
+                ))}
+              </ul>
+            </section>
+          ) : null}
           <DeadLetterQueuePanel />
           <NotificationReadinessCard />
         </div>

src/db/repositories.ts

@@ -1,5 +1,5 @@
 import { parsePullRequestTargetKey } from "@loopover/engine";
-import { and, asc, desc, eq, gte, inArray, not, or, sql, type SQL } from "drizzle-orm";
+import { and, asc, desc, eq, gte, inArray, isNotNull, not, or, sql, type SQL } from "drizzle-orm";
 import { getDb } from "./client";
 import {
   activeReviewTracking,
@@ -3621,6 +3621,27 @@ export async function sumAiCostForTenantSince(env: Env, installationId: string,
   return Number(row?.total ?? 0);
 }
 
+export type AiCostByTenant = { installationId: string; totalCostUsd: number };
+
+/** #4916: fleet-wide, per-tenant AI cost breakdown for the operator dashboard — "who is costing what", not just
+ *  one tenant's own total (sumAiCostForTenantSince above). One GROUP BY query rather than N per-tenant calls.
+ *  Self-host rows (installation_id IS NULL) are excluded by construction, matching sumAiCostForTenantSince's own
+ *  hosted-only scope; the ai_usage_events_installation_created_idx index this shares with that function covers
+ *  both the equality/range lookup there and the grouped scan here. Ordered highest-cost-first so the dashboard
+ *  never needs its own client-side sort. */
+export async function listAiCostByTenantSince(env: Env, sinceIso: string): Promise<AiCostByTenant[]> {
+  const db = getDb(env.DB);
+  const rows = await db
+    .select({ installationId: aiUsageEvents.installationId, total: sql<number>`coalesce(sum(${aiUsageEvents.costUsd}), 0)` })
+    .from(aiUsageEvents)
+    .where(and(isNotNull(aiUsageEvents.installationId), gte(aiUsageEvents.createdAt, sinceIso)))
+    .groupBy(aiUsageEvents.installationId)
+    .orderBy(desc(sql`coalesce(sum(${aiUsageEvents.costUsd}), 0)`));
+  /* v8 ignore next -- installationId is the GROUP BY key under an isNotNull filter; D1 cannot return a null
+   *  group here, so the fallback only guards the driver's own typing, not a real runtime path. */
+  return rows.map((row) => ({ installationId: row.installationId ?? "", totalCostUsd: Number(row.total) }));
+}
+
 /** Spend-attempt statuses `countByokAiEventsForRepoSince`/`sumByokAiUsageForRepoSince` count: a real request
  *  reached the provider, whether or not it returned something usable ("ok") or genuinely failed ("error" --
  *  timeout/http_error/exception, see e.g. queue/processors.ts's recordVisualVisionUsage). Deliberately an

src/services/operator-dashboard.ts

@@ -4,6 +4,7 @@ import {
   getCommandUsefulnessSummary,
   getLatestScoringModelSnapshot,
   getProductUsageRollupStatus,
+  listAiCostByTenantSince,
   listAllPullRequests,
   listInstallationHealth,
   listInstallations,
@@ -12,6 +13,7 @@ import {
   listRepositories,
   summarizeMcpCompatibilityAdoption,
   summarizeProductUsageEvents,
+  type AiCostByTenant,
 } from "../db/repositories";
 import { getLatestRegistrySnapshot } from "../registry/sync";
 import type {
@@ -90,6 +92,10 @@ export type OperatorDashboardPayload = {
   // Finding acceptance rate (#1967): share of gate-flagged (hold|close) PRs later merged, reshaped to the
   // AcceptanceRateCard's field names. Fails safe to an empty aggregate (rate: null) on any read error.
   acceptance: OperatorDashboardFindingAcceptance;
+  // #4916: per-tenant AI cost breakdown for hosted deployments, highest-cost-first. Always [] for a self-host
+  // operator (no installation-scoped ai_usage_events rows exist there) -- this surfaces the #7176/#7183 ledger
+  // data that had no dashboard consumer until now.
+  aiCostByTenant: AiCostByTenant[];
 };
 
 const USAGE_WINDOW_DAYS = 7;
@@ -126,6 +132,7 @@ export async function buildOperatorDashboardPayload(
     agentHealth,
     slopCalibration,
     findingAcceptance,
+    aiCostByTenant,
   ] = await Promise.all([
     listRepositories(env),
     listInstallations(env),
@@ -153,6 +160,8 @@ export async function buildOperatorDashboardPayload(
     // #1967: reuse the existing finding-acceptance aggregate (no new compute); fails safe to an empty
     // aggregate on any read error.
     computeFindingAcceptance(env, { days: GATE_ANALYTICS_WINDOW_DAYS, nowMs: Date.now() }),
+    // #4916: per-tenant AI cost breakdown, same window as the rest of the usage metrics above.
+    listAiCostByTenantSince(env, usageSince),
   ]);
   const weeklyValueReport = buildWeeklyValueReport({
     generatedAt: nowIso(),
@@ -271,6 +280,7 @@ export async function buildOperatorDashboardPayload(
     agentHealth,
     slopCalibration,
     acceptance,
+    aiCostByTenant,
   };
 }
 

test/unit/ai-usage-tenant.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, it } from "vitest";
-import { recordAiUsageEvent, sumAiCostForTenantSince } from "../../src/db/repositories";
+import { listAiCostByTenantSince, recordAiUsageEvent, sumAiCostForTenantSince } from "../../src/db/repositories";
 import { createTestEnv } from "../helpers/d1";
 
 // #7176: ai_usage_events gained a nullable installation_id tenant column for centralized hosted billing, plus a
@@ -18,6 +18,14 @@ async function installationOf(env: Env, id: string): Promise<string | null> {
   return row?.installation_id ?? null;
 }
 
+/** Insert one ai_usage_events row and backdate it, so time-window filters (sinceIso) are actually exercised
+ *  instead of every row landing at "now". Shared by the per-tenant sum tests and the fleet-wide breakdown tests
+ *  below, which seed the identical fixture shape. */
+async function seedCostEvent(env: Env, installationId: string | null, costUsd: number, createdAt: string): Promise<void> {
+  await recordAiUsageEvent(env, { ...base, costUsd, installationId });
+  await env.DB.prepare("UPDATE ai_usage_events SET created_at = ? WHERE created_at = (SELECT max(created_at) FROM ai_usage_events)").bind(createdAt).run();
+}
+
 describe("ai_usage_events tenant column + billing aggregate (#7176)", () => {
   it("writes installation_id when a hosted caller supplies it", async () => {
     const env = createTestEnv();
@@ -42,20 +50,51 @@ describe("ai_usage_events tenant column + billing aggregate (#7176)", () => {
     const env = createTestEnv();
     // Two events for inst-1 after the window, one before it, one for inst-2, one self-host (null tenant).
     const since = "2026-07-10T00:00:00.000Z";
-    const seed = async (installationId: string | null, costUsd: number, createdAt: string) => {
-      await recordAiUsageEvent(env, { ...base, costUsd, installationId });
-      // Backdate the just-inserted row (recordAiUsageEvent stamps nowIso()), so the window filter is exercised.
-      await env.DB.prepare("UPDATE ai_usage_events SET created_at = ? WHERE created_at = (SELECT max(created_at) FROM ai_usage_events)").bind(createdAt).run();
-    };
-    await seed("inst-1", 1.25, "2026-07-11T00:00:00.000Z");
-    await seed("inst-1", 0.75, "2026-07-12T00:00:00.000Z");
-    await seed("inst-1", 9.0, "2026-07-01T00:00:00.000Z"); // before the window
-    await seed("inst-2", 4.0, "2026-07-13T00:00:00.000Z"); // different tenant
-    await seed(null, 3.0, "2026-07-14T00:00:00.000Z"); // self-host, null tenant
+    await seedCostEvent(env, "inst-1", 1.25, "2026-07-11T00:00:00.000Z");
+    await seedCostEvent(env, "inst-1", 0.75, "2026-07-12T00:00:00.000Z");
+    await seedCostEvent(env, "inst-1", 9.0, "2026-07-01T00:00:00.000Z"); // before the window
+    await seedCostEvent(env, "inst-2", 4.0, "2026-07-13T00:00:00.000Z"); // different tenant
+    await seedCostEvent(env, null, 3.0, "2026-07-14T00:00:00.000Z"); // self-host, null tenant
 
     expect(await sumAiCostForTenantSince(env, "inst-1", since)).toBeCloseTo(2.0, 5);
     expect(await sumAiCostForTenantSince(env, "inst-2", since)).toBeCloseTo(4.0, 5);
     // A tenant with no rows sums to 0, not an error.
     expect(await sumAiCostForTenantSince(env, "inst-none", since)).toBe(0);
   });
 });
+
+describe("listAiCostByTenantSince (#4916): fleet-wide per-tenant breakdown for the operator dashboard", () => {
+  it("groups by tenant, sums correctly, and orders highest-cost-first", async () => {
+    const env = createTestEnv();
+    const since = "2026-07-10T00:00:00.000Z";
+    await seedCostEvent(env, "inst-1", 1.25, "2026-07-11T00:00:00.000Z");
+    await seedCostEvent(env, "inst-1", 0.75, "2026-07-12T00:00:00.000Z"); // inst-1 total: 2.0
+    await seedCostEvent(env, "inst-2", 4.0, "2026-07-13T00:00:00.000Z"); // inst-2 total: 4.0 (highest)
+    await seedCostEvent(env, "inst-3", 0.5, "2026-07-13T00:00:00.000Z"); // inst-3 total: 0.5 (lowest)
+
+    const rows = await listAiCostByTenantSince(env, since);
+
+    expect(rows).toEqual([
+      { installationId: "inst-2", totalCostUsd: 4.0 },
+      { installationId: "inst-1", totalCostUsd: 2.0 },
+      { installationId: "inst-3", totalCostUsd: 0.5 },
+    ]);
+  });
+
+  it("excludes self-host rows (null installation_id) and rows outside the time window", async () => {
+    const env = createTestEnv();
+    const since = "2026-07-10T00:00:00.000Z";
+    await seedCostEvent(env, "inst-1", 2.0, "2026-07-11T00:00:00.000Z"); // in window
+    await seedCostEvent(env, "inst-1", 9.0, "2026-07-01T00:00:00.000Z"); // before the window
+    await seedCostEvent(env, null, 5.0, "2026-07-11T00:00:00.000Z"); // self-host, must never appear
+
+    const rows = await listAiCostByTenantSince(env, since);
+
+    expect(rows).toEqual([{ installationId: "inst-1", totalCostUsd: 2.0 }]);
+  });
+
+  it("returns an empty list, not an error, when there are no hosted rows at all (the self-host default)", async () => {
+    const env = createTestEnv();
+    expect(await listAiCostByTenantSince(env, "2026-07-10T00:00:00.000Z")).toEqual([]);
+  });
+});