wave3d-agent-sdk 0.2.7 → 0.2.8

package/README.md

@@ -21,19 +21,19 @@ Vocabulary:
 - Project: user workspace content. Reading a project is not opening/replacing live workspace.
 
 ```bash
-npx -y wave3d-agent-sdk@0.2.7 start
+npx -y wave3d-agent-sdk@0.2.8 start
 ```
 
 After Copy to Agent, restart stale SDK processes with MCP_TOKEN preserved as the local pairing secret. Keep it hidden:
 
 ```bash
-WAVE3D_MCP_TOKEN="$MCP_TOKEN" npx -y wave3d-agent-sdk@0.2.7 start
+WAVE3D_MCP_TOKEN="$MCP_TOKEN" npx -y wave3d-agent-sdk@0.2.8 start
 ```
 
 Check SDK build before trusting a running SDK process:
 
 ```bash
-npx -y wave3d-agent-sdk@0.2.7 --version
+npx -y wave3d-agent-sdk@0.2.8 --version
 ```
 
 The package bundles the WaveEngine SDK lookup corpus. No normal session needs a separate protected zip download.
@@ -43,7 +43,7 @@ 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.7 start
+npx -y wave3d-agent-sdk@0.2.8 start
 ```
 
 Agents choose topology first:
@@ -58,13 +58,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.7 cache search "continuous left rotation"
+npx -y wave3d-agent-sdk@0.2.8 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.7 cache refresh
+npx -y wave3d-agent-sdk@0.2.8 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

@@ -42483,8 +42483,8 @@ 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.7";
-var WAVE3D_AGENT_SDK_REQUIRED_BUILD = "agent-sdk-20260620.2";
+var WAVE3D_AGENT_SDK_REQUIRED_VERSION = "0.2.8";
+var WAVE3D_AGENT_SDK_REQUIRED_BUILD = "agent-sdk-20260620.3";
 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";
@@ -44416,7 +44416,7 @@ var WAVE_MCP_AGENT_BRIEF = [
   "VFS hashes: simple edit tools auto-resolve the latest mirror `contentHash`; pass `baseHash` only when you already have it or when using advanced `apply_wave_patch`. Always inspect `changedFiles`, `changedPaths`, `partial`, and `skippedOperations` after edits.",
   "VFS modules: scene-root modules and their owned helpers run inside the Studio authoring context, but helpers should stay pure or parameterized. Put live object ownership in scene-root/feature files, not shared helpers.",
   'VFS HTML sketches: for diagram/chart/doc-sketch requests, create or edit an exact `.html` file with Studio VFS tools. Mermaid renders from `<div class="mermaid">flowchart TD ...</div>` when that HTML file is active in the editor/coding pane; HTML sketches must never replace the live engine preview iframe. Do not put Mermaid in markdown fences unless user specifically wants markdown text.',
-  'VFS hot reload ownership: Studio hot reload targets the active/open edited file when safe. Editing `/main.ts` reloads the main graph; editing a scene-root module reloads that root; bootstrap/scene registry/assets/network/ambiguous helper surfaces escalate. In multi-file projects, standalone `hot_reload_wave_preview` follows the active Studio editor file, so do not expect it to reload an arbitrary unopened module by path. Put heavy world loading in bootstrap or a coarse world module. For intentional cross-module live entities, the owner module calls `waveStudio.exportEntity("Name", entity)` and importer modules call `waveStudio.importEntity<T>("Name")`; Studio restores the exported baseline and replays active importer overlays during source hot reload. Source execution order is dependency-driven: exporter roots run before importer roots; an exporter root runs before `main.ts` when main imports it; importer overlays run after exporter/main baseline. Entity names must be static string literals, unique, and acyclic or run/hot reload stops before execution. Keep shared helpers pure or parameterized.',
+  'VFS hot reload ownership: Studio hot reload targets the active/open edited file when safe. Editing `/main.ts` reloads the main graph; editing a scene-root module reloads that root; bootstrap/scene registry/assets/network/ambiguous helper surfaces escalate. In multi-file projects, standalone `hot_reload_wave_preview` follows the active Studio editor file, so do not expect it to reload an arbitrary unopened module by path. Put heavy world loading in bootstrap or a coarse world module. If authored UI in `main.ts` changes bootstrap/world-provider state, store the state and call `waveStudio.reloadPreview({ reason })`; do not call `myScene.hotReload(...)` from Studio-authored code because it bypasses Studio VFS/package/source-patch orchestration. For intentional cross-module live entities, the owner module calls `waveStudio.exportEntity("Name", entity)` and importer modules call `waveStudio.importEntity<T>("Name")`; Studio restores the exported baseline and replays active importer overlays during source hot reload. Source execution order is dependency-driven: exporter roots run before importer roots; an exporter root runs before `main.ts` when main imports it; importer overlays run after exporter/main baseline. Entity names must be static string literals, unique, and acyclic or run/hot reload stops before execution. Keep shared helpers pure or parameterized.',
   "Assets: when quoting or passing an existing asset, use typed bare refs in main files: `models.X`, `textures.X`, `materials.X`, `audios.X`, `hdr.X`, `cubeMaps.X`, `animations.X`, etc. Do not paste raw paths or edit Studio-managed generated files just to register assets. If the exact ref is not already visible, call category-first asset discovery (`find_wave_assets_by_category`, alias `list_wave_assets_by_category`, alias `search_wave_assets_by_category`, or tolerant `list_wave_assets`) with required `category` from user intent, semantic `query`, and small `limit` before editing code; category-filtered results can still be capped/truncated, so refine query before concluding absence. Use `list_wave_explorer_assets` only for uploaded library metadata, rename/delete, URL, path, size, or display/ref-name management.",
   "Asset authoring facade split: typed refs quote existing assets; `waveMaterial` authors material handles; `assetManager` is only for exact asset-pipeline/generated-asset APIs that a local SDK skill or API lookup names, such as SDF surfaces or surface ribbons. Do not treat `assetManager` as the default creative facade for materials or normal asset arguments.",
   "Material authoring: when creating, configuring, forking, or intentionally editing material handles, route to `wave.material.authoring` and start from `waveMaterial` (`createWater`, `createGrid`, `createSplatMaterial`, `createFromAsset`, `editAsset`). If a material handle later needs runtime sync, `assetManager` may be passed as the sync target; it is still not the authoring root.",
@@ -44441,7 +44441,7 @@ var WAVE_MCP_AUTHORING_GLOBALS_GUIDE = [
   "- Colors/materials/fx helpers: `COLOR`, `PALETTE`, `waveCOLOR`, `waveMaterial`, `shaderUniform`, `waveFx`, `waveFxPresets`, `FxAnchor`, `FxCondition`.",
   "- Controller movement helpers: `waveKinematicActor`, `netKinematicActor`, `KinematicHumanoidMovementState`, `KinematicVehicleMovementState`, and `KinematicFlightMovementState`. Use actor-level `.asHumanoid(...)`, `.asVehicle(...)`, or `.asFlight(...)` for player/controller movement.",
   "- Asset maps: use category-first refs returned by `find_wave_assets_by_category`, commonly `models`, `gaussianSplats`, `animations`, `materials`, `guis`, `textures`, `audios`, `instruments`, `videos`, `hdr`, `fonts`, `serializedData`, `terrains`, `fx`, and `particles`.",
-  "- Scene/runtime handles: prefer `myScene` for scene composition and `waveStudio` for Studio operations. `assetManager` is available, but use it only when an exact skill/API names an asset-pipeline or generated-asset factory; do not use it as the default facade for existing asset refs or material authoring. Use lower-level `ctx`, `engine`, or `scene` only when existing code or an exact API requires them.",
+  "- Scene/runtime handles: prefer `myScene` for scene composition and `waveStudio` for Studio operations. If authored UI changes bootstrap/world-provider state and needs the Studio preview to rebuild, call `waveStudio.reloadPreview({ reason })`, not `myScene.hotReload(...)`. `assetManager` is available, but use it only when an exact skill/API names an asset-pipeline or generated-asset factory; do not use it as the default facade for existing asset refs or material authoring. Use lower-level `ctx`, `engine`, or `scene` only when existing code or an exact API requires them.",
   "- Authoring systems/presets: `waveEventBus`, `waveRig`, `waveValueCurve`, `waveValueCurvePresets`, `waveMotionSignal`, `waveParam`, `WaveParam`, `WaveChoice`, `prefabModels`, `effectPrefabs`, and prefab helpers such as `rocketPrefab`.",
   "- Lowercase constructors: `prop`, `marker`, `sphere`, `point`, `cube`, `box`, `cylinder`, `capsule`, `cone`, `torus`, `plane`, `ground`, `line`, `arc`, `path`, and related shape helpers.",
   "- Type names are not import paths. If the handbook shows a type like `TransformVerbMode` or `WaveRateUnit`, look for the matching bare runtime value such as `Animate` or `DegreesPerSecond` before writing code. Transform `Snapshot` calls return a snapshot builder; call `.take()` before passing the pose to `transitionTo(...)`.",
@@ -44659,6 +44659,7 @@ var WAVE_MCP_STUDIO_TOOL_GUIDE = [
   "- `waveStudio.saveFor3dPrinting(target, options?)`: save export-friendly model.",
   "- `waveStudio.saveMaterial(request)`: save authored material asset.",
   "- `waveStudio.bakeTerrainMaterial(request)`: bake terrain material textures.",
+  "- `waveStudio.reloadPreview({ reason? })`: request the Wave Studio toolbar-style reload path from authored code. Use this when a UI authored in `main.ts` changes Studio/bootstrap-backed state such as active city/world provider and must re-run the Studio preview package. Do not call `myScene.hotReload(...)` from Studio-authored code for this; that bypasses Studio VFS/package/source-patch orchestration.",
   "- `waveStudio.exportEntity(name, entity)`: declare a live entity owned by the current source module for intentional modular reuse. `name` must be a static string literal and unique across runnable roots.",
   "- `waveStudio.importEntity<T>(name)`: import an exported live entity into the current source module; Studio restores the exporter baseline and prunes/replays importer callbacks/overlays during source hot reload. Studio orders source roots by export/import dependencies: exporter before importer; exporter before `main.ts` if main imports it; overlay importers after exporter/main baseline. Missing, duplicate, dynamic, or cyclic entity names stop run/hot reload before execution.",
   '- MCP command result rule: poll `get_wave_command_result({ requestId })` only when the previous tool response includes `status:"pending"` plus `requestId`. HTTP Gateway browser-backed tools may return pending and need that poll. WaveEngine Agent SDK browser-backed tools wait directly and return final results; its `get_wave_command_result` is a catalog-parity no-op unless a pending result was explicitly returned.',
@@ -46192,6 +46193,9 @@ var HOT_RELOAD_UNSAFE_SCENE_EVENT_CALLBACKS = /* @__PURE__ */ new Map([
   ["on", "myScene.on(...) is scene-scoped, but not authored-epoch scoped. It is cleared on scene transition, not on every preserve-scene hotreload. Use Wave-owned input/entity callbacks, or wait for a scoped Wave scene-event authoring API."],
   ["once", "myScene.once(...) is scene-scoped, but an unfired one-shot handler can survive preserve-scene hotreload. Use Wave-owned input/entity callbacks, or wait for a scoped Wave scene-event authoring API."]
 ]);
+var HOT_RELOAD_FORBIDDEN_STUDIO_SCENE_METHODS = /* @__PURE__ */ new Map([
+  ["hotReload", 'Studio-authored code must not call myScene.hotReload(...). Use waveStudio.reloadPreview({ reason: "..." }) so Wave Studio can flush VFS, rebuild the project package/bootstrap, sync assets, choose the correct reload tier, and return diagnostics.']
+]);
 var HOT_RELOAD_UNSAFE_CONSTRUCTORS = /* @__PURE__ */ new Map([
   ["Promise", "new Promise(...) is not hotreload-safe because it creates unmanaged callback closures. Use awaitable Wave APIs instead."],
   ["MutationObserver", "DOM observers are not hotreload-safe. Use an engine-owned wrapper that can be disposed by hotreload."],
@@ -46279,6 +46283,7 @@ function readPropertyReceiverPath(code, tokenStart) {
   while (index >= 0 && /\s/.test(code[index] ?? "")) index -= 1;
   if (code[index] !== ".") return "";
   index -= 1;
+  if (code[index] === "?") index -= 1;
   while (index >= 0 && /\s/.test(code[index] ?? "")) index -= 1;
   const endIndex = index + 1;
   while (index >= 0 && (isIdentifierPartChar(code[index]) || code[index] === "." || /\s/.test(code[index] ?? ""))) {
@@ -46328,6 +46333,9 @@ function skipQuotedRuntimeLiteral(code, startIndex, quote) {
   return index;
 }
 function buildHotReloadUnsafeMessage(params) {
+  if (params.severity === "error") {
+    return `${RUNTIME_HOT_RELOAD_SAFETY_WARNING_PREFIX} ERROR: forbidden Studio reload API '${params.token}' at ${params.path}:${params.line}:${params.column}. ${params.guidance}`;
+  }
   return `${RUNTIME_HOT_RELOAD_SAFETY_WARNING_PREFIX} WARNING: unsafe unmanaged callback API '${params.token}' at ${params.path}:${params.line}:${params.column}. Code will still run, but this callback is registered outside Wave's authored callback registry, so hotreload cannot unregister it and the closure can retain old scene/entity/model graphs. Memory leak risk. Recommendation: ${params.guidance}`;
 }
 function reportHotReloadUnsafeUsage(params) {
@@ -46336,6 +46344,7 @@ function reportHotReloadUnsafeUsage(params) {
   const key = `${params.path}:${line}:${column}:${params.token}`;
   if (params.reported.has(key)) return;
   params.reported.add(key);
+  const severity = params.severity ?? "warning";
   params.diagnostics.push({
     path: params.path,
     token: params.token,
@@ -46343,12 +46352,14 @@ function reportHotReloadUnsafeUsage(params) {
     length: params.token.length,
     line,
     column,
+    severity,
     guidance: params.guidance,
     message: buildHotReloadUnsafeMessage({
       path: params.path,
       token: params.token,
       line,
       column,
+      severity,
       guidance: params.guidance
     })
   });
@@ -46393,7 +46404,8 @@ function collectRuntimeHotReloadSafetyDiagnostics(path5, code, limit = HOT_RELOA
     const nextNonWhitespace = code[nextNonWhitespaceIndex] ?? "";
     const previousChar = readPreviousNonWhitespaceChar(code, tokenStart);
     const previousIdentifier = readPreviousIdentifier(code, tokenStart);
-    const isCall = nextNonWhitespace === "(";
+    const optionalCallParenIndex = nextNonWhitespace === "?" && code[nextNonWhitespaceIndex + 1] === "." ? readNextNonWhitespaceIndex(code, nextNonWhitespaceIndex + 2) : -1;
+    const isCall = nextNonWhitespace === "(" || optionalCallParenIndex >= 0 && code[optionalCallParenIndex] === "(";
     const receiverPath = previousChar === "." ? readPropertyReceiverPath(code, tokenStart) : "";
     const globalGuidance = HOT_RELOAD_UNSAFE_GLOBAL_CALLBACKS.get(token);
     if (globalGuidance) {
@@ -46420,6 +46432,20 @@ function collectRuntimeHotReloadSafetyDiagnostics(path5, code, limit = HOT_RELOA
       reportHotReloadUnsafeUsage({ code, path: path5, token, offset: tokenStart, guidance: sceneEventGuidance, diagnostics, reported });
       continue;
     }
+    const forbiddenStudioSceneMethodGuidance = HOT_RELOAD_FORBIDDEN_STUDIO_SCENE_METHODS.get(token);
+    if (forbiddenStudioSceneMethodGuidance && previousChar === "." && isCall && isWaveSceneEventReceiverPath(receiverPath)) {
+      reportHotReloadUnsafeUsage({
+        code,
+        path: path5,
+        token,
+        offset: tokenStart,
+        severity: "error",
+        guidance: forbiddenStudioSceneMethodGuidance,
+        diagnostics,
+        reported
+      });
+      continue;
+    }
     const constructorGuidance = HOT_RELOAD_UNSAFE_CONSTRUCTORS.get(token);
     if (constructorGuidance && (previousIdentifier === "new" || previousChar === "." && isCall)) {
       reportHotReloadUnsafeUsage({ code, path: path5, token, offset: tokenStart, guidance: constructorGuidance, diagnostics, reported });

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.dBbXqRbLTZgB2Lhd28PqH8fYLoSLaK0J
-bundleHash: dBbXqRbLTZgB2Lhd28PqH8fYLoSLaK0J
-zip: wave-engine-sdk-2026-06-17.1.dBbXqRbLTZgB2Lhd28PqH8fYLoSLaK0J.zip
+cacheKey: 2026-06-17.1.p4vUxjKn3o8fS2orbJ9I0RNBdO0G6_Dg
+bundleHash: p4vUxjKn3o8fS2orbJ9I0RNBdO0G6_Dg
+zip: wave-engine-sdk-2026-06-17.1.p4vUxjKn3o8fS2orbJ9I0RNBdO0G6_Dg.zip

package/dist/sdk/manifest.json

@@ -1,21 +1,21 @@
 {
-  "version": "2026-06-17.1.dBbXqRbLTZgB2Lhd28PqH8fYLoSLaK0J",
+  "version": "2026-06-17.1.p4vUxjKn3o8fS2orbJ9I0RNBdO0G6_Dg",
   "formatVersion": "2026-06-17.1",
-  "cacheKey": "2026-06-17.1.dBbXqRbLTZgB2Lhd28PqH8fYLoSLaK0J",
-  "bundleFileName": "wave-engine-sdk-2026-06-17.1.dBbXqRbLTZgB2Lhd28PqH8fYLoSLaK0J.zip",
-  "bundleHash": "dBbXqRbLTZgB2Lhd28PqH8fYLoSLaK0J",
+  "cacheKey": "2026-06-17.1.p4vUxjKn3o8fS2orbJ9I0RNBdO0G6_Dg",
+  "bundleFileName": "wave-engine-sdk-2026-06-17.1.p4vUxjKn3o8fS2orbJ9I0RNBdO0G6_Dg.zip",
+  "bundleHash": "p4vUxjKn3o8fS2orbJ9I0RNBdO0G6_Dg",
   "generatedAt": "2026-06-06T00:00:00.000Z",
   "sourceVersions": {
     "onboarding": {
       "promptVersion": "2026-06-15.2",
-      "promptHash": "6IuwZ1MMtoXP-Y2JRI5awkgnCmUDeP_e"
+      "promptHash": "S1t3TsiBEK-L5oyOlh3M-2aFvaLyaZ_u"
     },
     "apiHandbook": {
       "version": "1",
-      "contentHash": "5d904cc079d88968"
+      "contentHash": "edf117cbd2b09857"
     },
-    "waveSkillCorpusHash": "dzCK1XjEuVkGu72kgtFem6UZeDVf6q_t",
-    "sdkLookupCorpusHash": "mx3pTdmb3WJLL3G0ZJNyeIeWaIgNdY0o"
+    "waveSkillCorpusHash": "nhg-WfsotIdN1pRO41g97bff6RrKujrN",
+    "sdkLookupCorpusHash": "PIjMZyPz-ALuRLJcccp75RQqxQAi3oDV"
   },
   "cacheContract": {
     "llmContextCacheOnly": [
@@ -35,14 +35,14 @@
       "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.7 cache refresh",
+    "defaultRefreshCommand": "npx -y wave3d-agent-sdk@0.2.8 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."
   },
   "corpus": {
     "skillCount": 67,
-    "apiEntryCount": 4198,
-    "apiMethodGroupCount": 4477,
+    "apiEntryCount": 4201,
+    "apiMethodGroupCount": 4480,
     "apiInheritanceCount": 735
   },
   "files": [
@@ -51,7 +51,7 @@
       "mediaType": "application/json",
       "role": "lookup-guide",
       "bytes": 1310,
-      "hash": "uvziS0PdxD95roJpyUHd_irZBSYTNRiu"
+      "hash": "_bPlWbDd1MsHtcdVNv44Gh_XgmdtIYHw"
     },
     {
       "path": "skills/wave-skills.jsonl",
@@ -78,15 +78,15 @@
       "path": "api/entries.jsonl",
       "mediaType": "application/jsonl",
       "role": "api-corpus",
-      "bytes": 4166730,
-      "hash": "hFz8Q9gbIUDOQd7_qBKKxpSB2FRLBNcw"
+      "bytes": 4169568,
+      "hash": "jyGCEHeyJe5VSmLHEBzGc-ehK02T4Im_"
     },
     {
       "path": "api/method-groups.jsonl",
       "mediaType": "application/jsonl",
       "role": "api-corpus",
-      "bytes": 1399676,
-      "hash": "3viG72Eg9mAQ4kMS8necAhcnMjoZJphS"
+      "bytes": 1400372,
+      "hash": "ddN0Bqv0ue3BIPuzp4fh3zBtTlUzSfjJ"
     },
     {
       "path": "api/inheritance.jsonl",
@@ -100,14 +100,14 @@
       "mediaType": "application/json",
       "role": "api-corpus",
       "bytes": 219,
-      "hash": "WoKr13lMgd32rfZUdvIqrgZT2T0N9GW8"
+      "hash": "63XcQbDuL3ZswbTi4kAzD_Jt04FXIONX"
     },
     {
       "path": "search/search-documents.jsonl",
       "mediaType": "application/jsonl",
       "role": "search-index",
-      "bytes": 3915328,
-      "hash": "5mwnSpVQwpPzHFxP8mkpgSXj3MvCM68D"
+      "bytes": 3917846,
+      "hash": "AnlOOjUCNs-BOUdLrYzW5ugcAEnTA7JF"
     },
     {
       "path": "README.md",

package/package.json

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