tasq/node_modules/@ruvector/rvagent-wasm/README.md

rvagent-wasm

WASM bindings for rvAgent — run AI agents entirely in the browser or Node.js.

Features

• WasmAgent — Full agent execution in browser/Node.js with conversation history
• WasmMcpServer — MCP JSON-RPC server running in the browser (no backend required)
• Virtual Filesystem — In-memory file operations for sandboxed execution
• Gallery System — Built-in agent templates with RVF container export
• Zero Dependencies — Runs entirely client-side via WebAssembly

Installation

# Build from source
cd crates/rvAgent/rvagent-wasm
wasm-pack build --target web

# Or use the pre-built package
npm install rvagent-wasm  # (Not yet published)

Usage

WasmAgent

import init, { WasmAgent } from 'rvagent-wasm';

await init();

// Create an agent
const agent = new WasmAgent(JSON.stringify({
  model: "anthropic:claude-sonnet-4-20250514",
  name: "my-agent",
  instructions: "You are a helpful coding assistant.",
  max_turns: 50
}));

// Connect a model provider (calls your LLM API)
agent.set_model_provider(async (messagesJson) => {
  const messages = JSON.parse(messagesJson);
  const response = await fetch('/api/chat', {
    method: 'POST',
    body: JSON.stringify({ messages })
  });
  return (await response.json()).content;
});

// Send a prompt
const result = await agent.prompt("Write a hello world function");
console.log(result.response);

// Execute tools directly
agent.execute_tool('{"tool": "write_file", "path": "hello.js", "content": "console.log(\"Hello!\");"}');

// Check state
console.log(agent.turn_count());      // 1
console.log(agent.file_count());      // 1
console.log(agent.get_todos());       // []

WasmMcpServer

Run an MCP server entirely in the browser:

import init, { WasmMcpServer } from 'rvagent-wasm';

await init();

const mcp = new WasmMcpServer("rvagent-wasm");

// Handle MCP JSON-RPC requests
const response = mcp.handle_request(JSON.stringify({
  jsonrpc: "2.0",
  id: 1,
  method: "initialize",
  params: {}
}));

// List available tools
const tools = mcp.list_tools();

// Call a tool
const result = mcp.call_tool("write_file", JSON.stringify({
  path: "demo.txt",
  content: "Hello from WASM!"
}));

Gallery System

Access built-in agent templates:

// List all templates
const templates = mcp.handle_request(JSON.stringify({
  jsonrpc: "2.0",
  id: 1,
  method: "gallery/list",
  params: {}
}));

// Search templates
const searchResults = mcp.handle_request(JSON.stringify({
  jsonrpc: "2.0",
  id: 2,
  method: "gallery/search",
  params: { query: "coding assistant" }
}));

// Load a template
const loaded = mcp.handle_request(JSON.stringify({
  jsonrpc: "2.0",
  id: 3,
  method: "gallery/load",
  params: { id: "claude-code" }
}));

Available Tools

Tool	Description
read_file	Read file from virtual filesystem
write_file	Write file to virtual filesystem
edit_file	Apply string replacement to a file
list_files	List all files in virtual filesystem
write_todos	Manage todo list

Note: OS-level tools (execute, glob, grep) are intentionally omitted as they require system access unavailable in the browser sandbox.

MCP Methods

Method	Description
initialize	Initialize MCP connection
ping	Health check
tools/list	List available tools
tools/call	Execute a tool
resources/list	List virtual filesystem as resources
prompts/list	List prompts from active template
gallery/list	List all agent templates
gallery/search	Search templates by query
gallery/get	Get template details
gallery/load	Load template as active config
gallery/configure	Apply config overrides
gallery/categories	List template categories

API Reference

WasmAgent

Method	Description
new(configJson)	Create agent from JSON config
set_model_provider(callback)	Set JS callback for LLM calls
prompt(input)	Send prompt, get response (async)
execute_tool(toolJson)	Execute a tool directly
get_state()	Get conversation state as JSON
get_todos()	Get todo list as JSON
get_tools()	Get available tools
reset()	Clear state and start fresh
version()	Get crate version
name()	Get agent name
model()	Get model identifier
turn_count()	Get current turn count
is_stopped()	Check if agent is stopped
file_count()	Get virtual filesystem file count

WasmMcpServer

Method	Description
new(name)	Create MCP server
handle_request(json)	Handle JSON-RPC request
list_tools()	Get available tools as JSON
call_tool(name, paramsJson)	Call tool by name
gallery()	Get gallery info
is_initialized()	Check initialization status
name()	Get server name
version()	Get server version

Building

# Install wasm-pack
cargo install wasm-pack

# Build for web
wasm-pack build --target web

# Build for Node.js
wasm-pack build --target nodejs

# Run tests
cargo test
wasm-pack test --headless --chrome

Security

• Request size limit: 100 KB
• Path length limit: 256 characters
• Content length limit: 1 MB
• Path traversal (..) blocked
• Todo count limit: 1000 items

Architecture

rvagent-wasm/
├── src/
│   ├── lib.rs        # WasmAgent — main agent type
│   ├── backends.rs   # WasmStateBackend — virtual filesystem
│   ├── bridge.rs     # JsModelProvider — JS interop
│   ├── gallery.rs    # WasmGallery — template system
│   ├── mcp.rs        # WasmMcpServer — MCP protocol
│   ├── rvf.rs        # RVF container support
│   └── tools.rs      # Tool definitions and executor
└── pkg/              # Built WASM package
    ├── rvagent_wasm.js
    ├── rvagent_wasm.d.ts
    └── rvagent_wasm_bg.wasm

Related Crates

Crate	Description
rvagent-core	Agent state, graph, config
rvagent-backends	Backend protocol + implementations
rvagent-tools	Full tool implementations
rvagent-mcp	Native MCP client/server
rvagent-cli	Terminal UI

License

MIT OR Apache-2.0