chore(openspec): drop 9 superseded proposals + 11 stub archive files
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.
This commit is contained in:
2
openspec/changes/token-analyzer-ui/.openspec.yaml
Normal file
2
openspec/changes/token-analyzer-ui/.openspec.yaml
Normal file
@@ -0,0 +1,2 @@
|
||||
schema: spec-driven
|
||||
created: 2026-06-07
|
||||
3
openspec/changes/token-analyzer-ui/README.md
Normal file
3
openspec/changes/token-analyzer-ui/README.md
Normal file
@@ -0,0 +1,3 @@
|
||||
# token-analyzer-ui
|
||||
|
||||
Token analyzer dashboard UI with nav button
|
||||
70
openspec/changes/token-analyzer-ui/design.md
Normal file
70
openspec/changes/token-analyzer-ui/design.md
Normal file
@@ -0,0 +1,70 @@
|
||||
## 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 |
|
||||
26
openspec/changes/token-analyzer-ui/proposal.md
Normal file
26
openspec/changes/token-analyzer-ui/proposal.md
Normal file
@@ -0,0 +1,26 @@
|
||||
## Why
|
||||
|
||||
Token usage data is already accumulated per-session (agent_sessions.input_tokens/output_tokens/cost), per-tool (tool_cost_stats view), and per-task (tasks.token_breakdown JSONB), but there is no dedicated UI to view or analyze it. The only token surface today is the ContextMeter ring and the inline ChatThroughput readout — both per-chat, transient, and ephemeral. Users have no way to audit token consumption across sessions, compare provider costs, or understand where their context budget goes.
|
||||
|
||||
## What Changes
|
||||
|
||||
1. **Nav button**: Add a "Token Analytics" button to the sidebar nav, above the existing Settings button, linking to a new `/analytics` route.
|
||||
2. **Token Analytics page**: A new route/page at `/analytics` showing aggregate token usage across sessions, per-tool cost breakdown, and per-session token history.
|
||||
3. **API endpoints**: New or extended read endpoints to serve aggregate token data for the analytics page.
|
||||
|
||||
## Capabilities
|
||||
|
||||
### New Capabilities
|
||||
|
||||
- `token-analytics-dashboard`: Aggregate token usage dashboard page with per-session, per-tool, and per-provider breakdowns. Reuses existing `agent_sessions`, `tool_cost_stats`, and `token_breakdown` data sources.
|
||||
- `nav-button-token-analytics`: Sidebar nav button (above Settings) linking to the analytics route.
|
||||
|
||||
### Modified Capabilities
|
||||
|
||||
*(No existing capabilities have requirement changes — this is net-new.)*
|
||||
|
||||
## Impact
|
||||
|
||||
- **apps/web/src**: New page (`/opt/boocode/apps/web/src/pages/Analytics.tsx`), new route in App.tsx, new nav button in ProjectSidebar.tsx, new API client methods.
|
||||
- **apps/server or apps/coder**: Maybe a new aggregate endpoint if existing routes don't cover the required queries; otherwise reuse existing `/api/tools/cost_stats` and `/api/coder/sessions/:id/agent-sessions` endpoints.
|
||||
- **No schema changes** — all data is already persisted.
|
||||
@@ -0,0 +1,45 @@
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Nav button in sidebar
|
||||
|
||||
The sidebar (`ProjectSidebar.tsx`) SHALL include a "Token Analytics" button in the bottom-pinned section, positioned above the existing Settings button.
|
||||
|
||||
#### Scenario: Button renders above Settings
|
||||
|
||||
- **WHEN** the sidebar renders
|
||||
- **THEN** a "Token Analytics" button is visible in the bottom-pinned div
|
||||
- **AND** it is positioned above the "Settings" button
|
||||
|
||||
#### Scenario: Button navigates to /analytics
|
||||
|
||||
- **WHEN** the user clicks "Token Analytics"
|
||||
- **THEN** the app navigates to `/analytics`
|
||||
- **AND** the sidebar drawer closes on mobile
|
||||
|
||||
### Requirement: Button icon
|
||||
|
||||
The nav button SHALL use a visible icon alongside its label.
|
||||
|
||||
#### Scenario: Icon renders
|
||||
|
||||
- **WHEN** the sidebar renders
|
||||
- **THEN** the "Token Analytics" button displays an icon (use `BarChart3` or similar from lucide-react) and the label "Token Analytics"
|
||||
|
||||
### Requirement: Active route highlight
|
||||
|
||||
The nav button SHALL use the same active/hover styling as the Settings button.
|
||||
|
||||
#### Scenario: Active state
|
||||
|
||||
- **WHEN** the user is on the `/analytics` route
|
||||
- **THEN** the "Token Analytics" button has the same active background styling as other nav buttons
|
||||
|
||||
### Requirement: Mobile responsiveness
|
||||
|
||||
The nav button SHALL close the sidebar drawer on mobile after navigation, matching the Settings button behavior.
|
||||
|
||||
#### Scenario: Mobile navigation closes drawer
|
||||
|
||||
- **WHEN** the user is on mobile (sidebar is a slide-in drawer)
|
||||
- **AND** they click "Token Analytics"
|
||||
- **THEN** the sidebar drawer closes
|
||||
@@ -0,0 +1,73 @@
|
||||
## ADDED Requirements
|
||||
|
||||
### Requirement: Token analytics page route
|
||||
|
||||
The web app SHALL expose a route at `/analytics` that renders the token analytics dashboard.
|
||||
|
||||
#### Scenario: Route resolves to Analytics page
|
||||
|
||||
- **WHEN** the user navigates to `/analytics`
|
||||
- **THEN** the `Analytics` component renders without crashing
|
||||
- **AND** the sidebar nav button for "Token Analytics" shows as active
|
||||
|
||||
### Requirement: Aggregate usage summary
|
||||
|
||||
The dashboard SHALL display an aggregate summary of token usage across all data sources.
|
||||
|
||||
#### Scenario: Summary cards show totals
|
||||
|
||||
- **WHEN** the analytics page loads
|
||||
- **THEN** the page displays summary cards for: total input tokens, total output tokens, total cost (USD), and total sessions tracked
|
||||
- **AND** each card shows a numeric value with a short label
|
||||
|
||||
### Requirement: Per-session token breakdown
|
||||
|
||||
The dashboard SHALL display a list or table of recent sessions with per-session token and cost data.
|
||||
|
||||
#### Scenario: Session list renders
|
||||
|
||||
- **WHEN** `GET /api/coder/sessions/:id/agent-sessions` returns data
|
||||
- **THEN** the page renders a table with columns: session name, agent/provider, input tokens, output tokens, cost, last active
|
||||
|
||||
### Requirement: Per-tool cost breakdown
|
||||
|
||||
The dashboard SHALL display per-tool token consumption stats.
|
||||
|
||||
#### Scenario: Tool stats table renders
|
||||
|
||||
- **WHEN** the analytics page loads
|
||||
- **THEN** it fetches and renders the per-tool cost stats from `/api/tools/cost_stats`
|
||||
- **AND** displays: tool name, call count, avg prompt tokens, avg completion tokens, total avg tokens
|
||||
|
||||
### Requirement: Context window utilization
|
||||
|
||||
The dashboard SHALL display context window utilization data across sessions where available.
|
||||
|
||||
#### Scenario: Context usage section renders
|
||||
|
||||
- **WHEN** session message data with `ctx_used`/`ctx_max` fields is available
|
||||
- **THEN** a section shows average context utilization percentage across sessions
|
||||
|
||||
### Requirement: Token breakdown by category
|
||||
|
||||
The dashboard SHALL display token breakdown by category (system/user/assistant/tools/reasoning) where `token_breakdown` JSONB data exists.
|
||||
|
||||
#### Scenario: Category breakdown renders
|
||||
|
||||
- **WHEN** a session has `token_breakdown` data on its tasks
|
||||
- **THEN** the dashboard shows per-category token counts and a visual breakdown (e.g., stacked bar or pie segment)
|
||||
|
||||
### Requirement: Loading and error states
|
||||
|
||||
The dashboard SHALL handle loading and error states gracefully.
|
||||
|
||||
#### Scenario: Loading state
|
||||
|
||||
- **WHEN** data is being fetched
|
||||
- **THEN** a loading indicator is shown in each section
|
||||
|
||||
#### Scenario: Error state
|
||||
|
||||
- **WHEN** an API call fails
|
||||
- **THEN** the affected section shows an error message and a retry button
|
||||
- **AND** other sections continue to render independently
|
||||
32
openspec/changes/token-analyzer-ui/tasks.md
Normal file
32
openspec/changes/token-analyzer-ui/tasks.md
Normal file
@@ -0,0 +1,32 @@
|
||||
## 1. Nav Button
|
||||
|
||||
- [ ] 1.1 Add "Token Analytics" button in `apps/web/src/components/ProjectSidebar.tsx` above the Settings button, using `BarChart3` icon from lucide-react, linking to `/analytics`
|
||||
- [ ] 1.2 Add active route background styling matching the Settings button pattern
|
||||
- [ ] 1.2 On mobile, close the sidebar drawer after navigation (same as Settings button behavior)
|
||||
|
||||
## 2. API Layer
|
||||
|
||||
- [ ] 2.1 Verify existing `GET /api/tools/cost_stats` endpoint returns adequate data for the per-tool breakdown section
|
||||
- [ ] 2.2 Verify `GET /api/coder/sessions/:id/agent-sessions` returns `input_tokens`/`output_tokens`/`cost` fields
|
||||
- [ ] 2.3 Add `GET /api/coder/analytics/summary` endpoint returning aggregate totals (total_input, total_output, total_cost, session_count) OR plan to aggregate on the client side from session list data
|
||||
- [ ] 2.4 Add new API client methods in `apps/web/src/api/client.ts` for any new endpoints
|
||||
|
||||
## 3. Token Analytics Page
|
||||
|
||||
- [ ] 3.1 Create `apps/web/src/pages/Analytics.tsx` with summary cards section (total input/output tokens, total cost, sessions tracked) fetching from API
|
||||
- [ ] 3.2 Add per-session token breakdown table reusing `AgentSessionInfo` type, with columns: session, agent, input tokens, output tokens, cost
|
||||
- [ ] 3.3 Add per-tool cost breakdown table section reusing `ToolCostStat` type from `/api/tools/cost_stats`
|
||||
- [ ] 3.4 Add token category breakdown section using CSS stacked bar for `token_breakdown` data where available
|
||||
- [ ] 3.5 Add loading skeleton states and error handling with retry for each section independently
|
||||
- [ ] 3.6 Add empty states for each section when data is not available
|
||||
|
||||
## 4. Routing
|
||||
|
||||
- [ ] 4.1 Register the `/analytics` route in `apps/web/src/App.tsx`
|
||||
- [ ] 4.2 Verify navigation works from sidebar button and direct URL access
|
||||
|
||||
## 5. Verify
|
||||
|
||||
- [ ] 5.1 `pnpm typecheck` passes
|
||||
- [ ] 5.2 `pnpm -F web build` passes
|
||||
- [ ] 5.3 Visual: nav button renders correctly above Settings, analytics page loads with data, all sections handle loading/empty states
|
||||
Reference in New Issue
Block a user