RuFlo Web UI (flo.ruv.io) — capabilities, roadmap, and known limits

## Overview

The RuFlo Web UI (Beta) shipped in PR #1687 — a multi-model chat surface deployed to Cloud Run that talks to the same MCP backbone as the CLI, with no install required.

**Live URLs (all map to one Cloud Run service):**
- https://flo.ruv.io/ — primary
- https://ruflo.ruv.io/ — alias
- https://ruvocal.ruv.io/ — alias
- https://ruvocal-875130704813.us-central1.run.app/ — raw

**Source:** \`ruflo/src/ruvocal/\` (SvelteKit fork of HF chat-ui v0.20.0, with WASM-MCP layer from \`ruvnet/RuVector/ui/ruvocal\`).

**ADR:** [ruflo/docs/adr/ADR-033-RUVOCAL-WASM-MCP-INTEGRATION.md](https://github.com/ruvnet/ruflo/blob/main/ruflo/docs/adr/ADR-033-RUVOCAL-WASM-MCP-INTEGRATION.md)

---

## ✅ Shipped capabilities

### Models
- **Default:** Claude Sonnet 4.6 via OpenRouter (best tool-calling reliability)
- **Available:** Claude Sonnet 4.6, Claude Opus 4.7, Claude Haiku 4.5, Gemini 2.5 Pro, Gemini 2.5 Flash, GPT-4o
- All flagged \`supportsTools: true\` and \`multimodal: true\`
- Routing: \`OPENAI_BASE_URL=https://openrouter.ai/api/v1\` with \`OPENAI_API_KEY\` mapped from \`OPENROUTER_API_KEY\` Secret Manager secret

### MCP Tooling (~210 tools across 6 servers)

| Server | Source | Tools | Notes |
|--------|--------|-------|-------|
| Core | built-in (\`mcp-bridge\`) | 3 | \`search\`, \`web_research\`, \`guidance\` (Gemini-grounded search) |
| Intelligence | \`ruvector mcp start\` | 49 | Pattern learning, routing, AST analysis, security scan, RAG |
| Agents | \`ruflo mcp start\` | 50 | \`agent_spawn\`, \`swarm_init\`, \`hive-mind_*\`, \`task_create\` |
| Memory | \`ruflo mcp start\` | 35 | \`memory_store\`, \`memory_search\`, \`memory_retrieve\`, AgentDB |
| DevTools | \`ruflo mcp start\` | 73 | \`system_status\`, \`performance_*\`, \`analyze_diff*\`, \`github_*\`, \`terminal_execute\` |
| WASM Gallery | in-browser \`rvagent_wasm.{js,wasm}\` (588 KB) | 18 | IndexedDB-persisted templates, no server roundtrip |

The bridge is deployed as Cloud Run service \`mcp-bridge\` with \`min-instances=1\` (keeps backends warm) and \`120s\` MCP-init timeout for cold-start tolerance.

### Parallel tool calling (verified)
Server logs from the deployed instance:
\`\`\`
[mcp] tools executed; toolMsgCount: 4 ← single Claude response → 4 parallel tools
[mcp] tools executed; toolMsgCount: 6 ← single Claude response → 6 parallel tools
\`\`\`

The chat-ui dispatches all \`tool_calls\` from a single response via \`Promise.all\` (\`src/lib/server/textGeneration/mcp/toolInvocation.ts\`). Each tool's result streams back as a separate card in the UI.

### Persistent memory
- AgentDB (sql.js + HNSW) for cross-session recall
- 384-dim ONNX all-MiniLM-L6-v2 embeddings
- Surface via \`ruflo__memory_*\` and \`ruvector__hooks_remember/recall\` tools

### UX additions
- **Help icon** in sidebar → "RuFlo Capabilities" modal listing all 6 tool groups with per-tool descriptions and quick-start
- **8 RuFlo-themed example prompts** on the welcome screen (replacing HF defaults): swarm, memory, route, analyze diff, system health, WASM gallery, GOAP, neural training
- **RuFlo branding** throughout (\`PUBLIC_APP_NAME=RuFlo\`)
- **Chat input "MCP (6)"** pill showing all enabled servers; expandable per-server tool toggles

### Infrastructure
- **Embedded MongoDB** via \`INCLUDE_DB=true\` (multi-stage Dockerfile copies \`mongod\` from \`mongo:7\`); ephemeral on cold starts but acceptable for chat session storage
- **Custom domains** via Cloudflare DNS (CNAME unproxied so Google manages the cert): \`flo.ruv.io\`, \`ruflo.ruv.io\`, \`ruvocal.ruv.io\`
- **Cloud Build** pipeline with \`DOCKER_BUILDKIT=1\` for \`COPY --link\` syntax
- **\`.gcloudignore\`** prevents \`.gitignore\`'s \`models/*\` rule from stripping route directories during upload

---

## 🛠️ Roadmap / open work

### Web Workers for WASM MCP (P1)
**Why:** \`src/lib/wasm/index.ts\` (1,213 lines) and \`src/lib/stores/wasmMcp.ts\` (454 lines) load and execute the WASM MCP server on the **main thread**. The 588 KB \`rvagent_wasm_bg.wasm\` compile + init takes ~300ms and freezes the UI on first load.

**Scope:**
- New \`src/lib/wasm/wasm.worker.ts\` that owns the WASM module and IndexedDB persistence
- Postmessage RPC bridge replacing direct calls in \`wasmMcp.ts\`
- Async wrappers for the 13 currently-exported functions (\`callMcp\`, \`executeTool\`, \`listTools\`, \`listGalleryTemplates\`, \`searchGalleryTemplates\`, \`loadGalleryTemplate\`, etc.)
- Type-safe message schema (request id, method, params / result, error)

**Estimate:** 4–8 hours including svelte-check and a smoke test that compares wall-clock first-paint with/without the worker.

### Persistent MongoDB (P1)
**Current:** \`INCLUDE_DB=true\` runs \`mongod\` inside the Cloud Run container. Data evicts on cold starts.

**Options (in increasing complexity):**
1. **MongoDB Atlas M0 (free tier)** — provision externally, store URI as \`ruvocal-mongodb-url\` secret, stop using \`INCLUDE_DB\`. Cleanest for a beta.
2. **Cloud Run multi-container with mongo sidecar + Cloud Storage volume** — keep self-contained, gain persistence between cold starts. Needs the GA "Cloud Storage volume mounts" feature and a service-YAML rewrite.
3. **MongoDB on Compute Engine** — full control, ops overhead.

### Authentication (P1)
**Current:** \`AUTOMATIC_LOGIN=false\`, \`OPENID_CLIENT_ID=""\` — anonymous sessions only. Conversations persist by \`sessionId\` cookie.

**Wanted:** Google OAuth via OpenID Connect so we can show "Settings → Application" admin diagnostics, attach memory namespaces to a user, and enable per-user usage caps.

### UI: parallel tool-call visualization (P2)
The server already runs tools in parallel. The UI **renders** each tool-call card as it lands but doesn't visually group a single "step" the way Claude Code's task panel does (with collapsed thumbnails, durations, and parallel lanes). Worth a UX pass on \`ChatMessage.svelte\` and \`ToolUpdate.svelte\`.

### LLM router / Omni mode (P3)
\`LLM_ROUTER_ARCH_BASE_URL\` is empty so the auto-routing alias model isn't created. Re-enable when a smart router (Arch-Router) is hosted somewhere reachable.

### Bridge backend reliability (P2)
- The mcp-bridge cold-start issue (45–60s for ruflo / ruvector to boot) is mitigated by \`min-instances=1\` but not eliminated. Investigate whether the npm globals can be pre-warmed at image-build time more aggressively, or switch to npx with a global cache mount.
- Some optional groups (\`security\`, \`browser\`, \`neural\`, \`agentic-flow\`, \`claude-code\`, \`gemini\`, \`codex\`) ship in the Dockerfile but are gated by \`MCP_GROUP_*=true\` env vars and not enabled in the deploy. Audit and turn on the safe ones.

### Documentation (P2)
- README has the new section + capability table row (commit \`5cb4ca4f9\`).
- \`ADR-033\` is comprehensive but doesn't cover the OpenRouter provider switch as a follow-up; appendix needed.
- No user-facing docs page yet on \`docs.ruv.io\` or similar.

---

## 🐛 Known issues

1. **Gemini 2.5 Flash sometimes opts out of tool calls and returns empty content** when the conversation grows. \`final answer emitted (no tool_calls)\` then \`No output generated after streaming\`. Fix: select Claude Sonnet 4.6 (now default) or Gemini 2.5 Pro.
2. **\`/api/v2/debug/config\` returns 403** for non-admin users. By design — that endpoint is admin-gated. Only visible from Settings → Application. Cosmetic console error.
3. **First-time visitors see a 30+s cold start** if Cloud Run scales to zero on the bridge. The chat-ui side has \`min-instances=0\`; consider raising to 1 if user volume justifies it.
4. **MCP "Sorry, something went wrong"** on Gemini OAI-compat endpoint when sending tool results back as conversation history (\`Error: 400 status code (no body)\`). Fixed by switching default to Claude.
5. **WASM gallery is currently the mock implementation** (\`[WASM] Using mock rvagent-wasm implementation\`). The real \`rvagent_wasm.{js,wasm}\` ships but the mock fallback runs because the actual init script isn't wired into \`app.html\`. Tracking separately.
6. **Help modal still says "default: Gemini 2.5 Flash"** in the Quick Start text. One-line copy fix.

---

## 📂 Source layout reference

\`\`\`
ruflo/src/ruvocal/ # SvelteKit fork
├── src/
│ ├── lib/
│ │ ├── wasm/ # WASM MCP loader, IDB, tests
│ │ ├── components/wasm/ # GalleryPanel
│ │ ├── components/RufloHelpModal.svelte
│ │ ├── stores/wasmMcp.ts # Svelte store (main-thread for now)
│ │ ├── stores/mcpServers.ts # Multi-server registry
│ │ └── constants/{mcpExamples,routerExamples}.ts # RuFlo prompts
│ └── routes/... # SvelteKit routes
├── mcp-bridge/ # Express + spawn(npx ruflo|ruvector)
│ ├── index.js # Routes /mcp/, /mcp-servers
│ ├── mcp-stdio-kernel.js # Kept for future RVF tunnel
│ └── cloudbuild.yaml
├── static/wasm/rvagent_wasm.{js,wasm}
├── cloudbuild.yaml # ruvocal image build + Cloud Run deploy
├── .gcloudignore # CRITICAL — see ADR-033
└── Dockerfile # Multi-stage, INCLUDE_DB support
\`\`\`

---

## Acceptance criteria for closing this issue

- [ ] Web Workers wrap WASM MCP (P1)
- [ ] Persistent MongoDB (Atlas or Cloud Run volume) (P1)
- [ ] Google OAuth login enabled (P1)
- [ ] Parallel tool-call visualization parity with Claude Code (P2)
- [ ] Optional MCP groups (\`security\`, \`browser\`, \`neural\`, \`gemini\`, \`codex\`) enabled and tested (P2)
- [ ] Real \`rvagent_wasm\` wired into \`app.html\` (replace mock) (P2)
- [ ] Help-modal copy fixed ("default: Claude Sonnet 4.6") (P3)
- [ ] LLM router (Omni) enabled (P3)

cc @ruvnet

This is a multi-workstream roadmap rather than a single first contribution. Choose one acceptance-criteria item, then start with the named entry points such as src/lib/wasm/index.ts, src/lib/stores/wasmMcp.ts, ChatMessage.svelte, or ToolUpdate.svelte and run the stated checks or smoke test. Done is defined by the selected checklist item and its related validation.

Written by the indexing model from the issue text.