fluxy-bot 0.8.6 → 0.8.9

package/README.md

@@ -11,8 +11,8 @@ 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`) -- optional cloud service that maps `username.fluxy.bot` to the user's Cloudflare tunnel. Routes HTTP and WebSocket traffic. Only used with Quick Tunnels.
 3. **Cloudflare Tunnel** -- exposes `localhost:3000` to the internet. Two modes:
-   - **Quick Tunnel** -- zero-config, no account needed, random `*.trycloudflare.com` URL that changes on restart. Optionally paired with the relay for a permanent domain.
-   - **Named Tunnel** -- persistent URL with the user's own domain. Requires a Cloudflare account and DNS setup. No relay needed.
+    - **Quick Tunnel** -- zero-config, no account needed, random `*.trycloudflare.com` URL that changes on restart. Optionally paired with the relay for a permanent domain.
+    - **Named Tunnel** -- persistent URL with the user's own domain. Requires a Cloudflare account and DNS setup. No relay needed.
 
 The user chooses their tunnel mode during `fluxy init` via an interactive selector.
 
@@ -22,7 +22,7 @@ The user chooses their tunnel mode during `fluxy init` via an interactive select
 
 When `fluxy start` runs, the CLI spawns a single supervisor process. The supervisor then spawns child processes and manages their lifecycle:
 
-```
+```shell
 CLI (bin/cli.js)
   |
   spawns
@@ -46,20 +46,22 @@ All child processes auto-restart up to 3 times on crash (reset counter if alive
 
 The supervisor is a raw `http.createServer` (no Express) that routes every incoming request:
 
-| Path | Target | Notes |
-|---|---|---|
-| `/fluxy/widget.js` | Direct file serve | Chat bubble script, no-cache |
-| `/sw.js`, `/fluxy/sw.js` | Embedded service worker | PWA + push notification support |
-| `/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. HTML: no-cache. Hashed assets: immutable, 1yr max-age |
-| Everything else | Vite dev server (port 3002) | Dashboard + HMR |
+| Path                     | Target                          | Notes                                                                     |
+| ------------------------ | ------------------------------- | ------------------------------------------------------------------------- |
+| `/fluxy/widget.js`       | Direct file serve               | Chat bubble script, no-cache                                              |
+| `/sw.js`, `/fluxy/sw.js` | Embedded service worker         | PWA + push notification support                                           |
+| `/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. HTML: no-cache. Hashed assets: immutable, 1yr max-age |
+| 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) for both quick and named tunnels
 - Registers with the relay and maintains heartbeats (quick tunnel mode only)
 - Runs the Claude Agent SDK when users send chat messages
@@ -85,6 +87,7 @@ Express server on port 3001. Owns the database and all platform API logic. The s
 **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_in, tokens_out, model, audio_data, attachments as JSON)
 - `settings` -- key-value store (onboard config, provider, model, portal credentials, etc.)
@@ -94,6 +97,7 @@ Tables:
 Auto-migrations add missing columns on startup (session_id, audio_data, attachments).
 
 Key endpoints:
+
 - `/api/conversations` -- CRUD for conversations and messages (paginated with `before` cursor)
 - `/api/settings` -- key-value read/write
 - `/api/onboard` -- saves wizard configuration (provider, model, portal password, whisper key, names)
@@ -118,7 +122,7 @@ Portal passwords are hashed with scrypt (random 16-byte salt, stored as `salt:ha
 
 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.
 
-```
+```shell
 workspace/
   client/             React + Vite + Tailwind dashboard
     src/App.tsx        Main app entry (error boundary, rebuild overlay, onboard iframe)
@@ -150,12 +154,12 @@ The workspace is the only directory Claude is allowed to modify. The system prom
 
 The agent has no persistent memory between sessions except through files in the workspace:
 
-| File | Purpose |
-|---|---|
-| `MYSELF.md` | Agent identity, personality, operating manual. The agent's self-authored description of who it is. |
-| `MYHUMAN.md` | Profile of the user -- preferences, context, everything the agent has learned about them. |
-| `MEMORY.md` | Long-term curated knowledge. Distilled from daily notes into durable insights. |
-| `memory/YYYY-MM-DD.md` | Daily notes. Raw, append-only log of events and observations for that day. |
+| File                   | Purpose                                                                                            |
+| ---------------------- | -------------------------------------------------------------------------------------------------- |
+| `MYSELF.md`            | Agent identity, personality, operating manual. The agent's self-authored description of who it is. |
+| `MYHUMAN.md`           | Profile of the user -- preferences, context, everything the agent has learned about them.          |
+| `MEMORY.md`            | Long-term curated knowledge. Distilled from daily notes into durable insights.                     |
+| `memory/YYYY-MM-DD.md` | Daily notes. Raw, append-only log of events and observations for that day.                         |
 
 All four are injected into the system prompt at query time by `fluxy-agent.ts`. The agent reads and writes these files itself -- there's no external process managing them.
 
@@ -170,7 +174,11 @@ The scheduler runs in-process within the supervisor, checking every 60 seconds.
 Periodic wake-ups configured in `workspace/PULSE.json`:
 
 ```json
-{ "enabled": true, "intervalMinutes": 30, "quietHours": { "start": "23:00", "end": "07:00" } }
+{
+    "enabled": true,
+    "intervalMinutes": 30,
+    "quietHours": { "start": "23:00", "end": "07:00" }
+}
 ```
 
 When a pulse fires, the scheduler triggers the agent with a system-generated prompt. The agent can check in, review notes, or take proactive action. Quiet hours suppress pulses.
@@ -180,12 +188,21 @@ When a pulse fires, the scheduler triggers the agent with a system-generated pro
 Scheduled tasks configured in `workspace/CRONS.json`:
 
 ```json
-[{ "id": "...", "schedule": "0 9 * * *", "task": "Check the weather", "enabled": true, "oneShot": false }]
+[
+    {
+        "id": "...",
+        "schedule": "0 9 * * *",
+        "task": "Check the weather",
+        "enabled": true,
+        "oneShot": false
+    }
+]
 ```
 
 Uses `cron-parser` to match cron expressions against the current minute. One-shot crons are auto-removed after firing.
 
 When a cron or pulse fires:
+
 1. The scheduler calls `startFluxyAgentQuery` with the task
 2. It extracts `<Message>` blocks from the agent's response
 3. It sends push notifications for those messages
@@ -220,12 +237,14 @@ If Claude introduces a bug that crashes the dashboard, the chat stays alive. The
 ### Widget (supervisor/widget.js)
 
 Vanilla JS that injects:
+
 - A floating video bubble (60px, bottom-right corner, with Safari fallback image)
 - A slide-out panel (480px wide, full screen on mobile) containing the iframe at `/fluxy/`
 - A backdrop for dismissal
 - Keyboard dismiss (Escape key)
 
 Communicates with the iframe via `postMessage`:
+
 - `fluxy:close` -- iframe requests panel close
 - `fluxy:install-app` -- iframe requests PWA install prompt
 - `fluxy:show-ios-install` -- iframe requests iOS-specific install modal
@@ -240,6 +259,7 @@ Panel state persisted in localStorage (`fluxy_widget_open`) to survive HMR reloa
 ### 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
@@ -247,6 +267,7 @@ Client -> Server:
 - `settings:save` -- `{ ...settings }` (bypasses relay POST limitation)
 
 Server -> Client:
+
 - `bot:typing` -- agent started
 - `bot:token` -- streamed text chunk
 - `bot:tool` -- tool invocation (name, status)
@@ -266,6 +287,7 @@ Auto-reconnects with exponential backoff (1s -> 8s cap). Queues messages during
 ### PWA Support
 
 The chat SPA handles:
+
 - `beforeinstallprompt` for Android PWA install
 - iOS-specific install modal with step-by-step instructions
 - Standalone mode detection
@@ -309,7 +331,7 @@ The user selects a tunnel mode during `fluxy init`. The mode is stored in `~/.fl
 
 Zero configuration. No Cloudflare account needed.
 
-```
+```shell
 Phone browser
   |
   | https://bruno.fluxy.bot          (via relay, optional)
@@ -334,7 +356,7 @@ Supervisor                           User's machine
 
 Persistent URL with the user's own domain. Requires a Cloudflare account + domain.
 
-```
+```shell
 Phone browser
   |
   | https://bot.mydomain.com
@@ -365,6 +387,7 @@ Supervisor                           User's machine
 Node.js/Express + http-proxy + MongoDB. Hosted on Railway. Only used when the user opts into Quick Tunnel mode and registers a handle.
 
 **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
@@ -373,6 +396,7 @@ Node.js/Express + http-proxy + MongoDB. Hosted on Railway. Only used when the us
 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
@@ -380,16 +404,18 @@ Node.js/Express + http-proxy + MongoDB. Hosted on Railway. Only used when the us
 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 |
+
+| 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`.
 
@@ -425,21 +451,22 @@ Settings are saved via WebSocket (`settings:save` message) to bypass relay POST
 
 The CLI is the user-facing entry point. Commands:
 
-| Command | Description |
-|---|---|
-| `fluxy init` | First-time setup: interactive tunnel mode chooser (Quick or Named), creates config, installs cloudflared, boots server, optionally installs systemd daemon |
-| `fluxy start` | Boot the supervisor (or detect existing daemon and show status) |
-| `fluxy status` | Health check via `/api/health`, shows uptime, tunnel URL, and relay URL |
-| `fluxy update` | Downloads latest from npm registry, updates code directories, rebuilds UI, restarts daemon |
-| `fluxy tunnel` | Named tunnel management (subcommands below) |
-| `fluxy daemon` | Linux systemd management: install, start, stop, restart, status, logs, uninstall |
+| Command        | Description                                                                                                                                                |
+| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `fluxy init`   | First-time setup: interactive tunnel mode chooser (Quick or Named), creates config, installs cloudflared, boots server, optionally installs systemd daemon |
+| `fluxy start`  | Boot the supervisor (or detect existing daemon and show status)                                                                                            |
+| `fluxy status` | Health check via `/api/health`, shows uptime, tunnel URL, and relay URL                                                                                    |
+| `fluxy update` | Downloads latest from npm registry, updates code directories, rebuilds UI, restarts daemon                                                                 |
+| `fluxy tunnel` | Named tunnel management (subcommands below)                                                                                                                |
+| `fluxy daemon` | Linux systemd management: install, start, stop, restart, status, logs, uninstall                                                                           |
 
 **`fluxy tunnel` subcommands:**
-| Subcommand | Description |
-|---|---|
-| `fluxy tunnel setup` | Interactive named tunnel setup: login to Cloudflare, create tunnel, enter domain, generate config YAML, print CNAME instructions |
-| `fluxy tunnel status` | Show current tunnel mode and configuration |
-| `fluxy tunnel reset` | Switch back to quick tunnel mode |
+
+| Subcommand            | Description                                                                                                                      |
+| --------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
+| `fluxy tunnel setup`  | Interactive named tunnel setup: login to Cloudflare, create tunnel, enter domain, generate config YAML, print CNAME instructions |
+| `fluxy tunnel status` | Show current tunnel mode and configuration                                                                                       |
+| `fluxy tunnel reset`  | Switch back to quick tunnel mode                                                                                                 |
 
 **`fluxy init` tunnel chooser:**
 
@@ -461,15 +488,19 @@ On Linux, `fluxy daemon` generates a systemd unit file that runs the supervisor
 Two installation paths:
 
 **Via curl (production):**
-```
+
+```shell
 curl -fsSL https://fluxy.bot/install | sh
 ```
+
 The install script (`scripts/install.sh`) detects OS/arch, checks for Node.js >= 18 (or bundles Node 22.14.0), downloads the npm package, extracts to `~/.fluxy/`, and adds `fluxy` to PATH.
 
 **Via npm (development):**
-```
+
+```shell
 npm install fluxy-bot
 ```
+
 The `postinstall` script (`scripts/postinstall.js`) copies code directories to `~/.fluxy/`, runs `npm install --omit=dev` there, builds the chat UI if missing, and creates a `fluxy` symlink.
 
 Windows: `scripts/install.ps1` (PowerShell equivalent).
@@ -478,16 +509,16 @@ Windows: `scripts/install.ps1` (PowerShell equivalent).
 
 ## Data Locations
 
-| Path | Contents |
-|---|---|
-| `~/.fluxy/config.json` | Port, username, AI provider, tunnel mode/config, relay token, tunnel URL |
-| `~/.fluxy/cloudflared-config.yml` | Named tunnel config (generated by `fluxy tunnel setup`) |
-| `~/.fluxy/memory.db` | SQLite -- conversations, messages, settings, sessions, push subscriptions |
-| `~/.fluxy/bin/cloudflared` | Cloudflare tunnel binary |
-| `~/.fluxy/workspace/` | User's workspace copy (client, backend, memory files, skills, config) |
-| `~/.codex/codedeck-auth.json` | OpenAI OAuth tokens |
-| `~/.claude/.credentials.json` | Claude OAuth tokens (Linux/Windows) |
-| macOS Keychain `Claude Code-credentials` | Claude OAuth tokens (macOS, source of truth) |
+| Path                                     | Contents                                                                  |
+| ---------------------------------------- | ------------------------------------------------------------------------- |
+| `~/.fluxy/config.json`                   | Port, username, AI provider, tunnel mode/config, relay token, tunnel URL  |
+| `~/.fluxy/cloudflared-config.yml`        | Named tunnel config (generated by `fluxy tunnel setup`)                   |
+| `~/.fluxy/memory.db`                     | SQLite -- conversations, messages, settings, sessions, push subscriptions |
+| `~/.fluxy/bin/cloudflared`               | Cloudflare tunnel binary                                                  |
+| `~/.fluxy/workspace/`                    | User's workspace copy (client, backend, memory files, skills, config)     |
+| `~/.codex/codedeck-auth.json`            | OpenAI OAuth tokens                                                       |
+| `~/.claude/.credentials.json`            | Claude OAuth tokens (Linux/Windows)                                       |
+| macOS Keychain `Claude Code-credentials` | Claude OAuth tokens (macOS, source of truth)                              |
 
 ---
 
@@ -495,7 +526,7 @@ Windows: `scripts/install.ps1` (PowerShell equivalent).
 
 ### Sacred (never modified by the agent)
 
-```
+```shell
 bin/cli.js                          CLI entry point, startup sequence, update logic, daemon management
 supervisor/
   index.ts                          HTTP server, request routing, WebSocket handler, process orchestration
@@ -546,7 +577,7 @@ scripts/
 
 ### Workspace (agent-modifiable)
 
-```
+```shell
 workspace/
   client/
     index.html                      Dashboard HTML shell, PWA manifest, widget script tag