[Phase 5.2] Cost analytics: per-task and per-agent breakdowns + task board cost badge

[frankbria]

Goal

Extend the Costs page with detailed breakdowns, and add a cost badge to task board cards.

Background

Follows the summary page (#557). Users need to know which tasks are expensive and which agents drive cost.

Scope

Costs page additions (within /costs):

• Top 10 most expensive tasks table: task title, agent type, input tokens, output tokens, cost — link to task detail
• Cost by agent type breakdown: bar or pie chart comparing Claude Code vs Codex vs OpenCode vs ReAct
• Input vs output token split per period (stacked bar or summary row)
• Backend: GET /api/v2/costs/tasks?days=30 and GET /api/v2/costs/by-agent?days=30

Task board (/tasks):

• Add a small cost badge to each task card (e.g., $0.12) if cost data exists for that task
• Tooltip on hover showing token breakdown
• Zero cost or no data = badge hidden (not shown as $0.00)

Acceptance criteria

• Top-10 table renders with correct data
• Agent breakdown chart renders
• Task cards show cost badge where data exists
• npm test and npm run build pass

[coderabbitai]

🔗 Related PRs

#51 - feat: Add TaskStats component to Dashboard Overview tab [merged]
#169 - feat(dashboard): Add dedicated tabs for Tasks, Quality Gates, and Metrics [merged]
#213 - feat(planning): Add Generate Task Breakdown button to DiscoveryProgress [merged]
#215 - feat(dashboard): Add phase-aware task view integration (#016-6) [merged]
#234 - fix(ui): make TaskStats phase-aware to fix late-joining user bug [merged]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[traycerai]

Warning

Ticket Assist will be discontinued on May 1, 2026. After that date, the feature will no longer be available. We suggest installing the Traycer IDE Extension for continued AI-powered, spec-driven development. Thank you for choosing Traycer!

Plan

Observations

• The v2 backend uses workspace_path as a query param (via get_v2_workspace dependency), not project_id. The existing metrics.py router uses the legacy project_id pattern and is not registered in server.py — only v2 routers are mounted.
• TokenRepository already has get_task_token_summary, get_workspace_token_usage, and get_batch_token_usage. MetricsTracker has get_workspace_costs and get_task_token_summary. These are the building blocks for the new endpoints.
• The frontend uses swr + axios via file:web-ui/src/lib/api.ts, Tailwind CSS, @radix-ui/react-tooltip, and class-variance-authority. No charting library is installed — recharts, chart.js, etc. are absent from package.json.
• There is no existing /costs page in web-ui/src/app/.

Approach

Add two new v2 backend endpoints in a new costs_v2.py router, register it in server.py, extend the frontend API client, create the /costs page with a top-10 tasks table and an agent-type breakdown rendered as a pure CSS/Tailwind bar chart (no external charting library needed), and add a cost badge to TaskCard.

---

Implementation Steps

1. Backend — New costs_v2.py Router

Create file:codeframe/ui/routers/costs_v2.py following the exact pattern of file:codeframe/ui/routers/tasks_v2.py:

• Router prefix: /api/v2/costs, tag costs-v2
• Use get_v2_workspace dependency (same as all other v2 routers) to resolve the workspace from workspace_path query param.
• Both endpoints accept an optional days: int = Query(30, ge=1, le=365) parameter to compute a start_date cutoff (datetime.now(UTC) - timedelta(days=days)).

Endpoint 1 — GET /api/v2/costs/tasks

Query the workspace's token usage via MetricsTracker.get_workspace_costs() (already exists) but you need per-task granularity. Add a new method get_top_tasks_by_cost to file:codeframe/lib/metrics_tracker.py that:

• Calls db.get_workspace_token_usage(start_date, end_date) (already exists in TokenRepository)
• Groups records by task_id, summing input_tokens, output_tokens, estimated_cost_usd
• Joins with task titles by reading the workspace's task store (use codeframe.core.tasks.get(workspace, task_id) for each unique task_id)
• Returns the top 10 sorted by total_cost_usd descending

Response shape:

{
  "tasks": [
    {
      "task_id": str,
      "task_title": str,
      "agent_id": str,          // most-used agent for this task
      "input_tokens": int,
      "output_tokens": int,
      "total_cost_usd": float
    },
    ...  // up to 10 items
  ]
}

Endpoint 2 — GET /api/v2/costs/by-agent

Add a new method get_costs_by_agent_type to MetricsTracker that:

• Calls db.get_workspace_token_usage(start_date, end_date)
• Groups by agent_id, summing tokens and cost
• Returns a list sorted by cost descending

Response shape:

{
  "by_agent": [
    {
      "agent_id": str,
      "input_tokens": int,
      "output_tokens": int,
      "total_cost_usd": float,
      "call_count": int
    },
    ...
  ],
  "total_input_tokens": int,
  "total_output_tokens": int
}

Both endpoints should use @rate_limit_standard() and return HTTPException(500) on failure, consistent with other v2 routers.

---

2. Register the New Router in server.py

In file:codeframe/ui/server.py:

• Import costs_v2 alongside the other v2 routers in the import block
• Add app.include_router(costs_v2.router) with a comment # /api/v2/costs

---

3. Frontend — TypeScript Types

In file:web-ui/src/types/index.ts, add:

• TaskCostEntry — mirrors the tasks endpoint response item (task_id, task_title, agent_id, input_tokens, output_tokens, total_cost_usd)
• TaskCostsResponse — { tasks: TaskCostEntry[] }
• AgentCostEntry — (agent_id, input_tokens, output_tokens, total_cost_usd, call_count)
• AgentCostsResponse — { by_agent: AgentCostEntry[], total_input_tokens: number, total_output_tokens: number }

---

4. Frontend — API Client

In file:web-ui/src/lib/api.ts, add a costsApi object following the same pattern as tasksApi:

• costsApi.getTopTasks(workspacePath, days?) → GET /api/v2/costs/tasks
• costsApi.getByAgent(workspacePath, days?) → GET /api/v2/costs/by-agent

Both pass workspace_path and days as query params.

---

5. Frontend — /costs Page

Create file:web-ui/src/app/costs/page.tsx following the same workspace-guard pattern as file:web-ui/src/app/tasks/page.tsx (read workspacePath from getSelectedWorkspacePath() in a useEffect, show a "no workspace" fallback).

Create file:web-ui/src/components/costs/CostsView.tsx as the main component (analogous to TaskBoardView). It receives workspacePath as a prop and:

• Uses two useSWR calls: one for costsApi.getTopTasks and one for costsApi.getByAgent
• Renders a days selector (30 / 7 / 90) that updates both SWR keys

Top-10 Tasks Table — a <table> with Tailwind classes (consistent with the rest of the UI):

Task	Agent	Input Tokens	Output Tokens	Cost
Link to /tasks filtered by task ID	agent_id	formatted number	formatted number	$X.XXXXXX

Agent Breakdown — since no charting library is available, render a pure CSS horizontal bar chart using Tailwind:

• For each agent, show a label, a <div> bar whose width is set as an inline style percentage of the max cost, and a cost label
• This is a simple, dependency-free approach consistent with the existing stack

Input vs Output Token Split — a summary row below the agent chart showing total input tokens vs output tokens for the period (from the AgentCostsResponse totals).

---

6. Frontend — Task Card Cost Badge

Data flow: TaskBoardView already fetches all tasks via SWR. Add a second SWR call in TaskBoardView for costsApi.getTopTasks(workspacePath) to get a cost map. Build a Map<string, TaskCostEntry> keyed by task_id and pass it down through TaskBoardContent → TaskColumn → TaskCard as an optional costMap?: Map<string, TaskCostEntry> prop (same pattern as the existing requirementsMap).

In TaskCard: After the requirement badges section, conditionally render a cost badge when costMap?.get(task.id) exists and total_cost_usd > 0:

[cost icon]  $0.12  ← Badge with outline variant

Wrap it in a Tooltip (already imported) showing:

• Input tokens: X
• Output tokens: Y
• Total: $Z

Use the existing Badge component with variant="outline" and a small className override for sizing (matching the requirement badge style at h-5 px-1.5 text-[10px]).

Props chain changes (all optional, no breaking changes):

• TaskBoardView → add costMap state from SWR
• TaskBoardContent → add costMap?: Map<string, TaskCostEntry> to TaskBoardContentProps, pass through
• TaskColumn → add costMap? to its props, pass to each TaskCard
• TaskCard → add costMap? to TaskCardProps, render badge

---

7. Data Flow Diagram

sequenceDiagram
    participant UI as CostsView / TaskCard
    participant API as api.ts (costsApi)
    participant BE as costs_v2.py
    participant MT as MetricsTracker
    participant DB as TokenRepository

    UI->>API: costsApi.getTopTasks(workspacePath, days)
    API->>BE: GET /api/v2/costs/tasks?workspace_path=...&days=30
    BE->>MT: get_top_tasks_by_cost(workspace, start_date)
    MT->>DB: get_workspace_token_usage(start_date)
    DB-->>MT: raw records
    MT-->>BE: top 10 tasks aggregated
    BE-->>API: TaskCostsResponse
    API-->>UI: renders table + badge map

    UI->>API: costsApi.getByAgent(workspacePath, days)
    API->>BE: GET /api/v2/costs/by-agent?workspace_path=...&days=30
    BE->>MT: get_costs_by_agent_type(workspace, start_date)
    MT->>DB: get_workspace_token_usage(start_date)
    DB-->>MT: raw records
    MT-->>BE: AgentCostsResponse
    BE-->>API: AgentCostsResponse
    API-->>UI: renders bar chart + token split

Loading

Import In IDE

🤖 Prompt for AI Agents

## Observations

- The v2 backend uses `workspace_path` as a query param (via `get_v2_workspace` dependency), not `project_id`. The existing `metrics.py` router uses the legacy `project_id` pattern and is **not** registered in `server.py` — only v2 routers are mounted.
- `TokenRepository` already has `get_task_token_summary`, `get_workspace_token_usage`, and `get_batch_token_usage`. `MetricsTracker` has `get_workspace_costs` and `get_task_token_summary`. These are the building blocks for the new endpoints.
- The frontend uses `swr` + `axios` via `file:web-ui/src/lib/api.ts`, Tailwind CSS, `@radix-ui/react-tooltip`, and `class-variance-authority`. **No charting library is installed** — recharts, chart.js, etc. are absent from `package.json`.
- There is no existing `/costs` page in `web-ui/src/app/`.

## Approach

Add two new v2 backend endpoints in a new `costs_v2.py` router, register it in `server.py`, extend the frontend API client, create the `/costs` page with a top-10 tasks table and an agent-type breakdown rendered as a pure CSS/Tailwind bar chart (no external charting library needed), and add a cost badge to `TaskCard`.

---

## Implementation Steps

### 1. Backend — New `costs_v2.py` Router

Create `file:codeframe/ui/routers/costs_v2.py` following the exact pattern of `file:codeframe/ui/routers/tasks_v2.py`:

- **Router prefix**: `/api/v2/costs`, tag `costs-v2`
- Use `get_v2_workspace` dependency (same as all other v2 routers) to resolve the workspace from `workspace_path` query param.
- Both endpoints accept an optional `days: int = Query(30, ge=1, le=365)` parameter to compute a `start_date` cutoff (`datetime.now(UTC) - timedelta(days=days)`).

**Endpoint 1 — `GET /api/v2/costs/tasks`**

Query the workspace's token usage via `MetricsTracker.get_workspace_costs()` (already exists) but you need per-task granularity. Add a new method `get_top_tasks_by_cost` to `file:codeframe/lib/metrics_tracker.py` that:
- Calls `db.get_workspace_token_usage(start_date, end_date)` (already exists in `TokenRepository`)
- Groups records by `task_id`, summing `input_tokens`, `output_tokens`, `estimated_cost_usd`
- Joins with task titles by reading the workspace's task store (use `codeframe.core.tasks.get(workspace, task_id)` for each unique `task_id`)
- Returns the top 10 sorted by `total_cost_usd` descending

Response shape:
```
{
  "tasks": [
    {
      "task_id": str,
      "task_title": str,
      "agent_id": str,          // most-used agent for this task
      "input_tokens": int,
      "output_tokens": int,
      "total_cost_usd": float
    },
    ...  // up to 10 items
  ]
}
```

**Endpoint 2 — `GET /api/v2/costs/by-agent`**

Add a new method `get_costs_by_agent_type` to `MetricsTracker` that:
- Calls `db.get_workspace_token_usage(start_date, end_date)`
- Groups by `agent_id`, summing tokens and cost
- Returns a list sorted by cost descending

Response shape:
```
{
  "by_agent": [
    {
      "agent_id": str,
      "input_tokens": int,
      "output_tokens": int,
      "total_cost_usd": float,
      "call_count": int
    },
    ...
  ],
  "total_input_tokens": int,
  "total_output_tokens": int
}
```

Both endpoints should use `@rate_limit_standard()` and return `HTTPException(500)` on failure, consistent with other v2 routers.

---

### 2. Register the New Router in `server.py`

In `file:codeframe/ui/server.py`:
- Import `costs_v2` alongside the other v2 routers in the import block
- Add `app.include_router(costs_v2.router)` with a comment `# /api/v2/costs`

---

### 3. Frontend — TypeScript Types

In `file:web-ui/src/types/index.ts`, add:

- `TaskCostEntry` — mirrors the tasks endpoint response item (`task_id`, `task_title`, `agent_id`, `input_tokens`, `output_tokens`, `total_cost_usd`)
- `TaskCostsResponse` — `{ tasks: TaskCostEntry[] }`
- `AgentCostEntry` — (`agent_id`, `input_tokens`, `output_tokens`, `total_cost_usd`, `call_count`)
- `AgentCostsResponse` — `{ by_agent: AgentCostEntry[], total_input_tokens: number, total_output_tokens: number }`

---

### 4. Frontend — API Client

In `file:web-ui/src/lib/api.ts`, add a `costsApi` object following the same pattern as `tasksApi`:

- `costsApi.getTopTasks(workspacePath, days?)` → `GET /api/v2/costs/tasks`
- `costsApi.getByAgent(workspacePath, days?)` → `GET /api/v2/costs/by-agent`

Both pass `workspace_path` and `days` as query params.

---

### 5. Frontend — `/costs` Page

Create `file:web-ui/src/app/costs/page.tsx` following the same workspace-guard pattern as `file:web-ui/src/app/tasks/page.tsx` (read `workspacePath` from `getSelectedWorkspacePath()` in a `useEffect`, show a "no workspace" fallback).

Create `file:web-ui/src/components/costs/CostsView.tsx` as the main component (analogous to `TaskBoardView`). It receives `workspacePath` as a prop and:

- Uses two `useSWR` calls: one for `costsApi.getTopTasks` and one for `costsApi.getByAgent`
- Renders a `days` selector (30 / 7 / 90) that updates both SWR keys

**Top-10 Tasks Table** — a `<table>` with Tailwind classes (consistent with the rest of the UI):

| Task | Agent | Input Tokens | Output Tokens | Cost |
|------|-------|-------------|--------------|------|
| Link to `/tasks` filtered by task ID | agent_id | formatted number | formatted number | `$X.XXXXXX` |

**Agent Breakdown** — since no charting library is available, render a pure CSS horizontal bar chart using Tailwind:
- For each agent, show a label, a `<div>` bar whose `width` is set as an inline style percentage of the max cost, and a cost label
- This is a simple, dependency-free approach consistent with the existing stack

**Input vs Output Token Split** — a summary row below the agent chart showing total input tokens vs output tokens for the period (from the `AgentCostsResponse` totals).

---

### 6. Frontend — Task Card Cost Badge

**Data flow**: `TaskBoardView` already fetches all tasks via SWR. Add a second SWR call in `TaskBoardView` for `costsApi.getTopTasks(workspacePath)` to get a cost map. Build a `Map<string, TaskCostEntry>` keyed by `task_id` and pass it down through `TaskBoardContent` → `TaskColumn` → `TaskCard` as an optional `costMap?: Map<string, TaskCostEntry>` prop (same pattern as the existing `requirementsMap`).

**In `TaskCard`**: After the requirement badges section, conditionally render a cost badge when `costMap?.get(task.id)` exists and `total_cost_usd > 0`:

```
[cost icon]  $0.12  ← Badge with outline variant
```

Wrap it in a `Tooltip` (already imported) showing:
- Input tokens: X
- Output tokens: Y
- Total: $Z

Use the existing `Badge` component with `variant="outline"` and a small `className` override for sizing (matching the requirement badge style at `h-5 px-1.5 text-[10px]`).

**Props chain changes** (all optional, no breaking changes):
- `TaskBoardView` → add `costMap` state from SWR
- `TaskBoardContent` → add `costMap?: Map<string, TaskCostEntry>` to `TaskBoardContentProps`, pass through
- `TaskColumn` → add `costMap?` to its props, pass to each `TaskCard`
- `TaskCard` → add `costMap?` to `TaskCardProps`, render badge

---

### 7. Data Flow Diagram

```mermaid
sequenceDiagram
    participant UI as CostsView / TaskCard
    participant API as api.ts (costsApi)
    participant BE as costs_v2.py
    participant MT as MetricsTracker
    participant DB as TokenRepository

    UI->>API: costsApi.getTopTasks(workspacePath, days)
    API->>BE: GET /api/v2/costs/tasks?workspace_path=...&days=30
    BE->>MT: get_top_tasks_by_cost(workspace, start_date)
    MT->>DB: get_workspace_token_usage(start_date)
    DB-->>MT: raw records
    MT-->>BE: top 10 tasks aggregated
    BE-->>API: TaskCostsResponse
    API-->>UI: renders table + badge map

    UI->>API: costsApi.getByAgent(workspacePath, days)
    API->>BE: GET /api/v2/costs/by-agent?workspace_path=...&days=30
    BE->>MT: get_costs_by_agent_type(workspace, start_date)
    MT->>DB: get_workspace_token_usage(start_date)
    DB-->>MT: raw records
    MT-->>BE: AgentCostsResponse
    BE-->>API: AgentCostsResponse
    API-->>UI: renders bar chart + token split
```

---

Execution Information

Branch: main
Commit: 3f14270

---

💡 Tips

Supported Commands (Inside Comments)

• Use @traycerai generate to iterate on the previous version of the implementation plan.

Supported Commands (Inside Description)

• Add @traycerai ignore anywhere in the ticket description to prevent this ticket from being processed.
• Add @traycerai branch:<branch-name> anywhere in the ticket description to specify the target branch for the implementation plan.

Community

• Join our Discord Community to get help, request features, and share feedback.
• Follow us on X/Twitter for updates and announcements.