π The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated
TypeScript agentic-aiagentic-frameworkagentic-workflowagentsai-agentsai-assistantai-skillsautonomous-agentsclaudecodexdsh-pluginharnessmcp-servermulti-agentmulti-agent-systemsnpmskillsswarmswarm-intelligencetypescript
docs(adr-033): consolidate mid-iteration changes + follow-up matrix
Reuven6e048a511771
diff --git a/ruflo/docs/adr/ADR-033-RUVOCAL-WASM-MCP-INTEGRATION.md b/ruflo/docs/adr/ADR-033-RUVOCAL-WASM-MCP-INTEGRATION.mdindex 3236a0625e..17f029f18d 100644--- a/ruflo/docs/adr/ADR-033-RUVOCAL-WASM-MCP-INTEGRATION.md+++ b/ruflo/docs/adr/ADR-033-RUVOCAL-WASM-MCP-INTEGRATION.md@@ -145,19 +145,77 @@ TASK_MODEL=gemini-2.5-flashEarlier attempts with `https://router.huggingface.co/v1` returned `401 "Invalid username or password"` because the available `huggingface-token` secret doesn't auth against the user-facing router endpoint, and the OpenRouter API key was incorrectly mapped against the HF base URL. Google's OpenAI-compatible endpoint accepts `GOOGLE_AI_API_KEY` directly and exposes 56 Gemini variants.-### Known Issue (Out of Scope)+### Known Issue (RESOLVED 2026-05-01)-The homepage `/` returns HTTP 500 in production due to the `/api/v2/models` and `/api/v2/models/refresh` routes returning the SvelteKit "Page not found" page wrapped in a 500 status. Other `/api/v2/*` routes work normally. This is reproducible across multiple Cloud Run revisions and across both HuggingFace router and OpenRouter as the upstream provider β but does **not** reproduce locally with `npm run dev` using the same `.env`.+~~The homepage `/` returns HTTP 500 in production due to the `/api/v2/models` and `/api/v2/models/refresh` routes returning the SvelteKit "Page not found" page wrapped in a 500 status.~~-The error stack consistently points at `handleResponse (file:///app/build/server/chunks/APIClient-bd1S52Pj.js:421:11)` from the `+layout.ts` server-side `Promise.all` (index 1 = `client.models.get()`). The `models.ts` server module does refresh successfully (logs show `[models] Parsed models count: 129`, `[models] Model cache refreshed`) β the issue is between cache build and route response, specific to the production `adapter-node` build.+**Root cause** (found after extensive investigation): `.gitignore` line 16 was `models/*` (unanchored). With no `.gcloudignore` present, `gcloud builds submit` falls back to `.gitignore` for upload filtering β that pattern matched **every** `models/` directory in the tree, stripping `src/routes/api/v2/models/*` and `src/routes/models/*` from the source tarball **before Docker even saw it**. SvelteKit production builds inside the container therefore had no `/api/v2/models` route registered, so requests returned 404 which got wrapped as 500 by the layout chain.-This is unrelated to the WASM-MCP integration that this ADR covers; the WASM client code is shipped and serves correctly. The 500 is an HF chat-ui / SvelteKit production-build edge case worth a separate investigation (likely candidates: `superjson.stringify` over `getEndpoint` closures, a circular import in `chunks/models.js`, or route matcher caching for the `/api/v2/models` subtree).+**Fix:** `ruflo/src/ruvocal/.gcloudignore` (commit `e3b74f606`). All `/api/v2/*` routes now serve correctly. Verified via `gsutil cp` of the build's source tarball that all `+server.ts` files for the models subtree are present after the fix.++## Mid-Iteration Updates (2026-05-01)++This section consolidates changes that landed after the initial PR (#1687) merged:++### Provider switch: OpenRouter / Claude Sonnet 4.6 default++Gemini 2.5 Flash via the OpenAI-compat endpoint returned `Error: 400 status code (no body)` on the **follow-up call after a tool result** (the chat-ui sends the tool message back to the model in the next turn; Gemini's compat layer rejected the structure intermittently). The result was the user-visible "Sorry, something went wrong" after a tool fired.++Switched the deployed default to **Claude Sonnet 4.6 via OpenRouter** with `OPENAI_BASE_URL=https://openrouter.ai/api/v1` and `OPENAI_API_KEY` mapped from the `OPENROUTER_API_KEY` Secret Manager secret. Models exposed: Claude Sonnet 4.6 (default), Claude Opus 4.7, Claude Haiku 4.5, Gemini 2.5 Pro, Gemini 2.5 Flash, GPT-4o.++The system prompt explicitly instructs the model to emit multiple `tool_calls` in a single response when the request implies multiple independent steps. Server logs confirmed `toolMsgCount: 4` and `toolMsgCount: 6` β multiple tools dispatched in parallel via `Promise.all` in `src/lib/server/textGeneration/mcp/toolInvocation.ts`.++### MCP Bridge service (`mcp-bridge` on Cloud Run)++Deployed in parallel with `ruvocal` to expose 207 tools across 5 server groups (Core / Intelligence / Agents / Memory / DevTools). Pinned `--min-instances=1 --max-instances=1` so backends stay warm β Cloud Run was previously routing requests to cold instances that had not yet finished spawning `npx ruflo mcp start` and `npx ruvector mcp start`. Bumped the bridge's MCP `initialize` RPC timeout from 30s β 120s to handle cold-start boot times.++### Web Worker for WASM MCP (opt-in)++Added `src/lib/wasm/wasm.worker.ts` and `src/lib/wasm/workerClient.ts`. When the user opts in via `?worker=1` URL param or `localStorage.setItem("ruflo:wasm-worker", "true")`, `callMcp` routes through a worker-owned mock WasmMcpServer instead of the in-process module. Default behavior (in-process path) is unchanged.++The worker is self-contained β it does not import `$app/environment` (which is unresolvable in worker context) and ships a minimal `read_file / write_file / list_files` MCP surface as a placeholder until the real `rvagent_wasm.js` bundle is wired in.++### Custom domains++Mapped via Cloudflare DNS (CNAME unproxied so Google manages the cert):+- `flo.ruv.io` (primary)+- `ruflo.ruv.io`+- `ruvocal.ruv.io`++### UX additions++- **Help icon** in sidebar opens "RuFlo Capabilities" modal (`src/lib/components/RufloHelpModal.svelte`) with all 6 tool groups, quick-start, tips, and resource links.+- **8 RuFlo-themed example prompts** on the welcome screen (`src/lib/constants/{mcpExamples,routerExamples}.ts`) replacing HF defaults.+- **`PUBLIC_APP_NAME=RuFlo`** brands the title bar, sidebar, welcome modal, and PWA manifest.++### Bug fixes++- `mcp-bridge` returns a structured hint object instead of opaque 400 when `search` is called with an empty query (`Error: search requires a non-empty query string`).+- `cloudbuild.yaml` deploy step strips its `--set-env-vars` / `--set-secrets` flags so subsequent rebuilds preserve manually configured env (DOTENV_LOCAL with `MODELS`, `OPENAI_BASE_URL`, etc.). Initial env config is now set out-of-band via `gcloud run services update`.+- `DOCKER_BUILDKIT=1` env on the cloudbuild docker step (Dockerfile uses `COPY --link` BuildKit syntax).++## Follow-Up Work (tracked separately in [issue #1689](https://github.com/ruvnet/ruflo/issues/1689))++| Priority | Item | Notes |+|----------|------|-------|+| **P1** | **Make Web Worker mode default** | Currently opt-in (`?worker=1`). Blocked on bringing the worker's mock to parity with the main-thread mock (worker has 3 tools, main has 18) and on importing the real `rvagent_wasm.js` bundle into worker context. |+| **P1** | **Persistent MongoDB** | Cloud Run filesystem is ephemeral β chat history evicts on cold starts. Options (cleanest first): MongoDB Atlas M0 free tier with `MONGODB_URL` from Secret Manager; Cloud Run multi-container with `mongo:8` sidecar + GCS volume mount; MongoDB on Compute Engine. |+| **P1** | **Google OAuth login** | `OPENID_CLIENT_ID=""` today β anonymous sessions only. Wanted for admin diagnostics, per-user memory namespaces, and usage caps. Set `OPENID_CLIENT_ID`, `OPENID_CLIENT_SECRET`, `OPENID_SCOPES`. |+| **P2** | **Parallel tool-call visualization parity with Claude Code task panel** | Server-side parallel execution works; UI renders one tool-call card per call but doesn't visually group them as a single "step" with collapsed thumbnails, lane layout, or per-tool durations. UX pass needed on `ChatMessage.svelte` and `ToolUpdate.svelte`. |+| **P2** | **Real `rvagent_wasm` wired into worker** | Static bundle (`static/wasm/rvagent_wasm.{js,wasm}`) ships at 588 KB. Currently the page bundle uses `createMockWasmModule()` because the real WASM isn't loaded into `app.html`. Need a `<script type="module">` block (or worker-level `import("/wasm/rvagent_wasm.js")`) that calls `init()` and exposes the constructors on the global before `loadWasm()` runs. |+| **P3** | **Help-modal copy fix** | Quick Start section says "default: Gemini 2.5 Flash". Update to "default: Claude Sonnet 4.6" in `src/lib/components/RufloHelpModal.svelte`. |+| **P3** | **LLM router (Omni mode)** | `LLM_ROUTER_ARCH_BASE_URL` is empty so the auto-routing alias model isn't created. Re-enable when an Arch-Router is hosted somewhere reachable; restore `LLM_ROUTER_ROUTES_PATH` and the related `LLM_ROUTER_*` env vars. |## References- Upstream source: `https://github.com/ruvnet/ruvector` β `ui/ruvocal/`- Local target: `ruflo/src/ruvocal/`-- Branch: `feat/ruvocal-wasm-mcp-integration`+- Branch: `feat/ruvocal-wasm-mcp-integration` (squash-merged to `main`)- PR: https://github.com/ruvnet/ruflo/pull/1687-- Cloud Build config: `ruflo/src/ruvocal/cloudbuild.yaml`+- Follow-up issue: https://github.com/ruvnet/ruflo/issues/1689+- Cloud Build configs: `ruflo/src/ruvocal/cloudbuild.yaml`, `ruflo/src/ruvocal/mcp-bridge/cloudbuild.yaml`+- `.gcloudignore` (CRITICAL β see resolved root cause): `ruflo/src/ruvocal/.gcloudignore`+- Web Worker: `ruflo/src/ruvocal/src/lib/wasm/{wasm.worker.ts,workerClient.ts}`+- Help modal: `ruflo/src/ruvocal/src/lib/components/RufloHelpModal.svelte`+- Live URLs: https://flo.ruv.io/ Β· https://ruflo.ruv.io/ Β· https://ruvocal.ruv.io/- Related deployment ADR: ADR-029 (HF Chat UI on Cloud Run)