@jlongo78/agent-spaces 0.10.0-beta.2 → 0.10.0-beta.4

package/.next/standalone/docs/superpowers/specs/2026-04-22-claude-usage-display-design.md

@@ -1,183 +0,0 @@
-# Claude Usage Display — Design
-
-**Status:** draft
-**Owner:** jlongo
-**Last updated:** 2026-04-22
-
-## Overview
-
-A compact global readout of Anthropic plan-usage rate limits (the same data Claude Code's `/usage` command shows), mounted in the terminal page header. Surfaces how much of the user's 5-hour and 7-day rate-limit windows has been consumed, so they can judge whether to launch another Claude pane or throttle back. Data is pulled from Anthropic's `/api/oauth/usage` endpoint using the OAuth access token that Claude Code has already stored on disk.
-
-**Explicitly not in scope (v1):**
-- OAuth token refresh (passive — if access token is expired, the widget shows a "sign in via Claude Code" hint).
-- Per-pane / per-session usage breakdown (the Anthropic endpoint is account-wide).
-- Historical usage graphs.
-- Non-Claude-AI auth modes (API keys, Bedrock, Vertex). If the user isn't a Claude.ai subscriber with a local OAuth token, the widget hides.
-
-## User-facing behavior
-
-- Enter any workspace on `/terminal`.
-- If at least one pane in the active workspace has `agentType === 'claude'`, a compact usage strip appears in the header, to the right of the workspace selector and pane-count text.
-- The strip shows three thin progress bars side-by-side:
-  - **5h** — 5-hour rolling window (all models).
-  - **Opus** — 7-day Opus window.
-  - **Sonnet** — 7-day Sonnet window.
-- Each bar fills left-to-right with a percent label. Color: green ≤ 70%, amber 70-90%, red > 90%.
-- Hover any bar → tooltip `Resets in 2h 14m`.
-- If `extra_usage.is_enabled` and `used_credits > 0`, a small `+$X overage` badge appears to the right.
-- Click the strip → a popover expands showing all five rate-limit windows (5h, 7d overall, 7d Opus, 7d Sonnet, 7d OAuth-apps) plus the full overage block. Layout mirrors Claude Code's `/usage` settings tab. Click outside to dismiss.
-- If the access token is missing or expired, the strip renders dimmed with a single label `sign in via Claude Code` and a subtle icon. No error toast.
-- If the Anthropic endpoint returns 4xx/5xx or times out, the strip hides silently (no noisy failure).
-
-## Architecture
-
-```
-UI (terminal page header)
-  └── <ClaudeUsageStrip />  (src/components/claude/claude-usage-strip.tsx)
-       └── useClaudeUsage()   (polls /api/claude/usage every 60s)
-             └── GET /api/claude/usage  (src/app/api/claude/usage/route.ts)
-                   ├── reads ~/.claude/.credentials.json (claudeAiOauth field)
-                   ├── checks expiresAt — returns 401 if expired
-                   ├── calls https://api.anthropic.com/api/oauth/usage
-                   │     with Bearer <accessToken>, User-Agent "claude-code/<ver>"
-                   └── caches 30s in-memory (keyed by accessToken prefix)
-```
-
-Data flow: every 60s the component calls the route; the route returns a cached `Utilization` object (30s TTL) or fetches fresh. Either way the component gets the same JSON shape and renders.
-
-## Key files
-
-| Path | Role |
-|---|---|
-| `src/lib/claude/credentials.ts` | New. Reads `~/.claude/.credentials.json` and extracts the `claudeAiOauth` tokens with an expiry check. |
-| `src/lib/claude/usage.ts` | New. Thin wrapper: given an access token, calls Anthropic's `/api/oauth/usage` and returns `Utilization`. In-memory 30s cache. |
-| `src/app/api/claude/usage/route.ts` | New. `GET` handler that wires credentials → usage → JSON response. Handles missing/expired token with structured error shapes. |
-| `src/types/claude.ts` | Modify. Add `Utilization`, `RateLimit`, `ExtraUsage`, `UsageResponse` types. |
-| `src/hooks/use-claude-usage.ts` | New. React hook — polls the route, exposes `{ data, error, loading }`. Skips polling when `enabled: false`. |
-| `src/components/claude/claude-usage-strip.tsx` | New. The compact 3-bar strip + expanded popover. |
-| `src/app/(desktop)/terminal/page.tsx` | Modify. Mount `<ClaudeUsageStrip />` in header; pass `hasClaudePane` flag so it only renders when relevant. |
-| `docs/features/claude-usage.md` | New. Feature doc. |
-
-## Data model
-
-No DB changes. All transient state; no persistence beyond the in-memory cache in the API route.
-
-### TypeScript types
-
-```ts
-// src/types/claude.ts (append)
-
-export interface RateLimit {
-  utilization: number | null;  // 0-100
-  resets_at: string | null;    // ISO 8601
-}
-
-export interface ExtraUsage {
-  is_enabled: boolean;
-  monthly_limit: number | null;
-  used_credits: number | null;
-  utilization: number | null;
-}
-
-export interface Utilization {
-  five_hour?: RateLimit | null;
-  seven_day?: RateLimit | null;
-  seven_day_oauth_apps?: RateLimit | null;
-  seven_day_opus?: RateLimit | null;
-  seven_day_sonnet?: RateLimit | null;
-  extra_usage?: ExtraUsage | null;
-}
-
-export type UsageResponse =
-  | { status: 'ok'; data: Utilization }
-  | { status: 'unauthenticated' }
-  | { status: 'expired' }
-  | { status: 'upstream_error' };
-```
-
-### Credentials file shape (read-only, owned by Claude Code)
-
-```json
-{
-  "claudeAiOauth": {
-    "accessToken": "...",
-    "refreshToken": "...",
-    "expiresAt": 1735678800000,
-    "scopes": ["..."]
-  }
-}
-```
-
-Path: `$CLAUDE_CONFIG_DIR/.credentials.json` where `CLAUDE_CONFIG_DIR` defaults to `~/.claude`. Mode 0600. Spaces reads it with `fs.readFile`; if the file is missing, unreadable, or malformed, treat as unauthenticated.
-
-## APIs / contracts
-
-### Internal endpoint: `GET /api/claude/usage`
-
-**Response shapes (all JSON, content-type `application/json`):**
-
-- `200` `{ status: "ok", data: Utilization }` — happy path.
-- `200` `{ status: "unauthenticated" }` — credentials file missing or no `claudeAiOauth` block. Not a 4xx because this is an expected state, not a client error.
-- `200` `{ status: "expired" }` — access token is past `expiresAt`.
-- `200` `{ status: "upstream_error" }` — Anthropic endpoint returned non-2xx or timed out.
-
-Auth: piggybacks on `withUser`/`getAuthUser` like every other `/api/*` route. No new gate.
-
-**Caching:** in-memory `Map<tokenPrefix, { fetchedAt, data }>`. Hit if `Date.now() - fetchedAt < 30_000`. `tokenPrefix` is the first 16 chars of `accessToken` (enough to distinguish, avoids holding full tokens in a non-secure cache). Cache is process-local; it resets on server restart.
-
-**Upstream call:**
-- Method: `GET`
-- URL: `https://api.anthropic.com/api/oauth/usage`
-- Headers: `Authorization: Bearer <accessToken>`, `Content-Type: application/json`, `User-Agent: claude-code/<version-from-package-json>` (Anthropic uses the UA to classify the client; mimicking Claude Code is intentional here since we're reading the same account data).
-- Timeout: 5 seconds via `AbortController`.
-
-### External call
-
-- **Anthropic `/api/oauth/usage`** — see above. No secret of our own; we use the user's own OAuth access token.
-
-## Configuration & environment
-
-- `CLAUDE_CONFIG_DIR` — respected (defaults to `~/.claude`). Same env var Claude Code uses.
-- No feature flag, no tier gate. Community-tier feature.
-- No changes to env-var requirements for Spaces.
-
-## How to run / test locally
-
-```bash
-npm install
-npm run build
-npm start
-# visit http://localhost:3457/terminal, enter a workspace, add a Claude pane
-```
-
-Manual QA:
-
-1. With a valid OAuth session (you can run Claude Code once to produce `.credentials.json`): open a workspace, add a Claude pane, verify the usage strip appears in the header. Percentages should match what `/usage` shows inside Claude Code.
-2. Hover each bar → tooltip shows `Resets in …` timing.
-3. Click the strip → popover expands with all windows + overage block.
-4. Delete the Claude pane (only shell panes left) → strip hides.
-5. Expired token simulation: edit `.credentials.json` to set `claudeAiOauth.expiresAt` to a past timestamp; reload — strip shows "sign in via Claude Code".
-6. Missing credentials: temporarily move `.credentials.json` aside; reload — strip hides (or shows sign-in hint per UI state).
-7. Offline simulation: disconnect network; within a minute the strip should silently hide (`upstream_error` state), then reappear when connectivity returns.
-
-Automated: none for v1. The behavior is I/O-heavy (file read + remote call) and doesn't benefit from unit tests; the repo convention is to skip route tests for this shape of work.
-
-## Known quirks & decisions
-
-- **Passive refresh.** We do not refresh the OAuth access token when it expires. Claude Code owns the refresh lifecycle and also writes to `.credentials.json`; duplicating that logic risks racing Claude Code over the same file. Users refresh by running any Claude Code command (or `/login`).
-- **User-Agent mimicry.** The Anthropic endpoint expects a Claude-Code-shaped UA. We send `claude-code/<ver>` where `<ver>` comes from a constant in `src/lib/claude/usage.ts` (bumped manually if upstream ever changes expectations). This is not a secret; it's classification data.
-- **Account-wide data, rendered once.** Even though the widget is UX-scoped to "when a Claude pane is present," the data is account-wide and identical across all panes. Rendering once in the header, not per-pane, is intentional honesty.
-- **30s server cache + 60s client poll.** Means the UI can be up to 90s stale at the outer bound; acceptable for rate-limit windows that move in hours.
-- **Token prefix as cache key.** Using a 16-char prefix of `accessToken` rather than a full hash because the user ID isn't handy in this path. Collisions are theoretically possible but effectively nil.
-- **Graceful degradation.** Every failure mode (missing file, expired token, bad JSON, upstream error, timeout) resolves to one of four structured `UsageResponse` statuses — the UI renders accordingly. No exceptions bubble to the user.
-- **Direct-to-main workflow.** Per repo convention.
-
-## Open questions / TODOs
-
-- [ ] Active refresh — mirror Claude Code's `/oauth/token` refresh dance to keep the widget live past access-token expiry. Deferred per v1 scope.
-- [ ] Per-model detail on hover (messages/tokens sent toward each window) — Anthropic doesn't currently expose this via `/api/oauth/usage`, would need a different endpoint.
-- [ ] Local-JSONL-based "session cost so far" complement — different data source, different feature. Could coexist.
-
-## Changelog
-
-- 2026-04-22 — Initial design.