@agent-native/dispatch 0.31.13 → 0.31.14

package/src/server/lib/usage-metrics-store.spec.ts

@@ -33,6 +33,7 @@ vi.mock("@agent-native/core/settings", () => ({
 }));
 
 vi.mock("@agent-native/core/usage", () => ({
+  builderCreditsFromCostCents: (cents: number) => cents / 4,
   getUsageSummary: (...args: any[]) => mocks.getUsageSummary(...args),
   usageBillingForEngine: () => ({
     unit: "usd",
@@ -101,7 +102,7 @@ describe("listDispatchUsageMetrics", () => {
       orgId: null,
       role: null,
       scope: "solo",
-      totalUsers: 0,
+      totalUsers: 1,
     });
     expect(metrics.totals).toEqual({
       costCents: 0,
@@ -195,6 +196,35 @@ describe("listDispatchUsageMetrics", () => {
     ).toBe(true);
   });
 
+  it("keeps an unaffiliated workspace request scoped to the signed-in user", async () => {
+    mocks.getUsageSummary.mockResolvedValue(null);
+    mocks.listWorkspaceApps.mockResolvedValue([]);
+    mocks.execute.mockResolvedValue({ rows: [] });
+
+    const metrics = await listDispatchUsageMetrics({
+      sinceDays: 30,
+      scope: "workspace",
+    });
+
+    expect(metrics.access).toMatchObject({
+      viewerEmail: "owner@example.test",
+      orgId: null,
+      scope: "solo",
+      totalUsers: 1,
+    });
+    const scopedTokenQueries = mocks.execute.mock.calls
+      .map(([query]) => String((query as { sql?: string }).sql))
+      .filter(
+        (sql) => sql.includes("FROM token_usage") && sql.includes("WHERE"),
+      );
+    expect(scopedTokenQueries.length).toBeGreaterThan(0);
+    expect(
+      scopedTokenQueries.every((sql) =>
+        sql.includes("LOWER(owner_email) IN (?)"),
+      ),
+    ).toBe(true);
+  });
+
   it("filters workspace usage and prompts to a selected member", async () => {
     mocks.currentOrgId.mockReturnValue("org-a");
     mocks.currentOwnerEmail.mockReturnValue("owner@example.test");
@@ -237,4 +267,105 @@ describe("listDispatchUsageMetrics", () => {
       }),
     ).toBe(true);
   });
+
+  it("returns monthly credits and workspace app creation rows from shared tables", async () => {
+    const firstUsageAt = Date.UTC(2026, 6, 1, 12);
+    const secondUsageAt = Date.UTC(2026, 6, 15, 12);
+    const firstCreationAt = Date.UTC(2026, 6, 2, 12);
+    const secondCreationAt = Date.UTC(2026, 6, 20, 12);
+
+    mocks.currentOrgId.mockReturnValue("org-a");
+    mocks.currentOwnerEmail.mockReturnValue("owner@example.test");
+    mocks.getUsageSummary.mockResolvedValue(null);
+    mocks.listWorkspaceApps.mockResolvedValue([]);
+    mocks.execute.mockImplementation(async ({ sql }: { sql: string }) => {
+      if (sql.includes("SELECT role FROM org_members")) {
+        return { rows: [{ role: "owner" }] };
+      }
+      if (sql.includes("SELECT email, role, joined_at")) {
+        return {
+          rows: [
+            { email: "owner@example.test", role: "owner", joined_at: null },
+            { email: "member@example.test", role: "member", joined_at: null },
+          ],
+        };
+      }
+      if (
+        sql.includes("FROM token_usage") &&
+        sql.includes("ORDER BY created_at ASC")
+      ) {
+        return {
+          rows: [
+            {
+              created_at: firstUsageAt,
+              owner_email: "member@example.test",
+              label: "chat",
+              input_tokens: 10,
+              output_tokens: 20,
+              cache_read_tokens: 0,
+              cache_write_tokens: 0,
+              cost_cents_x100: 10000,
+            },
+            {
+              created_at: secondUsageAt,
+              owner_email: "member@example.test",
+              label: "tool",
+              input_tokens: 30,
+              output_tokens: 40,
+              cache_read_tokens: 5,
+              cache_write_tokens: 2,
+              cost_cents_x100: 20000,
+            },
+          ],
+        };
+      }
+      if (sql.includes("FROM dispatch_audit_events")) {
+        return {
+          rows: [
+            {
+              created_at: firstCreationAt,
+              owner_email: "member@example.test",
+              actor: "member@example.test",
+              target_id: "app-one",
+            },
+            {
+              created_at: secondCreationAt,
+              owner_email: "member@example.test",
+              actor: "member@example.test",
+              target_id: "app-two",
+            },
+          ],
+        };
+      }
+      return { rows: [] };
+    });
+
+    const metrics = await listDispatchUsageMetrics({
+      sinceDays: 365,
+      scope: "workspace",
+    });
+
+    expect(metrics.monthlyByUser).toEqual([
+      {
+        month: "2026-07",
+        ownerEmail: "member@example.test",
+        costCents: 300,
+        credits: 75,
+        calls: 2,
+        chatCalls: 1,
+        inputTokens: 40,
+        outputTokens: 60,
+        cacheReadTokens: 5,
+        cacheWriteTokens: 2,
+      },
+    ]);
+    expect(metrics.workspaceAppCreationsByUserMonth).toEqual([
+      {
+        month: "2026-07",
+        ownerEmail: "member@example.test",
+        count: 2,
+        appIds: ["app-one", "app-two"],
+      },
+    ]);
+  });
 });

package/src/server/lib/usage-metrics-store.ts

@@ -10,6 +10,7 @@ import { getDbExec } from "@agent-native/core/db";
 import { getSetting } from "@agent-native/core/settings";
 import { ForbiddenError } from "@agent-native/core/sharing";
 import {
+  builderCreditsFromCostCents,
   getUsageSummary,
   usageBillingForEngine,
   type UsageBillingMode,
@@ -73,6 +74,26 @@ export interface DailyUsageMetric {
   activeUsers: number;
 }
 
+export interface MonthlyUserUsageMetric {
+  month: string;
+  ownerEmail: string;
+  costCents: number;
+  credits: number;
+  calls: number;
+  chatCalls: number;
+  inputTokens: number;
+  outputTokens: number;
+  cacheReadTokens: number;
+  cacheWriteTokens: number;
+}
+
+export interface WorkspaceAppCreationMetric {
+  month: string;
+  ownerEmail: string;
+  count: number;
+  appIds: string[];
+}
+
 export interface RecentUsageMetric {
   id: number;
   createdAt: number;
@@ -134,6 +155,8 @@ export interface DispatchUsageMetrics {
   byLabel: UsageMetricBucket[];
   byModel: UsageMetricBucket[];
   daily: DailyUsageMetric[];
+  monthlyByUser: MonthlyUserUsageMetric[];
+  workspaceAppCreationsByUserMonth: WorkspaceAppCreationMetric[];
   appAccess: AppAccessMetric[];
   recent: RecentUsageMetric[];
 }
@@ -412,37 +435,6 @@ async function listOrgMembers(orgId: string | null): Promise<MemberRecord[]> {
     .filter((member) => member.email);
 }
 
-async function listSignedInUsers(): Promise<MemberRecord[]> {
-  const authRows = await queryRows<Record<string, unknown>>(
-    `SELECT email, created_at AS joined_at FROM "user" ORDER BY created_at ASC`,
-  );
-  if (authRows.length > 0) {
-    return authRows
-      .map((row) => ({
-        email: stringField(row, "email").trim(),
-        role: null,
-        joinedAt: nullableNumberField(row, "joined_at"),
-      }))
-      .filter((member) => member.email);
-  }
-
-  const usageRows = await queryRows<{ email?: string }>(
-    `SELECT DISTINCT owner_email AS email FROM token_usage`,
-  );
-  const threadRows = await queryRows<{ email?: string }>(
-    `SELECT DISTINCT owner_email AS email FROM chat_threads`,
-  );
-  const emails = new Set<string>();
-  for (const row of [...usageRows, ...threadRows]) {
-    if (row.email) emails.add(row.email);
-  }
-  return [...emails].sort().map((email) => ({
-    email,
-    role: null,
-    joinedAt: null,
-  }));
-}
-
 function usageScope(
   sinceMs: number,
   memberEmails: string[],
@@ -497,6 +489,28 @@ function ownerThreadScope(
   };
 }
 
+function workspaceAppCreationScope(
+  sinceMs: number,
+  orgId: string | null,
+  memberEmails: string[],
+): { where: string; args: unknown[] } {
+  const filters = ["created_at >= ?", "action = ?"];
+  const args: unknown[] = [sinceMs, "workspace-app.pending"];
+
+  if (orgId) {
+    filters.push("org_id = ?");
+    args.push(orgId);
+  }
+  if (memberEmails.length > 0) {
+    filters.push(
+      `LOWER(owner_email) IN (${memberEmails.map(() => "?").join(", ")})`,
+    );
+    args.push(...memberEmails.map((email) => email.toLowerCase()));
+  }
+
+  return { where: filters.join(" AND "), args };
+}
+
 function bucketFromRow(row: Record<string, unknown>): UsageMetricBucket {
   const key = stringField(row, "k");
   return {
@@ -610,7 +624,7 @@ export async function listDispatchUsageMetrics(input: {
       ? [{ email: viewerEmail, role, joinedAt: null }]
       : orgId
         ? await listOrgMembers(orgId)
-        : await listSignedInUsers();
+        : [{ email: viewerEmail, role: null, joinedAt: null }];
   const members =
     viewScope === "workspace" && orgId && rawMembers.length === 0
       ? [{ email: viewerEmail, role, joinedAt: null }]
@@ -632,9 +646,7 @@ export async function listDispatchUsageMetrics(input: {
   }
   const memberEmails = selectedUserEmail
     ? [selectedUserEmail]
-    : orgId
-      ? members.map((member) => member.email)
-      : [];
+    : members.map((member) => member.email);
   const memberByEmail = new Map(
     members.map((member) => [member.email.toLowerCase(), member]),
   );
@@ -645,11 +657,25 @@ export async function listDispatchUsageMetrics(input: {
     ? ownerThreadScope(sinceMs, selectedUserEmail)
     : threadScope(sinceMs, memberEmails);
 
-  const [apps, totalsRows, byApp, byUserBase, byLabel, byModel, chatStats] =
-    await Promise.all([
-      listWorkspaceApps({ includeAgentCards: false }),
-      queryRows<Record<string, unknown>>(
-        `SELECT
+  const workspaceAppCreation = workspaceAppCreationScope(
+    sinceMs,
+    orgId,
+    memberEmails,
+  );
+
+  const [
+    apps,
+    totalsRows,
+    byApp,
+    byUserBase,
+    byLabel,
+    byModel,
+    chatStats,
+    workspaceAppCreationRows,
+  ] = await Promise.all([
+    listWorkspaceApps({ includeAgentCards: false }),
+    queryRows<Record<string, unknown>>(
+      `SELECT
             COALESCE(SUM(cost_cents_x100), 0) AS cost_x100,
             COUNT(*) AS calls,
             SUM(CASE WHEN label = 'chat' THEN 1 ELSE 0 END) AS chat_calls,
@@ -660,29 +686,36 @@ export async function listDispatchUsageMetrics(input: {
             COUNT(DISTINCT owner_email) AS active_users
           FROM token_usage
           WHERE ${usage.where}`,
-        usage.args,
-      ),
-      usageBuckets(
-        `COALESCE(NULLIF(app, ''), 'unattributed')`,
-        usage.where,
-        usage.args,
-        20,
-      ),
-      usageBuckets("owner_email", usage.where, usage.args, 50),
-      usageBuckets(
-        `COALESCE(NULLIF(label, ''), 'chat')`,
-        usage.where,
-        usage.args,
-        20,
-      ),
-      usageBuckets(
-        `COALESCE(NULLIF(model, ''), 'unknown')`,
-        usage.where,
-        usage.args,
-        20,
-      ),
-      loadChatStats(threads.where, threads.args),
-    ]);
+      usage.args,
+    ),
+    usageBuckets(
+      `COALESCE(NULLIF(app, ''), 'unattributed')`,
+      usage.where,
+      usage.args,
+      20,
+    ),
+    usageBuckets("owner_email", usage.where, usage.args, 50),
+    usageBuckets(
+      `COALESCE(NULLIF(label, ''), 'chat')`,
+      usage.where,
+      usage.args,
+      20,
+    ),
+    usageBuckets(
+      `COALESCE(NULLIF(model, ''), 'unknown')`,
+      usage.where,
+      usage.args,
+      20,
+    ),
+    loadChatStats(threads.where, threads.args),
+    queryRows<Record<string, unknown>>(
+      `SELECT owner_email, actor, target_id, created_at
+          FROM dispatch_audit_events
+          WHERE ${workspaceAppCreation.where}
+          ORDER BY created_at ASC`,
+      workspaceAppCreation.args,
+    ),
+  ]);
 
   const topAppRows = await queryRows<Record<string, unknown>>(
     `SELECT owner_email AS owner_email,
@@ -746,7 +779,8 @@ export async function listDispatchUsageMetrics(input: {
   }
 
   const dayRows = await queryRows<Record<string, unknown>>(
-    `SELECT created_at, owner_email, label, cost_cents_x100
+    `SELECT created_at, owner_email, label, input_tokens, output_tokens,
+        cache_read_tokens, cache_write_tokens, cost_cents_x100
       FROM token_usage
       WHERE ${usage.where}
       ORDER BY created_at ASC`,
@@ -756,10 +790,16 @@ export async function listDispatchUsageMetrics(input: {
     string,
     { costX100: number; calls: number; chatCalls: number; users: Set<string> }
   >();
+  const monthlyByUserMap = new Map<
+    string,
+    Omit<MonthlyUserUsageMetric, "credits">
+  >();
   for (const row of dayRows) {
     const date = new Date(numberField(row, "created_at"))
       .toISOString()
       .slice(0, 10);
+    const month = date.slice(0, 7);
+    const ownerEmail = stringField(row, "owner_email");
     const current = dailyMap.get(date) ?? {
       costX100: 0,
       calls: 0,
@@ -769,8 +809,29 @@ export async function listDispatchUsageMetrics(input: {
     current.costX100 += numberField(row, "cost_cents_x100");
     current.calls += 1;
     if (stringField(row, "label") === "chat") current.chatCalls += 1;
-    current.users.add(stringField(row, "owner_email"));
+    current.users.add(ownerEmail);
     dailyMap.set(date, current);
+
+    const monthlyKey = `${ownerEmail}\u0000${month}`;
+    const monthly = monthlyByUserMap.get(monthlyKey) ?? {
+      month,
+      ownerEmail,
+      costCents: 0,
+      calls: 0,
+      chatCalls: 0,
+      inputTokens: 0,
+      outputTokens: 0,
+      cacheReadTokens: 0,
+      cacheWriteTokens: 0,
+    };
+    monthly.costCents += numberField(row, "cost_cents_x100") / 100;
+    monthly.calls += 1;
+    if (stringField(row, "label") === "chat") monthly.chatCalls += 1;
+    monthly.inputTokens += numberField(row, "input_tokens");
+    monthly.outputTokens += numberField(row, "output_tokens");
+    monthly.cacheReadTokens += numberField(row, "cache_read_tokens");
+    monthly.cacheWriteTokens += numberField(row, "cache_write_tokens");
+    monthlyByUserMap.set(monthlyKey, monthly);
   }
   const daily = [...dailyMap.entries()]
     .map(([date, value]) => ({
@@ -782,6 +843,51 @@ export async function listDispatchUsageMetrics(input: {
     }))
     .sort((a, b) => a.date.localeCompare(b.date));
 
+  const monthlyByUser = [...monthlyByUserMap.values()]
+    .map((row) => ({
+      ...row,
+      credits: builderCreditsFromCostCents(row.costCents),
+    }))
+    .sort(
+      (a, b) =>
+        a.month.localeCompare(b.month) ||
+        a.ownerEmail.localeCompare(b.ownerEmail),
+    );
+
+  const workspaceAppCreationMap = new Map<
+    string,
+    { month: string; ownerEmail: string; count: number; appIds: Set<string> }
+  >();
+  for (const row of workspaceAppCreationRows) {
+    const month = new Date(numberField(row, "created_at"))
+      .toISOString()
+      .slice(0, 7);
+    const ownerEmail =
+      stringField(row, "owner_email") || stringField(row, "actor");
+    if (!ownerEmail) continue;
+    const key = `${ownerEmail}\u0000${month}`;
+    const current = workspaceAppCreationMap.get(key) ?? {
+      month,
+      ownerEmail,
+      count: 0,
+      appIds: new Set<string>(),
+    };
+    current.count += 1;
+    const appId = stringField(row, "target_id");
+    if (appId) current.appIds.add(appId);
+    workspaceAppCreationMap.set(key, current);
+  }
+  const workspaceAppCreationsByUserMonth = [...workspaceAppCreationMap.values()]
+    .map(({ appIds, ...row }) => ({
+      ...row,
+      appIds: [...appIds].sort(),
+    }))
+    .sort(
+      (a, b) =>
+        a.month.localeCompare(b.month) ||
+        a.ownerEmail.localeCompare(b.ownerEmail),
+    );
+
   const recentRows = await queryRows<Record<string, unknown>>(
     `SELECT id, created_at, owner_email, app, label, model,
         input_tokens, output_tokens, cache_read_tokens, cache_write_tokens,
@@ -873,6 +979,8 @@ export async function listDispatchUsageMetrics(input: {
     byLabel,
     byModel,
     daily,
+    monthlyByUser,
+    workspaceAppCreationsByUserMonth,
     appAccess,
     recent,
   };

package/src/server/plugins/agent-chat.spec.ts

@@ -27,10 +27,12 @@ describe("Dispatch agent chat plugin", () => {
         initialToolNames: expect.arrayContaining([
           "list-workspace-apps",
           "update-workspace-app-metadata",
+          "list-dispatch-usage-metrics",
         ]),
         mcp: {
           connectorCatalog: expect.arrayContaining([
             "start-workspace-app-creation",
+            "list-dispatch-usage-metrics",
           ]),
         },
         actionRoutePublicPaths: ["/_agent-native/actions/list-workspace-apps"],

package/src/server/plugins/agent-chat.ts

@@ -28,6 +28,7 @@ const INITIAL_TOOL_NAMES = [
   "upsert-destination",
   "list-dreams",
   "start-workspace-app-creation",
+  "list-dispatch-usage-metrics",
   "list-available-workspace-templates",
   "provider-api-catalog",
   "provider-api-docs",
@@ -44,6 +45,7 @@ export default createAgentChatPlugin({
     connectorCatalog: [
       "resolve-integration-source-context",
       "start-workspace-app-creation",
+      "list-dispatch-usage-metrics",
     ],
   },
   // Without this, AGENT_ORG_ID is never set on agent action calls and every
@@ -91,6 +93,7 @@ Use the standard workspace primitives:
 - Treat first-party apps such as Mail, Calendar, Analytics, Brain, Assets, and Dispatch as existing hosted/connected neighbors available through links and A2A/default connected agents. Do not create wrapper apps, child apps, nested routes, or cloned template copies just to give a new app access to them; build only the genuinely new workflow and delegate cross-app work to those existing apps.
 - Integration grants are not provider capability limits. For ad hoc provider inspection, querying, reporting, or troubleshooting, call provider-api-catalog/provider-api-docs, then provider-api-request against the provider's real HTTP API. Use connectionId for a specific shared grant and accountId for a specific OAuth account. Never expose secret values or silently widen app access while doing this.
 - For broad provider searches, joins, classification, corpus counts, or absence claims, fetch every relevant page or an explicitly bounded cohort, stage/save large responses with stageAs/saveToFile/fetchAllPages, and reduce them with query-staged-dataset or run-code. Report source, filters, row counts, pagination, truncation, failed pages, and uncovered gaps.
+- For Builder.io or AI credit spend, LLM usage by workspace member or month, or workspace app/Builder branch creation history, call list-dispatch-usage-metrics with scope=workspace and the requested sinceDays. Its monthlyByUser and workspaceAppCreationsByUserMonth fields are the authoritative shared-database result; do not ask for a user export or BigQuery schema.
 
 When a user asks for something like a digest, reminder, routing rule, or saved behavior:
 - First decide whether it should be a resource, a recurring job, a destination, or a delegated task.