wave3d-agent-sdk 0.2.0

package/README.md

@@ -0,0 +1,95 @@
+# 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 bearer-token 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.
+
+```bash
+npx -y wave3d-agent-sdk@0.2.0 start
+```
+
+Check SDK build before trusting a running SDK process:
+
+```bash
+npx -y wave3d-agent-sdk@0.2.0 --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:
+
+```bash
+npx -y wave3d-agent-sdk@0.2.0 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 SDK 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 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:
+
+```bash
+npx -y wave3d-agent-sdk@0.2.0 cache search "continuous left rotation"
+```
+
+`cache refresh` without MCP arguments reinstalls the bundled SDK into `~/.wave3d/agent-cache`:
+
+```bash
+npx -y wave3d-agent-sdk@0.2.0 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
+
+```bash
+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 bearer tokens as secrets. Prefer passing them through `WAVE3D_MCP_TOKEN` or `WAVESTUDIO_MCP_TOKEN` rather than shell history when possible.