wave3d-agent-sdk

WaveEngine Agent SDK for same-machine Wave Studio MCP plus bundled WaveEngine lookup.

This package has two jobs:

• start: long-running live MCP transport for same-machine Studio reads/writes.
• bundled WaveEngine SDK Cache: local skill/API/example lookup, auto-prepared by start, cache status, and cache search.

Do not use SDK cache commands to switch MCP transport. Do not treat SDK cache failure as WaveEngine Agent SDK transport failure.

Vocabulary:

• WaveEngine Agent SDK: same-machine live MCP transport from wave3d-agent-sdk start.
• HTTP Gateway: Wave Studio Next/Vercel MCP transport for remote/cloud/sandbox fallback Studio operations.
• WaveEngine SDK Cache: package-bundled public-safe skill/API/example lookup data.
• MCP Session: paired Wave Studio browser session and MCP_TOKEN state.
• Local Pairing Secret: MCP_TOKEN on localhost. It pairs the local SDK process to the current Studio session; it is not account/cloud auth.
• HTTP Gateway Bearer: MCP_TOKEN on an HTTP Gateway URL. It can be adopted locally, but localhost health remains the source of truth for SDK state.
• VFS Mirror: HTTP Gateway read/edit snapshot. Local SDK live reads/writes use browser VFS.
• Project: user workspace content. Reading a project is not opening/replacing live workspace.

npx -y [email protected] start

After Copy to Agent, restart stale SDK processes with MCP_TOKEN preserved as the local pairing secret. Keep it hidden:

WAVE3D_MCP_TOKEN="$MCP_TOKEN" npx -y [email protected] start

Check SDK build before trusting a running SDK process:

npx -y [email protected] --version

The package bundles the WaveEngine SDK lookup corpus. No normal session needs a separate protected zip download.

Recommended Agent Flow

Wave Studio Copy to Agent defaults same-machine live MCP transport to this SDK:

npx -y [email protected] start

Agents choose topology first:

• Same computer as Wave Studio browser: try copied localhost MCP_URL, call self_check_wave_mcp with copied expectedVersion and expectedBuildHash, and restart exact SDK command from Copy to Agent if self_check_wave_mcp is missing, SDK is stale, tools are missing, or the SDK prints secrets before fallback. If restart happens after Copy to Agent, preserve MCP_TOKEN with WAVE3D_MCP_TOKEN="$MCP_TOKEN" so the new SDK process can authorize that local pairing secret. HTTP Gateway is degraded fallback only after SDK cannot run, update, or adopt; successful Gateway auth or convenience is not a same-machine fallback reason.
• Different machine, remote container, cloud agent, sandbox without shell/Node/npm, or localhost points to agent machine instead of user browser machine: use MCP_HTTP_GATEWAY_FALLBACK_URL directly. Do not start WaveEngine Agent SDK on wrong machine.

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

Use MCP_HTTP_GATEWAY_FALLBACK_URL only for topology mismatch, remote/sandboxed runtime, or an SDK runtime that cannot run/update/adopt after same-machine repair. HTTP Gateway is for Studio operations. It does not provide cloud API lookup.

For unfamiliar authoring, use the local SDK tools:

npx -y [email protected] cache search "continuous left rotation"

cache refresh without MCP arguments reinstalls the bundled SDK into ~/.wave3d/agent-cache:

npx -y [email protected] cache refresh

Old cache refresh --mcp-url <url> --token <token> arguments are ignored. Normal users update the npm package; no separate zip download exists.

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, 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.

Commands

wave3d-agent-sdk --version
wave3d-agent-sdk start
wave3d-agent-sdk doctor
wave3d-agent-sdk cache status
wave3d-agent-sdk cache refresh
wave3d-agent-sdk cache search "rotate around left"
wave3d-agent-sdk cache clear

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

start exposes 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 HTTP Gateway tool catalog plus SDK session discovery extras; if a hosted tool is missing locally, SDK process is stale or broken. Restart it with exact package version in Copy to Agent.

cache refresh validates and extracts the bundled WaveEngine SDK zip under ~/.wave3d/agent-cache, then builds a MiniSearch index. It never fetches a remote SDK zip.

Security Defaults

• SDK listens on 127.0.0.1 by default.
• Non-loopback hosts require --allow-network and should only be used on trusted network.
• Studio browser routes require trusted Wave Studio Origin header.
• Bundled SDK files are hash-checked, path-sanitized, and size-bounded before extraction.
• Legacy remote SDK download arguments are ignored; bundled SDK files are the only supported source.
• cache clear refuses dangerous paths and unmarked custom cache directories.

Token Safety

Treat Wave Studio MCP_TOKEN values as secrets. Prefer passing them through WAVE3D_MCP_TOKEN or WAVESTUDIO_MCP_TOKEN rather than shell history when possible.