feat(costs): cost analytics page (#557)

codeframe/persistence/repositories/token_repository.py

@@ -3,7 +3,7 @@
 Extracted from monolithic Database class for better maintainability.
 """
 
-from datetime import datetime
+from datetime import datetime, timedelta, timezone
 from typing import List, Optional, Dict, Any, TYPE_CHECKING
 import logging
 
@@ -274,6 +274,83 @@ def get_workspace_token_usage(
         cursor.execute(query, params)
         return [dict(row) for row in cursor.fetchall()]
 
+    def get_costs_summary(self, days: int) -> Dict[str, Any]:
+        """Aggregate token_usage costs into daily buckets for analytics.
+
+        Args:
+            days: Number of trailing days to include in the summary.
+
+        Returns:
+            Dictionary with keys:
+                total_spend_usd: float — sum of estimated_cost_usd in window
+                total_tasks: int — distinct task_id count (excludes NULL)
+                avg_cost_per_task: float — total_spend_usd / total_tasks (0 if no tasks)
+                daily: list of {"date": "YYYY-MM-DD", "cost_usd": float}
+                       — one entry per day in the window, oldest first,
+                         zero-filled for days with no spend.
+        """
+        if days <= 0:
+            raise ValueError("days must be a positive integer")
+
+        now_utc = datetime.now(timezone.utc)
+        # Inclusive window starting at midnight UTC, `days` calendar days back.
+        # Use a space-separated, offset-free format so lexicographic comparison
+        # works against both `CURRENT_TIMESTAMP` defaults ("YYYY-MM-DD HH:MM:SS")
+        # and Python `.isoformat()` outputs ("YYYY-MM-DDTHH:MM:SS+00:00").
+        end_date = now_utc.date()
+        start_date = end_date - timedelta(days=days - 1)
+        start_iso = start_date.strftime("%Y-%m-%d %H:%M:%S")
+        # Exclusive upper bound = midnight after today, so the daily chart and
+        # the KPI cards always cover the same set of rows even if some records
+        # are future-dated (clock skew, bad seed data).
+        end_iso = (end_date + timedelta(days=1)).strftime("%Y-%m-%d %H:%M:%S")
+
+        cursor = self.conn.cursor()
+
+        # Totals over the window. total_spend includes NULL-task records so it
+        # matches the chart; total_tasks only counts records linked to a task.
+        cursor.execute(
+            """
+            SELECT
+                COALESCE(SUM(estimated_cost_usd), 0.0) AS total_spend,
+                COUNT(DISTINCT CASE WHEN task_id IS NOT NULL THEN task_id END) AS task_count
+            FROM token_usage
+            WHERE timestamp >= ? AND timestamp < ?
+            """,
+            (start_iso, end_iso),
+        )
+        totals = cursor.fetchone()
+        total_spend = float(totals["total_spend"] or 0.0)
+        total_tasks = int(totals["task_count"] or 0)
+        avg_cost = (total_spend / total_tasks) if total_tasks > 0 else 0.0
+
+        # Daily aggregation — group by calendar date in UTC
+        cursor.execute(
+            """
+            SELECT
+                DATE(timestamp) AS day,
+                COALESCE(SUM(estimated_cost_usd), 0.0) AS cost
+            FROM token_usage
+            WHERE timestamp >= ? AND timestamp < ?
+            GROUP BY DATE(timestamp)
+            """,
+            (start_iso, end_iso),
+        )
+        by_day: Dict[str, float] = {row["day"]: float(row["cost"] or 0.0) for row in cursor.fetchall()}
+
+        daily: List[Dict[str, Any]] = []
+        for offset in range(days):
+            d = start_date + timedelta(days=offset)
+            iso = d.isoformat()
+            daily.append({"date": iso, "cost_usd": by_day.get(iso, 0.0)})
+
+        return {
+            "total_spend_usd": total_spend,
+            "total_tasks": total_tasks,
+            "avg_cost_per_task": avg_cost,
+            "daily": daily,
+        }
+
     def get_project_costs_aggregate(self, project_id: int) -> Dict[str, Any]:
         """Get aggregated cost statistics for a project.
 

codeframe/ui/routers/costs_v2.py

@@ -0,0 +1,130 @@
+"""Cost analytics API router for CodeFRAME v2 (issue #557).
+
+Aggregates the workspace's `token_usage` table into a daily-bucket summary
+for the /costs page in the web UI. Hosts a single endpoint:
+
+    GET /api/v2/costs/summary?days=30
+
+Returns an empty-state payload (all zeros, zero-filled daily series) when
+no spend data exists or the table isn't present — never 404.
+
+The handler opens the workspace SQLite database directly to avoid the
+pre-existing schema conflict between `codeframe/core/workspace.py` and
+`codeframe/persistence/schema_manager.py` — wiring `TokenRepository`
+to a raw connection skips `Database.initialize()` entirely.
+"""
+
+import logging
+import sqlite3
+from datetime import datetime, timedelta, timezone
+from typing import Dict, List
+
+from fastapi import APIRouter, Depends, Query, Request
+from pydantic import BaseModel
+
+from codeframe.core.workspace import Workspace
+from codeframe.lib.rate_limiter import rate_limit_standard
+from codeframe.persistence.repositories.token_repository import TokenRepository
+from codeframe.ui.dependencies import get_v2_workspace
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter(prefix="/api/v2/costs", tags=["metrics"])
+
+
+class DailyCostPoint(BaseModel):
+    """One day of aggregated spend."""
+
+    date: str  # ISO format YYYY-MM-DD
+    cost_usd: float
+
+
+class CostSummaryResponse(BaseModel):
+    """Aggregated spend over the requested window."""
+
+    total_spend_usd: float
+    total_tasks: int
+    avg_cost_per_task: float
+    daily: List[DailyCostPoint]
+
+
+def _empty_summary(days: int) -> Dict:
+    """Build a zero-state response with `days` daily buckets."""
+    end_date = datetime.now(timezone.utc).date()
+    start_date = end_date - timedelta(days=days - 1)
+    daily = [
+        {"date": (start_date + timedelta(days=i)).isoformat(), "cost_usd": 0.0}
+        for i in range(days)
+    ]
+    return {
+        "total_spend_usd": 0.0,
+        "total_tasks": 0,
+        "avg_cost_per_task": 0.0,
+        "daily": daily,
+    }
+
+
+def _query_costs(db_path: str, days: int) -> Dict:
+    """Query the workspace DB via TokenRepository on a raw connection.
+
+    Returns an empty summary if the DB can't be opened or the table is missing,
+    rather than raising — keeps the endpoint safe for fresh workspaces.
+
+    TODO(schema-conflict): we open the connection directly rather than through
+    `Database(...).initialize()` because the v2 workspace schema in
+    `codeframe/core/workspace.py` and the global schema in
+    `persistence/schema_manager.py` define `blockers` incompatibly, and
+    `Database.initialize()` therefore crashes on existing workspace DBs.
+    Remove this workaround once the two schemas converge.
+    """
+    try:
+        conn = sqlite3.connect(db_path)
+        conn.row_factory = sqlite3.Row
+    except sqlite3.Error as e:
+        logger.warning("costs: failed to open %s: %s", db_path, e)
+        return _empty_summary(days)
+
+    try:
+        try:
+            cursor = conn.cursor()
+            cursor.execute(
+                "SELECT name FROM sqlite_master WHERE type='table' AND name='token_usage'"
+            )
+            if cursor.fetchone() is None:
+                return _empty_summary(days)
+
+            repo = TokenRepository(sync_conn=conn)
+            return repo.get_costs_summary(days)
+        except sqlite3.Error as e:
+            # Locked DB, corrupted schema, etc. — fall back to empty state
+            # rather than 500'ing the dashboard.
+            logger.warning("costs: query failed on %s: %s", db_path, e)
+            return _empty_summary(days)
+    finally:
+        conn.close()
+
+
+@router.get("/summary", response_model=CostSummaryResponse)
+@rate_limit_standard()
+async def get_costs_summary(
+    request: Request,
+    workspace: Workspace = Depends(get_v2_workspace),
+    days: int = Query(30, ge=7, le=90, description="Window size in days (7-90)"),
+):
+    """Return total spend, task count, average cost, and a daily series.
+
+    Reads from the workspace's `token_usage` table. Returns zero-filled
+    daily buckets so the client can render a chart without conditionals.
+    If the table doesn't exist (no agent has run in this workspace yet),
+    returns an empty-state response rather than an error.
+    """
+    summary = _query_costs(str(workspace.db_path), days)
+    return CostSummaryResponse(
+        total_spend_usd=summary["total_spend_usd"],
+        total_tasks=summary["total_tasks"],
+        avg_cost_per_task=summary["avg_cost_per_task"],
+        daily=[
+            DailyCostPoint(date=d["date"], cost_usd=d["cost_usd"])
+            for d in summary["daily"]
+        ],
+    )

codeframe/ui/server.py

@@ -22,6 +22,7 @@
     batches_v2,
     blockers_v2,
     checkpoints_v2,
+    costs_v2,
     diagnose_v2,
     discovery_v2,
     environment_v2,
@@ -483,6 +484,7 @@ async def test_broadcast(message: dict, project_id: int = None):
 app.include_router(batches_v2.router)       # /api/v2/batches
 app.include_router(blockers_v2.router)      # /api/v2/blockers
 app.include_router(checkpoints_v2.router)   # /api/v2/checkpoints
+app.include_router(costs_v2.router)         # /api/v2/costs
 app.include_router(diagnose_v2.router)      # /api/v2/tasks/{id}/diagnose
 app.include_router(discovery_v2.router)     # /api/v2/discovery
 app.include_router(environment_v2.router)   # /api/v2/env