wave3d-agent-bridge

Same-machine Wave Studio Local Agent Helper.

This package has two separate modes:

• start: long-running live MCP transport for same-machine Studio reads/writes.
• cache refresh: one-shot local docs retrieval for skill/API/example search.

Do not use cache refresh to switch MCP transport, and do not treat cache failure as Local Agent Helper transport failure.

Vocabulary:

• Local Agent Helper: same-machine live MCP transport from wave3d-agent-bridge start.
• HTTP Gateway: Wave Studio Next/Vercel MCP transport, local dev or hosted production.
• Corpus Cache: one-shot local docs/API/skill retrieval from cache refresh.
• MCP Session: paired Wave Studio browser session and bearer-token state.
• VFS Mirror: HTTP Gateway read/edit hash snapshot. Local helper live reads/writes use the browser VFS.
• Project: user workspace content. Reading a project is not opening/replacing the live workspace.

npx -y [email protected] start

Check the helper build before trusting a running local process:

npx -y [email protected] --version

The package does not bundle the Wave Studio skill/API corpus. It downloads that corpus after a paired localhost Wave Studio dev server or an authorized hosted Wave Studio MCP endpoint/token provides the cache manifest.

Recommended Agent Flow

Wave Studio's Copy to Agent message defaults live MCP transport to this helper:

npx -y [email protected] start

Agents should choose topology first:

• Same computer as the Wave Studio browser: try the copied localhost MCP_URL, call self_check_wave_mcp with the copied expectedVersion and expectedBuildHash, and restart the exact helper command from Copy to Agent if the helper is stale, missing tools, or prints bearer tokens before fallback.
• Different machine, remote container, cloud agent, sandbox without shell/Node/npm, or localhost points to the agent machine instead of the user's browser machine: use MCP_HTTP_GATEWAY_FALLBACK_URL directly. Do not start Local Agent Helper on the wrong machine.

Call get_wave_mcp_health (aliases: mcp_health, mcp_status) whenever transport/helper/cache/session status is unclear. It reports the current endpoint kind, helper version/build, tool catalog hash/count, paired sessions, and Corpus Cache state.

Use MCP_HTTP_GATEWAY_FALLBACK_URL only for topology mismatch, remote/sandboxed runtime, or helper that cannot run/update/adopt after the same-machine repair path.

After successful transport selection and onboarding, use this separate Corpus Cache command only for local docs retrieval when unfamiliar authoring needs lookup and local Node/npm/filesystem cache are allowed:

npx -y [email protected] cache refresh --mcp-url "$MCP_URL" --token "$MCP_TOKEN"

That command downloads the authorized corpus, validates the zip manifest plus every file path/size/hash, extracts it under ~/.wave3d/agent-cache, and builds a local MiniSearch index. Refresh against the already chosen active endpoint: same-machine uses MCP_URL; non-local uses MCP_HTTP_GATEWAY_FALLBACK_URL. For non-local cache refresh, set MCP_URL to MCP_HTTP_GATEWAY_FALLBACK_URL before running the command template. When MCP_URL is localhost, Local Agent Helper first uses the paired localhost Wave Studio dev corpus when available; otherwise, if the copied bearer is HTTP-Gateway-capable, it proxies the protected manifest and zip through the same local endpoint. Do not ask for HTTP Gateway while helper restart or local dev corpus repair is still possible. If the user refuses local Node/npm or local caching, agents should skip Corpus Cache and use HTTP Gateway query tools online instead. Cache refresh does not create, repair, or select the live MCP transport.

Wave Studio MCP uses an Agent Behavior Harness. Assessment tools stay open so agents can inspect session/files/assets/skills/diagnostics when needed, but clear user requests should start a route early with start_wave_task. Exact API lookup and mutating tools require start_wave_task, a taskRouteId, and advance_wave_task when moving into lookup, execute, or verify phases. For exact power-user commands, agents should classify code.direct_edit; for obvious current-code pattern changes, classify code.semantic_guess_edit. These fast lanes skip broad skill/API lookup, not taskRouteId, deterministic edits, hot reload, or verification.

For same-machine live read/write, start the Local Agent Helper before or immediately after copying the MCP message:

npx -y [email protected] start

Commands

wave3d-agent-bridge --version
wave3d-agent-bridge start
wave3d-agent-bridge doctor
wave3d-agent-bridge cache status
wave3d-agent-bridge cache refresh --mcp-url <url> --token <token>
wave3d-agent-bridge cache search "rotate around left"
wave3d-agent-bridge cache clear

start runs the Local Agent Helper on 127.0.0.1:47231 by default. Wave Studio uses it when reachable from the same computer; different-machine/cloud/sandbox agents should use the HTTP Gateway instead of starting a helper on the wrong machine.

start exposes the same-machine live Studio tool surface, including project save/share/new/open/rename, VFS edits, preview run/hot reload, screenshots, runtime diagnostics, entity snapshots, runtime markers, and get_wave_runtime_performance_snapshot for FPS/tick-rate/scene-weight/heap telemetry. Local tools/list mirrors the HTTP Gateway tool catalog plus helper-only session discovery extras; if a hosted tool is missing locally, the helper process is stale or broken. Restart it with the exact package version in Copy to Agent.

cache refresh calls get_wave_agent_corpus_bundle on the provided MCP endpoint, downloads the returned zip from the same endpoint origin, validates the zip manifest plus every file path/size/hash, extracts it under ~/.wave3d/agent-cache, and builds a MiniSearch index. If the endpoint is Local Agent Helper paired to localhost Wave Studio dev, the helper proxies the local dev corpus. If the endpoint is Local Agent Helper and the bearer is HTTP-Gateway-capable, the helper proxies the protected corpus. No corpus files are shipped in this npm package.

Security Defaults

• The helper listens on 127.0.0.1 by default.
• Non-loopback hosts require --allow-network and should only be used on a trusted network.
• Studio browser routes require a trusted Wave Studio Origin header.
• Corpus downloads are restricted to the same origin as the MCP endpoint, hash-checked, path-sanitized, and size-bounded before extraction.
• cache clear refuses dangerous paths and unmarked custom cache directories.

Token Safety

Treat Wave Studio MCP bearer tokens as secrets. Prefer passing them through WAVE3D_MCP_TOKEN or WAVESTUDIO_MCP_TOKEN rather than shell history when possible.