AI Cost & Token Usage Dashboard

Status: Not yet available. This feature was fully built in PR #137 but could not be merged due to TypeScript CI failures. This page documents the intended behaviour for when the feature ships.

---

Overview

The AI Cost & Budget Dashboard gives you per-project visibility into exactly where your AI agent credits are going. Every agent run deducts credits from your project balance; this dashboard surfaces those deductions in a structured, actionable way — broken down by agent type, pipeline run, and month.

Once shipped, the dashboard will be accessible at:

/dashboard/products/[project-id]/ai-cost

It will appear in the product sidebar under Operations → AI Cost & Budget (identified by the BrainCircuit icon), placed after the existing Revenue & Growth section.

---

Dashboard Tabs

By Agent Type

A horizontal bar chart showing each agent type's total credit spend for the current month. Each row includes:

• Agent name and color indicator
• Number of runs
• Total tokens consumed (input + output)
• Dollar cost and percentage of total spend

Agent types covered include: Implementation, Research, Testing, Release, Security, Documentation, Design, Marketing, UI/UX, Performance, Compliance, Revenue, Dependency, and more.

Monthly Trend

A 6-month CSS bar chart of historical spend, letting you spot month-over-month growth or anomalies at a glance.

Top Pipelines

A table of the most expensive pipeline runs, showing:

• Run ID (linked to the pipeline run detail page)
• Run status and trigger type
• Start time
• Number of agent jobs
• Total tokens consumed
• Total cost

Recent Runs

A chronological list of the last 50 individual credit deduction events, enriched with agent type labels. Useful for auditing specific agent invocations.

---

Budget Alerts

You can configure a monthly credit budget limit per project. Once set, a progress bar appears at the top of the dashboard:

Threshold	Indicator
< 80% consumed	🟢 Green — on track
80–99% consumed	🟡 Yellow — approaching limit
≥ 100% consumed	🔴 Red — limit exceeded, with guidance text

The budget limit is stored in billingSettings under the key ai_budget_monthly_limit and can be updated at any time via the dashboard UI.

---

Data Model

All cost data is derived by joining:

creditTransactions → agentJobs → pipelineRuns

Queries are scoped to the specific project, ensuring cross-project data never leaks into a single project view.

---

tRPC API (Pending)

Once shipped, the following aiCost router procedures will be available via tRPC:

aiCost.getMonthlySummary

Returns the current month's total spend, a breakdown by agent type sorted by cost, the top 5 pipeline runs by cost, the configured budget limit, and the percentage of that budget consumed.

aiCost.getMonthlyTrend

Returns the last 6 months of spend as a bucketed time series.

aiCost.getCrossProjectSummary

Returns an aggregate monthly spend view across all projects owned by the authenticated user.

aiCost.setBudgetLimit

// Input
{ projectId: string; limitDollars: number }

Upserts a monthly credit budget threshold. Pass 0 to remove the limit.

aiCost.getRecentTransactions

Returns the last 50 agent run credit deduction records, enriched with agent type labels.

---

Current Blocker

This feature is blocked because CI fails with TS2307 errors for six missing router modules referenced in src/lib/trpc/root.ts. Until those modules exist or their imports are removed, the typecheck job will not pass and the PR cannot merge.

See the v1.0.136 changelog entry for the full list of missing modules and remediation options.