fluxy-bot 0.4.16 → 0.4.17

package/README.md

@@ -0,0 +1,371 @@
+# Fluxy
+
+A self-hosted AI agent that runs on the user's machine with a full-stack workspace it can modify, a chat interface for remote control, and a relay system for public access via custom domains.
+
+---
+
+## System Overview
+
+Fluxy is three separate codebases working together:
+
+1. **Fluxy Bot** (this repo) -- runs on the user's machine. Supervisor process, worker API, workspace app, chat UI.
+2. **Fluxy Relay** (separate server at `api.fluxy.bot`) -- cloud service that maps `username.fluxy.bot` to the user's Cloudflare tunnel. Routes HTTP and WebSocket traffic.
+3. **Cloudflare Quick Tunnel** -- ephemeral tunnel created by `cloudflared` binary, exposes `localhost:3000` to the internet via a random `*.trycloudflare.com` URL.
+
+The relay gives users a permanent domain. The tunnel gives the relay a target. The supervisor ties everything together locally.
+
+---
+
+## Process Architecture
+
+When `fluxy start` runs, the CLI spawns a single supervisor process. The supervisor then spawns three child processes and manages their lifecycle:
+
+```
+CLI (bin/cli.js)
+  |
+  spawns
+  v
+Supervisor (supervisor/index.ts)        port 3000    HTTP server + WebSocket + reverse proxy
+  |
+  +-- Worker (worker/index.ts)          port 3001    Express API, SQLite, auth, conversations
+  +-- Vite Dev Server                   port 3002    Serves workspace/client with HMR
+  +-- Backend (workspace/backend/)      port 3004    User's custom Express server
+  +-- cloudflared (tunnel)              --           Exposes port 3000 to the internet
+```
+
+Port allocation: base port (default 3000), worker = base+1, Vite = base+2, backend = base+4.
+
+All child processes auto-restart up to 3 times on crash. The supervisor catches SIGINT/SIGTERM and tears everything down gracefully.
+
+---
+
+## Supervisor (supervisor/index.ts)
+
+The supervisor is a raw `http.createServer` (no Express) that routes every incoming request:
+
+| Path | Target | Notes |
+|---|---|---|
+| `/app/api/*` | Backend (port 3004) | Strips `/app/api` prefix before forwarding |
+| `/api/*` | Worker (port 3001) | Auth middleware checks Bearer token on mutations |
+| `/fluxy/*` | Static files from `dist-fluxy/` | Pre-built chat SPA, cached aggressively |
+| `/fluxy/widget.js` | Direct file serve | Chat bubble script injected into dashboard |
+| Everything else | Vite dev server (port 3002) | Dashboard + HMR |
+
+WebSocket upgrades:
+- `/fluxy/ws` -- Fluxy chat. Auth-gated via query param token. Handled by an in-process `WebSocketServer`.
+- Everything else -- proxied to Vite dev server for HMR.
+
+The supervisor also:
+- Manages the Cloudflare tunnel lifecycle (start, stop, health watchdog every 30s)
+- Registers with the relay and maintains heartbeats
+- Runs the Claude Agent SDK when users send chat messages
+- Restarts the backend process when Claude edits workspace files
+- Broadcasts `app:hmr-update` to all connected dashboard clients after file changes
+
+### Auth Middleware
+
+The supervisor validates Bearer tokens on `/api/*` POST/PUT/DELETE requests by calling the worker's `/api/portal/validate-token` endpoint. Token results are cached for 60 seconds. Auth-exempt routes (login, onboard, health) skip this check.
+
+The `/app/api/*` route has no auth -- the user's workspace backend handles its own authentication.
+
+---
+
+## Worker (worker/index.ts)
+
+Express server on port 3001. Owns the database and all platform API logic. The supervisor never touches SQLite directly -- everything goes through HTTP.
+
+**Database:** `~/.fluxy/memory.db` (SQLite via better-sqlite3, WAL mode)
+
+Tables:
+- `conversations` -- chat sessions (id, title, model, session_id, timestamps)
+- `messages` -- individual messages (role, content, tokens, audio, attachments as JSON)
+- `settings` -- key-value store (onboard config, provider, model, portal credentials, etc.)
+- `sessions` -- auth tokens with 7-day expiry
+
+Key endpoints:
+- `/api/conversations` -- CRUD for conversations and messages
+- `/api/settings` -- key-value read/write
+- `/api/onboard` -- saves wizard configuration (provider, model, portal password, whisper key)
+- `/api/onboard/status` -- returns current setup state
+- `/api/portal/login` -- password auth (POST with JSON body or GET with Basic Auth header)
+- `/api/portal/validate-token` -- session token validation
+- `/api/whisper/transcribe` -- audio-to-text via OpenAI Whisper API
+- `/api/handle/*` -- register, change, release relay handles
+- `/api/context/current` and `/api/context/set` -- tracks which conversation is active
+
+Portal passwords are hashed with scrypt (random 16-byte salt, stored as `salt:hash`).
+
+---
+
+## Workspace
+
+The workspace is a full-stack app template that Claude can freely modify. It lives at `workspace/` in the project and gets copied to `~/.fluxy/workspace/` on first install.
+
+```
+workspace/
+  client/           React + Vite + Tailwind dashboard
+    src/App.tsx      Main app entry (error boundary, rebuild overlay, onboard iframe)
+    index.html       PWA manifest, service worker registration, widget script
+  backend/
+    index.ts         Express server template (reads .env, opens app.db)
+  .env               Environment variables for the backend
+  app.db             SQLite database for workspace data
+  files/             Attachment storage (audio, images, documents)
+```
+
+The backend runs on port 3004, accessed at `/app/api/*` through the supervisor proxy. The `/app/api` prefix is stripped before reaching the backend, so routes are defined as `/health` not `/app/api/health`.
+
+The frontend is served by Vite with HMR. When Claude edits files, Vite picks up changes instantly for the frontend. The supervisor restarts the backend process after any file write by the agent.
+
+The workspace is the only directory Claude is allowed to modify. The system prompt explicitly tells it never to touch `supervisor/`, `worker/`, `shared/`, or `bin/`.
+
+---
+
+## Fluxy Chat
+
+The chat UI is a standalone React SPA built separately (`vite.fluxy.config.ts` -> `dist-fluxy/`). It runs inside an iframe injected by `widget.js` on the dashboard.
+
+### Why an iframe?
+
+If Claude introduces a bug that crashes the dashboard, the chat stays alive. The user can still talk to Claude and ask for a fix. The chat and dashboard are completely isolated -- different React trees, different build outputs, different error boundaries.
+
+### Widget (supervisor/widget.js)
+
+Vanilla JS that injects:
+- A floating video bubble (60px, bottom-right corner)
+- A slide-out panel (480px wide, full screen on mobile) containing the iframe at `/fluxy/`
+- A backdrop for dismissal
+
+Communicates with the iframe via `postMessage`:
+- `fluxy:close` -- iframe requests panel close
+- `fluxy:install-app` -- iframe requests PWA install prompt
+- `fluxy:onboard-complete` -- iframe notifies onboarding finished
+- `fluxy:hmr-update` -- supervisor notifies dashboard of file changes (forwarded to parent)
+
+### Chat Protocol (WebSocket)
+
+Client -> Server:
+- `user:message` -- `{ content, conversationId?, attachments? }` where attachments are `{ type, name, mediaType, data(base64) }`
+- `user:stop` -- abort current agent query
+- `user:clear-context` -- clear conversation and agent session
+- `whisper:transcribe` -- `{ audio: base64 }` (bypasses relay POST limitation)
+- `settings:save` -- `{ ...settings }` (bypasses relay POST limitation)
+
+Server -> Client:
+- `bot:typing` -- agent started
+- `bot:token` -- streamed text chunk
+- `bot:tool` -- tool invocation (name, status)
+- `bot:response` -- final complete response
+- `bot:error` -- error message
+- `chat:conversation-created` -- new conversation ID assigned
+- `chat:sync` -- message from another connected client
+- `chat:cleared` -- context was cleared
+- `app:hmr-update` -- file changes detected, dashboard should reload
+
+### WebSocket Client (ws-client.ts)
+
+Auto-reconnects with exponential backoff (1s -> 8s cap). Queues messages during disconnection. Sends heartbeat pings every 25 seconds. Auth token passed as query parameter on connect.
+
+---
+
+## Claude Agent SDK Integration (supervisor/fluxy-agent.ts)
+
+When the configured provider is Anthropic, chat messages are routed through the Claude Agent SDK instead of a raw API call.
+
+- Runs with `permissionMode: bypassPermissions` -- full tool access, no confirmation prompts
+- Working directory: `workspace/`
+- Max 50 turns per query
+- System prompt: Claude Code preset + custom addendum from `worker/prompts/fluxy-system-prompt.txt`
+- Sessions tracked in-memory (conversationId -> sessionId) for multi-turn context
+
+The agent has access to all Claude Code tools (Read, Write, Edit, Bash, Grep, Glob, etc.). After a query completes, the supervisor checks if Write or Edit tools were used. If so, it restarts the backend and broadcasts an HMR update.
+
+OAuth tokens are managed by `worker/claude-auth.ts` using PKCE flow against `claude.ai`. Tokens are stored in the macOS Keychain (primary) or `~/.claude/.credentials.json` (fallback). Refresh tokens are used to renew access tokens with a 5-minute expiry buffer.
+
+For non-Anthropic providers (OpenAI, Ollama), the supervisor falls back to `ai.chat()` with simple message history -- no agent tools, no file access.
+
+---
+
+## Tunnel + Relay System
+
+### Problem
+
+The user's machine is behind NAT. We need a public URL so they can access their bot from their phone.
+
+### Solution: Three Tiers
+
+```
+Phone browser
+  |
+  | https://bruno.fluxy.bot
+  v
+Fluxy Relay (api.fluxy.bot)        Cloud server, maps username -> tunnel URL
+  |
+  | https://random-abc.trycloudflare.com
+  v
+Cloudflare Quick Tunnel            Ephemeral tunnel, changes on restart
+  |
+  | http://localhost:3000
+  v
+Supervisor                         User's machine
+```
+
+### Cloudflare Tunnel (supervisor/tunnel.ts)
+
+- Auto-downloads `cloudflared` binary to `~/.fluxy/bin/` on first run
+- Spawns: `cloudflared tunnel --url http://localhost:3000 --no-autoupdate`
+- Extracts tunnel URL from stdout (regex match for `*.trycloudflare.com`)
+- Health check: HEAD request to tunnel URL with 5s timeout
+- Watchdog runs every 30s, detects sleep/wake gaps (>60s between ticks), auto-restarts dead tunnels
+
+### Relay Server (separate codebase)
+
+Node.js/Express + http-proxy + MongoDB. Hosted on Railway.
+
+**Registration flow:**
+1. User picks a username during onboarding
+2. Bot calls `POST /api/register` with username + tier
+3. Relay stores tokenHash (SHA-256) in MongoDB, returns raw token + relay URL
+4. Bot stores token in `~/.fluxy/config.json`
+5. Bot calls `PUT /api/tunnel` with its cloudflared URL
+6. Relay marks bot online, starts accepting proxied traffic
+
+**Request proxying:**
+1. Request hits `bruno.fluxy.bot`
+2. Subdomain middleware extracts username + tier from hostname
+3. MongoDB lookup returns the bot's tunnel URL
+4. `proxy.web(req, res, { target: tunnelUrl })` forwards everything -- headers, body, method
+5. Response streams back to the user's browser
+
+**Presence:**
+- Bot sends `POST /api/heartbeat` every 30 seconds with its tunnel URL
+- Relay considers a bot stale if no heartbeat in 120 seconds
+- Stale bots get a 503 offline page (auto-refreshes every 15s)
+- On graceful shutdown, bot calls `POST /api/disconnect`
+
+**Domain tiers:**
+| Tier | Subdomain | Path shortcut | Cost |
+|---|---|---|---|
+| Premium | `bruno.fluxy.bot` | `fluxy.bot/bruno` | $5/mo |
+| Free | `bruno.my.fluxy.bot` | `my.fluxy.bot/bruno` | Free |
+
+Same username can exist on both tiers independently. Compound unique index on `username + tier`.
+
+**WebSocket proxying:**
+The relay listens for HTTP upgrade events outside of Express middleware. This is critical -- Express middleware (body parsing, CORS) must not touch WebSocket upgrades. The upgrade handler parses the subdomain, looks up the bot, and calls `proxy.ws()`.
+
+### Critical Constraint: POST Bodies Through the Relay
+
+The relay's `express.json()` middleware must run AFTER the subdomain resolver, not before. If body parsing runs first, it consumes the request stream and `http-proxy` has nothing to forward. This was a real bug -- the fix was scoping `express.json()` to `/api` routes only, letting proxied traffic pass through with raw streams intact.
+
+The Fluxy chat has additional workarounds for this (sending settings and whisper data over WebSocket instead of POST), but with the relay fix these are no longer strictly necessary. They remain as defense-in-depth.
+
+---
+
+## Onboarding (supervisor/chat/OnboardWizard.tsx)
+
+Multi-step wizard shown on first launch (inside the Fluxy chat iframe):
+
+1. **Welcome** -- intro screen
+2. **Provider** -- choose Claude (Anthropic) or OpenAI Codex
+3. **Model** -- select specific model (Opus, Sonnet, Haiku / GPT-5.x variants)
+4. **Auth** -- OAuth PKCE flow for Claude, or manual API key entry
+5. **Handle** -- register a public username with the relay (checks availability in real time)
+6. **Portal** -- set username/password for remote access
+7. **Whisper** -- optional voice transcription setup with OpenAI key
+8. **Done** -- completion screen
+
+Settings are saved via WebSocket (`settings:save` message) to bypass relay POST limitations.
+
+---
+
+## Data Locations
+
+| Path | Contents |
+|---|---|
+| `~/.fluxy/config.json` | Port, username, AI provider, relay token, tunnel URL |
+| `~/.fluxy/memory.db` | SQLite -- conversations, messages, settings, sessions |
+| `~/.fluxy/bin/cloudflared` | Cloudflare tunnel binary |
+| `~/.fluxy/workspace/` | User's workspace copy (client, backend, .env, app.db, files/) |
+| `~/.claude/.credentials.json` | Claude OAuth tokens (Linux/Windows) |
+| macOS Keychain `Claude Code-credentials` | Claude OAuth tokens (macOS, source of truth) |
+
+---
+
+## File Map
+
+### Sacred (never modified by the agent)
+
+```
+bin/cli.js                          CLI entry point, startup sequence, update logic
+supervisor/
+  index.ts                          HTTP server, request routing, WebSocket handler, process orchestration
+  worker.ts                         Worker process spawn/stop/restart
+  backend.ts                        Backend process spawn/stop/restart
+  tunnel.ts                         Cloudflare tunnel lifecycle, health watchdog
+  vite-dev.ts                       Vite dev server startup for dashboard HMR
+  fluxy-agent.ts                    Claude Agent SDK wrapper, session management
+  file-saver.ts                     Attachment storage (audio, images, documents)
+  widget.js                         Chat bubble + panel injected into dashboard
+  chat/
+    fluxy-main.tsx                  Chat SPA entry -- auth, WS connection, message routing
+    onboard-main.tsx                Onboard SPA entry
+    OnboardWizard.tsx               Multi-step setup wizard
+    ARCHITECTURE.md                 Network topology and relay workaround docs
+    src/
+      hooks/useFluxyChat.ts         Chat state management, message protocol, streaming
+      lib/ws-client.ts              WebSocket client with reconnect + queue
+      lib/auth.ts                   Token storage and auth fetch wrapper
+      components/Chat/              InputBar, MessageBubble, MessageList
+      components/LoginScreen.tsx    Portal login UI
+worker/
+  index.ts                          Express API server -- all platform endpoints
+  db.ts                             SQLite schema, CRUD operations
+  claude-auth.ts                    Claude OAuth PKCE flow, token refresh, Keychain integration
+  codex-auth.ts                     OpenAI OAuth flow
+  prompts/fluxy-system-prompt.txt   System prompt that constrains the agent
+shared/
+  config.ts                         Load/save ~/.fluxy/config.json
+  paths.ts                          All path constants (PKG_DIR, DATA_DIR, WORKSPACE_DIR)
+  relay.ts                          Relay API client (register, heartbeat, disconnect, tunnel update)
+  ai.ts                             AI provider abstraction (Anthropic, OpenAI, Ollama)
+  logger.ts                         Colored console logging
+```
+
+### Workspace (agent-modifiable)
+
+```
+workspace/
+  client/
+    index.html                      Dashboard HTML shell, PWA manifest, widget script tag
+    src/main.tsx                     React DOM entry
+    src/App.tsx                      Dashboard root -- error boundary, rebuild overlay
+    src/components/                  Dashboard UI components
+  backend/
+    index.ts                        Express server template with .env loading and SQLite
+  .env                              Environment variables
+  app.db                            Workspace SQLite database
+  files/                            Uploaded file storage
+```
+
+---
+
+## Key Design Decisions
+
+**Why a supervisor + worker split instead of one process?**
+Process isolation. If the worker crashes (bad DB migration, OOM), the supervisor keeps running, the tunnel stays up, the chat stays connected. The user can still talk to Claude. Same logic for the backend -- if Claude writes buggy code, only the backend dies.
+
+**Why serve the chat from pre-built static files instead of Vite?**
+The chat must survive dashboard crashes. If Vite dies or the workspace frontend throws, the chat iframe loads from `dist-fluxy/` which is just static files. No build process, no dev server dependency.
+
+**Why WebSocket for chat instead of HTTP streaming?**
+The relay couldn't reliably forward POST bodies (now fixed). WebSocket was the workaround. It also gives us bidirectional real-time communication, multi-device sync, and heartbeat detection for free.
+
+**Why bypassPermissions on the agent?**
+The whole point is that the user talks to Claude from their phone and Claude does whatever's needed. Confirmation prompts would require a terminal session that doesn't exist. The workspace directory boundary + the system prompt are the safety rails.
+
+**Why Cloudflare Quick Tunnel instead of a persistent tunnel?**
+Zero configuration. No Cloudflare account needed. The tradeoff is the URL changes on restart, which is why the relay exists -- it provides the stable domain layer on top.
+
+**Why two Vite configs?**
+`vite.config.ts` builds the workspace dashboard (user-facing app). `vite.fluxy.config.ts` builds the Fluxy chat SPA. They're separate apps with separate entry points, bundled independently. The chat is pre-built at publish time; the dashboard runs as a dev server with HMR.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fluxy-bot",
-  "version": "0.4.16",
+  "version": "0.4.17",
   "description": "Self-hosted, self-evolving AI agent with its own dashboard.",
   "type": "module",
   "license": "MIT",

package/supervisor/backend.ts

@@ -5,7 +5,9 @@ import { log } from '../shared/logger.js';
 
 let child: ChildProcess | null = null;
 let restarts = 0;
+let lastSpawnTime = 0;
 const MAX_RESTARTS = 3;
+const STABLE_THRESHOLD = 30_000; // 30s — if backend ran this long, it wasn't a crash loop
 
 export function getBackendPort(basePort: number): number {
   return basePort + 4;
@@ -13,6 +15,7 @@ export function getBackendPort(basePort: number): number {
 
 export function spawnBackend(port: number): ChildProcess {
   const backendPath = path.join(PKG_DIR, 'workspace', 'backend', 'index.ts');
+  lastSpawnTime = Date.now();
 
   child = spawn(process.execPath, ['--import', 'tsx/esm', backendPath], {
     cwd: path.join(PKG_DIR, 'workspace'),
@@ -31,10 +34,14 @@ export function spawnBackend(port: number): ChildProcess {
   child.on('exit', (code) => {
     if (code !== 0 && code !== null) {
       log.warn(`Backend crashed (code ${code})`);
+      // If backend was alive for >30s, it's not a crash loop — reset counter
+      if (Date.now() - lastSpawnTime > STABLE_THRESHOLD) {
+        restarts = 0;
+      }
       if (restarts < MAX_RESTARTS) {
         restarts++;
         log.info(`Restarting backend (${restarts}/${MAX_RESTARTS})...`);
-        setTimeout(() => spawnBackend(port), 1000);
+        setTimeout(() => spawnBackend(port), 1000 * restarts);
       } else {
         log.error('Backend failed too many times. Use Fluxy chat to debug.');
       }

package/supervisor/index.ts

@@ -426,7 +426,6 @@ export async function startSupervisor() {
                   resetBackendRestarts();
                   stopBackend();
                   spawnBackend(backendPort);
-                  broadcastFluxy('app:hmr-update');
                 }
                 return; // don't forward bot:done to client
               }
@@ -565,6 +564,22 @@ export async function startSupervisor() {
   spawnWorker(workerPort);
   spawnBackend(backendPort);
 
+  // Watch workspace/backend/ for file changes — auto-restart backend
+  // This catches edits from Claude Code CLI, VS Code, or any external tool
+  const backendDir = path.join(PKG_DIR, 'workspace', 'backend');
+  let backendRestartTimer: ReturnType<typeof setTimeout> | null = null;
+  const backendWatcher = fs.watch(backendDir, { recursive: true }, (_event, filename) => {
+    if (!filename || !filename.match(/\.(ts|js|json)$/)) return;
+    // Debounce: wait 500ms for rapid edits to settle
+    if (backendRestartTimer) clearTimeout(backendRestartTimer);
+    backendRestartTimer = setTimeout(() => {
+      log.info(`[watcher] Backend file changed: ${filename} — restarting...`);
+      resetBackendRestarts();
+      stopBackend();
+      spawnBackend(backendPort);
+    }, 500);
+  });
+
   // Tunnel
   let tunnelUrl: string | null = null;
   if (config.tunnel.enabled) {
@@ -633,6 +648,8 @@ export async function startSupervisor() {
   // Shutdown
   const shutdown = async () => {
     log.info('Shutting down...');
+    backendWatcher.close();
+    if (backendRestartTimer) clearTimeout(backendRestartTimer);
     if (watchdogInterval) clearInterval(watchdogInterval);
     stopHeartbeat();
     const latestConfig = loadConfig();