rdc 0.1.0__tar.gz

rdc-0.1.0/.ai/browser-context-design.md

@@ -0,0 +1,58 @@
+# Browser Context & Preview System
+
+## Overview
+
+RDC provides shared browser sessions between the developer and AI agents, with context capture (screenshot + accessibility tree) for feeding visual information to agents.
+
+## Architecture
+
+```
+Dashboard (iframe viewer)
+    ↓ session_id
+RDC Server (FastAPI)
+    ├── BrowserManager (browser.py)
+    │     ├── create_session(target_url)
+    │     ├── capture_context(session_id)
+    │     └── stop_session(session_id)
+    ↓ CDP (WebSocket)
+Browserless Docker Container
+    (ghcr.io/browserless/chromium)
+```
+
+## Components
+
+### Browser Sessions
+- Browserless Docker containers with headless Chromium
+- CDP (Chrome DevTools Protocol) for programmatic access
+- Live viewer embeddable in dashboard iframe
+- Session state persisted in SQLite (`browser_sessions` table)
+
+### Context Capture
+- Screenshot + accessibility tree + page metadata
+- Stored in `~/.rdc/contexts/`
+- Attachable to tasks for agent consumption
+- API: `POST /context/capture`, `GET /context`, `GET /context/{id}/screenshot`
+
+### rrweb Session Recording
+- Records DOM mutations for session replay
+- CDP binding for low-latency event push
+- Periodic buffer drain as fallback
+- Chunked JSON storage in `~/.rdc/recordings/{rec_id}/chunk_{n}.json`
+
+### PinchTab Integration
+- Connect to existing browser tabs (no Docker needed)
+- Uses PinchTab browser extension for CDP access
+- Same context capture capabilities
+
+## Dashboard Integration
+
+- **Browser tab**: Start/stop sessions, view in iframe, capture context
+- **Attachments tab**: Browse captured contexts, share with agents
+- **PinchTab tab**: Connect to existing browser tabs
+
+## MCP Tools
+
+Agents can capture and read browser context via MCP:
+- `capture_browser_context` — screenshot + a11y tree
+- `get_browser_context` — read previously captured context
+- `browser_eval` — evaluate JavaScript in the browser

rdc-0.1.0/.ai/context.md

@@ -0,0 +1,123 @@
+# RDC (Remote Dev Ctrl) - Development Context
+
+Last Updated: 2026-03-12
+
+## Project Overview
+
+RDC is a command center for AI-assisted development. FastAPI server + React dashboard + CLI for managing projects, terminals, tasks, processes, and AI agents.
+
+- **Web dashboard**: `http://127.0.0.1:8420` (three layouts: desktop, mobile, kiosk)
+- **CLI**: `rdc` (Typer-based)
+- **Remote access**: Cloudflare Tunnel + Caddy reverse proxy
+
+## Architecture
+
+### Backend (`src/remote_dev_ctrl/server/`)
+
+| File | Purpose |
+|------|---------|
+| `app.py` | FastAPI routes, WebSocket handlers, API endpoints |
+| `config.py` | Config loading, RDC_HOME resolution |
+| `terminal.py` | PTY management (`socat`-based), WebSocket relay |
+| `worker.py` | Task execution engine (polls DB, spawns agents) |
+| `intent.py` | AI orchestrator (natural language → dashboard actions) |
+| `streaming.py` | SSE/streaming endpoints |
+| `knowledge.py` | Bridge between DB projects and knowledge indexer |
+| `middleware.py` | Auth middleware, rate limiting, public path config |
+| `browser.py` | Browserless container management, CDP context capture |
+| `agents/manager.py` | Agent provider abstraction |
+| `db/connection.py` | SQLite connection pool |
+| `db/repositories.py` | SQLite repositories (Project, Task, Event, etc.) |
+| `db/models.py` | Pydantic models for all DB tables |
+| `db/migrate.py` | SQL migration runner (auto-runs on startup) |
+
+### Frontend (`frontend/src/`)
+
+| Directory | Purpose |
+|-----------|---------|
+| `layouts/` | `desktop.tsx`, `mobile.tsx`, `kiosk.tsx` — all first-class |
+| `features/` | Feature modules (terminal, tasks, chat, browser, wiki, mobile) |
+| `stores/` | Zustand state (state-store, ui-store, terminal-store, etc.) |
+| `hooks/` | Shared hooks (use-orchestrator, use-voice) |
+| `components/` | Shared UI components |
+| `lib/` | API client, WebSocket manager, utilities |
+
+### Key Subsystems
+
+1. **Terminal System** (`terminal.py`)
+   - PTY relay via `socat` subprocesses — survive server restarts
+   - Session metadata in `~/.rdc/terminal_sessions.json`
+   - WebSocket relay at `/terminals/{id}/ws`
+   - MCP approval detection for cursor-agent
+
+2. **Task/Worker System** (`worker.py`)
+   - API creates tasks in SQLite (`status: pending`)
+   - Worker polls DB, claims tasks, spawns agent subprocesses
+   - Agent monitoring, completion handling, orphan recovery
+   - Worker heartbeat for liveness detection
+
+3. **State Synchronization**
+   - Server → WebSocket `/ws/state` → `state-store.ts` → Zustand selectors
+   - All connected clients get real-time state updates
+
+4. **Browser Preview** (`browser.py`)
+   - Browserless Docker containers for shared browser sessions
+   - CDP-based context capture (screenshot + accessibility tree)
+   - rrweb session recording with chunked storage
+   - PinchTab integration for connecting to existing browser tabs
+
+5. **Knowledge Base** (`knowledge.py` + `frontend/src/features/wiki/`)
+   - Indexes `.ai/` directories from registered projects
+   - Full-page route at `/kb` with tree nav, search, markdown viewer
+   - Create/edit docs via REST API
+
+6. **AI Orchestrator** (`intent.py`)
+   - Natural language → structured actions (open terminal, create task, etc.)
+   - Used by chat panels and voice commands
+
+## Database
+
+Single SQLite database at `~/.rdc/data/rdc.db` (consolidated from previous multi-DB setup).
+
+Schema managed by SQL migrations in `src/remote_dev_ctrl/server/db/migrations/rdc/`.
+Migrations auto-run on server startup via `db/migrate.py`.
+
+Key tables: `projects`, `tasks`, `events`, `workers`, `browser_sessions`, `contexts`, `agent_registry`, `process_configs`, `settings`.
+
+## CLI Commands
+
+```bash
+rdc server start [--reload]    # Start FastAPI server
+rdc server start -d            # Daemonized
+rdc add <name> <path>          # Register a project
+rdc list                       # List projects
+rdc remove <name>              # Remove a project
+```
+
+## Development
+
+```bash
+# Frontend build (must pass with zero errors)
+cd frontend && pnpm run build
+
+# Frontend dev server (proxies API to :8420)
+cd frontend && pnpm dev
+
+# Server with hot-reload
+rdc server start --reload
+
+# Type-check only
+cd frontend && npx tsc --noEmit
+```
+
+## File Locations
+
+- Main server: `src/remote_dev_ctrl/server/`
+- Frontend: `frontend/src/`
+- Database: `~/.rdc/data/rdc.db`
+- Migrations: `src/remote_dev_ctrl/server/db/migrations/rdc/`
+- Config: `~/.rdc/config.yml`
+- Agent logs: `~/.rdc/logs/agents/`
+- Process logs: `~/.rdc/logs/processes/`
+- Browser recordings: `~/.rdc/recordings/`
+- Context snapshots: `~/.rdc/contexts/`

rdc-0.1.0/.ai/learnings.md

@@ -0,0 +1,67 @@
+# RDC Development Learnings
+
+Corrections and patterns learned during development.
+
+## Rebrand: adt → rdc
+
+The project was rebranded from `agent-dev-tool` (CLI: `adt`) to `remote-dev-ctrl` (CLI: `rdc`).
+- Python module: `src/remote_dev_ctrl/`
+- Config dir: `~/.rdc/` (falls back to `~/.adt/` for compat)
+- DB: `rdc.db` (falls back to `adt.db`)
+- Env vars: `RDC_HOME`, `RDC_SECRET_KEY` (falls back to `ADT_*`)
+- Frontend localStorage: `rdc_*` (migration shim in `main.tsx`)
+
+## All Three Layouts Are First-Class
+
+Desktop, Mobile, and Kiosk layouts must all be updated when making feature changes.
+- Desktop: `layouts/desktop.tsx`
+- Mobile: `layouts/mobile.tsx`
+- Kiosk: `layouts/kiosk.tsx`
+
+## Terminal PTY Architecture
+
+- `terminal.py` uses `socat`-based PTY relay processes that survive server restarts
+- Background buffer polling pre-WebSocket, event-loop `add_reader` post-connect
+- MCP detection: server-side `_mcp_approval_needed` flag in StateSnapshot
+- Default command: plain `cursor-agent` (no --resume). Configurable per-project.
+
+## cursor-agent Quirks
+
+- `cursor-agent --resume` + MCP Server Approval = exits with code 0 (bug)
+- `cursor-agent` (fresh session, no `--resume`) works correctly
+- Uses Ink (React terminal UI) — requires raw mode on stdin, needs a real PTY
+
+## CDP / rrweb Recording
+
+- `Runtime.evaluate` scopes `var` declarations — use `window.rrweb = ...` explicitly
+- Dual push/pull: CDP binding for low-latency + periodic buffer drain as fallback
+- Recordings stored as chunked JSON in `~/.rdc/recordings/{rec_id}/chunk_{n}.json`
+
+## Frontend Build
+
+- `pnpm run build` runs `tsc -b && vite build`
+- Unused variables/imports are build errors (strict TypeScript)
+- Always build after changes to verify zero errors
+
+## Auth Middleware
+
+- Public paths defined in `middleware.py` (`PUBLIC_PATHS` and `PUBLIC_PATH_PREFIXES`)
+- New SPA routes must be added to public paths so the frontend `index.html` gets served
+- Frontend handles auth client-side via localStorage token
+
+## Flexbox Height Issues
+
+Use proper flexbox chain to prevent panels from being cut off:
+```html
+<div class="h-screen flex flex-col">
+  <header class="shrink-0">...</header>
+  <main class="flex-1 min-h-0 overflow-auto">...</main>
+</div>
+```
+Key: `min-h-0` on flex children prevents content from expanding beyond bounds.
+
+## Database Migrations
+
+- SQL files in `src/remote_dev_ctrl/server/db/migrations/rdc/`
+- Auto-run on server startup via `db/migrate.py`
+- Single consolidated SQLite DB at `~/.rdc/data/rdc.db`

rdc-0.1.0/.ai/worker-design.md

@@ -0,0 +1,62 @@
+# RDC Task Worker Architecture
+
+## Overview
+
+The worker is a background process that executes tasks by spawning agent subprocesses. It's decoupled from the API server so tasks survive API restarts.
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────┐
+│                  SQLite DB                   │
+│  tasks (queue) │ agents (state) │ workers    │
+└────────────────┼────────────────┼────────────┘
+     poll         │  update        │ heartbeat
+┌────────────────▼────────────────▼────────────┐
+│                 RDC Worker                    │
+│  Task Poller → Agent Monitor → Health Report │
+│         ↓                                    │
+│    Agent Subprocesses (cursor-agent, etc.)   │
+└──────────────────────────────────────────────┘
+                    (independent)
+┌──────────────────────────────────────────────┐
+│              FastAPI Server                   │
+│  POST /tasks (insert) │ WebSocket (broadcast)│
+└──────────────────────────────────────────────┘
+```
+
+## How It Works
+
+1. **API** creates tasks in DB (`status: pending`)
+2. **Worker** polls DB, atomically claims next pending task
+3. **Worker** spawns agent subprocess (cursor-agent or web-native)
+4. **Worker** monitors subprocess for completion
+5. **Worker** updates task status in DB (completed/failed)
+6. **API** reads updated state, broadcasts via WebSocket
+
+## Key Components
+
+- `server/worker.py` — TaskWorker class with poll/spawn/monitor/heartbeat loops
+- `server/agents/manager.py` — AgentManager for subprocess lifecycle
+- `db/repositories.py` — TaskRepository with atomic claim/complete/fail operations
+
+## Task Lifecycle
+
+```
+pending → claimed (by worker) → in_progress → completed/failed
+                                    ↓
+                              needs_review → approved/rejected
+```
+
+## CLI
+
+```bash
+rdc server start        # Server includes integrated worker
+rdc server start -d     # Daemonized
+```
+
+## Recovery
+
+- **API restarts**: Worker (integrated) restarts with server, recovers orphaned tasks
+- **Agent crashes**: Worker detects via PID monitoring, marks task as failed
+- **Orphan detection**: On startup, scans for tasks claimed but not running