indifferentketchup
c935687725
Drop 9 batch proposals that are superseded by the boocode-lift-analysis (boocontext-audit, conductor upgrades, self-healing/verify-gate skills): add-3tier-memory, import-llm-evaluator, import-pregel-engine, plugin-platform, conductor-evolution, code-intelligence-upgrade, dev-workflow, ui-overhaul, agent-reliability. Delete 11 stub archive files (49-66B each, 'Status: Shipped. Archived.' only) that provide zero documentation value over the existing CHANGELOG.md + git tags.
71 lines
3.9 KiB
Markdown
71 lines
3.9 KiB
Markdown
## Context
|
|
|
|
BooCode already accumulates token/cost data across multiple backend paths:
|
|
|
|
- **opencode warm server**: `stepEndedToUsage()` normalizes per-step events → `agent_sessions.input_tokens/output_tokens/cost` (opencode-server.ts, opencode-usage.ts)
|
|
- **claude-sdk backend**: accumulates per-turn `input_tokens/output_tokens/cost` on `agent_sessions` (claude-sdk.ts)
|
|
- **Native inference**: `UsageFrame` WS frame carries `completion_tokens/ctx_used/ctx_max`; tasks persist `token_breakdown` JSONB (`{system,user,assistant,tools,reasoning,total}`) at terminal state
|
|
- **Tool cost stats**: `tool_cost_stats` DB view provides per-tool 100-call rolling window (`/api/tools/cost_stats`)
|
|
- **Arena contestants**: `token_breakdown` JSONB + `tokens_per_sec` + `cost_tokens` on contestant rows
|
|
|
|
The gap: no dedicated page to view any of this data in aggregate.
|
|
|
|
## Goals / Non-Goals
|
|
|
|
**Goals:**
|
|
- Add a nav button above Settings in the sidebar linking to `/analytics`
|
|
- Create a Token Analytics page at `/analytics` that displays:
|
|
- Aggregate usage summary cards (total tokens, cost, sessions)
|
|
- Per-session token/cost table (from `agent_sessions`)
|
|
- Per-tool cost breakdown (from `tool_cost_stats`)
|
|
- Per-category breakdown where `token_breakdown` exists
|
|
- Loading/error/empty states
|
|
- Reuse existing API endpoints where possible; add one new aggregate endpoint if needed
|
|
|
|
**Non-Goals:**
|
|
- Real-time streaming updates (page-level refresh on mount is fine)
|
|
- Export/download of analytics data
|
|
- Per-user or per-project filtering in v1 (global view only)
|
|
- Historical time-series charts (summary cards + tables are sufficient for v1)
|
|
- Arena token analytics (deferred — data exists but integration adds scope)
|
|
|
|
## Decisions
|
|
|
|
### D1 — New page route vs pane in existing workspace
|
|
|
|
**Decision:** New standalone page at `/analytics` (not a workspace pane).
|
|
|
|
**Rationale:** Token analytics is a global overview, not scoped to a specific chat/session. A workspace pane would only be accessible when a session is active. A standalone route works from anywhere. The Settings page already uses this pattern (`/settings`).
|
|
|
|
### D2 — API strategy
|
|
|
|
**Decision:** Reuse existing endpoints; add one new aggregate endpoint.
|
|
|
|
**Existing endpoints to use:**
|
|
- `GET /api/tools/cost_stats` — per-tool token stats
|
|
- `GET /api/coder/sessions/:id/agent-sessions` — per-session token data (fetched per session)
|
|
|
|
**Potential new endpoint (TBD during implementation):**
|
|
- `GET /api/coder/analytics/summary` — aggregate across all sessions (total input/output tokens, total cost, session count). If this adds too much backend scope, the frontend can aggregate from the existing session list endpoint instead.
|
|
|
|
### D3 — Styling
|
|
|
|
**Decision:** Match existing page patterns (`Settings` page layout: max-w container, card components, muted headers, shadcn table).
|
|
|
|
**Rationale:** Consistency. Every page in the app follows the same visual language (Tailwind v4 + shadcn nova). No new styling patterns needed.
|
|
|
|
### D4 — Visual token category breakdown
|
|
|
|
**Decision:** Simple CSS-only stacked bar for the `token_breakdown` category visualization (no chart library dependency).
|
|
|
|
**Rationale:** A stacked horizontal bar (system + user + assistant + tools + reasoning = total) can be done with CSS divs and `w-%` classes. Avoids adding a charting dependency for v1.
|
|
|
|
## Risks / Trade-offs
|
|
|
|
| Risk | Mitigation |
|
|
|------|------------|
|
|
| `agent_sessions` data is per-(chat,agent) — may be sparse if user doesn't use opencode/claude-sdk backends | Graceful: section shows empty state with explanation |
|
|
| Data freshness: the page fetches on mount, not on WebSocket push | Acceptable for v1 (analytics is a "check on things" page, not a dashboard) |
|
|
| Token count accuracy differs by backend (opencode reports model counts, analyzer estimates at chars/4) | Document the estimation methodology on the page |
|
|
| New page adds bundle size | Negligible — reuses existing shadcn components and API types |
|