unity-open-mcp 1.0.0 → 1.1.0

package/dist/tool-router.js

@@ -1,6 +1,8 @@
 import { AssetModelCache, isCompressible, routeCompressible } from "./compressible-router.js";
 import { listAssetsOffline, findReferencesOffline, dependenciesOffline } from "./offline.js";
-import { resolveEditorLogPath, readLogTail, DEFAULT_LOG_TAIL_BYTES, detectStaleLog, detectStaleAssembly, parseLogAuthorship, compareLogAuthorship } from "./unity-log.js";
+import { resolveEditorLogPath, readLogTail, DEFAULT_LOG_TAIL_BYTES, detectStaleLog, detectStaleAssembly, detectErrorsPredatingEdits, parseLogAuthorship, compareLogAuthorship } from "./unity-log.js";
+import { toolHintReference } from "./tool-hint.js";
+import { scanForFdExhaustion } from "./editor-wedge.js";
 import { summarizeProjectHealth, extractProjectHealthIssues } from "./project-health.js";
 import { countProjectAsmdefs, countAssembliesWithErrors } from "./asmdef-discovery.js";
 import { buildCapabilities } from "./capabilities/build-capabilities.js";
@@ -8,11 +10,12 @@ import { RULE_CATALOG, FIX_CATALOG } from "./capabilities/rule-catalog.js";
 import { GROUP_IDS, TOOL_GROUPS, AUTO_ACTIVATE_GROUPS, groupToTools, getGroup, } from "./capabilities/tool-groups.js";
 import { recommendGroups, } from "./capabilities/intent-groups.js";
 import { listRules } from "./capabilities/list-rules.js";
+import { viewCapabilities } from "./capabilities/capabilities-view.js";
 import { generateSkill } from "./skill/generate-skill.js";
 import { getKnownClientKeys } from "./skill/client-paths.js";
 import { ALL_TOOLS } from "./tools/index.js";
 import { lockPath, readInstanceLock, classifyInstance, isPidAlive } from "./instance-discovery.js";
-import { PORT_ENV_VAR, TYPED_EDITOR_ACTIVATE_INSTRUCTION } from "./constants.js";
+import { PORT_ENV_VAR, EXPECTED_BRIDGE_WIRE_CONTRACT } from "./constants.js";
 import { findUnityForProject, readProcessCommandLine } from "./running-unity.js";
 // M31-optimizations Plan 1 / L14 — opt-in route-logging gate. Resolved once at
 // module load into a boolean; the per-dispatch log sites read the boolean
@@ -51,7 +54,7 @@ const defaultHubBackend = {
     setInstallPath: (path) => setInstallPath(path),
 };
 import { BATCH_TOOL_NAMES, ALWAYS_BATCH_TOOLS } from "./batch-spawn.js";
-import { readProfileAndDetail, applyPaging, attachPagination, foldVerifyResult, parseResultBody, withResultBody, } from "./output-profile.js";
+import { readProfileAndDetail, applyPaging, attachPagination, foldVerifyResult, parseResultBody, withResultBody, isOutputProfile, } from "./output-profile.js";
 /**
  * Single source of truth for the `_source` tag. Every route-tagging site goes
  * through one of the two helpers below so live / offline / local stay
@@ -339,7 +342,25 @@ function groupLiveRefsByKind(paths) {
 }
 // Operator-facing "what to do next" hint for each coarse status. Kept short
 // and action-oriented so the Validation Suite can render it inline.
-function bridgeStatusNextStep(status) {
+function bridgeStatusNextStep(status, wedge) {
+    if (status === "wedged") {
+        return wedge?.reason === "main_thread_wedged"
+            ? "Unity's main thread is wedged — the HTTP listener still answers /ping, but the " +
+                "editor heartbeat has stopped, which is the signature of a MODAL DIALOG blocking " +
+                "the message pump (material/scene converters and several ExecuteMenuItem paths " +
+                "open one). This is NOT a compile failure and NOT a dead bridge assembly — a dead " +
+                "assembly has no listener at all. It cannot self-heal and no tool can dismiss the " +
+                "dialog: an operator must dismiss it in the Unity UI, after which queued calls " +
+                "resume. Prefer non-interactive APIs over unity_open_mcp_execute_menu for " +
+                "converter-style menus."
+            : "The Unity Editor hit the Bee build driver's file-descriptor exhaustion — the " +
+                "process is alive and the listener answers, but it can no longer BUILD: " +
+                "Library/ScriptAssemblies stops updating, so C# edits never take effect and " +
+                "unity_open_mcp_execute_csharp silently runs the previous assembly. Do not trust " +
+                "any result computed since. Call unity_open_mcp_read_compile_errors to confirm " +
+                "the editor_fd_exhaustion issue, save scene work, then restart the Editor " +
+                "(unity_open_mcp_restart_editor with confirm: true, or manually).";
+    }
     switch (status) {
         case "running":
             return "Bridge is ready. Proceed with live-only MCP tools.";
@@ -371,7 +392,66 @@ function bridgeStatusNextStep(status) {
                 "Bridge) and confirm it is started.";
     }
 }
-function bridgeStatusRecoveryHint(status) {
+/**
+ * specs/feedback.md 2026-08-24 — wire-contract staleness block.
+ *
+ * The field report: a blocker fixed and shipped on 2026-08-17 (registry tools
+ * rejecting the transport envelope keys, which made `editor_status` uncallable
+ * with default args) recurred against an installed bridge that still reported
+ * `bridgeVersion "1.0.0"` — the same string the FIXED source reports, because
+ * the package semver does not move for a wire-contract fix. "Your install is
+ * stale" and "this regressed" were therefore indistinguishable at the call
+ * site, and the agent had no way to pick between reinstalling and filing a bug.
+ *
+ * `BridgeSession.WireContract` is bumped for every observable change to the
+ * request/response contract, so comparing it against
+ * {@link EXPECTED_BRIDGE_WIRE_CONTRACT} answers that question directly. A
+ * bridge that predates the field reports no `wireContract` at all — `bridge`
+ * is then null and `stale` is true, which is the correct reading (it is older
+ * than revision 1 by definition).
+ *
+ * Returns null when /ping was unreachable: there is no bridge to compare, and a
+ * bogus "stale" on an offline bridge would be worse than silence.
+ */
+function wireContractBlock(reachable, reported) {
+    if (!reachable)
+        return null;
+    const bridge = typeof reported === "number" ? reported : null;
+    const stale = bridge === null || bridge < EXPECTED_BRIDGE_WIRE_CONTRACT;
+    return {
+        bridge,
+        expected: EXPECTED_BRIDGE_WIRE_CONTRACT,
+        stale,
+        note: stale
+            ? "The installed Unity bridge package is OLDER than this MCP server's wire " +
+                "contract" +
+                (bridge === null
+                    ? " (it does not report `wireContract` at all, so it predates revision 1)"
+                    : ` (revision ${bridge} vs ${EXPECTED_BRIDGE_WIRE_CONTRACT})`) +
+                ". A tool failing in a way the docs say is fixed is almost certainly " +
+                "this staleness, not a regression: reinstall/update the bridge package " +
+                "in Unity (Package Manager > the unity-open-mcp-bridge git URL) and " +
+                "retry before filing anything. bridgeVersion alone cannot tell you " +
+                "this — it does not move for a wire-contract fix."
+            : null,
+    };
+}
+function bridgeStatusRecoveryHint(status, wedge) {
+    if (status === "wedged") {
+        return wedge?.reason === "main_thread_wedged"
+            ? {
+                tool: "unity_open_mcp_editor_status",
+                reason: "Main thread wedged (likely a modal dialog): /ping answers but the " +
+                    "editor heartbeat stopped. No tool can dismiss a modal — an operator " +
+                    "must close it in the Unity UI, then editor_status confirms recovery.",
+            }
+            : {
+                tool: "unity_open_mcp_read_compile_errors",
+                reason: "editor_fd_exhaustion in the freshest Editor.log — the Editor answers " +
+                    "HTTP but can no longer build, so C# edits never take effect. Confirm " +
+                    "with read_compile_errors, then restart the Editor.",
+            };
+    }
     if (status === "dead_bridge") {
         return {
             tool: "unity_open_mcp_read_compile_errors",
@@ -490,10 +570,21 @@ export class ToolRouter {
         }
         // Compact drill-down reads: offline-first for text-serialized assets, fall
         // back to live bridge for binary formats. The compressible-router handles
-        // the source selection internally.
+        // the source selection internally and tags the payload `_source`
+        // ("offline" when it was served from the disk parser without touching the
+        // bridge; error results tag their origin too — "local" for caller-side
+        // validation, "offline" for a failed offline-first attempt with the
+        // bridge down). Derive `_route` from that tag: stamping route:"live"
+        // unconditionally mislabeled offline-served reads as bridge responses —
+        // contradictory metadata that pointed an agent's diagnostics at the
+        // bridge for data it never produced.
         if (isCompressible(toolName)) {
             const result = await routeCompressible(toolName, args, live, this.modelCache, this.projectPath);
-            return injectRouteMeta(result, { route: "live" });
+            const source = parseResultBody(result)?._source;
+            const meta = source === "offline" || source === "local"
+                ? { route: source }
+                : { route: "live" };
+            return injectRouteMeta(result, meta);
         }
         const canBatch = this.batch.isBatchTool(toolName);
         const isPing = toolName === "unity_open_mcp_ping";
@@ -561,6 +652,11 @@ export class ToolRouter {
                         mode: "batch",
                         compiling: false,
                         isPlaying: false,
+                        // feedback 2026-08-17 — provenance marker distinguishing this
+                        // synthesized fallback (no probe was possible; the live route was
+                        // unavailable) from the live route's verified probe answer
+                        // (source:"probe" + asOf).
+                        source: "unprobed",
                         _route: {
                             route: "batch",
                             fallbackReason: "live_unavailable",
@@ -700,6 +796,16 @@ export class ToolRouter {
         // newest Library/ScriptAssemblies/*.dll mtime against Assets/**/*.cs source
         // mtimes and surface staleAssembly when any source is newer than the DLL.
         const staleAsm = detectStaleAssembly(this.projectPath);
+        // specs/feedback.md 2026-08-14 — "these errors may predate your edits".
+        // Three consecutive reads returned the same error block for code that had
+        // already been fixed, with no staleness signal: Editor.log's FILE mtime
+        // was fresh (asset imports keep appending) while the error BLOCK inside it
+        // was old, so the staleLog heuristic could not fire. The built-assembly
+        // mtime is the anchor that works — a cited source newer than the newest
+        // built DLL proves no compile has COMPLETED since the edit.
+        const errorsPredateEdits = errors.length > 0
+            ? detectErrorsPredatingEdits(errors.map((e) => e.file), this.projectPath, staleAsm.dllMtimeMs)
+            : null;
         // feedback-04-08-opus §2 — log-authorship cross-check. A batch run of a
         // NEWER Unity writes a log whose errors (e.g. an API deprecation that is
         // only an error on that version) CANNOT occur in the live editor. Parse the
@@ -729,7 +835,17 @@ export class ToolRouter {
             : "no_errors_found";
         const errorsMayNotApply = health.unhealthy &&
             (!!staleLog || authorshipCheck.versionMismatch);
-        const status = errorsMayNotApply ? "stale_log" : logVerdict;
+        // feedback 2026-08-17 — a clean bill of health read from the ROTATED log
+        // is not a clean bill of health. When logSource is a prev_log_* value the
+        // resolver fell back to Editor-prev.log while a live Editor writes a
+        // different file; an agent reading only `status` got a false green. A
+        // no-errors read from a rotated log is explicitly `indeterminate`.
+        const prevLogRead = resolvedLog.reason.startsWith("prev_log_");
+        const status = errorsMayNotApply
+            ? "stale_log"
+            : logVerdict === "no_errors_found" && prevLogRead
+                ? "indeterminate"
+                : logVerdict;
         // specs/feedback.md 2026-08-12 — partial-compile signal. Unity compiles
         // assemblies in dependency order; when an early assembly fails the pipeline
         // may not reach dependent ones, so the reported errors can be a SUBSET of
@@ -749,6 +865,54 @@ export class ToolRouter {
         const assembliesWithErrors = partialCompileLikely
             ? countAssembliesWithErrors(errors.map((e) => e.file), this.projectPath)
             : 0;
+        // Headline assembly. Precedence (most severe first):
+        //   1. errorsMayNotApply — stale log / version mismatch: the errors may
+        //      not apply at all (feedback-fable-04-08 §4).
+        //   2. errorsPredateEdits — errors + a stale assembly: the error block
+        //      was written by a compile that predates the on-disk edits (no
+        //      compile has COMPLETED since: every built DLL is older than a cited
+        //      source). The log-mtime staleness heuristic cannot see this — asset
+        //      imports keep appending to Editor.log, so the FILE is fresh while
+        //      the error BLOCK inside it is old. Say so in the headline rather
+        //      than letting the agent re-read code it has already fixed
+        //      (specs/feedback.md 2026-08-14).
+        //   3. feedback 2026-08-17 — errors + staleAssembly WITHOUT the
+        //      cited-files proof: the whole-Assets scan still shows a source
+        //      newer than the newest built DLL, so the error block may come from
+        //      an earlier compile. The 2026-08-14 fix covered only the
+        //      errorsPredateEdits shape; this extends the headline caveat to the
+        //      staleAssembly shape (the field report's 12 stale CS errors had
+        //      staleAssembly:true but the headline stated them as fact).
+        //   4. indeterminate (feedback 2026-08-17) — no errors, but read from the
+        //      ROTATED log: not a verified clean bill of health.
+        //   5. the plain health headline.
+        const headline = errorsMayNotApply
+            ? `${errors.length} error(s) in Editor.log, but the log appears ` +
+                "STALE or authored by a different Unity — these errors may NOT " +
+                "apply to the running editor. Do NOT act on them until a genuine " +
+                `recompile (${toolHintReference("unity_open_mcp_recompile_scripts")}) ` +
+                "confirms them."
+            : errorsPredateEdits
+                ? `${health.headline} NOTE: these errors may PREDATE your edits — ` +
+                    `${errorsPredateEdits.files.length} cited source file(s) are newer ` +
+                    "than the newest built assembly, so no compile has completed since " +
+                    "you changed them. Force a recompile " +
+                    `(${toolHintReference("unity_open_mcp_recompile_scripts")}) and ` +
+                    "re-read before acting on them."
+                : hasErrors && staleAsm.staleAssembly
+                    ? `${health.headline} NOTE: the error block may PREDATE the current ` +
+                        `sources — ${staleAsm.newerSources.length} Assets/**/*.cs source(s) ` +
+                        "are newer than the newest built assembly, so these errors may come " +
+                        "from an earlier compile. Force a recompile " +
+                        `(${toolHintReference("unity_open_mcp_recompile_scripts")}) and ` +
+                        "re-read before acting on them."
+                    : status === "indeterminate"
+                        ? "No errors found, but this is NOT a verified clean bill of " +
+                            `health: the read came from the ROTATED log (${resolvedLog.reason === "prev_log_live_editor" ? "Editor-prev.log chosen because a live editor holds the project" : "Editor-prev.log fallback"}) ` +
+                            "while a live Editor may be writing a different log. Confirm via " +
+                            "the live bridge (unity_open_mcp_editor_status / a live tool " +
+                            "probe) or re-read after the Editor settles."
+                        : health.headline;
         return sourceResult({
             status,
             // When the errors may not apply (stale log / version mismatch), the
@@ -758,14 +922,11 @@ export class ToolRouter {
             // log verdict is preserved in `logVerdict` for callers that want the
             // literal signal regardless of freshness.
             unhealthy: errorsMayNotApply ? false : health.unhealthy,
-            headline: errorsMayNotApply
-                ? `${errors.length} error(s) in Editor.log, but the log appears ` +
-                    "STALE or authored by a different Unity — these errors may NOT " +
-                    "apply to the running editor. Do NOT act on them until a genuine " +
-                    "recompile (unity_open_mcp_recompile_scripts, in the typed-editor " +
-                    `group — ${TYPED_EDITOR_ACTIVATE_INSTRUCTION} first) confirms them.`
-                : health.headline,
-            ...(errorsMayNotApply ? { logVerdict } : {}),
+            headline,
+            // Raw verdict preserved whenever the top-level status was rewritten
+            // (stale_log downgrade OR the indeterminate prev-log case), so callers
+            // can still read what the log literally said.
+            ...(errorsMayNotApply || status === "indeterminate" ? { logVerdict } : {}),
             errorCount: errors.length,
             errors,
             // specs/feedback.md 2026-08-12 — present only when there are errors AND
@@ -816,6 +977,26 @@ export class ToolRouter {
                     staleAssemblyNewerSources: staleAsm.newerSources,
                 }
                 : {}),
+            // specs/feedback.md 2026-08-14 — machine-readable sibling of the
+            // headline caveat above. Present ONLY when errors were returned AND at
+            // least one file they cite is newer than the newest built assembly, so
+            // the error block cannot reflect the current source. Distinct from
+            // `staleLogSuspected` (log-file mtime) and `staleAssembly` (whole
+            // Assets/ scan): this names the cited files the agent is about to
+            // re-read.
+            ...(errorsPredateEdits
+                ? {
+                    errorsMayPredateEdits: true,
+                    errorsMayPredateEditsFiles: errorsPredateEdits.files,
+                    errorsMayPredateEditsHint: "These errors were parsed from a compile that ran BEFORE the " +
+                        "listed files were last edited (each is newer than the newest " +
+                        "Library/ScriptAssemblies/*.dll, so no compile has completed " +
+                        "since). Do not re-read or re-fix that code on the strength of " +
+                        "this block — force a recompile " +
+                        `(${toolHintReference("unity_open_mcp_recompile_scripts")}) ` +
+                        "and read again.",
+                }
+                : {}),
             // feedback-04-08-opus §2 — log authorship. Emitted whenever the header
             // was parseable (the live editor's long tail usually has no header, so
             // these stay absent in the common case). On a version mismatch the hint
@@ -945,6 +1126,12 @@ export class ToolRouter {
             ? args.kind
             : undefined;
         const includePlanned = args.include_planned !== false;
+        // specs/feedback.md 2026-08-24 — the tool surface defaults to `compact`
+        // (the unfolded catalog is ~513 KB, which overflows a typical harness
+        // per-result ceiling). `buildCapabilities` itself keeps returning the full
+        // shape so its other caller (generate_skill) is unaffected; the fold is a
+        // view applied here.
+        const profile = isOutputProfile(args.profile) ? args.profile : "compact";
         // M18 Plan 2 / T18.2.3 — when the bridge is live, probe its compiled-
         // state tool inventory so per-group `available` reflects whether each
         // domain dependency compiled in (e.g. UNITY_OPEN_MCP_EXT_NAVIGATION).
@@ -970,7 +1157,11 @@ export class ToolRouter {
             fixes: FIX_CATALOG,
             availableBridgeTools,
         }, { kind, includePlanned });
-        return sourceResult(result, "local");
+        return sourceResult(viewCapabilities(result, {
+            profile,
+            page_size: typeof args.page_size === "number" ? args.page_size : undefined,
+            cursor: typeof args.cursor === "string" ? args.cursor : undefined,
+        }), "local");
     }
     async routeListRules(args) {
         const assetKind = typeof args.asset_kind === "string" ? args.asset_kind : undefined;
@@ -1474,8 +1665,52 @@ export class ToolRouter {
             if (proc)
                 unityProcessPid = proc.pid;
         }
+        // specs/feedback.md 2026-08-14 — wedge detection, evaluated BEFORE the
+        // existing token ladder because both wedges masquerade as one of its
+        // healthy-looking outcomes.
+        //
+        // (a) main_thread_wedged. `dead_bridge` means "live PID + stale
+        //     heartbeat". A modal dialog produces exactly that (the heartbeat is
+        //     written from EditorApplication.update, which a blocked pump stops
+        //     running) — but a dead bridge ASSEMBLY cannot answer /ping at all,
+        //     because the listener lives in the assembly that failed to compile.
+        //     So a reachable /ping alongside a stale heartbeat rules out the
+        //     safe-mode diagnosis and identifies a stalled main thread instead.
+        // (b) editor_fd_exhaustion. Process, heartbeat and /ping all survive a
+        //     dead build driver, so nothing in the existing ladder can see it.
+        //     One regex over the freshest log tail can (the same scan
+        //     read_compile_errors runs), and it only runs when the ladder would
+        //     otherwise report a healthy editor — the offline/stopped paths have
+        //     no editor to be wedged.
+        let wedge = null;
+        if (classification === "dead_bridge" && pingReachable) {
+            wedge = {
+                reason: "main_thread_wedged",
+                detail: "The instance lock's heartbeat is stale (the editor main thread stopped " +
+                    "ticking) but the bridge listener still answers /ping. A failed bridge " +
+                    "assembly would take the listener down with it, so this is a blocked main " +
+                    "thread — almost always a modal dialog — not Safe Mode.",
+            };
+        }
+        else if (pingReachable && connected) {
+            const fd = scanForFdExhaustion(this.projectPath, this.resolveLiveEditorPid(), this.globalLogPathOverride);
+            if (fd.present) {
+                wedge = {
+                    reason: "editor_fd_exhaustion",
+                    detail: "The freshest Editor.log carries the Bee build-driver file-descriptor " +
+                        "exhaustion signature. The Editor answers HTTP but cannot build: " +
+                        "Library/ScriptAssemblies stops updating, so C# edits never take effect " +
+                        "and execute_csharp keeps running the previous assembly.",
+                    ...(fd.logPath ? { logPath: fd.logPath } : {}),
+                    ...(fd.raw ? { raw: fd.raw } : {}),
+                };
+            }
+        }
         let status;
-        if (classification === "dead_bridge") {
+        if (wedge !== null) {
+            status = "wedged";
+        }
+        else if (classification === "dead_bridge") {
             status = "dead_bridge";
         }
         else if (compiling) {
@@ -1517,7 +1752,13 @@ export class ToolRouter {
             // Safe Mode / compile failure", not the generic "stopped" the bare
             // status used to suggest.
             classification,
-            recoveryHint: bridgeStatusRecoveryHint(status),
+            recoveryHint: bridgeStatusRecoveryHint(status, wedge),
+            // specs/feedback.md 2026-08-14 — present ONLY when the editor is wedged.
+            // `classification` keeps mirroring the instance lock verbatim (healthy |
+            // reloading | dead_bridge | gone) so that contract is unchanged; the
+            // wedge is carried by the tool's own `status` token plus this block, and
+            // `ready` is false either way.
+            ...(wedge !== null ? { wedged: wedge } : {}),
             instance: {
                 lockPath: lockOnDisk,
                 classification,
@@ -1535,10 +1776,15 @@ export class ToolRouter {
                     isPlaying: pingBody?.isPlaying ?? null,
                     unityVersion: pingBody?.unityVersion ?? null,
                     bridgeVersion: pingBody?.bridgeVersion ?? null,
+                    wireContract: pingBody?.wireContract ?? null,
                     mode: pingBody?.mode ?? null,
                 }
                 : { reachable: false },
-            nextStep: bridgeStatusNextStep(status),
+            // specs/feedback.md 2026-08-24 — null when /ping was unreachable; a
+            // `stale: true` block is the signal to reinstall the Unity package
+            // rather than file a regression.
+            wireContract: wireContractBlock(pingReachable, pingBody?.wireContract),
+            nextStep: bridgeStatusNextStep(status, wedge),
         };
         // bridge_status never reports an error — even a stopped bridge is a
         // successful status read. _source=local because the synthesis happens in