@jlongo78/agent-spaces 0.9.7 → 0.9.9

package/.next/standalone/docs/superpowers/specs/2026-04-21-workspace-todos-design.md

@@ -0,0 +1,180 @@
+# Workspace Todos — Design
+
+**Status:** draft
+**Owner:** jlongo
+**Last updated:** 2026-04-21
+
+## Overview
+
+A lightweight todo list attached to each Spaces workspace so a user can jot down reminders without breaking flow. Lives inline at the top of the `/terminal` page, always visible, scoped to the active workspace. Minimal: text + checkbox + delete. No priorities, due dates, assignees, or agent integration in v1.
+
+**Explicitly not in scope (v1):**
+- Agent read/write via MCP or CLI
+- Drag-to-reorder
+- Cross-workspace views or global todos
+- Due dates, priorities, tags, notes
+- Sharing across users (single-user repo instance assumed)
+
+## User-facing behavior
+
+- Navigate to `/terminal`. A compact todo bar sits above the pane grid.
+- Empty state shows only the input: "Add todo…".
+- Type text, press Enter → todo is added to the bottom of the uncompleted list. Input stays focused for rapid capture.
+- Click a todo's checkbox → strike-through, row animates/sinks below all uncompleted items. Completed rows stack newest-first (most recently completed on top of the completed section).
+- Click a todo's text → inline edit. Enter saves. Esc cancels.
+- Click `×` → deletes the todo (no confirm for v1).
+- "Show completed" toggle (default on) — when off, completed rows hide but are retained in the DB.
+- Switching workspaces in the workspace chooser refetches the list.
+- If the list exceeds ~40% of viewport height, the internal list scrolls; the input stays pinned.
+
+No keyboard shortcut to focus the input in v1 (stretch: `Ctrl/Cmd+Shift+T`).
+
+## Architecture
+
+```
+/terminal page (src/app/(desktop)/terminal/page.tsx)
+  ├── <WorkspaceTodos workspaceId={activeWorkspaceId}/>   (new)
+  │     └── GET/POST/PATCH/DELETE /api/workspaces/:id/todos[…]
+  └── pane grid (existing)
+
+Server:
+  src/app/api/workspaces/[id]/todos/route.ts           (GET, POST)
+  src/app/api/workspaces/[id]/todos/[todoId]/route.ts  (PATCH, DELETE)
+
+DB (SQLite, per-user):
+  workspace_todos table  (schema migration appended to src/lib/db/schema.ts)
+  query helpers          (src/lib/db/queries.ts — new functions)
+```
+
+Data flow: component mounts → `GET` todos for active workspace → render. Mutations are optimistic (update local state immediately, then fire the request; on failure, revert and show a toast using whatever toast infra already exists, or `console.error` for v1 if none).
+
+## Key files
+
+| Path | Role |
+|---|---|
+| `src/lib/db/schema.ts` | Append `workspace_todos` table + index to `initSchema()` |
+| `src/lib/db/queries.ts` | New: `getWorkspaceTodos`, `addWorkspaceTodo`, `updateWorkspaceTodo`, `deleteWorkspaceTodo` |
+| `src/app/api/workspaces/[id]/todos/route.ts` | New: `GET`, `POST` handlers |
+| `src/app/api/workspaces/[id]/todos/[todoId]/route.ts` | New: `PATCH`, `DELETE` handlers |
+| `src/components/workspace/workspace-todos.tsx` | New: the inline UI component |
+| `src/app/(desktop)/terminal/page.tsx` | Mount `<WorkspaceTodos>` above the pane grid |
+| `src/types/` or inline in component | `Todo` TypeScript type |
+| `tests/db/workspace-todos.test.ts` | New: unit tests for query helpers |
+| `tests/api/workspace-todos.test.ts` | New: happy-path tests for each route |
+| `docs/features/workspace-todos.md` | New: feature doc per `FEATURE_DOC_GUIDE.md` |
+
+## Data model
+
+### Table: `workspace_todos`
+
+```sql
+CREATE TABLE IF NOT EXISTS workspace_todos (
+  id            INTEGER PRIMARY KEY AUTOINCREMENT,
+  workspace_id  INTEGER NOT NULL REFERENCES workspaces(id) ON DELETE CASCADE,
+  text          TEXT    NOT NULL,
+  completed     INTEGER NOT NULL DEFAULT 0,
+  sort_order    INTEGER NOT NULL DEFAULT 0,
+  created       TEXT    NOT NULL DEFAULT (datetime('now')),
+  completed_at  TEXT
+);
+CREATE INDEX IF NOT EXISTS idx_workspace_todos_workspace
+  ON workspace_todos(workspace_id);
+```
+
+Declared inside `initSchema()` in `src/lib/db/schema.ts` — same pattern as every other table in this file. No separate migration file.
+
+### TypeScript type
+
+```ts
+export interface Todo {
+  id: number;
+  workspaceId: number;
+  text: string;
+  completed: boolean;
+  sortOrder: number;
+  created: string;
+  completedAt: string | null;
+}
+```
+
+### Invariants
+
+- `sort_order` is only meaningful among uncompleted rows. When adding a todo, `sort_order = max(sort_order for uncompleted rows in this workspace) + 1`.
+- Listing order: `ORDER BY completed ASC, CASE WHEN completed = 0 THEN sort_order END ASC, completed_at DESC` — uncompleted first by sort_order, then completed newest-first.
+- `completed_at` is set to `datetime('now')` when `completed` flips 0→1, cleared to `NULL` on 1→0.
+- Workspace delete cascades and removes all associated todos (`ON DELETE CASCADE`).
+
+## APIs / contracts
+
+All routes live under `src/app/api/workspaces/[id]/todos/`. Auth piggybacks on whatever protects the rest of `/api/workspaces/*` — no new gate introduced.
+
+### `GET /api/workspaces/:id/todos`
+- **Returns:** `Todo[]` sorted per the invariant above.
+- **Errors:** `404` if workspace does not exist.
+
+### `POST /api/workspaces/:id/todos`
+- **Body:** `{ text: string }` — trimmed server-side; reject empty after trim with `400`.
+- **Returns:** the newly created `Todo`.
+- **Errors:** `400` empty text, `404` workspace not found.
+
+### `PATCH /api/workspaces/:id/todos/:todoId`
+- **Body:** `{ text?: string, completed?: boolean }` — at least one field required.
+- **Behavior:** if `completed` flips 0→1, server sets `completed_at = now()`; on 1→0, clears it. Text updates trim and reject empty.
+- **Returns:** the updated `Todo`.
+- **Errors:** `400` invalid body, `404` not found.
+
+### `DELETE /api/workspaces/:id/todos/:todoId`
+- **Returns:** `{ ok: true }`.
+- **Errors:** `404` not found.
+
+No bulk endpoints, no reorder endpoint in v1.
+
+## Configuration & environment
+
+None. No env vars, no feature flag, no tier gate — this is a Community-tier feature, always on.
+
+## How to run / test locally
+
+```bash
+# from repo root
+npm install
+npm run build
+npm start
+# visit http://localhost:3457/terminal
+```
+
+Manual QA checklist:
+1. Add 3 todos. Check order (newest at bottom of uncompleted).
+2. Check the middle one → it strikes through and sinks below the uncompleted pair.
+3. Toggle "show completed" off → the completed one hides.
+4. Toggle it back on, uncheck the completed one → it returns to uncompleted.
+5. Edit a todo's text via inline edit. Reload the page → change persisted.
+6. Delete a todo → gone.
+7. Switch workspaces in the workspace chooser → list swaps; original workspace's todos are still intact when you switch back.
+8. Delete a workspace that has todos → no orphan rows remain (verify via SQLite CLI: `SELECT * FROM workspace_todos WHERE workspace_id = <deleted_id>;`).
+
+Automated:
+```bash
+npm test -- tests/db/workspace-todos.test.ts
+npm test -- tests/api/workspace-todos.test.ts
+```
+
+## Known quirks & decisions
+
+- **No agent write access (v1).** A coworker's "pi /todos" plugin lets agents add todos from inside the session, which is genuinely powerful. Deferred because it requires a new MCP tool or CLI surface, and the user wants to ship the UI-only version first to validate the habit.
+- **Schema lives in `initSchema()`, not a migration file.** Matches the existing convention in `src/lib/db/schema.ts` — no separate migration files exist in this repo.
+- **No drag-to-reorder.** YAGNI. Adding at end is fine for short lists; revisit if users start making 20+ todo lists.
+- **No confirm on delete.** Matches the minimal ethos; if users delete the wrong one, they re-add. Add a 3-second undo toast in a follow-up if this proves painful.
+- **Optimistic updates without a toast library.** If the repo doesn't already have a toast system, v1 falls back to `console.error` on failure plus refetching state. This is acceptable for a local-only app.
+- **Ship to `main` directly, no PR.** Per user preference for this repo.
+
+## Open questions / TODOs
+
+- [ ] Confirm the active-workspace hook/context already exposes `workspaceId` to the terminal page, or whether `<WorkspaceTodos>` needs to fetch it itself. Check `src/components/workspace/workspace-chooser.tsx` during implementation.
+- [ ] Decide whether the "show completed" toggle state persists across reloads (localStorage) or is ephemeral. Default: ephemeral for v1.
+- [ ] Stretch: keyboard shortcut to focus the add-todo input from anywhere on the terminal page.
+- [ ] Stretch: agent write access via MCP tool once UI v1 proves out.
+
+## Changelog
+
+- 2026-04-21 — Initial design.

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

@@ -0,0 +1,183 @@
+# 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.

package/.next/standalone/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@jlongo78/agent-spaces",
-  "version": "0.9.7",
+  "version": "0.9.9",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@jlongo78/agent-spaces",
-      "version": "0.9.7",
+      "version": "0.9.9",
       "license": "AGPL-3.0-only",
       "dependencies": {
         "@dnd-kit/core": "^6.3.1",

package/.next/standalone/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jlongo78/agent-spaces",
-  "version": "0.9.7",
+  "version": "0.9.9",
   "description": "Agent workspace manager for Claude, Codex, Gemini, and more",
   "bin": {
     "spaces": "./bin/spaces.js"

package/.next/standalone/src/app/(desktop)/settings/page.tsx

@@ -2,7 +2,7 @@
 
 import { useState, useEffect, useRef } from 'react';
 import { useSync } from '@/hooks/use-sessions';
-import { Settings, RefreshCw, FolderOpen, Loader2, Shield, CheckCircle2, BarChart3, Plus, X, FolderCode } from 'lucide-react';
+import { Settings, RefreshCw, FolderOpen, Loader2, Shield, CheckCircle2, BarChart3, Plus, X, FolderCode, ListTodo } from 'lucide-react';
 import { api } from '@/lib/api';
 import { track, setOptOut } from '@/lib/telemetry';
 import { useTier } from '@/hooks/use-tier';
@@ -36,6 +36,9 @@ export default function SettingsPage() {
   const [telemetryOptOut, setTelemetryOptOut] = useState(false);
   const [telemetryLoading, setTelemetryLoading] = useState(true);
 
+  // Workspace todos toggle
+  const [todosEnabled, setTodosEnabled] = useState(false);
+
   useEffect(() => {
     if (!hasAuth) {
       setTotpLoading(false);
@@ -70,11 +73,22 @@ export default function SettingsPage() {
       .then(data => {
         setTelemetryOptOut(data.telemetryOptOut);
         setDevDirectories(data.devDirectories || []);
+        setTodosEnabled(!!data.todosEnabled);
         setTelemetryLoading(false);
       })
       .catch(() => setTelemetryLoading(false));
   }, []);
 
+  const handleTodosToggle = async () => {
+    const next = !todosEnabled;
+    setTodosEnabled(next);
+    await fetch(api('/api/config'), {
+      method: 'PUT',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ todosEnabled: next }),
+    });
+  };
+
   const saveDevDirectories = async (dirs: string[]) => {
     setDevDirectories(dirs);
     await fetch(api('/api/config'), {
@@ -391,6 +405,31 @@ export default function SettingsPage() {
           )}
         </div>
 
+        {/* Experimental features */}
+        <div className="bg-white dark:bg-zinc-900 border border-zinc-200 dark:border-zinc-800 rounded-lg p-5">
+          <h3 className="font-semibold flex items-center gap-2 mb-3">
+            <ListTodo className="w-4 h-4" />
+            Experimental
+          </h3>
+          <p className="text-sm text-muted-foreground mb-3">
+            Opt-in to features that are still being shaped.
+          </p>
+          <label className="flex items-start gap-3 cursor-pointer">
+            <input
+              type="checkbox"
+              checked={todosEnabled}
+              onChange={handleTodosToggle}
+              className="mt-0.5 w-4 h-4 rounded border-zinc-300 dark:border-zinc-700 text-indigo-500 focus:ring-indigo-500"
+            />
+            <div>
+              <div className="text-sm">Workspace todos</div>
+              <div className="text-xs text-muted-foreground mt-0.5">
+                Show a horizontal row of todo chips above the pane grid in each workspace.
+              </div>
+            </div>
+          </label>
+        </div>
+
         {/* Telemetry */}
         <div className="bg-white dark:bg-zinc-900 border border-zinc-200 dark:border-zinc-800 rounded-lg p-5">
           <h3 className="font-semibold flex items-center gap-2 mb-3">