wave3d-agent-sdk 0.2.2 → 0.2.4

package/README.md

@@ -19,13 +19,19 @@ Vocabulary:
 - Project: user workspace content. Reading a project is not opening/replacing live workspace.
 
 ```bash
-npx -y wave3d-agent-sdk@0.2.2 start
+npx -y wave3d-agent-sdk@0.2.4 start
+```
+
+After Copy to Agent, restart stale SDK processes with the copied bearer preserved. Keep the token hidden:
+
+```bash
+WAVE3D_MCP_TOKEN="$MCP_TOKEN" npx -y wave3d-agent-sdk@0.2.4 start
 ```
 
 Check SDK build before trusting a running SDK process:
 
 ```bash
-npx -y wave3d-agent-sdk@0.2.2 --version
+npx -y wave3d-agent-sdk@0.2.4 --version
 ```
 
 The package bundles the WaveEngine SDK lookup corpus. No normal session needs a separate protected zip download.
@@ -35,12 +41,12 @@ The package bundles the WaveEngine SDK lookup corpus. No normal session needs a
 Wave Studio Copy to Agent defaults same-machine live MCP transport to this SDK:
 
 ```bash
-npx -y wave3d-agent-sdk@0.2.2 start
+npx -y wave3d-agent-sdk@0.2.4 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.
+- 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 bearer tokens before fallback. If restart happens after Copy to Agent, preserve the copied bearer with `WAVE3D_MCP_TOKEN="$MCP_TOKEN"` so the new SDK process can authorize that local bearer.
 - 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.
@@ -50,13 +56,13 @@ Use `MCP_HTTP_GATEWAY_FALLBACK_URL` only for topology mismatch, remote/sandboxed
 For unfamiliar authoring, use the local SDK tools:
 
 ```bash
-npx -y wave3d-agent-sdk@0.2.2 cache search "continuous left rotation"
+npx -y wave3d-agent-sdk@0.2.4 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.2 cache refresh
+npx -y wave3d-agent-sdk@0.2.4 cache refresh
 ```
 
 Old `cache refresh --mcp-url <url> --token <token>` arguments are ignored. Normal users update the npm package; no separate zip download exists.

package/dist/cli.js

@@ -42533,10 +42533,12 @@ function normalizeWaveGenieAssetUploadRequest(request) {
 
 // ../../src/lib/waveStudio/aiAssist/bridge/localAgentSdkContract.ts
 var WAVE3D_AGENT_SDK_PACKAGE_NAME = "wave3d-agent-sdk";
-var WAVE3D_AGENT_SDK_REQUIRED_VERSION = "0.2.2";
-var WAVE3D_AGENT_SDK_REQUIRED_BUILD = "agent-sdk-20260617.3";
+var WAVE3D_AGENT_SDK_REQUIRED_VERSION = "0.2.4";
+var WAVE3D_AGENT_SDK_REQUIRED_BUILD = "agent-sdk-20260617.5";
 var WAVE3D_AGENT_SDK_PACKAGE_SPEC = `${WAVE3D_AGENT_SDK_PACKAGE_NAME}@${WAVE3D_AGENT_SDK_REQUIRED_VERSION}`;
 var WAVE3D_AGENT_SDK_START_COMMAND = `npx -y ${WAVE3D_AGENT_SDK_PACKAGE_SPEC} start`;
+var WAVE3D_AGENT_SDK_TOKEN_ENV_VAR = "WAVE3D_MCP_TOKEN";
+var WAVE3D_AGENT_SDK_TOKEN_PRESERVING_START_COMMAND = `${WAVE3D_AGENT_SDK_TOKEN_ENV_VAR}="$MCP_TOKEN" ${WAVE3D_AGENT_SDK_START_COMMAND}`;
 var WAVE3D_AGENT_SDK_CACHE_REFRESH_COMMAND_TEMPLATE = `npx -y ${WAVE3D_AGENT_SDK_PACKAGE_SPEC} cache refresh`;
 var WAVE3D_AGENT_SDK_CACHE_REFRESH_SHELL_COMMAND = `npx -y ${WAVE3D_AGENT_SDK_PACKAGE_SPEC} cache refresh`;
 
@@ -44428,7 +44430,7 @@ var WAVE_MCP_AGENT_BRIEF = [
   '0-role. Roleplay lock: you are the Wave Studio authoring agent for this session. Stay in that role, follow Wave authoring strategy, use concrete MCP tools, and briefly confirm "Wave Studio authoring role accepted" after onboarding acceptance.',
   "0. Think in skills, act with tools. `studio.*` names are routing families, not callable tool names; call the real MCP tools listed under each family.",
   "0a. Do not invent MCP tool names. After onboarding, call `tools/list` (or read the returned tool catalog) and use concrete names. Common aliases and safe high-confidence typos are tolerated; destructive/write fuzzy matches require an exact follow-up call. There is no `get_wave_current_project`; use `get_wave_session` for current project/session/active-file context.",
-  `0b. Transport rule: choose topology first. Same-machine agent + same Wave Studio browser computer -> use copied \`MCP_URL\` WaveEngine Agent SDK (\`http://127.0.0.1:47231/mcp\`). If localhost is refused/unreachable, start exact SDK \`${WAVE3D_AGENT_SDK_START_COMMAND}\` when your runtime allows shell/Node/npm. If SDK is stale, missing tools, or prints bearer tokens, stop it and restart with that exact command, then recheck /health and tools/list. Same-machine stale/missing tools/401-with-Gateway-success means repair local SDK first, do not use HTTP Gateway first. Different machine, remote container, cloud agent, sandbox without shell/Node/npm, or localhost points to the agent machine -> use \`MCP_HTTP_GATEWAY_FALLBACK_URL\` directly. Do not start WaveEngine Agent SDK on the wrong machine.`,
+  `0b. Transport rule: choose topology first. Same-machine agent + same Wave Studio browser computer -> use copied \`MCP_URL\` WaveEngine Agent SDK (\`http://127.0.0.1:47231/mcp\`). If localhost is refused/unreachable, start exact SDK \`${WAVE3D_AGENT_SDK_START_COMMAND}\` when your runtime allows shell/Node/npm. If SDK is stale, missing tools, printing bearer tokens, or local 401 follows an SDK restart, stop it and restart while preserving the copied bearer with \`${WAVE3D_AGENT_SDK_TOKEN_PRESERVING_START_COMMAND}\`; use the current MCP_TOKEN value without printing it. Then recheck /health and tools/list. Same-machine stale/missing tools/401-with-Gateway-success means repair local SDK first, do not use HTTP Gateway first. Different machine, remote container, cloud agent, sandbox without shell/Node/npm, or localhost points to the agent machine -> use \`MCP_HTTP_GATEWAY_FALLBACK_URL\` directly. Do not start WaveEngine Agent SDK on the wrong machine.`,
   "0b-recovery. If connection/session/onboarding/cache/mirror/timeout state is unclear, call `get_wave_mcp_health` (aliases `mcp_health`, `mcp_status`) first for status, then call `recover_wave_connection({ lastErrorCode?, failedTool?, symptom? })` and follow its `nextAction` exactly. Use recovery after `agent_onboarding_required`, `session_not_found`, `command_timeout`, `command_lease_expired`, `workspace_mirror_not_ready`, `hosted_mcp_proxy_failed`, local/HTTP Gateway fallback confusion, or sleeping-tab symptoms. If local HTTP returns 401 but HTTP Gateway accepts the same token, update/restart WaveEngine Agent SDK first. If every endpoint returns 401/bridge_auth_invalid before any tool result, ask user for fresh Copy to Agent.",
   `0c. Cache priorities: Priority 1 is active role/context cache. Keep the role, coding guardrails, authoring workflow, full intent taxonomy (${WAVE_MCP_TASK_INTENT_KIND_VALUES.join(", ")}), Studio tool policy, assets/VFS/hot-reload rules, prompt version, and prompt hash in active LLM context as system-prompt-like rules. Priority 2 is WaveEngine SDK Cache. Production HTTP Gateway/local-SDK bearer onboarding must not claim normal cached success until SDK cache is prepared or explicit accept proof passes. If cache cannot work because sandbox/no filesystem/no Node/npm/user refusal/refresh failure, accept degraded fallback explicitly with \`waveEngineSdkFallbackMode:"studio_ops_only"\` plus \`waveEngineSdkUnavailableReason\` plus \`studioOpsOnlyFallbackAccepted:true\`, and warn user HTTP Gateway is Studio-ops-only and exact API lookup requires local SDK/cache repair. Keep live transport and retrieval cache separate: \`wave3d-agent-sdk start\` is long-running MCP transport; \`wave3d-agent-sdk cache refresh\` reinstalls the package-bundled SDK locally. Never use cache refresh to switch MCP transport, and never treat cache failure as local transport failure. Use SDK Cache for unfamiliar authoring skill/API lookup when Node/npm/local cache are allowed.`,
   '0d. Local parity rule: WaveEngine Agent SDK `tools/list` mirrors the HTTP Gateway catalog plus SDK session discovery extras. Live-session tools run through the paired browser. Local calls wait directly for browser results. Only call `get_wave_command_result` when a tool response actually includes `status:"pending"` and `requestId`; on local it is normally catalog parity only.',
@@ -44671,7 +44673,7 @@ var WAVE_MCP_STUDIO_TOOL_GUIDE = [
   "- MCP names: HTTP Gateway = Next/Vercel endpoint for remote/sandbox Studio operations; WaveEngine Agent SDK = same-machine live MCP transport from long-running `wave3d-agent-sdk start`; WaveEngine SDK Cache = package-bundled local skill/API docs retrieval; VFS Mirror = HTTP Gateway workspace snapshot. Do not confuse these modules.",
   "- MCP recovery: when connection/session/onboarding/cache/mirror/timeout state is unclear, call `recover_wave_connection({ lastErrorCode?, failedTool?, symptom? })` first and follow its returned `nextAction`. This is the explicit recovery path for sleeping tabs, local/HTTP Gateway confusion, mirror-not-ready, onboarding-required, command timeout/lease expiry, and hosted proxy/cache failures.",
   '- Local parity rule: WaveEngine Agent SDK `tools/list` mirrors the HTTP Gateway catalog plus SDK session discovery extras. Direct local live-session tools include VFS edits, assets/uploads, project save/open/new/read/share, preview run/hot reload, diagnostics, performance, screenshots, entity snapshots, and runtime markers. Local browser-backed calls wait directly for browser results. Only call `get_wave_command_result` if a tool returns `status:"pending"` plus `requestId`; on local it normally exists only for catalog parity and reports no local pending-command queue.',
-  `- MCP topology: same-machine agents should run \`${WAVE3D_AGENT_SDK_START_COMMAND}\`, check /health, and update/restart SDK if version is stale, tools are missing, or SDK prints bearer tokens; after restart recheck /health and tools/list. Same-machine stale/missing tools/401-with-Gateway-success means repair local SDK first, not HTTP Gateway first. Different-machine/cloud/sandbox agents should use \`MCP_HTTP_GATEWAY_FALLBACK_URL\` directly; starting WaveEngine Agent SDK there binds localhost beside the agent, not beside the user browser. Stale SDK/cache are not reasons to use HTTP Gateway fallback; wrong-machine localhost is.`,
+  `- MCP topology: same-machine agents should run \`${WAVE3D_AGENT_SDK_START_COMMAND}\`, check /health, and update/restart SDK if version is stale, tools are missing, or SDK prints bearer tokens; after restart recheck /health and tools/list. If restart happens after Copy-to-Agent, preserve the bearer with \`${WAVE3D_AGENT_SDK_TOKEN_PRESERVING_START_COMMAND}\` using the current MCP_TOKEN value without printing it, otherwise the new SDK may be healthy but unable to authorize the copied local token. Same-machine stale/missing tools/401-with-Gateway-success means repair local SDK first, not HTTP Gateway first. Different-machine/cloud/sandbox agents should use \`MCP_HTTP_GATEWAY_FALLBACK_URL\` directly; starting WaveEngine Agent SDK there binds localhost beside the agent, not beside the user browser. Stale SDK/cache are not reasons to use HTTP Gateway fallback; wrong-machine localhost is.`,
   `- MCP cache priorities: Priority 1 is active role/context cache: keep role, guardrails, authoring workflow, asset/VFS/hot-reload rules, prompt version, and prompt hash in active LLM context. Priority 2 is WaveEngine SDK Cache: production HTTP Gateway/local-SDK bearer onboarding must not claim normal cached success until SDK cache is prepared or accept proof passes. If accept returns \`wave_engine_sdk_cache_not_ready\`, update/restart \`wave3d-agent-sdk\` or run \`${WAVE_MCP_CORPUS_CACHE_COMMAND_TEMPLATE}\`, then retry accept. If local cache cannot work because sandbox/no filesystem/no Node/npm/user refusal/refresh failure, explicitly accept degraded fallback with \`waveEngineSdkFallbackMode:"studio_ops_only"\`, a valid \`waveEngineSdkUnavailableReason\`, and \`studioOpsOnlyFallbackAccepted:true\`; warn user HTTP Gateway is Studio-ops-only and exact API lookup requires local SDK/cache repair. This cache command reinstalls the package-bundled SDK locally; it is not WaveEngine Agent SDK transport. Never run it to switch MCP transport; never treat cache failure as local transport failure.`,
   "- Main-file globals include `myScene`, `assetManager`, `waveEngine`, `waveStudio`, and direct asset maps such as `models`, `gaussianSplats`, `textures`, `materials`, `animations`, `audios`, `hdr`, `cubeMaps`, `fonts`, `serializedData`, `terrains`, `fx`, `particles`. Availability is not endorsement: choose the intent-owned facade/skill before using a global.",
   `- Bare authoring globals: common examples include ${WAVE_AUTHORING_COMMON_GLOBAL_EXAMPLES_TEXT}, \`waveMaterial\`, \`waveFx\`, \`waveValueCurve\`, and \`waveParam\`. Use them directly in \`main.ts\`; do not import or namespace-qualify them. If the task is unfamiliar, retrieve the relevant \`wave.*\` skill first; for the full generated exact-global surface, call local-SDK \`query_wave_api\`.`,
@@ -44714,7 +44716,7 @@ var WAVE_MCP_TOOL_CATALOG_GUIDE = [
   "- `get_wave_coding_guardrails`: call after onboarding acceptance; returns policy, file context, tool catalog, and recipes.",
   '- `get_wave_mcp_health` (aliases `mcp_health`, `mcp_status`): read-only self diagnostic for endpoint kind, SDK version/build, tool catalog hash/count, onboarding, session/VFS, and WaveEngine SDK Cache state. Use when the agent asks "am I local/cloud/current/cached?" or any MCP state is unclear.',
   "- `get_wave_tool_map`: stable complete concrete MCP tool menu grouped by family plus policy flags. Use only when `tools/list` feels truncated or unclear.",
-  `- Transport topology rule: same-machine agents should run \`${WAVE3D_AGENT_SDK_START_COMMAND}\`, check /health, and update/restart SDK if version is stale, tools are missing, or SDK prints bearer tokens; after restart recheck /health and tools/list. Same-machine stale/missing tools/401-with-Gateway-success means repair local SDK first, not HTTP Gateway first. Different-machine/cloud/sandbox agents should use \`MCP_HTTP_GATEWAY_FALLBACK_URL\` directly. Stale SDK/cache are local setup issues, not fallback triggers; wrong-machine localhost is a topology mismatch.`,
+  `- Transport topology rule: same-machine agents should run \`${WAVE3D_AGENT_SDK_START_COMMAND}\`, check /health, and update/restart SDK if version is stale, tools are missing, or SDK prints bearer tokens; after Copy-to-Agent, restart with \`${WAVE3D_AGENT_SDK_TOKEN_PRESERVING_START_COMMAND}\` using the current MCP_TOKEN value without printing it so the copied local bearer still works. After restart recheck /health and tools/list. Same-machine stale/missing tools/401-with-Gateway-success means repair local SDK first, not HTTP Gateway first. Different-machine/cloud/sandbox agents should use \`MCP_HTTP_GATEWAY_FALLBACK_URL\` directly. Stale SDK/cache are local setup issues, not fallback triggers; wrong-machine localhost is a topology mismatch.`,
   "- `recover_wave_connection`: direct Observe recovery tool. Call after onboarding required, session missing, command timeout/lease expired, mirror not ready, hosted proxy/cache failure, local/HTTP Gateway confusion, or sleeping-tab symptoms. It returns exact next action: re-onboard, get session, wake tab, update/restart SDK, wait mirror, retry, use HTTP Gateway fallback, or ask fresh Copy to Agent.",
   '- WaveEngine SDK Cache: normal API/skill lookup lives inside the local `wave3d-agent-sdk` SDK package. Update/restart SDK when SDK is stale or missing. HTTP Gateway is Studio-ops-only and does not provide cloud API lookup. If local SDK cannot work because sandbox/no filesystem/no Node/npm/user refusal/refresh failure, explicitly accept degraded fallback with `waveEngineSdkFallbackMode:"studio_ops_only"`, a valid `waveEngineSdkUnavailableReason`, and `studioOpsOnlyFallbackAccepted:true`; warn user exact API lookup requires local SDK repair. This is retrieval cache, not WaveEngine Agent SDK transport. Never treat SDK cache failure as local transport failure. Keep Priority 1 role, guardrails, workflow, assets/VFS/hot-reload rules, prompt version, and prompt hash in active LLM context.',
   "- Work-mode rule: Observe reads directly; Operate direct Studio commands directly; Author/Diagnose routes through `start_wave_task`; General avoids Wave tools. Operate tools include run/hot reload, save/share, VFS create/rename/delete exact files, asset upload/rename/delete exact assets, new project, project rename, and open project by exact projectId.",
@@ -44883,7 +44885,7 @@ var LOCAL_MCP_AGENT_ONBOARDING_PROMPT = [
   `The WaveEngine Agent SDK answers skill/API/guardrail tools from the bundled WaveEngine SDK Cache. The SDK ships inside \`wave3d-agent-sdk\`; \`start\`, \`cache status\`, and \`cache search\` auto-prepare it locally. During \`accept_wave_agent_onboarding\`, production/HTTP-Gateway bearers must verify this local SDK cache before normal success. If missing, stale, or unverified, accept returns \`wave_engine_sdk_cache_not_ready\`; update/restart the exact SDK package or run the local bundled repair command \`${WAVE_MCP_CORPUS_CACHE_COMMAND_TEMPLATE}\`, then retry accept. If the agent is sandboxed, has no filesystem/Node/npm, or user refuses local SDK/cache, explicitly accept degraded Studio-ops-only fallback with \`waveEngineSdkFallbackMode:"studio_ops_only"\`, a valid \`waveEngineSdkUnavailableReason\`, and \`studioOpsOnlyFallbackAccepted:true\`; warn user HTTP Gateway can still do VFS/assets/project/preview/capture, but exact API lookup is unavailable until local SDK works. Keep the exact SDK command in active context as \`waveEngineSdkCacheCommandCached\`. Use local skill onion retrieval: \`list_wave_skill_families\` -> choose family ids -> \`query_wave_skills\` with \`families\`/\`familyId\` -> \`get_wave_skill\` -> \`query_wave_api\` only for exact signature/global/value uncertainty. HTTP Gateway is not an API lookup fallback.`,
   "",
   "Mandatory phased handshake:",
-  "Phase 0 WaveEngine Agent SDK preflight is not optional. Do these phases in order before user work: 1 initialize endpoint; 2 call `self_check_wave_mcp` with the exact `expectedVersion` and `expectedBuildHash` from Copy-to-Agent; hard-stop if stale/hardStop is true or tool count/hash looks missing, then restart the SDK command from the copy block and retry; 2a when status is unclear, call `get_wave_mcp_health`/`mcp_status` to read endpoint/SDK/tool/SDK/session state; 3 call `get_wave_agent_onboarding` and cache Priority 1 rules in active context; 4 call `accept_wave_agent_onboarding` with acceptedRole true, current promptVersion/promptHash, all required cachedSections, full intentKindsCached list, exact waveEngineSdkCacheCommandCached template, and every context-cache confirmation true; if it returns `wave_engine_sdk_cache_not_ready`, update/restart SDK or run the bundled SDK repair command and retry accept; if local SDK cannot work, explicitly accept Studio-ops-only fallback and do not do unfamiliar API authoring; 5 call `tools/list` and prefer concrete tool names from the returned catalog; 6 call `get_wave_session`; 7 call `list_wave_files`; 8 if the tool menu is unclear, call `get_wave_tool_map`. Observe tools such as file reads, assets, diagnostics, screenshots, snapshots, performance, and markers stay open. Operate tools such as run preview, hot reload, save/share/rename/open/new project, VFS create/rename/delete, and asset upload/rename/delete are direct Studio commands when the user asks for that operation. Author/Diagnose tools such as `query_wave_api`, `edit_wave_file`, `apply_wave_patch`, and code behavior changes use `start_wave_task`. After startup, report phase status briefly. If a required phase fails or any later MCP state is unclear, call `get_wave_mcp_health` for state and `recover_wave_connection({ lastErrorCode?, failedTool?, symptom? })` for nextAction before asking user for a fresh copy; do not skip ahead.",
+  `Phase 0 WaveEngine Agent SDK preflight is not optional. Do these phases in order before user work: 1 initialize endpoint; 2 call \`self_check_wave_mcp\` with the exact \`expectedVersion\` and \`expectedBuildHash\` from Copy-to-Agent; hard-stop if stale/hardStop is true or tool count/hash looks missing, then restart SDK while preserving the copied bearer with \`${WAVE3D_AGENT_SDK_TOKEN_PRESERVING_START_COMMAND}\` using the current MCP_TOKEN value hidden; 2a when status is unclear, call \`get_wave_mcp_health\`/\`mcp_status\` to read endpoint/SDK/tool/SDK/session state; 3 call \`get_wave_agent_onboarding\` and cache Priority 1 rules in active context; 4 call \`accept_wave_agent_onboarding\` with acceptedRole true, current promptVersion/promptHash, all required cachedSections, full intentKindsCached list, exact waveEngineSdkCacheCommandCached template, and every context-cache confirmation true; if it returns \`wave_engine_sdk_cache_not_ready\`, update/restart SDK or run the bundled SDK repair command and retry accept; if local SDK cannot work, explicitly accept Studio-ops-only fallback and do not do unfamiliar API authoring; 5 call \`tools/list\` and prefer concrete tool names from the returned catalog; 6 call \`get_wave_session\`; 7 call \`list_wave_files\`; 8 if the tool menu is unclear, call \`get_wave_tool_map\`. Observe tools such as file reads, assets, diagnostics, screenshots, snapshots, performance, and markers stay open. Operate tools such as run preview, hot reload, save/share/rename/open/new project, VFS create/rename/delete, and asset upload/rename/delete are direct Studio commands when the user asks for that operation. Author/Diagnose tools such as \`query_wave_api\`, \`edit_wave_file\`, \`apply_wave_patch\`, and code behavior changes use \`start_wave_task\`. After startup, report phase status briefly. If a required phase fails or any later MCP state is unclear, call \`get_wave_mcp_health\` for state and \`recover_wave_connection({ lastErrorCode?, failedTool?, symptom? })\` for nextAction before asking user for a fresh copy; do not skip ahead.`,
   "Tool-name tolerance: concrete names from tools/list remain preferred. Common aliases and safe high-confidence typos are tolerated. Destructive/write fuzzy matches return did-you-mean instead of executing.",
   "Glossary: WaveEngine Agent SDK = same-machine live MCP transport plus bundled SDK lookup; HTTP Gateway = Next/Vercel MCP transport for remote/sandbox Studio ops; WaveEngine SDK Cache = package-bundled public docs/API/skill retrieval; MCP Session = browser pairing/token state; VFS Mirror = HTTP Gateway read/edit hash snapshot; Project = user workspace content. Do not merge these concepts.",
   "",
@@ -44907,7 +44909,7 @@ var LOCAL_MCP_AGENT_ONBOARDING_PROMPT = [
   "",
   "WaveEngine Agent SDK scope:",
   'This endpoint mirrors the HTTP Gateway tool catalog plus local SDK session-discovery extras. Live-session Studio tools for VFS, preview, capture, runtime probes, assets, uploads, project save/share/open/new/read, and file operations run through the connected browser. Local browser-backed calls wait for the browser result directly. Only call `get_wave_command_result` when a tool result actually contains `status:"pending"` plus `requestId`; otherwise local `get_wave_command_result` exists only for catalog parity and reports that no local pending-command queue is used. Skill/API/guardrail tools read the bundled WaveEngine SDK Cache prepared by the SDK package. Do not treat SDK cache miss as local transport failure.',
-  "Recovery rule: `recover_wave_connection` is the first tool after `agent_onboarding_required`, `session_not_found`, `command_timeout`, `command_lease_expired`, `hosted_mcp_proxy_failed`, unclear local/HTTP Gateway fallback, or sleeping-tab symptoms. If local HTTP refuses, start/restart WaveEngine Agent SDK and retry 10 seconds. If local HTTP returns 401 but HTTP Gateway accepts the same token, SDK is stale/not adopted: restart exact SDK and retry local. If every endpoint rejects token before a tool result, ask user for fresh Copy to Agent."
+  `Recovery rule: \`recover_wave_connection\` is the first tool after \`agent_onboarding_required\`, \`session_not_found\`, \`command_timeout\`, \`command_lease_expired\`, \`hosted_mcp_proxy_failed\`, unclear local/HTTP Gateway fallback, or sleeping-tab symptoms. If local HTTP refuses, start/restart WaveEngine Agent SDK and retry 10 seconds. If local HTTP returns 401 but HTTP Gateway accepts the same token, SDK is stale/not adopted: restart with \`${WAVE3D_AGENT_SDK_TOKEN_PRESERVING_START_COMMAND}\` using the current MCP_TOKEN value hidden, then retry local. If every endpoint rejects token before a tool result, ask user for fresh Copy to Agent.`
 ].join("\n");
 
 // ../../scripts/wavegenie-sdk/mcp/referenceTools.ts
@@ -49334,7 +49336,7 @@ function getReadToolDefinitions() {
   return [
     {
       name: "self_check_wave_mcp",
-      description: "Run first local-SDK self-check. Pass expectedVersion and expectedBuildHash exactly from the Copy-to-Agent message; without external expected values a stale SDK can only compare against itself. Verifies SDK version/build, tool catalog hash/count, paired session count, and route-evidence health. If stale/hardStop is true, restart the exact SDK command from Copy to Agent before doing user work.",
+      description: `Run first local-SDK self-check. Pass expectedVersion and expectedBuildHash exactly from the Copy-to-Agent message; without external expected values a stale SDK can only compare against itself. Verifies SDK version/build, tool catalog hash/count, paired session count, and route-evidence health. If stale/hardStop is true, restart SDK with copied bearer preserved via ${WAVE3D_AGENT_SDK_TOKEN_PRESERVING_START_COMMAND} before doing user work.`,
       inputSchema: {
         type: "object",
         properties: {
@@ -49739,7 +49741,7 @@ function localConnectionRecoveryResult(args, context) {
     nextAction = "Wave Studio tab is paired but not actively polling commands, or browser-backed command timed out. Ask user to focus/wake the tab and verify MCP is live; retry the same tool once on the same local endpoint/token.";
     nextTool = failedTool || "get_wave_session";
     requiresUserAction = true;
-    steps.push(`If SDK /health is down or stale, restart \`${WAVE3D_AGENT_SDK_START_COMMAND}\`; if /health is OK and version matches Copy to Agent, do not restart SDK first.`);
+    steps.push(`If SDK /health is down before pairing, start \`${WAVE3D_AGENT_SDK_START_COMMAND}\`; after Copy-to-Agent, restart stale SDK with \`${WAVE3D_AGENT_SDK_TOKEN_PRESERVING_START_COMMAND}\` using the current MCP_TOKEN value hidden. If /health is OK and version matches Copy to Agent, do not restart SDK first.`);
   } else if (lastErrorCode === "session_write_not_allowed" || selectedSession?.accessMode !== "readwrite") {
     state = "write_access_not_ready";
     nextAction = "Read tools can continue. For write/run/hot reload, user must make the Studio MCP session read-write/adopt WaveEngine Agent SDK, then retry same local endpoint/token or paste fresh Copy to Agent if token changed.";
@@ -50266,7 +50268,7 @@ async function callReadTool(name, args, context) {
         taskRouteId: activeRoute.taskRouteId,
         phase: activeRoute.phase
       } : null,
-      nextAction: !stale ? "Agent SDK version/build/tool catalog look current. Continue with get_wave_session and list_wave_files." : externalExpectedProvided ? `Agent SDK is stale. Stop it and restart with: ${WAVE3D_AGENT_SDK_START_COMMAND}` : "Self-check needs expectedVersion and expectedBuildHash from the Copy-to-Agent message; rerun self_check_wave_mcp with those exact values before user work.",
+      nextAction: !stale ? "Agent SDK version/build/tool catalog look current. Continue with get_wave_session and list_wave_files." : externalExpectedProvided ? `Agent SDK is stale. Stop it and restart while preserving the copied bearer: ${WAVE3D_AGENT_SDK_TOKEN_PRESERVING_START_COMMAND}` : "Self-check needs expectedVersion and expectedBuildHash from the Copy-to-Agent message; rerun self_check_wave_mcp with those exact values before user work.",
       hardStop: stale
     });
   }
@@ -52259,7 +52261,7 @@ async function commandStart(options) {
   const handle = await startWaveEngineAgentSdkServer({
     host,
     port: readNumberFlag(options, "port") ?? DEFAULT_PORT2,
-    token: readStringFlag(options, "token"),
+    token: readStringFlag(options, "token") ?? process.env.WAVE3D_MCP_TOKEN ?? process.env.WAVESTUDIO_MCP_TOKEN,
     sessionTtlMs: readNumberFlag(options, "session-ttl-ms")
   });
   console.log(`[WaveEngine Agent SDK] sdkId=${handle.bridgeId}`);

package/dist/sdk/README.md

@@ -3,6 +3,6 @@
 Bundled public-safe WaveEngine SDK lookup cache for wave3d-agent-sdk.
 Generated from sanitized public API/skill corpus during package build.
 
-cacheKey: 2026-06-17.1.ahR9MhSr8vzetTBJN7--J7zIJCn0weU3
-bundleHash: ahR9MhSr8vzetTBJN7--J7zIJCn0weU3
-zip: wave-engine-sdk-2026-06-17.1.ahR9MhSr8vzetTBJN7--J7zIJCn0weU3.zip
+cacheKey: 2026-06-17.1.WXZSA5Qy4wTqmcbeW86e8xxyaA82djd3
+bundleHash: WXZSA5Qy4wTqmcbeW86e8xxyaA82djd3
+zip: wave-engine-sdk-2026-06-17.1.WXZSA5Qy4wTqmcbeW86e8xxyaA82djd3.zip

package/dist/sdk/manifest.json

@@ -1,21 +1,21 @@
 {
-  "version": "2026-06-17.1.ahR9MhSr8vzetTBJN7--J7zIJCn0weU3",
+  "version": "2026-06-17.1.WXZSA5Qy4wTqmcbeW86e8xxyaA82djd3",
   "formatVersion": "2026-06-17.1",
-  "cacheKey": "2026-06-17.1.ahR9MhSr8vzetTBJN7--J7zIJCn0weU3",
-  "bundleFileName": "wave-engine-sdk-2026-06-17.1.ahR9MhSr8vzetTBJN7--J7zIJCn0weU3.zip",
-  "bundleHash": "ahR9MhSr8vzetTBJN7--J7zIJCn0weU3",
+  "cacheKey": "2026-06-17.1.WXZSA5Qy4wTqmcbeW86e8xxyaA82djd3",
+  "bundleFileName": "wave-engine-sdk-2026-06-17.1.WXZSA5Qy4wTqmcbeW86e8xxyaA82djd3.zip",
+  "bundleHash": "WXZSA5Qy4wTqmcbeW86e8xxyaA82djd3",
   "generatedAt": "2026-06-06T00:00:00.000Z",
   "sourceVersions": {
     "onboarding": {
       "promptVersion": "2026-06-15.2",
-      "promptHash": "yGZ7rW90VPeluCzcJAXwZTlJHlhDXk5Q"
+      "promptHash": "q5ctGPrUpvUFSjNtoaC-ZEYnwwQtHGP6"
     },
     "apiHandbook": {
       "version": "1",
-      "contentHash": "ff608d6d66055f42"
+      "contentHash": "09025648e3d8a784"
     },
-    "waveSkillCorpusHash": "zYNMifq0Tf_Ck95E1rgKD7pb7o0EJDIO",
-    "sdkLookupCorpusHash": "OKnpFUeYw8RequlcuAeAH2PVG2TS-SwJ"
+    "waveSkillCorpusHash": "t3i8l8f4xNa_2BHAN1XE5MnERgRCFW6y",
+    "sdkLookupCorpusHash": "VH-f574z_jXGGSc1tsUiqz3tIKqHQyUy"
   },
   "cacheContract": {
     "llmContextCacheOnly": [
@@ -34,18 +34,18 @@
       "searchDocuments"
     ],
     "rule": "Priority 1 always-on sections must stay in LLM chat/system context. The WaveEngine SDK local cache is public-safe retrieval data, never the only memory for core policy.",
-    "defaultRefreshCommand": "npx -y wave3d-agent-sdk@0.2.2 cache refresh",
+    "defaultRefreshCommand": "npx -y wave3d-agent-sdk@0.2.4 cache refresh",
     "refreshRule": "When using WaveEngine SDK local cache, compare cacheKey, bundleHash, and sourceVersions before trusting local lookup. If any value differs, update the SDK package or reinstall its bundled SDK cache and rebuild local indexes. Do not fetch a remote SDK zip.",
     "onlineFallback": "HTTP Gateway does not provide cloud API lookup. If local Node/npm or cache is refused/unavailable, use only concrete Studio operations and already-known code; repair the local WaveEngine SDK before unfamiliar API authoring."
   },
   "download": {
     "sameOriginPath": "/api/waveStudio/bridge/mcp/corpus",
     "cacheBustingQuery": "",
-    "etag": "\"wave-engine-sdk-ahR9MhSr8vzetTBJN7--J7zIJCn0weU3\""
+    "etag": "\"wave-engine-sdk-WXZSA5Qy4wTqmcbeW86e8xxyaA82djd3\""
   },
   "corpus": {
-    "skillCount": 65,
-    "apiEntryCount": 5000,
+    "skillCount": 66,
+    "apiEntryCount": 4997,
     "apiMethodGroupCount": 1143
   },
   "files": [
@@ -54,14 +54,14 @@
       "mediaType": "application/json",
       "role": "lookup-guide",
       "bytes": 1288,
-      "hash": "5MdWUJuF3G57JL8Pxn7h_SkYL_oFxao0"
+      "hash": "k_26htBpNNH8-SmpOF00Gr7WeDK9MNqt"
     },
     {
       "path": "skills/wave-skills.jsonl",
       "mediaType": "application/jsonl",
       "role": "skill-corpus",
-      "bytes": 472843,
-      "hash": "BHx1prKm-ggF4ggk9ZUfKusRGPCmobPd"
+      "bytes": 483939,
+      "hash": "ey9Iqfr75sDt2Mj_6r7zNyMlu-N5a0Vn"
     },
     {
       "path": "skills/foundations.jsonl",
@@ -74,15 +74,15 @@
       "path": "skills/families.json",
       "mediaType": "application/json",
       "role": "skill-corpus",
-      "bytes": 44401,
-      "hash": "MlM0qqK1BMGUsOv5Zgf3YbjGiIfU4IjM"
+      "bytes": 45433,
+      "hash": "-lNpueMu8en-tvaF0aki0of-WAen3oB9"
     },
     {
       "path": "api/entries.jsonl",
       "mediaType": "application/jsonl",
       "role": "api-corpus",
-      "bytes": 4526446,
-      "hash": "qOT8R4_becmncqN1sAZzCwo18n2OHgbe"
+      "bytes": 4524222,
+      "hash": "ppDJKjbnzzxzmvFd-XPS7p8BuHVRrYzU"
     },
     {
       "path": "api/method-groups.jsonl",
@@ -96,14 +96,14 @@
       "mediaType": "application/json",
       "role": "api-corpus",
       "bytes": 192,
-      "hash": "3RotzIDkoahE_90Fi1JQjv8lZKr6rhwH"
+      "hash": "F6-eeIySGY2NAltvBD-M1WrTivPfNnYe"
     },
     {
       "path": "search/search-documents.jsonl",
       "mediaType": "application/jsonl",
       "role": "search-index",
-      "bytes": 4039188,
-      "hash": "zIGmnONrO849VVRDhUW4wa4W-UgkRLzz"
+      "bytes": 4044604,
+      "hash": "X3mOQI-rYByry0A6lTw5RLjYpcg8y1fJ"
     },
     {
       "path": "README.md",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wave3d-agent-sdk",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "description": "WaveEngine Agent SDK for same-machine Wave Studio MCP plus bundled WaveEngine lookup.",
   "type": "module",
   "license": "UNLICENSED",