unity-open-mcp 1.1.0 → 1.3.0

package/dist/skill/references/routing-and-lifecycle.md

@@ -0,0 +1,62 @@
+# Routing and lifecycle
+
+## Lifecycle & scene safety
+
+
+| Policy                | Meaning                                                                             | Tools                                                                                                                                                                                                                              |
+| --------------------- | ----------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `none`                | Read-only, returns immediately                                                      | `ping`, `find_members`, `validate_edit`, `checkpoint_create`, `delta`, `find_references`, `dependencies`, `scan_paths`, `read_asset`, `search_assets`, `list_assets`, `editor_status`, `read_console`, `screenshot`, `profiler_*`, `spatial_query`, `visual_compare` |
+| `editor_settle`       | Mutating; bridge waits for asset refresh/serialization to finish                    | `apply_fix`, `reserialize`                                                                                                                                                                                                         |
+| `restart_then_settle` | Mutating; may trigger domain reload; bridge blocks until compile finishes (cap 60s) | `execute_csharp`, `invoke_method`, `execute_menu`, `compile_check`                                                                                                                                                                 |
+| `custom_confirmation` | Async; returns immediately, result via external completion signal you poll          | `run_tests`                                                                                                                                                                                                                        |
+
+
+> The table above is the bridge's settle-timing surface (how long it blocks before returning). For the **recovery-axis** taxonomy — `none` / `compile-reload` / `modal-dialog` / `scene-dirty` / `process-stale`, describing what to do when a call fails or stalls — read `capabilities.tools[].lifecycle` (+ `lifecycleNote`) per tool, and `capabilities.lifecycleBlock` for the full class table. See the docs §Lifecycle policy for the `compile-reload` agent limits (notably `compile_check` is batch-only and returns `editor_instance_locked` when a live Editor holds the project lock).
+
+**Active-scene dirty guard.** Before any `restart_then_settle` op, the bridge preflights loaded scenes. If any scene has unsaved changes, the call refuses with `error.code = "scene_dirty"` + `dirtyScenes[]` + `agentNextSteps` so Unity's native save modal never interrupts. Recover by: saving first (`scene_save`), discarding (`EditorSceneManager.RestoreSavedSceneState()`), or passing `ignore_scene_dirty: true` on `execute_csharp` / `invoke_method` / `execute_menu` / `scene_create` / `scene_open` / `editor_set_state` / `build_set_target` / `build_set_defines` / `settings_set_player`.
+
+`scene_create` / `scene_open` are guarded only in their default Single mode (it closes every open scene without saving); `mode: "additive"` keeps open scenes and skips the guard. `apply_fix`, `reserialize`, and the other scene mutators (`scene_save` / `scene_unload` / `scene_set_active` / `scene_focus` / `sceneview_set_camera`) are **not** guarded.
+
+**Power-tool deny heuristic.** `execute_csharp` / `execute_menu` are blocked from destructive patterns by default (`EditorApplication.Exit`, `Application.Quit`, `AssetDatabase.DeleteAsset`, `BuildPipeline.BuildPlayer`, `File/Quit`, `TestRunnerApi`). Refused calls return `error.code = "denied_by_policy"` (csharp) or `"menu_blocked"` (menu) with the matched pattern + alternative. If you genuinely need one, set **both** `gate: "off"` and `confirm_bypass: true` — the bypass is audited. `execute_menu` also tells `menu_not_found` (no item at that path — fix the path) from `menu_disabled` (the item exists but its validate function rejected the current Editor state, e.g. nothing selected — change the selection/state, not the path).
+
+**`execute_csharp` runs on Unity's main thread — never block it.** The snippet executes synchronously inline on `EditorApplication.update`, so any blocking primitive wedges the editor **unrecoverably**: `WaitOne` / `.Result` / `Thread.Sleep` / `while(!done)` waiting for a callback, and driving `TestRunnerApi` (which delivers its callbacks on the same main thread), all deadlock. The HTTP timeout fires on the worker thread and **cannot self-heal a stuck main thread** — no further editor tick runs, so the editor must be killed externally. The timeout envelope's `agentNextSteps` will tell you this; heed it (check `editor_status` / `bridge_status` before retrying, **don't** just raise `timeout_ms`). For test execution use `unity_senses_run_tests` (async, does not block). For everything else, prefer a typed tool or write the snippet to be non-blocking (fire-and-forget + poll via a follow-up call).
+
+## Routing rules
+
+Treat `capabilities.routePolicy` + `batchCapable` as source of truth. `batchCapable` is about the **headless batch-spawn fallback** only (`capabilities.routing.perToolFlagMeaning` says so inline) — it does not decide what may be a nested `batch_execute` step.
+
+- **Live is the default** — when the bridge is connected, most tools route to `POST /tools/{name}` on the Editor.
+- **Batch fallback** — spawns headless Unity (`-batchmode`) **only** for `batchCapable: true` tools when the live bridge is unavailable. `find_members`, `execute_csharp`, `invoke_method`, and the allowed `execute_menu` subset can use this route; mutating power tools do not get the live gate/checkpoint flow in headless mode.
+- **Exact Editor guard** — before a headless spawn, the server reads `ProjectSettings/ProjectVersion.txt` and requires that exact installed Unity. `unity_version_not_installed` / `unity_version_mismatch` mean nothing was spawned; install or select the exact Editor, then retry (no server restart needed). Use `UNITY_OPEN_MCP_ALLOW_VERSION_MISMATCH=1` only for an intentional upgrade or compatibility run because a different Unity can rewrite package/project metadata during load.
+- **Senses are live-only** — `run_tests`, screenshots, profiler, console, spatial queries have no batch form.
+- **Offline reads** (`list_assets`, `find_references`, `read_asset`, `search_assets`) parse the project from disk and never need Unity. Coverage: text-serialized Unity YAML (`.prefab`/`.unity`/`.asset`/`.mat`/`.controller`/`.anim`/`.playable`/`.preset`/`.spriteatlas`/`.terrainlayer`/`.vfx`) **plus** JSON assets not covered by YAML-only parsers (`.asmdef`, `.shadergraph`/`.shadersubgraph`). `read_asset` also reconstructs the full hierarchy offline, parses prefab-variant overrides (matching `prefab_get_overrides`), and surfaces `integrity[]` signals (missing refs, missing scripts, malformed JSON, orphaned prefab instances) on the response — act on them before a `validate_edit` round-trip.
+- **`dependencies` is live-only** — it reuses the verify `Dependencies.Scanner` (forward) + `ReferenceGraph` (reverse), both of which call AssetDatabase. No offline form.
+- **`compile_check` is always batch** — spawns a fresh headless Unity that recompiles from scratch, even when the live bridge is up.
+- **Verify scans (`scan_all`, `baseline_create`, `regression_check`) are always batch** — they run in the headless verify package and are not registered on the live bridge, so even with the bridge up they spawn fresh Unity (`_route.fallbackReason: "verify_always_batch"`). Expect `editor_instance_locked` when a live Editor holds the project lock — close it and retry, or use the live `validate_edit` / `scan_paths` for a scoped health check instead.
+
+
+Snippets import `Object = UnityEngine.Object` automatically unless the caller supplies an Object alias. Snippets run in a separate assembly and can access public APIs. Use explicit reflection for inspection of internals; assembly-access bypass is not supported.
+
+## Session-owned jobs
+
+`unity_open_mcp_jobs` stays local and visible while Unity reloads or disconnects.
+Use it only when an operation has an explicit job adapter; declarations alone do
+not enable a job. `wait` observes for at most 30 seconds without owning execution.
+A lost connection is not proof of failure: `orphaned` requires operation-specific
+evidence before any retry. A `running` job with lifecycle `disconnected` is still
+being observed through a busy or unreachable Editor; keep waiting.
+`cancel_requested` is not cancellation confirmation.
+Terminal records and idempotency keys survive for 30 minutes in the same server
+session, but not across a server restart. Keep routing and agent metadata stable.
+While a project job runs, conflicting calls return `job_busy` with `error.job`
+(`jobId`, `commandId`, `phase`) and `agentNextSteps`. `execute_csharp` is refused
+even with `read_only: true`: the bridge cannot verify a snippet writes nothing.
+The starting agent waits with that `jobId` (others get `job_not_found`); use typed
+reads meanwhile and retry once after a terminal state, never in a loop.
+
+
+For project commands, exact describe precedes invoke/start. After async start,
+call status and bounded wait; inspect terminal gate results even on failure or
+cancellation. A job does not weaken scope, deny or dirty-scene policy. Never use
+reflection to bypass an unavailable declaration. Builds/imports/packages/bakes
+are unsupported job targets.

package/dist/skill/references/senses-and-tests.md

@@ -0,0 +1,41 @@
+# Senses and tests
+
+## Agent senses (live-only, no batch fallback)
+
+- `**unity_senses_run_tests`** — EditMode + PlayMode test runner with per-test pass/fail. Filter by assembly / namespace / class / method. Set `include_passes: false` on large suites to avoid truncation. **Never fire a second `run_tests` before the first resolves** (no concurrency guard; results interleave). Results are retrieved by the server polling a results file (NOT via `unity_senses_pull_events`). A run that is superseded by a newer run, or aborted when play mode is entered mid-EditMode-run, writes a terminal file with `status:"aborted"` + `reason` (`superseded_by_run` | `playmode_entered`) — the poll resolves to that instead of timing out.
+  - **Zero-match looks like "no results".** When the filter matches zero tests, `TestRunnerApi.Execute` runs nothing and the result is `status:"completed"` with `summary.total:0` and a `note` — that is a no-match filter, not a failure. `test_class` maps to NUnit `groupNames` (a partial/group match), and `assembly_name` must name a real test assembly.
+  - **Single-test workaround.** To run one test method deterministically (and get NUnit assertion failures verbatim), invoke the test class/method directly via `unity_open_mcp_invoke_method` instead of `run_tests`.
+  - **Brief reloading window after a run.** A test run (PlayMode especially) can trigger a Unity domain reload that freezes the bridge's heartbeat for a few seconds. The MCP server recognizes an in-flight run and treats that window as a normal reload rather than a dead bridge, so subsequent tools keep waiting instead of failing fast with `bridge_compile_failed`. For robustness, after `run_tests` returns `{status:"started", runId}`, poll the result file (or call `ping` / `editor_status`) once before issuing other tools — the run itself is async and the bridge may still be settling.
+  - **Headless / CI alternative.** `run_tests` has no MCP batch form (it needs a live Editor). For headless CI, invoke Unity's CLI directly with `-runTests`. **Omit `-quit`** — with `-quit` the editor exits after the initial asset refresh, *before* the test runner starts, so no tests run and no XML is written despite an exit code of 0. The correct invocation:
+    ```
+    Unity -batchmode -projectPath <project> -runTests -testPlatform EditMode \
+          -testResults out.xml -logFile run.log -nographics
+    ```
+    Exit codes: `0` = all tests passed, `2` = test failures present (NOT a process error — do not treat 2 as a crash), `3` = test runner setup failure. Known **batchmode-only** red tests that pass in the GUI editor — don't try to "fix" these, validate them in the GUI editor instead: in-process HTTP-server lifecycle (socket-disposed), GPU/SceneView (no graphic device under `-nographics`), Unity-6's removed `LogEntries.GetEntries(List<LogEntry>)` internal API (console/capture), MSBuild/Roslyn `Microsoft.Build.Utilities.Core` host assembly load, and TimeManager SerializedProperty float access.
+- `**unity_senses_read_console`** — console entries via reflection. Filter `type: "error"` to confirm clean compile. `detail: "summary"` for messages only (saves tokens); `detail: "verbose"` includes Unity-internal frames.
+- `**unity_senses_screenshot**` — Scene / Game / **composed** / isolated 2×2 composite of one GameObject. `view: "game"` renders `Camera.main` **only** — Screen-Space Overlay UI and multi-camera compositions are NOT in the frame; use `view: "composed"` to verify UI edits (the full player frame: all cameras by depth + Overlay canvases).
+- `**unity_senses_screenshot_camera**` — render from an arbitrary world-space pose (position + rotation + fov) without moving the scene/game camera; transient camera, scene camera untouched.
+- `**unity_senses_capture_inline**` — same targets as `screenshot` but returns the PNG as an inline base64 image (no temp file) for agents that don't read the filesystem.
+- `**unity_senses_visual_compare**` — visual regression: capture a named reference snapshot (`action: save`) from scene / game / isolated view, then `action: compare` a later capture against it to check whether an edit visually broke anything. Returns `pixelDiffPercent`, `mismatchedPixels`, `perceptualDistance` (8×8 average-hash Hamming distance — tolerates minor anti-aliasing drift), and `match` (true when `pixelDiffPercent <= sensitivity * 100`; default `sensitivity: 0.01` = 1%). On a non-zero diff, returns an inline diff image (mismatched pixels highlighted red over the current frame). References persist under `~/.unity-open-mcp/screenshots/references/`; `action: list` / `delete` manage them. The `compare` resamples the current capture to the reference dimensions if they differ, so the diff is resolution-stable.
+- `**unity_senses_screenshot_window**` — capture an Editor window (Console / Hierarchy / Inspector / Project / Scene / Game / custom). **Windows-only**: on macOS/Linux returns `not_supported` (the editor-window backbuffer is not bound during bridge dispatch, so a readback produces a blank frame) — use the OS screen-capture tool, or `screenshot {view:"composed"}` for the rendered Game view. On Windows, a blank/solid-color frame is rejected with `blank_capture` rather than reported as `ok`.
+- `**unity_senses_frame_debugger**` — control Unity's Frame Debugger: `action: enable` opens the window and starts capturing, `action: disable` stops it, `action: list` returns the draw-call list (shader / pass / material / render target / vertex/index/instance counts per call). Read-only (gate off); the response reports `windowOpened` so you know Editor UI may have changed. Enable, render a frame, then call `list` to inspect draw calls.
+- `**unity_senses_profiler_capture**` / `profiler_memory` / `profiler_rendering` — frame hierarchy, memory allocators, rendering env.
+- `**unity_senses_profiler_capture_frame`** — single-frame deep profiler capture. Returns one (or a few, via `frame_count`) frame's full sample tree, optionally filtered by `modules` (Profiler category names, e.g. "CPU,Rendering"). Deeper than `profiler_capture`; bound output with `max_depth` (default 8) and `max_items` (default 200). If the Profiler is off, the tool enables it for the capture, then restores it to disabled once data is captured; `profilerWasEnabled` reports the PRIOR state. On a cold capture (Profiler was off and no frame is recorded yet) the tool returns `status:"warming_up"` instead of blocking — it leaves the Profiler enabled, so re-issue the call shortly to receive the frame data.
+- `**unity_senses_spatial_query**` — physics-based raycast / overlap / bounds / ground_check / nearest against the live scene.
+- `**unity_senses_pull_events**` — incremental console logs + editor-state transitions (compile start/stop, play-mode). Cheaper than `read_console` for "what happened since my last call"; first call opens the stream, later calls return only new events. Returns `bridge_unavailable` when the bridge is down. The stream self-heals across Unity restarts and domain reloads (the server re-reads the bridge port+token from the instance lock on every reconnect, backing off 2s→30s), so after a reload keep polling instead of assuming the stream is dead.
+
+**Verification habit:** after any C# change, run `read_console` with `type: "error"` (or `run_tests` on the affected assembly) to confirm compile + tests pass before declaring done.
+
+### Return serialization (execute_csharp / invoke_method)
+
+Results are walked by a depth-limited reflective serializer before becoming `mutation.output`:
+
+- Structs/POCOs → JSON objects with public fields/props (`return new Vector3(1,2,3)` → `{"$type":"Vector3","x":1,"y":2,"z":3}`).
+- Lists truncate to 100 items (`max_items` configurable); truncated arrays report `{"items":[...],"truncated":N}`.
+- Recursion caps at depth 4 (`max_depth` configurable).
+- Cycles / `UnityEngine.Object` refs never infinite-loop — back-edges become `{"$ref":"TypeName"}`, Unity objects become `{"$type":...,"name":...,"instanceId":...}`.
+- **Malformed output is rejected, not trusted.** The per-member walk is try/catch'd, but an exception can still escape mid-walk (e.g. a `TypeLoadException` when a field references a missing assembly), leaving unbalanced JSON. `execute_csharp` validates the serialized output before it enters the envelope; if it isn't a balanced JSON object the call fails with `error.code = "execution_error"` and a diagnostic naming the return type. On the rare chance the body is still corrupted in transit, the MCP server surfaces `bridge_response_unparsable` instead of a fake success — either way you'll never see a `_compileVerify`-annotated result missing its `mutation` block.
+
+### `execute_csharp` read-only probe flag (`read_only`)
+
+`execute_csharp` defaults to mutating and requires a non-empty `paths_hint`. For pure inspection, pass `read_only: true`: no scope, checkpoint, or validation is needed, even when the scene is dirty or a hint was supplied. This is a caller assertion, not a sandbox: never use it for writes or disruptive lifecycle transitions. Known compile/refresh, scene-switch, and play-transition calls retain protection, and the deny heuristic still applies. See the request and batch guidance below.

package/dist/skill/references/yaml-and-offline-work.md

@@ -0,0 +1,33 @@
+# YAML and offline work
+
+### Reserialize after direct YAML edits
+
+When you edit `.prefab` / `.unity` / `.asset` / `.mat` / `.controller` / `.anim` directly as YAML text, run `**unity_open_mcp_reserialize`** with the touched `paths` (the `paths` array doubles as gate scope). Round-trip rewrites canonically so missing fields, wrong indentation, and stale `fileID` references surface in `gate.delta`. Whole-project reserialize is intentionally unsupported — enumerate assets you edited. Default targets asset YAML only (no `.meta` diff on body-only edits); pass `include_meta: true` only for upgrade/importer-change workflows.
+
+Prefer a typed live tool while the Editor is reachable. Never directly edit an open or dirty scene or asset YAML. If direct editing is necessary, explicitly identify the offline-file route and confirm the target is not open/dirty. Offline work remains supported when the Editor is unavailable or the user chooses file-level repair. Preserve GUID/fileID relationships and verify the intended scene: wrong-scene edits can silently damage a different asset. Reimport/reserialize the touched files and run scoped validation before trusting the result.
+
+### read_asset: map, not dump
+
+Raw Unity YAML is enormous. `read_asset` returns counts, a `cmp` table declaring repeated component sets once (referenced by `c1`/`c2` codes), and a folded `tree`. Drill down with `field_limit` + `component` / `path` / `profile=full` (or `detail=verbose`) instead of re-reading raw YAML. Session cache reuses the parsed model (`_cache: "hit"`). `profile: full` disables render-only folding; `field_limit: 0` (default) returns names only — bump it before `component` drill-down so fields are available. `page_size`/`cursor` page the `tree` rows.
+
+Use `**search_assets`** to locate prefabs/components/GUIDs; each result tags *why* it matched so you know which `read_asset` drill-down to run next.
+
+### Reads that save tokens
+
+Raw Unity data is large. Prefer the cheap, structured reads before reaching for verbose output:
+
+- **`read_asset`** returns a folded `tree` + `cmp` table + counts, not raw YAML. Drill into a subtree with `component` / `path` + `field_limit` instead of re-reading the whole asset; the parsed model is session-cached (`_cache: "hit"`). `field_limit: 0` (default) returns field names only — bump it only for a `component` drill-down where you need values.
+- **`manage_tools(action="list_groups")`** — sessions start with two default-on groups (`core` + `gate-and-verify`); activate only the other group you need so the full **250+ tool** surface stays out of the prompt. Prefer `action="activate_for"` with a free-text `intent` (or `action="suggest"` to preview) over hand-picking ids — it brings the right groups online in one call.
+- **`read_console`** with `detail: "summary"` returns messages only; reserve `detail: "verbose"` for when you need Unity-internal stack frames.
+- **`search_assets`** tags *why* each result matched, so you skip broad reads and go straight to the right drill-down.
+- **Output profiles + paging.** The heavy tools (`read_asset`, `search_assets`, `scene_get_data`, `find_references`, `validate_edit`, `scan_paths`, `component_get`) take `profile: compact|balanced|full` (`compact` is the default — the cheap folded/counts shape). Raise to `balanced`/`full` to expand. Page large results with `page_size` + the `pagination.next_cursor` token (omit `page_size` to get the whole payload at once). For `component_get`, start compact then use `property_path` or paging to expand one subtree. For `find_references` / `validate_edit` / `scan_paths`, the compact default returns counts/groupings only — pass `profile: "balanced"` to get the per-asset / per-issue lists those tools previously returned by default. (The legacy `detail` / `max_results` / `max_nodes` caps remain as aliases.)
+- **`capabilities`** before assuming tool names/schemas/route policy — cheaper than discovering a tool's real signature by trial and error.
+- **Prefer typed tools** (`component_modify`, `scene_get_data`, …) over `execute_csharp` / `invoke_method` — explicit schemas, smaller request/response envelopes, same gate.
+
+### find_references before delete
+
+Before deleting or moving an asset, call `**find_references*`* to see who depends on it. Offline-first (no live bridge needed for text-serialized assets).
+
+### dependencies: both directions in one call
+
+When you need **both** directions (what this asset depends on AND what depends on it), or the broken-edge / cycle view, call `**dependencies*`*. It returns the forward + reverse edge sets plus the same `broken_dependency` GUIDs and `dependency_cycle` trails the `dependencies` verify rule computes — no second dependency graph is built (it reuses the verify scanner + the `find_references` reverse walker). Live bridge only (the scanners call AssetDatabase); pass `detail: "summary"` for counts only when you just need the magnitude.

package/dist/templates/mcp-wrapper.sh

@@ -0,0 +1,35 @@
+#!/usr/bin/env bash
+# unity-open-mcp MCP wrapper.
+#
+# Resolves UNITY_PROJECT_PATH from THIS SCRIPT'S location, so it works no
+# matter what working directory the AI client spawns the MCP server in. Use it
+# for clients that expand neither ${workspaceFolder} nor environment variables
+# in their MCP config (for example Codex and ZCode).
+#
+# Committed to the repository; contains no machine-specific paths.
+# Regenerate with: unity-open-mcp setup --wrapper …
+#
+# Override the Unity subfolder for a one-off run:
+#   UNITY_SUBPATH=OtherClient bash <this script>
+set -euo pipefail
+
+script_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+workspace_root="$(cd "${script_dir}/__WORKSPACE_FROM_SCRIPT__" && pwd)"
+subpath="${UNITY_SUBPATH-__UNITY_SUBPATH__}"
+
+if [ -n "${subpath}" ]; then
+  project_path="${workspace_root}/${subpath}"
+else
+  project_path="${workspace_root}"
+fi
+
+for marker in __UNITY_ROOT_MARKERS__; do
+  if [ ! -d "${project_path}/${marker}" ]; then
+    echo "unity-open-mcp: ${project_path} is not a Unity project root (missing ${marker}/)." >&2
+    echo "unity-open-mcp: set UNITY_SUBPATH to the Unity folder relative to ${workspace_root}." >&2
+    exit 1
+  fi
+done
+
+export UNITY_PROJECT_PATH="${project_path}"
+exec npx -y "unity-open-mcp@__UNITY_OPEN_MCP_VERSION__" "$@"

package/dist/tool-contract.d.ts

@@ -0,0 +1,8 @@
+import type { Tool } from "@modelcontextprotocol/sdk/types.js";
+type Schema = Record<string, any>;
+/** Locator names are explicit in the published contract; aliases retain their wire key. */
+export declare function canonicalSchema(name: string, input: Schema): Tool["inputSchema"];
+/** Validate before dispatch, including nested records; arbitrary value payloads stay opaque. */
+export declare function validateSchema(value: any, schema: Schema, path?: string): string[];
+export declare function wireArguments(value: any, schema: Schema, notes?: string[]): any;
+export {};

package/dist/tool-contract.js

@@ -0,0 +1,253 @@
+import { implementedRules } from "./capabilities/rule-catalog.js";
+// Explicit semantic inventory: prose edits must never change a locator contract.
+const GAME_OBJECT_PATH_TOOLS = new Set([
+    "unity_senses_spatial_query",
+    "unity_open_mcp_prefab_create",
+    "unity_open_mcp_prefab_apply",
+    "unity_open_mcp_prefab_revert",
+    "unity_open_mcp_prefab_unpack",
+    "unity_open_mcp_prefab_get_overrides",
+    "unity_open_mcp_prefab_status",
+    "unity_open_mcp_gameobject_destroy",
+    "unity_open_mcp_gameobject_duplicate",
+    "unity_open_mcp_gameobject_find",
+    "unity_open_mcp_gameobject_modify",
+    "unity_open_mcp_gameobject_set_parent",
+    "unity_open_mcp_component_add",
+    "unity_open_mcp_component_destroy",
+    "unity_open_mcp_component_get",
+    "unity_open_mcp_component_modify",
+    "unity_open_mcp_scene_focus",
+    "unity_open_mcp_selection_set",
+    "unity_open_mcp_navigation_surface_add",
+    "unity_open_mcp_navigation_set_bake_settings",
+    "unity_open_mcp_navigation_surface_bake",
+    "unity_open_mcp_navigation_modifier_add",
+    "unity_open_mcp_navigation_modifier_volume_add",
+    "unity_open_mcp_navigation_link_add",
+    "unity_open_mcp_navigation_agent_add",
+    "unity_open_mcp_navigation_agent_set_destination",
+    "unity_open_mcp_navigation_get",
+    "unity_open_mcp_navigation_modify",
+    "unity_open_mcp_probuilder_get_mesh_info",
+    "unity_open_mcp_probuilder_extrude",
+    "unity_open_mcp_probuilder_delete_faces",
+    "unity_open_mcp_probuilder_set_face_material",
+    "unity_open_mcp_particle_system_get",
+    "unity_open_mcp_particle_system_modify",
+    "unity_open_mcp_splines_add_knot",
+    "unity_open_mcp_splines_set_knot",
+    "unity_open_mcp_splines_set_tangent_mode",
+    "unity_open_mcp_splines_evaluate",
+    "unity_open_mcp_splines_get_knots",
+    "unity_open_mcp_splines_modify",
+    "unity_open_mcp_light_add",
+    "unity_open_mcp_light_set",
+    "unity_open_mcp_light_modify",
+    "unity_open_mcp_reflection_probe_bake",
+    "unity_open_mcp_reflection_probe_get",
+    "unity_open_mcp_audio_source_add",
+    "unity_open_mcp_audio_source_modify",
+    "unity_open_mcp_ui_canvas_add",
+    "unity_open_mcp_ui_layout_group_add",
+    "unity_open_mcp_ui_element_modify",
+    "unity_open_mcp_constraint_add",
+    "unity_open_mcp_lod_group_configure",
+    "unity_open_mcp_lod_add_level",
+    "unity_open_mcp_terrain_set_heights",
+    "unity_open_mcp_terrain_paint_layer",
+    "unity_open_mcp_terrain_place_trees",
+    "unity_open_mcp_terrain_set_neighbors",
+    "unity_open_mcp_cinemachine_set_targets",
+    "unity_open_mcp_cinemachine_set_lens",
+    "unity_open_mcp_cinemachine_set_body",
+    "unity_open_mcp_cinemachine_set_noise",
+    "unity_open_mcp_cinemachine_brain_ensure",
+    "unity_open_mcp_timeline_director_bind",
+    "unity_open_mcp_tilemap_set_tile",
+    "unity_open_mcp_tilemap_box_fill",
+]);
+const ASSET_PATH_TOOLS = new Set([
+    "unity_open_mcp_scene_create",
+    "unity_open_mcp_scene_open",
+    "unity_open_mcp_scene_save",
+    "unity_open_mcp_scene_unload",
+    "unity_open_mcp_scene_set_active",
+    "unity_open_mcp_scene_get_data",
+]);
+// GameObject host selectors for the "supply only one selector" rule. `name`
+// selects by name unless the tool uses it as a payload; such tools name their
+// by-name selector here and publish their full set as `x-gameobject-selectors`,
+// which the bridge's BatchSchemaValidator reads from the generated schema.
+const DEFAULT_GAMEOBJECT_SELECTORS = ["instance_id", "game_object_path", "path", "target_path", "name"];
+const NAME_SELECTOR_OVERRIDES = {
+    // `name` is the new name; the target is resolved by name_target.
+    unity_open_mcp_gameobject_modify: "name_target",
+};
+/** Selector keys the one-selector rule applies to; null when the schema has no GameObject host. */
+function gameObjectSelectors(schema) {
+    if (Array.isArray(schema["x-gameobject-selectors"]))
+        return schema["x-gameobject-selectors"];
+    if (schema["x-project-command"] || !schema.properties?.game_object_path)
+        return null;
+    return DEFAULT_GAMEOBJECT_SELECTORS.filter(k => schema.properties[k]);
+}
+/** Locator names are explicit in the published contract; aliases retain their wire key. */
+export function canonicalSchema(name, input) {
+    const schema = structuredClone(input);
+    const props = schema.properties;
+    // offline_integrity is a reporting aggregator, not a registered VerifyRunner rule.
+    for (const key of ["include_rules", "exclude_rules", ...(name === "unity_open_mcp_scan_paths" ? ["categories"] : [])])
+        if (props[key]?.items)
+            props[key].items.enum = implementedRules().filter(r => r.id !== "offline_integrity").map(r => r.id);
+    const rename = (s, old, key) => {
+        if (!s.properties?.[old] || s.properties[key])
+            return;
+        s.properties[key] = { ...s.properties[old], "x-wire-key": old };
+        s.properties[old] = { ...s.properties[old], deprecated: true, "x-alias-for": key,
+            description: `Deprecated alias; use ${key}.` };
+        delete s.properties[old].default;
+        if (s.required?.includes(old)) {
+            s.required = s.required.filter((k) => k !== old);
+            s.allOf = [...(s.allOf ?? []), { anyOf: [{ required: [key] }, { required: [old] }] }];
+        }
+    };
+    if (GAME_OBJECT_PATH_TOOLS.has(name))
+        rename(schema, "path", "game_object_path");
+    if (ASSET_PATH_TOOLS.has(name))
+        rename(schema, "path", "asset_path");
+    rename(schema, "prefab_asset_path", "asset_path");
+    if (props.prefab_asset_path)
+        props.prefab_path = { type: "string", deprecated: true, "x-alias-for": "asset_path", description: "Deprecated alias; use asset_path." };
+    if (props.game_object_path && !props.target_path)
+        props.target_path = { type: "string", deprecated: true, "x-alias-for": "game_object_path", description: "Deprecated alias; use game_object_path." };
+    if (/component_(get|modify|add)/.test(name))
+        rename(schema, "type_name", "component_type");
+    if (name.endsWith("component_modify"))
+        rename(props.fields.items, "path", "property_path");
+    if (name === "unity_open_mcp_find_references" || name === "unity_open_mcp_dependencies") {
+        props.path = { type: "string", deprecated: true, "x-alias-for": "asset_path", description: "Deprecated alias; use asset_path." };
+        for (const branch of schema.oneOf ?? [])
+            if (branch.required?.includes("asset_path")) {
+                branch.required = branch.required.filter((k) => k !== "asset_path");
+                branch.anyOf = [{ required: ["asset_path"] }, { required: ["path"] }];
+            }
+    }
+    if (props.prefab_path)
+        for (const clause of schema.allOf ?? [])
+            if (clause.anyOf?.some((b) => b.required?.includes("asset_path")))
+                clause.anyOf.push({ required: ["prefab_path"] });
+    if (props.game_object_path) {
+        const nameSelector = NAME_SELECTOR_OVERRIDES[name] ?? "name";
+        if (nameSelector !== "name")
+            schema["x-gameobject-selectors"] = DEFAULT_GAMEOBJECT_SELECTORS.map(k => k === "name" ? nameSelector : k).filter(k => props[k]);
+        props.game_object_path.description = `GameObject hierarchy path, e.g. Root/Child. Supply only one host selector: instance_id, game_object_path, or ${nameSelector}.`;
+    }
+    if (props.component_type)
+        props.component_type.description = "Component type (full name preferred); alternative to component_instance_id.";
+    return schema;
+}
+/**
+ * An explicit `null` for an OPTIONAL property whose schema declares a
+ * non-null type is read as "omitted": MCP clients routinely serialize an
+ * absent optional argument as null, and the bridge's own readers treat such a
+ * value as absent. A required property, a property without a declared type
+ * (opaque patch values such as component_modify's `value`) and a type that
+ * lists `null` keep the value as sent.
+ */
+function isNullOmitted(schema, key, value) {
+    if (value !== null)
+        return false;
+    if ((schema.required ?? []).includes(key))
+        return false;
+    const type = schema.properties?.[key]?.type;
+    if (!type)
+        return false;
+    return !(Array.isArray(type) ? type : [type]).includes("null");
+}
+/** `value` without its null-omitted properties; the input object is not mutated. */
+function withoutNullOmitted(value, schema) {
+    if (!schema.properties)
+        return value;
+    const kept = Object.entries(value).filter(([key, v]) => !isNullOmitted(schema, key, v));
+    return kept.length === Object.keys(value).length ? value : Object.fromEntries(kept);
+}
+/** Validate before dispatch, including nested records; arbitrary value payloads stay opaque. */
+export function validateSchema(value, schema, path = "args") {
+    if (value && typeof value === "object" && !Array.isArray(value))
+        value = withoutNullOmitted(value, schema);
+    const errors = [];
+    for (const op of ["anyOf", "oneOf", "allOf"])
+        if (schema[op]) {
+            const n = schema[op].filter((s) => validateSchema(value, s, path).length === 0).length;
+            if ((op === "anyOf" && !n) || (op === "oneOf" && n !== 1) || (op === "allOf" && n !== schema[op].length))
+                errors.push(`${path} must satisfy ${op}`);
+        }
+    const matches = (t) => t === "array" ? Array.isArray(value) : t === "object" ? value !== null && typeof value === "object" && !Array.isArray(value) : t === "integer" ? Number.isInteger(value) : t === "null" ? value === null : typeof value === t;
+    if (schema.type && !(Array.isArray(schema.type) ? schema.type : [schema.type]).some(matches))
+        return [`${path} must be ${schema.type}`];
+    if (schema.enum && !schema.enum.includes(value))
+        errors.push(`${path} must be one of ${schema.enum.join(", ")}`);
+    if (value && typeof value === "object" && !Array.isArray(value)) {
+        for (const key of schema.required ?? [])
+            if (value[key] === undefined)
+                errors.push(`${path}.${key} is required`);
+        const selectorKeys = gameObjectSelectors(schema);
+        if (selectorKeys) {
+            const supplied = (k) => value[k] !== undefined && value[k] !== null && value[k] !== "" && value[k] !== 0 && value[k] !== "0";
+            const selectors = selectorKeys.filter(supplied);
+            if (selectors.length > 1)
+                errors.push(`${path}: supply only one GameObject selector (prefer game_object_path); ignored keys: ${selectors.join(", ")}`);
+            if (supplied("component_instance_id") && ["component_type", "type_name"].some(supplied))
+                errors.push(`${path}: component_instance_id and component_type are alternatives`);
+        }
+        if (schema.properties)
+            for (const [key, child] of Object.entries(value)) {
+                const prop = Object.prototype.hasOwnProperty.call(schema.properties, key) ? schema.properties[key] : undefined;
+                if (!prop && schema.additionalProperties === false)
+                    errors.push(`${path}.${key} is unknown; canonical keys: ${Object.keys(schema.properties).filter(k => !schema.properties[k].deprecated).join(", ")}`);
+                if (prop) {
+                    if (prop["x-alias-for"] && Object.keys(value).some(other => other !== key && (other === prop["x-alias-for"] || schema.properties[other]?.["x-alias-for"] === prop["x-alias-for"])))
+                        errors.push(`${path}.${key} conflicts with another selector; use only ${prop["x-alias-for"]}`);
+                    errors.push(...validateSchema(child, prop, `${path}.${key}`));
+                }
+            }
+    }
+    if (Array.isArray(value) && schema.items)
+        value.forEach((v, i) => errors.push(...validateSchema(v, schema.items, `${path}[${i}]`)));
+    if (typeof value === "string" && schema.pattern && !new RegExp(schema.pattern).test(value))
+        errors.push(`${path} does not match ${schema.pattern}`);
+    const size = typeof value === "number" ? value : typeof value === "string" || Array.isArray(value) ? value.length : undefined;
+    if (size !== undefined) {
+        for (const k of ["minimum", "minItems", "minLength"])
+            if (schema[k] !== undefined && size < schema[k])
+                errors.push(`${path} violates ${k}`);
+        if (typeof value === "number" && schema.exclusiveMinimum !== undefined && value <= schema.exclusiveMinimum)
+            errors.push(`${path} violates exclusiveMinimum`);
+        if (typeof value === "number" && schema.exclusiveMaximum !== undefined && value >= schema.exclusiveMaximum)
+            errors.push(`${path} violates exclusiveMaximum`);
+        for (const k of ["maximum", "maxItems", "maxLength"])
+            if (schema[k] !== undefined && size > schema[k])
+                errors.push(`${path} violates ${k}`);
+    }
+    return errors;
+}
+export function wireArguments(value, schema, notes = []) {
+    if (Array.isArray(value))
+        return value.map(v => wireArguments(v, schema.items ?? {}, notes));
+    if (!value || typeof value !== "object" || !schema.properties)
+        return value;
+    const out = {};
+    // Null-omitted properties never reach the wire: the bridge validates the
+    // same schema and would otherwise refuse the null the server just waived.
+    for (const [key, v] of Object.entries(withoutNullOmitted(value, schema))) {
+        const p = schema.properties[key] ?? {};
+        const canonical = p["x-alias-for"];
+        if (canonical)
+            notes.push(`${key} is deprecated; use ${canonical}.`);
+        const target = p["x-wire-key"] ?? (canonical ? schema.properties[canonical]?.["x-wire-key"] ?? canonical : key);
+        out[target] = wireArguments(v, p, notes);
+    }
+    return out;
+}
+//# sourceMappingURL=tool-contract.js.map

package/dist/tool-contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-contract.js","sourceRoot":"","sources":["../src/tool-contract.ts"],"names":[],"mappings":"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"}

package/dist/tool-router.d.ts

@@ -1,7 +1,9 @@
+import { JobManager } from "./jobs/job-manager.js";
+import { type RequestIdentity } from "./agent-identity.js";
+import { type BridgeTagConfirmation } from "./release-lookup.js";
 import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
 import type { Router } from "./router.js";
-import type { LiveClient } from "./live-client.js";
-import type { BatchSpawn } from "./batch-spawn.js";
+import { LiveClient } from "./live-client.js";
 import type { BridgeEventStream } from "./event-stream.js";
 export declare function resolveRouteLogEnabled(env?: NodeJS.ProcessEnv): boolean;
 export declare const ROUTE_LOG_ENABLED: boolean;
@@ -23,7 +25,8 @@ export interface HubControlBackend {
     getInstallPath(): InstallPathResult;
     setInstallPath(path: string): ReturnType<typeof setInstallPath>;
 }
-import type { ToolSessionState } from "./tool-session-state.js";
+import { BatchSpawn } from "./batch-spawn.js";
+import { type ToolSessionState } from "./tool-session-state.js";
 export type SourceTag = "live" | "offline" | "local";
 export interface RouteMeta {
     /**
@@ -45,6 +48,19 @@ export interface RouteMeta {
      */
     editorPid?: number;
 }
+/**
+ * Release lookups behind `unity_open_mcp_upgrade`. Injectable so unit tests
+ * never touch npm or GitHub; production uses the shared `release-lookup`
+ * module with the global fetch.
+ */
+export interface ReleaseLookup {
+    latest(): Promise<{
+        version: string;
+    }>;
+    confirmBridgeTag(version: string): Promise<BridgeTagConfirmation>;
+}
+/** Test seam for the upgrade route's network lookups. Returns a restore function. */
+export declare function setReleaseLookupForTest(lookup: ReleaseLookup | null): () => void;
 export declare class ToolRouter implements Router {
     private live;
     private batch;
@@ -54,6 +70,10 @@ export declare class ToolRouter implements Router {
     private onToolListChanged?;
     private hubBackend;
     private globalLogPathOverride?;
+    private jobManager?;
+    get jobs(): JobManager;
+    closeJobs(): void;
+    routeJobs(args: Record<string, unknown>, identity?: RequestIdentity): Promise<CallToolResult>;
     private readonly modelCache;
     /**
      * M28-refactoring Plan 3 (T3.2) — named-tool dispatch map. Replaces the
@@ -68,17 +88,41 @@ export declare class ToolRouter implements Router {
     private routeHandlers?;
     private getRouteHandlers;
     constructor(live: LiveClient, batch: BatchSpawn, projectPath: string, eventStream: BridgeEventStream, sessionState: ToolSessionState, onToolListChanged?: (() => void | Promise<void>) | undefined, hubBackend?: HubControlBackend, globalLogPathOverride?: string | undefined);
-    route(toolName: string, args: Record<string, unknown>): Promise<CallToolResult>;
+    route(toolName: string, args: Record<string, unknown>, identity?: RequestIdentity): Promise<CallToolResult>;
+    /**
+     * `capabilities` / `bridge_status` with an explicit project_path, from any
+     * entry point (direct, manage_tools invoke, port override). The probe router
+     * gets the arguments without project_path, so it dispatches normally. A
+     * per-request port override is refused rather than dropped or mixed in:
+     * project_path brings its own port/auth discovery, and pinging the override
+     * port would present another bridge's answer as the probed project's.
+     */
+    private routeProjectProbe;
+    /**
+     * Router for a read-only probe of another project: its own port/auth
+     * discovery and a throwaway copy of this session. Discovery still reconciles
+     * auto-activation against the probed project's inventory, so the probe
+     * reports that project's view, but only the copy changes — this session's
+     * active groups and tools/list stay put, and no list_changed is wired. The
+     * probe tools are local-only and never spawn Unity; the probe's own batch
+     * router only answers headless availability for that project's editor.
+     */
+    private projectProbeRouter;
+    private static readonly PROBE_BATCH_CACHE_SIZE;
+    private readonly probeBatchByProject;
+    private projectProbeBatch;
     /**
      * M23 Plan 3 — route with a per-call live-client override. Used when a
      * per-request `_meta.port` override targets a different bridge instance than
      * the default. The override client bypasses shared session state (it is a
      * fresh LiveClient aimed at the override port); all other routing logic is
-     * identical to {@link route}. When `overrideLive` is null the default client
-     * is used (identical to {@link route}).
+     * identical to {@link route}. `identity` carries the override port and the
+     * request's agent id.
      */
-    routeOverride(toolName: string, args: Record<string, unknown>, overrideLive: LiveClient): Promise<CallToolResult>;
+    routeOverride(toolName: string, args: Record<string, unknown>, overrideLive: LiveClient, identity: RequestIdentity): Promise<CallToolResult>;
     private routeCore;
+    private routeValidated;
+    private routeUnchecked;
     private batchPingResult;
     /**
      * feedback-fable-04-08 §7 — when a `live_unavailable` batch fallback lands
@@ -106,6 +150,17 @@ export declare class ToolRouter implements Router {
     private routeListRules;
     private routeGenerateSkill;
     private routeManageTools;
+    /**
+     * `unity_open_mcp_upgrade` is a live tool, but its network lookups run HERE
+     * rather than inside the bridge: the bridge tool executes on the Editor main
+     * thread, where a 10 s registry timeout would freeze the Editor and every
+     * queued bridge request. The bridge only ever receives a resolved
+     * `target_version`, and an apply that will re-pin through UPM is forwarded
+     * only after the `bridge-v<version>` release tag was confirmed to exist —
+     * the same preview → confirm → apply order the bridge window follows.
+     */
+    private routeUpgrade;
+    private routeProjectCommands;
     private manageToolsListGroups;
     private manageToolsSuggest;
     private manageToolsActivateFor;