Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 3 additions & 13 deletions docs/ai-coder/agents/platform-controls/spend-management.md
Original file line number Diff line number Diff line change
Expand Up @@ -53,26 +53,16 @@ Both appear only when the deployment has the AI Gateway entitlement.

## Spend details

Coder has no dedicated deployment-wide spend dashboard.
Spend is shown where it is actionable:

- **Admin settings** > **AI** > **User spend**: total and per-user AI Gateway spend for the selected organization and reporting period.
If you can also view AI sessions, you can filter it by provider, model, and client.
- **Agents page and user menu**: the signed-in user's spend against their budget, as described previously.
- **Group settings**: each member's spend against the group's budget, for admins who can manage the group.
- **Chat summary panel**: the cost of one chat tree, on a chat's Summary tab.
A subagent reports the total for its whole tree, including the chat that started it.

Organization administrators can export per-user, per-group, per-model, and per-provider spend to CSV:

```sh
curl -X GET "https://coder.example.com/api/v2/organizations/$ORGANIZATION/ai/spend/export" \
-H "Coder-Session-Token: $CODER_SESSION_TOKEN"
```

A successful response has the `Content-Type` header `text/csv; charset=utf-8` and starts with this CSV header:

```csv
user_id,username,group_id,group_name,organization_id,organization_name,model,provider,provider_name,input_tokens,output_tokens,cache_read_tokens,cache_write_tokens,cost_micros,period_start,period_end
```
For organization spend exports, refer to [AI Gateway spend export](../../ai-gateway/cost-controls.md#spend-export).

The AI Gateway [sessions views](../../ai-gateway/audit.md#navigating-the-ui) show per-request token usage, which is the input to those costs rather than the costs themselves.

Expand Down
16 changes: 10 additions & 6 deletions docs/ai-coder/ai-gateway/cost-controls.md
Original file line number Diff line number Diff line change
Expand Up @@ -313,7 +313,11 @@ Visibility follows the viewer's role:
| Every user | Their own spend and budget, or unlimited state, in their avatar menu |
| Members of a group | The group's spend and budget, and their own member row |
| Owners, User Admins, and organization administrators | Spend and budgets for every group and every member |
| Readers of an organization's group members | Organization totals and per-user spend on the **User spend** page |

- The **User spend** page under **Admin settings** > **AI** shows total and per-user AI Gateway spend for the selected organization and reporting period.
You can open it if you can read the organization's group members, as Owners, Auditors, Template Admins, User Admins, and their organization-scoped equivalents can.
If you can also view AI sessions, you can filter it by provider, model, and client.
- The **Groups** page compares each group's spend with the combined limits of
the members it covers.
- The **Members** tab of a group reports each member's spend, their budget, and
Expand All @@ -332,11 +336,9 @@ Administrators can also use the
[Get user AI spend](../../reference/api/enterprise.md#get-user-ai-spend) API
endpoint to see a user's current effective group.

### CSV Export
### Spend export

Users who can read group-member data for the organization can export approximate
spend for reporting and internal cost allocation. The export is available through
the API only.
If you can read the organization's group members, you can export approximate spend for reporting and internal cost allocation.

```sh
curl -H "Coder-Session-Token: $CODER_SESSION_TOKEN" \
Expand All @@ -346,8 +348,10 @@ curl -H "Coder-Session-Token: $CODER_SESSION_TOKEN" \
- Without parameters, the export covers the current budget period.
- To select a range, pass `period_start` and `period_end` together as RFC 3339
timestamps. A range can span at most 31 days.
- Each row breaks spend down by user, group, model, and provider, with the
underlying token counts.
- Spend is attributed through each request's effective budget group, which falls back to the organization's `Everyone` group when no budget applies, so only usage recorded without any effective group is excluded.
- Each CSV row breaks spend down by user, group, model, and provider, with the underlying token counts.

For programmatic per-user reporting, refer to the [List organization AI spend by user API reference](../../reference/api/enterprise.md#list-organization-ai-spend-by-user).

### Prometheus Metrics

Expand Down
54 changes: 48 additions & 6 deletions site/src/modules/dashboard/DashboardLayout.test.tsx
Original file line number Diff line number Diff line change
@@ -1,7 +1,10 @@
import { screen } from "@testing-library/react";
import userEvent from "@testing-library/user-event";
import { HttpResponse, http } from "msw";
import { HttpResponse, http, type PathParams } from "msw";
import type { RouteObject } from "react-router";
import type { AuthorizationRequest, Entitlements } from "#/api/typesGenerated";
import {
MockDefaultOrganization,
MockEntitlements,
MockNoPermissions,
MockPermissions,
Expand All @@ -16,15 +19,22 @@ import { DashboardLayout } from "./DashboardLayout";
const renderDashboardLayout = async ({
actual,
entitlement = "entitled",
features,
limit,
permissions = MockPermissions,
organizationChecks = false,
warnings,
children = [{ element: <h1>Test page</h1> }],
}: {
actual?: number;
entitlement?: "entitled" | "grace_period" | "not_entitled";
features?: Partial<Entitlements["features"]>;
limit?: number;
permissions?: typeof MockPermissions;
/** Answer for authorization checks keyed by organization id. */
organizationChecks?: boolean;
warnings?: string[];
children?: RouteObject[];
}) => {
server.use(
http.get("/api/v2/entitlements", () => {
Expand All @@ -41,18 +51,33 @@ const renderDashboardLayout = async ({
...(actual !== undefined ? { actual } : {}),
...(limit !== undefined ? { limit } : {}),
},
...features,
},
});
}),
http.post("/api/v2/authcheck", () => {
return HttpResponse.json(permissions);
// The inbox request fires once the permission queries settle and has no
// default handler.
http.get("/api/v2/notifications/inbox", () => {
return HttpResponse.json({ notifications: [], unread_count: 0 });
}),
http.post<PathParams, AuthorizationRequest>(
"/api/v2/authcheck",
async ({ request }) => {
const { checks } = await request.json();
return HttpResponse.json(
MockDefaultOrganization.id in checks
? Object.fromEntries(
Object.keys(checks).map((id) => [id, organizationChecks]),
)
: permissions,
);
},
),
);

renderWithAuth(<DashboardLayout />, {
children: [{ element: <h1>Test page</h1> }],
});
const result = renderWithAuth(<DashboardLayout />, { children });
await waitForLoaderToBeRemoved();
return result;
};

test("Show the new Coder version notification", async () => {
Expand Down Expand Up @@ -97,6 +122,23 @@ test("shows AI Governance over-limit warning in LicenseBanner for admin users",
).toBeInTheDocument();
});

test("navigates an organization group member reader to AI settings from Admin settings", async () => {
const { router } = await renderDashboardLayout({
permissions: MockNoPermissions,
features: { aibridge: { enabled: true, entitlement: "entitled" } },
organizationChecks: true,
children: [{ path: "/ai/settings", element: <h1>AI settings</h1> }],
});

const user = userEvent.setup();
await user.click(
await screen.findByRole("button", { name: "Admin settings" }),
);
await user.click(await screen.findByRole("menuitem", { name: "AI" }));
await screen.findByRole("heading", { name: "AI settings" });
expect(router.state.location.pathname).toBe("/ai/settings");
});

test("renders a skip link before navigation content", async () => {
renderWithAuth(<DashboardLayout />, {
children: [{ element: <h1>Test page</h1> }],
Expand Down
19 changes: 16 additions & 3 deletions site/src/modules/dashboard/Navbar/Navbar.tsx
Original file line number Diff line number Diff line change
@@ -1,4 +1,5 @@
import { useQuery } from "react-query";
import { aiSpendOrganizations } from "#/api/queries/aiBridge";
import { buildInfo } from "#/api/queries/buildInfo";
import type { LinkConfig } from "#/api/typesGenerated";
import { useProxy } from "#/contexts/ProxyContext";
Expand All @@ -10,14 +11,19 @@ import {
canViewDeploymentSettings,
} from "#/modules/permissions";
import { useCanShareOrganizationMCPServers } from "#/pages/AISettingsPage/MCPServersPage/organizationSharing";
import { canViewAISpend } from "#/pages/AISettingsPage/SpendPage/spendAccess";
import { useFeatureVisibility } from "../useFeatureVisibility";
import { NavbarView } from "./NavbarView";

export const Navbar: React.FC = () => {
const { metadata } = useEmbeddedMetadata();
const buildInfoQuery = useQuery(buildInfo(metadata["build-info"]));
const { appearance, canViewOrganizationSettings, organizations } =
useDashboard();
const {
appearance,
canViewOrganizationSettings,
entitlements,
organizations,
} = useDashboard();
const { user: me, permissions, signOut } = useAuthenticated();
const featureVisibility = useFeatureVisibility();
const proxyContextValue = useProxy();
Expand Down Expand Up @@ -46,8 +52,15 @@ export const Navbar: React.FC = () => {
organizations,
{ enabled: !canViewSiteWideAISettings },
);
const spendOrganizationsQuery = useQuery({
...aiSpendOrganizations(),
enabled:
entitlements.features.aibridge.enabled && !canViewSiteWideAISettings,
});
const canViewAISettings =
canViewSiteWideAISettings || organizationMCPSharing.canShare;
canViewSiteWideAISettings ||
organizationMCPSharing.canShare ||
canViewAISpend(entitlements, spendOrganizationsQuery.data);
const canCreateChat = permissions.createChat;

const uniqueLinks = new Map<string, LinkConfig>();
Expand Down
57 changes: 57 additions & 0 deletions site/src/modules/management/AISettingsSidebar.test.tsx
Original file line number Diff line number Diff line change
@@ -0,0 +1,57 @@
import { screen } from "@testing-library/react";
import userEvent from "@testing-library/user-event";
import { createMemoryRouter } from "react-router";
import { expect, it, vi } from "vitest";
import { API, withDefaultFeatures } from "#/api/api";
import {
MockEntitlements,
MockNoPermissions,
MockOrganization,
MockUserMember,
} from "#/testHelpers/entities";
import { renderWithRouter } from "#/testHelpers/renderHelpers";
import { AISettingsSidebar } from "./AISettingsSidebar";

const mockAIGatewayEntitlements = {
...MockEntitlements,
features: withDefaultFeatures({
aibridge: { enabled: true, entitlement: "entitled" },
}),
};

vi.mock("#/hooks/useAuthenticated", () => ({
useAuthenticated: () => ({
user: MockUserMember,
permissions: MockNoPermissions,
}),
}));
vi.mock("#/modules/dashboard/useDashboard", () => ({
useDashboard: () => ({
entitlements: mockAIGatewayEntitlements,
organizations: [MockOrganization],
}),
}));

it("links organization group member readers to the User spend page", async () => {
const user = userEvent.setup();
vi.spyOn(API, "getOrganizations").mockResolvedValue([MockOrganization]);
vi.spyOn(API, "checkAuthorization").mockResolvedValue({
[MockOrganization.id]: true,
});
vi.spyOn(API.experimental, "getChatModels").mockResolvedValue({
models: [],
providers: [],
unsupported_providers: [],
});
const router = createMemoryRouter(
[
{ path: "/ai/settings", element: <AISettingsSidebar /> },
{ path: "/ai/settings/spend", element: <div /> },
],
{ initialEntries: ["/ai/settings?org=second"] },
);
renderWithRouter(router);
await user.click(await screen.findByRole("link", { name: "User spend" }));
expect(router.state.location.pathname).toBe("/ai/settings/spend");
expect(router.state.location.search).toBe("?org=second");
});
13 changes: 12 additions & 1 deletion site/src/modules/management/AISettingsSidebar.tsx
Original file line number Diff line number Diff line change
@@ -1,25 +1,36 @@
import type { FC } from "react";
import { useQuery } from "react-query";
import { aiSpendOrganizations } from "#/api/queries/aiBridge";
import { useAuthenticated } from "#/hooks/useAuthenticated";
import { useDashboard } from "#/modules/dashboard/useDashboard";
import AISettingsSidebarView from "#/modules/management/AISettingsSidebarView";
import { useCanShareOrganizationMCPServers } from "#/pages/AISettingsPage/MCPServersPage/organizationSharing";
import { useAccessibleModelOrganizations } from "#/pages/AISettingsPage/ModelsPage/organizationModels";
import { canViewAISpend } from "#/pages/AISettingsPage/SpendPage/spendAccess";

/**
* A sidebar for AI settings.
*/
export const AISettingsSidebar: FC = () => {
const { permissions } = useAuthenticated();
const { organizations } = useDashboard();
const { entitlements, organizations } = useDashboard();
const accessibleOrgsQuery = useAccessibleModelOrganizations(organizations);
const organizationMCPSharing = useCanShareOrganizationMCPServers(
organizations,
{ enabled: !permissions.editDeploymentConfig },
);
const spendOrganizationsQuery = useQuery({
...aiSpendOrganizations(),
enabled: entitlements.features.aibridge.enabled,
});

return (
<AISettingsSidebarView
permissions={permissions}
canViewAISpend={canViewAISpend(
entitlements,
spendOrganizationsQuery.data,
)}
canAccessOrganizationModels={
(accessibleOrgsQuery.organizations.length ?? 0) > 0
}
Expand Down
22 changes: 15 additions & 7 deletions site/src/modules/management/AISettingsSidebarView.stories.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -32,6 +32,7 @@ const LocationProbe = () => {

const aiSettingsRoutes: [RouterRoute, ...RouterRoute[]] = [
{ path: "/ai/settings/governance", useStoryElement: true },
{ path: "/ai/settings/spend", useStoryElement: true },
{ path: "/ai/settings/gateway-keys", useStoryElement: true },
{ path: "/ai/settings/providers", useStoryElement: true },
{ path: "/ai/settings/coder-agents", useStoryElement: true },
Expand Down Expand Up @@ -88,13 +89,20 @@ const meta: Meta<typeof AISettingsSidebarView> = {
export default meta;
type Story = StoryObj<typeof AISettingsSidebarView>;

export const CoderAgentsActive: Story = {
play: async ({ canvasElement }) => {
const canvas = within(canvasElement);
await expect(canvas.getByRole("link", { name: "Models" })).toBeVisible();
await expect(
canvas.queryByRole("link", { name: "Spend" }),
).not.toBeInTheDocument();
export const CoderAgentsActive: Story = {};

export const SpendVisible: Story = {
args: {
canViewAISpend: true,
},
};

export const UserSpendActive: Story = {
args: {
canViewAISpend: true,
},
parameters: {
reactRouter: atLocation("/ai/settings/spend"),
},
};

Expand Down
Loading
Loading