wave3d-agent-sdk 0.2.9 → 0.2.10

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.9 start
+npx -y wave3d-agent-sdk@0.2.10 start
 ```
 
 After Copy to Agent, run the exact start command 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.9 start
+WAVE3D_MCP_TOKEN="$MCP_TOKEN" npx -y wave3d-agent-sdk@0.2.10 start
 ```
 
 Check SDK build before trusting a running SDK process:
 
 ```bash
-npx -y wave3d-agent-sdk@0.2.9 --version
+npx -y wave3d-agent-sdk@0.2.10 --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.9 start
+npx -y wave3d-agent-sdk@0.2.10 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.9 cache search "continuous left rotation"
+npx -y wave3d-agent-sdk@0.2.10 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.9 cache refresh
+npx -y wave3d-agent-sdk@0.2.10 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

@@ -42488,8 +42488,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.9";
-var WAVE3D_AGENT_SDK_REQUIRED_BUILD = "agent-sdk-20260620.4";
+var WAVE3D_AGENT_SDK_REQUIRED_VERSION = "0.2.10";
+var WAVE3D_AGENT_SDK_REQUIRED_BUILD = "agent-sdk-20260621.1";
 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";
@@ -44421,7 +44421,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. 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.',
+  '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. Static VFS/package/asset-surface changes can be detected from file/package diffs and Studio may upgrade the tier automatically. Runtime-authored UI state changes cannot be inferred from files; if UI in `main.ts` changes bootstrap/world-provider/runtime-envelope state, store the state and call `waveStudio.reloadPreview({ reason, invalidates: ["world-provider"] })`. Valid invalidations are `bootstrap`, `world-provider`, and `runtime-envelope`. 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.",
@@ -44446,7 +44446,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. 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.",
+  '- Scene/runtime handles: prefer `myScene` for scene composition and `waveStudio` for Studio operations. If authored UI changes bootstrap/world-provider/runtime-envelope state and needs the Studio preview package to rebuild, call `waveStudio.reloadPreview({ reason, invalidates: ["world-provider"] })`, not `myScene.hotReload(...)`. Valid invalidations are `bootstrap`, `world-provider`, and `runtime-envelope`; use the narrowest true reason. `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(...)`.",
@@ -44483,11 +44483,11 @@ var WAVE_MCP_CODING_GUARDRAIL = [
   "6b. Asset facade split: passing an existing asset uses typed refs such as `models.X`, `textures.X`, `materials.X`, or `audios.X`; material authoring starts from `waveMaterial`; `assetManager` is reserved for exact low-level generated-asset/asset-pipeline APIs named by a local SDK skill or API lookup. Do not use `assetManager` as the default material, asset-ref, or path-surface authoring root.",
   '7. Use category-first asset discovery before referencing uploaded user assets, project aliases, or ambiguous built-in assets. Preferred tool: `find_wave_assets_by_category`; aliases: `list_wave_assets_by_category`, `search_wave_assets_by_category`, tolerant `list_wave_assets`. Choose category from user intent first, then query: `list_wave_assets_by_category({ category:"materials", query:"grass", limit:50 })`. For sound use `audios`, for 3D objects use `models`, for sky/HDR use `hdr`, for cube-map sky/environment use `cubeMaps`, for images use `textures`. Category-filtered responses can still be capped/truncated; absence there is not absence in the library. Only use asset refs returned by this tool. If the current code already contains the exact ref and the user asks for a small pattern-preserving edit, you may reuse that visible ref.',
   "7a. Use `list_wave_explorer_assets` when you need uploaded asset explorer metadata such as path, URL, size, or display/ref name for rename/delete/library work. It is not a fallback for built-in/public code refs and may be empty while `find_wave_assets_by_category` has many usable refs.",
-  "8. Wave Studio automations: `project.assetrefs.ts`, `project.scene.ts`, `project.scenes.ts`, and `project.execution.ts` are automatically managed by Wave Studio and are MCP read-only for agents. `bootstrap.ts` / scene `*/bootstrap.ts` is normally managed too. Edit bootstrap only when you can confidently pass `managedFileEditReason` as one of: `world_streaming_or_terrain_provider` (including Google Maps 3D tiles), `render_profile_or_runtime_backend`, `media_consent_or_capture_plan`, `external_ai_or_tts_backend`, `scene_envelope_or_template_baseline`, `baseline_setup_before_user_main`, or `stale_api_update_to_latest`. Never edit bootstrap for `asset_manifest_or_loader`, `instrument_registry`, `scene_registry`, or `execution_manifest`; Studio owns those. Do not edit managed files to register/preload assets, wire scenes, execution order, or force bootstrap sync; write user-authored scene code in `main.ts` or feature modules with bare refs like `models.Robot` or `textures.Grass`, then let Studio sync bootstrap/asset/scene/execution wiring. Hot reload is the normal way to see code changes. If the hot-reload path discovers new asset/bootstrap/scene-surface needs, Studio automatically upgrades the reload tier internally (`patchMain`, `preserveScene`, or hard `rebuildScene`). Only the hard rebuild tier performs a full bundled scene run.",
+  '8. Wave Studio automations: `project.assetrefs.ts`, `project.scene.ts`, `project.scenes.ts`, and `project.execution.ts` are automatically managed by Wave Studio and are MCP read-only for agents. `bootstrap.ts` / scene `*/bootstrap.ts` is normally managed too. Edit bootstrap only when you can confidently pass `managedFileEditReason` as one of: `world_streaming_or_terrain_provider` (including Google Maps 3D tiles), `render_profile_or_runtime_backend`, `media_consent_or_capture_plan`, `external_ai_or_tts_backend`, `scene_envelope_or_template_baseline`, `baseline_setup_before_user_main`, or `stale_api_update_to_latest`. Never edit bootstrap for `asset_manifest_or_loader`, `instrument_registry`, `scene_registry`, or `execution_manifest`; Studio owns those. Do not edit managed files to register/preload assets, wire scenes, execution order, or force bootstrap sync; write user-authored scene code in `main.ts` or feature modules with bare refs like `models.Robot` or `textures.Grass`, then let Studio sync bootstrap/asset/scene/execution wiring. Hot reload is the normal way to see code changes. Static VFS/package/asset-surface changes can be detected from file/package diffs, so Studio may upgrade the reload tier internally (`patchMain`, `preserveScene`, or hard `rebuildScene`). Runtime-authored UI state changes cannot be inferred from files; when UI changes bootstrap/world-provider/runtime-envelope state, call `waveStudio.reloadPreview({ reason, invalidates: ["world-provider"] })` with the narrowest valid invalidation: `bootstrap`, `world-provider`, or `runtime-envelope`. Only the hard rebuild tier performs a full bundled scene run.',
   "9. Use `waveStudio.*` only for Studio host services. Check `waveStudio.capabilities.assetSave` before save/bake calls.",
   '10. Make deterministic file edits through the simplest fitting tool. Default to forgiving `edit_wave_file`: oldText infers exact replace, startLine/endLine infers line replace, `edits:[{startLine,endLine,text}]` or `edits:[{rangeOffset,rangeLength,text}]` performs one-file multi-edit, and path+text/content with no oldText infers whole-file replace. It is the primary simple edit tool and can omit `baseHash`; Studio resolves the latest hosted VFS mirror contentHash and still applies browser-side stale-write checks. Prefer canonical fields: `path` for file path, `text` for line/whole-file content, and `newText` for text replacement; `filePath`, `replacement`, and `content` are accepted as aliases where useful. Use `apply_wave_patch({ operations: [...] })` for multi-file edits, grouped cross-file edits, unified diffs, or full rewrites; a single bare operation is tolerated for mistake recovery but operations:[...] is preferred. Use `create_wave_file`, `rename_wave_file`, and `delete_wave_file` to split projects into `.ts` modules such as `/actors/player.ts`, `/systems/obstacles.ts`, and `/levels/obby.ts` instead of growing one giant `main.ts`; newly created `.ts/.tsx` files are standalone runnable source roots by default, so top-level scene code in them runs on Run/hot reload. Pass `runnable:false` only for pure helper modules that should not execute on their own. These same VFS tools also create `.html` sketch files for diagrams/charts/docs, with Mermaid rendered from `<div class="mermaid">...</div>` when the HTML file is active in the editor/coding pane; HTML sketches must never replace the live engine preview iframe. Scene-root modules and their owned helpers run inside the Studio authoring context, but helpers should stay pure or parameterized. Studio hot reload targets the active/open edited file when safe: `/main.ts` reloads the whole main graph, scene-root modules reload that root, and bootstrap/scene registry/assets/network/ambiguous helper surfaces escalate. Standalone `hot_reload_wave_preview` has no target path and follows the currently open/active Studio editor file in multi-file projects. A feature file should own the objects, callbacks, promoted GLB parts, and appearance mutations it wants to iterate on. For intentional live entity reuse across modules, the owner calls `waveStudio.exportEntity("Name", entity)` and importers call `waveStudio.importEntity<T>("Name")`; do not pass live entities through shared helper exports. Use exact VFS paths from `list_wave_files`; read target file before writing. `contentHash` is a cooperative stale-write fingerprint, not a security boundary. For advanced compact `apply_wave_patch` operations, pass the latest full-file `contentHash` as `baseHash`: one `lineEdits`, one `textEdits`, one strict `searchReplace`, or one `unifiedDiff`. Do not send multiple compact ops for the same file with the same baseHash; the first edit changes the file hash and later compact ops skip as stale. Scoped `read_wave_file` line ranges do not change the `textEdits` offset base; they do pair naturally with line-based edits. Existing-file `writeFile` requires `baseHash` unless `forceOverwrite: true`; force overwrite is only for intentional stale overwrites.',
   "10a. Always inspect `changedFiles`, `changedPaths`, `partial`, `skippedOperations`, `hotReloadRequested`, `hotReloadSkippedReason`, and `runtimeVerification`; treat skipped operations, no-content-change skips, unscheduled hot reloads, runtime verification errors, and `runtimeVerification.diagnostics.editorErrorCount > 0` as work still needing attention.",
-  "11. After the final code edit, default to hot reload. Prefer `awaitHotReload: true` on the edit tool when you want one MCP response with edit result + hot reload + bounded diagnostics. `requestHotReload:true` also waits for diagnostics by default unless paired with `awaitHotReload:false`. Standalone `run_wave_preview` / `hot_reload_wave_preview` also wait by default and return `runtimeVerification`; set `awaitRuntimeResult:false` only for intentional fire-and-poll. Caveat: standalone `hot_reload_wave_preview` mirrors the toolbar button and reloads the currently open/active TypeScript file in multi-file projects; it does not take a target path or reload every user-created .ts module. That hot-reload request may internally upgrade from `patchMain` to `preserveScene` or hard `rebuildScene` when assets/bootstrap/scene surface changed; do not manually force bootstrap sync. Use `run_wave_preview` only when diagnostics show no successful preview yet (`hasRunSucceeded: false`), the user explicitly asks for a full run/restart, or hot reload/polling fails and a full restart is the last resort. `pause_wave_preview` and `resume_wave_preview` are direct preview controls mirroring the toolbar pause/resume buttons.",
+  '11. After the final code edit, default to hot reload. Prefer `awaitHotReload: true` on the edit tool when you want one MCP response with edit result + hot reload + bounded diagnostics. `requestHotReload:true` also waits for diagnostics by default unless paired with `awaitHotReload:false`. Standalone `run_wave_preview` / `hot_reload_wave_preview` also wait by default and return `runtimeVerification`; set `awaitRuntimeResult:false` only for intentional fire-and-poll. Caveat: standalone `hot_reload_wave_preview` mirrors the toolbar button and reloads the currently open/active TypeScript file in multi-file projects; it does not take a target path or reload every user-created .ts module. That hot-reload request may internally upgrade from `patchMain` to `preserveScene` or hard `rebuildScene` when assets/bootstrap/scene surface changed; do not manually force bootstrap sync. Runtime-authored UI that changes bootstrap/world-provider/runtime-envelope state must call `waveStudio.reloadPreview({ reason, invalidates: ["world-provider"] })` because Studio cannot infer that from static file diffs. Use `run_wave_preview` only when diagnostics show no successful preview yet (`hasRunSucceeded: false`), the user explicitly asks for a full run/restart, or hot reload/polling fails and a full restart is the last resort. `pause_wave_preview` and `resume_wave_preview` are direct preview controls mirroring the toolbar pause/resume buttons.',
   '12. After run/hot reload, use returned `runtimeVerification` when present; otherwise call `get_wave_runtime_diagnostics` repeatedly until `runtimeBusy` is false and `lastRuntimeOutcome` is `success` or `error`. Use `previewExecutionPhase` to distinguish Studio preparing work from the preview iframe executing it. `isRunning` is only the Studio scheduling flag, not the final runtime completion gate. If the edit/runtime tool returned `requestedAt` or `runtimeActionRequestedAt`, ignore diagnostics whose `lastRuntimeOutcomeAt` is older than that timestamp. Treat `latestError` as current only when `lastRuntimeOutcome` is `error`; older error lines can remain in returned logs as history. Treat `editorErrorCount > 0` as blocking Monaco/linter/compile failure and read `editorDiagnostics` before claiming success, even when `lastRuntimeOutcome` is `success`. If `lastRuntimeOutcome` is `success` and `editorErrorCount` is 0, verify visually with `capture_wave_screenshot({ resolution: "L" })` or structurally with `get_wave_runtime_entity_snapshot({ variableName, filePath? })` instead of declaring failure from old log text. Same-machine screenshots usually return `localPath`; hosted screenshots return exact field `dataBase64`, not `imageBase64`.',
   "12a. Marker waypoint workflow: when the human asks to use preview marking tools such as `clickToMark()`, route with `marker.use` plus the code/project intent, then call `list_wave_runtime_markers`. Treat marker records as runtime observation data, write marker `worldPosition`/`worldRotation` into the appropriate path/waypoint/placement code, hot reload, and verify with screenshot or marker re-read. One marker read may happen before routing only when needed to decide the code intent. Use path/placement skills only when current code does not reveal the marker-to-code pattern.",
   `13. To use locally generated assets in code, prefer \`create_wave_asset_upload\` for local files when available: pass assetKind from the Wave Studio upload policy SSOT (${getWaveStudioBridgeAssetUploadKindHelpText()}), stat the file first, pass exact byte size, get \`uploadUrl\` + \`uploadHeaders\`, upload raw bytes with plain HTTP PUT using every returned header exactly, keep \`clientToken\`/\`uploadHeaders.Authorization\` out of logs, call \`get_wave_asset_upload_status\` until \`receivedBytes === sizeBytes\`, then call \`commit_wave_asset_upload\` with the same uploadId, assetKind, filename, contentType, and sizeBytes from the create response. No local Python, Vercel package, or Blob SDK is required. On hosted MCP this uses hosted temporary object storage; on same-machine local MCP it uses the local SDK as temporary staging. If direct upload is unavailable, use \`stage_wave_asset_upload_chunk\` plus \`commit_wave_asset_chunk_upload\`: omit uploadId only for chunkIndex 0, then reuse the returned uploadId for every later chunk and for commit. Use \`upload_wave_asset\` with exactly one of \`dataBase64\` or \`dataUrl\` only for small inline assets. If staging is abandoned before commit, call \`abort_wave_asset_upload\` with the uploadId. Do not abort after commit returns pending or completed; the Studio browser cleans committed staging after execution. Hosted MCP cannot read local filesystem paths through inline upload. All flows stage bytes outside the command queue, cap staged bytes at 300 MB, and return \`asset.bareRef\`, for example \`textures.Albedo\`, \`cubeMaps.Studio\`, \`materials.Wood\`, \`audios.Click\`, \`models.Robot\`, \`animations.Run\`, \`fonts.Title\`, or \`serializedData.Config\`. If the name already exists, the upload result returns \`skipped: true\` and the existing asset. Staged chunks/blobs are also swept lazily after about 24 hours. Model-family uploads enable meshoptimizer by default unless \`useMeshoptimizer\` is false.`,
@@ -44664,7 +44664,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.reloadPreview({ reason?, invalidates? })`: request the Wave Studio toolbar-style reload path from authored code. Use `invalidates: ["world-provider"]` when UI authored in `main.ts` changes Studio/bootstrap-backed runtime state such as active city/world provider and must rebuild the Studio preview package. Valid invalidations are `bootstrap`, `world-provider`, and `runtime-envelope`; use the narrowest true reason. 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.',
@@ -46199,7 +46199,7 @@ var HOT_RELOAD_UNSAFE_SCENE_EVENT_CALLBACKS = /* @__PURE__ */ new Map([
   ["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.']
+  ["hotReload", 'Studio-authored code must not call myScene.hotReload(...). Use waveStudio.reloadPreview({ reason: "...", invalidates: ["world-provider"] }) when authored UI changes bootstrap/world-provider/runtime-envelope state 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."],
@@ -52407,10 +52407,8 @@ function readLocalSdkPeerHealth(value) {
   const data = isRecord4(value.data) ? value.data : value;
   const bridgeId = readStringProperty(data, "bridgeId");
   const protocolVersion = readStringProperty(data, "protocolVersion");
-  const requiredPackage = readStringProperty(data, "requiredPackage");
   const isCurrentSdkProtocol = protocolVersion === "waveengine-agent-sdk-http-v1";
-  const isLegacyHelperProtocol = protocolVersion === "local-agent-helper-http-v1" && typeof requiredPackage === "string" && requiredPackage.startsWith("wave3d-agent-bridge@");
-  if (!bridgeId || !bridgeId.startsWith("wgbridge_") || !isCurrentSdkProtocol && !isLegacyHelperProtocol) {
+  if (!bridgeId || !bridgeId.startsWith("wgbridge_") || !isCurrentSdkProtocol) {
     return null;
   }
   return {
@@ -52529,34 +52527,7 @@ async function findChildProcessIds(parentPid) {
   }
 }
 function isWaveEngineAgentProcessCommand(command) {
-  return /\bwave3d-agent-(sdk|bridge)\b/.test(command);
-}
-function isLegacyBridgePeer(health) {
-  return health.protocolVersion === "local-agent-helper-http-v1";
-}
-async function stopLegacyBridgeLaunchAgent(health) {
-  if (!isLegacyBridgePeer(health) || process.platform !== "darwin") return;
-  const getuid = process.getuid;
-  if (typeof getuid !== "function") return;
-  const uid = getuid();
-  const launchTarget = `gui/${uid}/com.wave3d.agent-bridge`;
-  console.log("[WaveEngine Agent SDK] Stopping legacy wave3d-agent-bridge launch agent before replacement.");
-  try {
-    await execFileAsync("launchctl", ["bootout", launchTarget], {
-      timeout: 2500,
-      maxBuffer: 128 * 1024,
-      windowsHide: true
-    });
-  } catch {
-  }
-  try {
-    await execFileAsync("launchctl", ["remove", "com.wave3d.agent-bridge"], {
-      timeout: 2500,
-      maxBuffer: 128 * 1024,
-      windowsHide: true
-    });
-  } catch {
-  }
+  return /\bwave3d-agent-sdk\b/.test(command);
 }
 async function collectVerifiedSdkPeerProcessIds(seedPids) {
   const targetPids = /* @__PURE__ */ new Set();
@@ -52641,7 +52612,6 @@ async function waitForSdkPeerPortRelease(port, deadlineMs) {
   return false;
 }
 async function terminateVerifiedSdkPeer(health, port) {
-  await stopLegacyBridgeLaunchAgent(health);
   const seedPids = /* @__PURE__ */ new Set();
   if (health.processId && health.processId !== process.pid) seedPids.add(health.processId);
   for (const pid of await findListenerProcessIds(port)) seedPids.add(pid);

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.TzPhd-nl78ioHZ5HHdOLeV95c3YCuOJf
-bundleHash: TzPhd-nl78ioHZ5HHdOLeV95c3YCuOJf
-zip: wave-engine-sdk-2026-06-17.1.TzPhd-nl78ioHZ5HHdOLeV95c3YCuOJf.zip
+cacheKey: 2026-06-17.1.fz3T9rwUI7jgxk1aZBl-4dloSaAXWjEf
+bundleHash: fz3T9rwUI7jgxk1aZBl-4dloSaAXWjEf
+zip: wave-engine-sdk-2026-06-17.1.fz3T9rwUI7jgxk1aZBl-4dloSaAXWjEf.zip

package/dist/sdk/manifest.json

@@ -1,21 +1,21 @@
 {
-  "version": "2026-06-17.1.TzPhd-nl78ioHZ5HHdOLeV95c3YCuOJf",
+  "version": "2026-06-17.1.fz3T9rwUI7jgxk1aZBl-4dloSaAXWjEf",
   "formatVersion": "2026-06-17.1",
-  "cacheKey": "2026-06-17.1.TzPhd-nl78ioHZ5HHdOLeV95c3YCuOJf",
-  "bundleFileName": "wave-engine-sdk-2026-06-17.1.TzPhd-nl78ioHZ5HHdOLeV95c3YCuOJf.zip",
-  "bundleHash": "TzPhd-nl78ioHZ5HHdOLeV95c3YCuOJf",
+  "cacheKey": "2026-06-17.1.fz3T9rwUI7jgxk1aZBl-4dloSaAXWjEf",
+  "bundleFileName": "wave-engine-sdk-2026-06-17.1.fz3T9rwUI7jgxk1aZBl-4dloSaAXWjEf.zip",
+  "bundleHash": "fz3T9rwUI7jgxk1aZBl-4dloSaAXWjEf",
   "generatedAt": "2026-06-06T00:00:00.000Z",
   "sourceVersions": {
     "onboarding": {
       "promptVersion": "2026-06-15.2",
-      "promptHash": "YyLcFG8-h779ReTOG7GOz4mjgutRtKZw"
+      "promptHash": "XmQbudg8ys8LmiXVENo3zVyngwfWfTD7"
     },
     "apiHandbook": {
       "version": "1",
       "contentHash": "edf117cbd2b09857"
     },
     "waveSkillCorpusHash": "nhg-WfsotIdN1pRO41g97bff6RrKujrN",
-    "sdkLookupCorpusHash": "1DUg8-FDFbzXLOMm12TB3-S_y4c6Z74H"
+    "sdkLookupCorpusHash": "cIY-jnbSR_-b2nlQgJwVDT7ffQyZ372l"
   },
   "cacheContract": {
     "llmContextCacheOnly": [
@@ -35,7 +35,7 @@
       "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.9 cache refresh",
+    "defaultRefreshCommand": "npx -y wave3d-agent-sdk@0.2.10 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."
   },
@@ -50,8 +50,8 @@
       "path": "cache-policy.json",
       "mediaType": "application/json",
       "role": "lookup-guide",
-      "bytes": 1310,
-      "hash": "PCkIsr75VpI_nQ4ufjVs-j13jCuh_YUL"
+      "bytes": 1311,
+      "hash": "cKZ5cpwWvIcymqtgXmCcrFyPK5pMUCKm"
     },
     {
       "path": "skills/wave-skills.jsonl",

package/package.json

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