unity-open-mcp 1.1.0 → 1.3.0

package/dist/live-client.js

@@ -1,13 +1,15 @@
+import { randomUUID } from "node:crypto";
+import { PingCache } from "./ping-cache.js";
 import { BridgeToolsCache } from "./bridge-tools-cache.js";
 import { StaleAssemblyCache } from "./stale-assembly-cache.js";
 import { EditorWedgeCache, scanForFdExhaustion } from "./editor-wedge.js";
 import { detectStaleAssembly } from "./unity-log.js";
 import { deriveIsError } from "./gate-error.js";
-import { readFileSync, readdirSync, statSync, unlinkSync } from "node:fs";
+import { readFileSync, readdirSync, realpathSync, statSync, unlinkSync } from "node:fs";
 import { join } from "node:path";
 import { pollAndDismissDialogs, readDismissConfig, } from "./dialog-dismiss.js";
-import { readInstanceLock, classifyInstance, lockPath, isPidAlive, statusDir, hasRecentPendingTestRun, resolveRefreshedEndpoint } from "./instance-discovery.js";
-import { bridgeBaseUrl, BRIDGE_DEFAULT_TIMEOUT_MS, BRIDGE_HOST_SAFE_TIMEOUT_CAP_MS, BRIDGE_MIN_TIMEOUT_MS, PORT_ENV_VAR, PROJECT_PATH_ENV_VAR, } from "./constants.js";
+import { readInstanceLock, classifyInstance, lockPath, isPidAlive, statusDir, hasRecentPendingTestRun, resolveRefreshedEndpoint, normalizePath, findInstanceLockByPort, computePort } from "./instance-discovery.js";
+import { bridgeBaseUrl, BRIDGE_DEFAULT_TIMEOUT_MS, BRIDGE_HOST_SAFE_TIMEOUT_CAP_MS, BRIDGE_MIN_TIMEOUT_MS, COMPILE_STATE_HEADER, PORT_ENV_VAR, PROJECT_PATH_ENV_VAR, } from "./constants.js";
 import { findUnityForProject } from "./running-unity.js";
 import { makeErrorResult } from "./results.js";
 import { checkBridgeCompat, isVersionCheckSuppressed, } from "./compat.js";
@@ -21,10 +23,19 @@ import { readRetryTunables, } from "./retry-policy.js";
 // an agent can branch when a recompile reported success but the compiled state
 // did not advance.
 import { detectCompileVerify, buildCompileVerifyAnnotation, } from "./compile-verify.js";
-import { lifecycleFor } from "./capabilities/lifecycle.js";
+import { lifecycleForCall } from "./capabilities/lifecycle.js";
 // M23 Plan 3 — per-process agent identity (sent as X-Agent-Id so the bridge's
 // fair round-robin queue can schedule across agents).
 import { PROCESS_AGENT_ID } from "./agent-identity.js";
+function canonicalProjectPath(p) {
+    let real = p;
+    try {
+        real = realpathSync.native(p);
+    }
+    catch { /* unresolvable here: compare as spelled */ }
+    const norm = normalizePath(real);
+    return process.platform === "win32" ? norm.toLowerCase() : norm;
+}
 const PING_TIMEOUT_MS = 5_000;
 // BRIDGE_DEFAULT_TIMEOUT_MS now lives in constants.ts (single source shared
 // with the bridge C# parity test). The client fetch timeout must never
@@ -85,6 +96,7 @@ const COMPILE_RELOAD_ANNOTATION_TOOLS = new Set([
     "unity_open_mcp_package_remove",
     "unity_open_mcp_reimport_package",
     "unity_open_mcp_compile_check",
+    "unity_open_mcp_recompile_scripts",
 ]);
 /**
  * M4 — should the compile-verify annotation run for this tool? Returns true
@@ -182,6 +194,11 @@ function buildOfflineHint(projectPath) {
     }
     return `${base} (lock not readable — Unity may not be running).`;
 }
+/** `/project-command-jobs` answered without a job snapshot; `status` is its non-OK HTTP status. */
+export class ProjectJobHttpError extends Error {
+    status;
+    constructor(status) { super(`Project job transport HTTP ${status}`); this.status = status; }
+}
 export class LiveClient {
     baseUrl;
     pingCache;
@@ -216,6 +233,8 @@ export class LiveClient {
     /** specs/feedback.md 2026-07-03 — opt-in for the "Unsaved changes to scene"
      *  modal (destructive under every policy, off by default). */
     allowUnsavedSceneDismiss;
+    /** Explicit opt-in for continuing through a non-matching Editor warning. */
+    allowVersionMismatch;
     /** M14 — per-session bearer token auto-discovered from the instance lock.
      *  Undefined when no live lock was found (older bridge / env port override);
      *  in that case no Authorization header is sent and the bridge must be in
@@ -246,6 +265,8 @@ export class LiveClient {
      *  the constructor used; without it a refresh would silently switch from an
      *  env-pinned port to the lock port. */
     envPort;
+    /** Memoized outcome of the bridge-vs-server project-path comparison. */
+    projectMatch = null;
     constructor(port, pingCache, authToken, projectPath, agentId = PROCESS_AGENT_ID, envPort) {
         this.baseUrl = bridgeBaseUrl(port);
         this.pingCache = pingCache;
@@ -281,6 +302,7 @@ export class LiveClient {
         this.dialogPolicy = dismissCfg.policy;
         this.allowProjectUpgrade = dismissCfg.allowProjectUpgrade;
         this.allowUnsavedSceneDismiss = dismissCfg.allowUnsavedSceneDismiss;
+        this.allowVersionMismatch = dismissCfg.allowVersionMismatch;
         this.compatWarned = false;
     }
     /**
@@ -303,6 +325,57 @@ export class LiveClient {
             console.warn(result.message);
         }
     }
+    /** Bounded read-only main-thread snapshot; unavailable bridges fail open to logs. */
+    async readCompileState() {
+        try {
+            this.refreshEndpointFromLock();
+            const res = await this.fetchWithTimeout("/compile-state", { method: "GET" }, 2000);
+            const body = await res.json();
+            return res.ok ? this.acceptCompileState(body) : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    /** The compile state that qualifies a tool result: the snapshot the bridge
+     *  took inside the call's own dispatch when the call asked for it
+     *  (COMPILE_STATE_HEADER), else a fresh read. An older bridge never attaches
+     *  one, and the bridge leaves it off once a compile ran during the call's
+     *  settle wait, so neither path can qualify a result with a state older
+     *  than the call. */
+    async compileStateFor(res) {
+        const header = res.headers.get(COMPILE_STATE_HEADER);
+        if (header !== null) {
+            try {
+                return this.acceptCompileState(JSON.parse(Buffer.from(header, "base64").toString("utf8")));
+            }
+            catch { /* malformed: read it instead */ }
+        }
+        return this.readCompileState();
+    }
+    /** A well-formed compile state reported for this client's project, else null. */
+    acceptCompileState(body) {
+        if (body === null || typeof body !== "object")
+            return null;
+        if (typeof body.generation !== "number" || typeof body.status !== "string")
+            return null;
+        if (this.projectPath && !this.sameProject(body.projectPath))
+            return null;
+        return body;
+    }
+    /** The bridge reports DirectoryInfo.FullName while the server holds a
+     *  path.resolve'd string; separators, drive-letter case and /private-style
+     *  symlinks can differ for the same project, and a strict compare would
+     *  silently disable live compile state. Compare canonical forms instead. */
+    sameProject(reported) {
+        if (typeof reported !== "string" || !this.projectPath)
+            return false;
+        if (this.projectMatch?.reported === reported)
+            return this.projectMatch.same;
+        const same = canonicalProjectPath(reported) === canonicalProjectPath(this.projectPath);
+        this.projectMatch = { reported, same };
+        return same;
+    }
     async isLiveAvailable(fetchTimeoutMs) {
         try {
             const res = await this.fetchWithTimeout("/ping", { method: "GET" }, fetchTimeoutMs);
@@ -328,14 +401,14 @@ export class LiveClient {
     getCachedPing() {
         return this.pingCache.get();
     }
-    async route(toolName, args) {
+    async route(toolName, args, commandLifecycle) {
         if (toolName === "unity_open_mcp_ping") {
             return this.handlePing();
         }
         if (toolName === "unity_senses_run_tests") {
             return this.handleRunTests(args);
         }
-        return this.handleToolCall(toolName, args);
+        return this.handleToolCall(toolName, args, commandLifecycle);
     }
     async handlePing() {
         try {
@@ -441,7 +514,7 @@ export class LiveClient {
             });
         }
     }
-    async handleToolCall(toolName, args) {
+    async handleToolCall(toolName, args, commandLifecycle) {
         const readyError = await this.ensureReady();
         if (readyError)
             return readyError;
@@ -460,15 +533,64 @@ export class LiveClient {
         // warning that told the agent to "force a rebuild" after `return 42;`.
         // The set below is the subset of compile-reload tools whose PURPOSE is to
         // trigger or observe a recompile; see `shouldAnnotateCompileVerify`.
-        const isCompileReload = lifecycleFor(toolName).class === "compile-reload";
+        const isCompileReload = lifecycleForCall(toolName, args).class === "compile-reload";
         const annotate = isCompileReload && shouldAnnotateCompileVerify(toolName);
         const before = annotate ? await this.captureCompileSnapshot() : null;
-        const result = await this.postTool(toolName, args, true);
+        const result = await this.postTool(toolName, args, true, 1, commandLifecycle);
         if (annotate && !result.isError && before !== null) {
             return this.annotateCompileVerify(toolName, result, before, args);
         }
         return result;
     }
+    /**
+     * Transient client for a per-request `_meta.port` override. The override
+     * names a bridge, not a project, so the client binds to the project whose
+     * instance lock claims that port: its lock-derived diagnostics
+     * (bridge_compile_failed, cold Safe Mode, the ping lockCheck, the offline
+     * hint) and its bearer token then describe the Editor actually called, not
+     * the configured project. With no claiming lock it binds to the configured
+     * project only when that project has no lock and the port is its
+     * deterministic one; otherwise it runs without a project, so a failure
+     * reports plain bridge_offline instead of another Editor's state. The port
+     * is passed as envPort: an explicit override never re-resolves from a lock.
+     * A private PingCache keeps the default bridge's readiness snapshot from
+     * short-circuiting this bridge's own /ping.
+     */
+    static forPortOverride(port, defaultProjectPath, agentId) {
+        const lock = findInstanceLockByPort(port);
+        const projectPath = lock
+            ? lock.projectPath
+            : defaultProjectPath && !readInstanceLock(defaultProjectPath) && computePort(defaultProjectPath) === port
+                ? defaultProjectPath
+                : undefined;
+        const token = lock && isPidAlive(lock.pid) ? lock.authToken : undefined;
+        const authToken = typeof token === "string" && token.length > 0 ? token : undefined;
+        return new LiveClient(port, new PingCache(), authToken, projectPath, agentId, port);
+    }
+    /** Preserve configured endpoint/auth when attaching an independent job owner. */
+    forAgent(agent) {
+        return new LiveClient(Number(new URL(this.baseUrl).port), new PingCache(), this.authToken, this.projectPath, agent, this.envPort);
+    }
+    /** Job-owned test start has no transport replay; poll the existing file handoff. */
+    async runTestsJob(args, onStarted) {
+        const readyError = await this.ensureReady();
+        if (readyError)
+            return readyError;
+        const { timeout_ms: _budget, ...startArgs } = args;
+        const response = await this.fetchWithTimeout("/tools/unity_senses_run_tests", {
+            method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify(startArgs),
+        }, 10_000);
+        if (!response.ok)
+            throw new Error(`Test start HTTP ${response.status}; execution outcome unknown.`);
+        const body = await response.json();
+        if (body.status !== "started" || body.runId !== args.run_id) {
+            if (body.error || body.mutation)
+                return { content: [{ type: "text", text: JSON.stringify(body) }], isError: true };
+            throw new Error("Test start did not confirm the owned run id.");
+        }
+        onStarted();
+        return this.pollTestResults(String(args.run_id), args);
+    }
     async handleRunTests(args) {
         const readyError = await this.ensureReady();
         if (readyError)
@@ -669,20 +791,22 @@ export class LiveClient {
      * (1 initial attempt + N retries), matching the documented RETRY_CONFIG
      * semantics; once exhausted the offline error is surfaced instead of recursing.
      */
-    async postTool(toolName, args, retryOn503, attempt = 1) {
+    async postTool(toolName, args, retryOn503, attempt = 1, commandLifecycle) {
         try {
-            const res = await this.postToolFetch(toolName, args, retryOn503);
+            const res = await this.postToolFetch(toolName, args, retryOn503, commandLifecycle);
             // 503 + compile settled cleanly → re-POST once without 503 retry. This is
             // a deliberate single re-dispatch (retryOn503 flips to false, so a second
             // 503 surfaces the error), but it still counts as a POST attempt for the
             // recursion bound.
             if (isCompileRepostSentinel(res)) {
-                return this.postTool(toolName, args, false, attempt + 1);
+                return this.postTool(toolName, args, false, attempt + 1, commandLifecycle);
             }
             return res;
         }
         catch (err) {
-            return this.handlePostFailure(toolName, args, err, retryOn503, attempt);
+            if (err instanceof Error && err.message.startsWith("bridge_response_request_mismatch"))
+                return makeErrorResult({ code: "bridge_response_request_mismatch", message: err.message });
+            return this.handlePostFailure(toolName, args, err, retryOn503, attempt, commandLifecycle);
         }
     }
     /**
@@ -693,7 +817,7 @@ export class LiveClient {
      * should re-POST without 503 retry. Throws on transient fetch failure so the
      * caller's catch runs {@link handlePostFailure}.
      */
-    async postToolFetch(toolName, args, retryOn503) {
+    async postToolFetch(toolName, args, retryOn503, commandLifecycle) {
         const rawTimeout = args.timeout_ms;
         const explicitTimeout = typeof rawTimeout === "number";
         const requestedTimeoutMs = explicitTimeout ? rawTimeout : 60_000;
@@ -719,7 +843,12 @@ export class LiveClient {
         const fetchTimeout = Math.max(timeoutMs + 10_000, BRIDGE_DEFAULT_TIMEOUT_MS + 10_000);
         const res = await this.fetchWithTimeout(`/tools/${toolName}`, {
             method: "POST",
-            headers: { "Content-Type": "application/json; charset=utf-8" },
+            headers: {
+                "Content-Type": "application/json; charset=utf-8",
+                // shapeToolResult qualifies these results with the compile state;
+                // the bridge snapshots it inside this call's dispatch on request.
+                ...(STALE_DOMAIN_ANNOTATION_TOOLS.has(toolName) ? { [COMPILE_STATE_HEADER]: "1" } : {}),
+            },
             body: JSON.stringify(forwardedArgs),
         }, fetchTimeout);
         if (res.status === 503 && retryOn503) {
@@ -743,7 +872,7 @@ export class LiveClient {
                 },
             });
         }
-        const result = await this.shapeToolResult(toolName, res);
+        const result = await this.shapeToolResult(toolName, res, commandLifecycle, args);
         // Surface the clamp ONLY when the caller explicitly requested a timeout
         // above the cap (feedback N1). When timeout_ms is absent the server default
         // (60s) is silently clamped to the cap — there is no caller expectation to
@@ -776,7 +905,7 @@ export class LiveClient {
      *   - direct body (verbatim, isError when a top-level error field is present),
      *   - unparsable body (bridge_response_unparsable corruption error).
      */
-    async shapeToolResult(toolName, res) {
+    async shapeToolResult(toolName, res, commandLifecycle, args = {}) {
         // The bridge returns TWO response shapes from /tools/*:
         //   1. A MUTATION envelope: { mutation: { success, ... }, gate: {...} }
         //      for gate-tracked mutating tools (gameobject_*, assets_*, etc.).
@@ -830,7 +959,27 @@ export class LiveClient {
             STALE_DOMAIN_ANNOTATION_TOOLS.has(toolName) &&
             parsed.error == null &&
             parsed._staleDomain === undefined) {
-            const staleAsm = this.resolveStaleAssembly();
+            const liveCompile = await this.compileStateFor(res);
+            const staleAsm = liveCompile?.status === "no_errors_found" && liveCompile.sourceMatches === true
+                ? null : liveCompile?.status === "assembly_stale"
+                ? { staleAssembly: true, newerSources: [], hint: "Source content changed after the completed compile generation. Recompile before trusting this result." }
+                : this.resolveStaleAssembly();
+            if (liveCompile) {
+                // Compact projection only. The full body carries `errors[]` — every
+                // CS diagnostic of a failed compile — and would repeat it on every
+                // read result for the rest of the session; read_compile_errors owns
+                // the list. Keep just the fields that qualify THIS result.
+                parsed._compileState = {
+                    status: liveCompile.status,
+                    generation: liveCompile.generation,
+                    sourceMatches: liveCompile.sourceMatches,
+                    beforeAssemblyMtimeMs: liveCompile.beforeAssemblyMtimeMs,
+                    afterAssemblyMtimeMs: liveCompile.afterAssemblyMtimeMs,
+                    // The header snapshot carries the count; a /compile-state read, the list.
+                    errorCount: Array.isArray(liveCompile.errors) ? liveCompile.errors.length
+                        : typeof liveCompile.errorCount === "number" ? liveCompile.errorCount : 0,
+                };
+            }
             if (staleAsm != null && staleAsm.staleAssembly) {
                 // specs/feedback.md 2026-08-14 — a stale assembly plus a wedged build
                 // driver is not a footnote, it is an execution-integrity failure. In
@@ -950,7 +1099,7 @@ export class LiveClient {
         // 2026-07-03-c contract) — that path keeps bridge_response_unparsable.
         if (parsed == null) {
             const isEmptyLikeReload = rawText.trim().length === 0;
-            if (isEmptyLikeReload && lifecycleFor(toolName).class === "compile-reload") {
+            if (isEmptyLikeReload && (commandLifecycle === "restart_then_settle" || lifecycleForCall(toolName, args).class === "compile-reload")) {
                 return {
                     content: [
                         {
@@ -1036,7 +1185,7 @@ export class LiveClient {
      * itself bounded (`transientRetryAttempts` iterations of `/ping`); this outer
      * bound caps how many times we re-enter that recovery + re-POST cycle.
      */
-    async handlePostFailure(toolName, args, err, retryOn503, attempt) {
+    async handlePostFailure(toolName, args, err, retryOn503, attempt, commandLifecycle) {
         const endpointBefore = this.baseUrl;
         const recovered = await this.handleTransientOffline("post");
         if (recovered !== null)
@@ -1046,9 +1195,10 @@ export class LiveClient {
         // budget is the initial attempt plus the configured transient retry count.
         const maxAttempts = 1 + this.retry.transientRetryAttempts;
         const attemptsExhausted = attempt >= maxAttempts;
-        if (!attemptsExhausted &&
+        if (toolName !== "unity_open_mcp_project_commands" &&
+            !attemptsExhausted &&
             shouldRetryPostAfterFailure(err, endpointChanged)) {
-            return this.postTool(toolName, args, retryOn503, attempt + 1);
+            return this.postTool(toolName, args, retryOn503, attempt + 1, commandLifecycle);
         }
         const exhaustedNote = attemptsExhausted
             ? ` The POST retry budget (${maxAttempts} attempt${maxAttempts === 1 ? "" : "s"}) was exhausted after ${attempt} attempt${attempt === 1 ? "" : "s"}; the bridge is reachable by /ping but POSTs keep failing.`
@@ -1461,6 +1611,7 @@ export class LiveClient {
                 policy: this.dialogPolicy,
                 allowProjectUpgrade: this.allowProjectUpgrade,
                 allowUnsavedSceneDismiss: this.allowUnsavedSceneDismiss,
+                allowVersionMismatch: this.allowVersionMismatch,
                 abortSignal: dismissAbort.signal,
             };
             dismissDone = this.runDismissLoop(dismissOpts);
@@ -1558,6 +1709,36 @@ export class LiveClient {
             };
         }
     }
+    /** Private job transport: one bounded request, never an automatic mutation retry. */
+    async projectCommandJob(args) {
+        const response = await this.fetchWithTimeout("/project-command-jobs", {
+            method: "POST", body: JSON.stringify(args), headers: { "Content-Type": "application/json" },
+        }, 10_000);
+        if (!response.ok)
+            throw new ProjectJobHttpError(response.status);
+        return await response.json();
+    }
+    /** Fresh authenticated bounded catalog read; no disk/session cache can hide a reload. */
+    async projectCommands(args) {
+        const query = new URLSearchParams({ catalog: "project_commands" });
+        for (const key of ["action", "id", "query", "group", "package", "offset", "limit"])
+            if (args[key] !== undefined)
+                query.set(key, String(args[key]));
+        for (const tag of args.tags ?? [])
+            query.append("tag", tag);
+        try {
+            const response = await this.fetchWithTimeout(`/tools?${query}`, { method: "GET" }, 5_000);
+            if (!response.ok)
+                return { error: { code: "catalog_unavailable", message: `Bridge catalog HTTP ${response.status}.` } };
+            const body = await response.json();
+            if (body.catalogVersion !== 1 || (!body.error && (args.action === "describe" ? !body.command : !Array.isArray(body.commands))))
+                return { error: { code: "catalog_unsupported", message: "Bridge does not support project command catalog version 1. Update the bridge." } };
+            return body;
+        }
+        catch {
+            return { error: { code: "catalog_unavailable", message: "Project command catalog requires a reachable live Editor. Retry after compilation/reload settles." } };
+        }
+    }
     /**
      * M18 Plan 2 / T18.2.3 — fetch the compiled-state tool inventory from the
      * bridge (`GET /tools`). Returns the set of tool names the bridge compiled
@@ -1637,6 +1818,12 @@ export class LiveClient {
         const dllMtime = this.newestScriptAssembliesMtime();
         if (dllMtime !== undefined)
             snap.dllMtimeMs = dllMtime;
+        const compile = await this.readCompileState();
+        if (compile) {
+            snap.compileGeneration = compile.generation;
+            snap.compileStatus = compile.status;
+            snap.sourceMatches = compile.sourceMatches === true && compile.status === "no_errors_found";
+        }
         return snap;
     }
     /**
@@ -1739,8 +1926,6 @@ export class LiveClient {
             : undefined;
         const detection = detectCompileVerify({ before, after, sourceMtimeMs });
         const annotation = buildCompileVerifyAnnotation(detection);
-        if (annotation === null)
-            return result;
         // Inject into the first text content block's JSON body. Mirrors the
         // injectRouteMeta shape in tool-router.ts.
         const textIndex = result.content.findIndex((c) => c.type === "text");
@@ -1751,7 +1936,7 @@ export class LiveClient {
             return result;
         try {
             const body = JSON.parse(block.text);
-            body._compileVerify = annotation;
+            body._compileVerify = { ...annotation, before, after };
             const newContent = result.content.slice();
             newContent[textIndex] = { type: "text", text: JSON.stringify(body) };
             return { ...result, content: newContent };
@@ -1819,6 +2004,8 @@ export class LiveClient {
         // from the instance lock. Merge with any caller-supplied headers so we
         // never clobber a per-request value.
         const headers = new Headers(init.headers);
+        const requestId = randomUUID();
+        headers.set("X-Request-Id", requestId);
         if (this.authToken && !headers.has("Authorization")) {
             headers.set("Authorization", `Bearer ${this.authToken}`);
         }
@@ -1833,6 +2020,12 @@ export class LiveClient {
             headers,
             signal: controller.signal,
         }).then((res) => {
+            const echoedId = res.headers.get("X-Request-Id");
+            if (echoedId !== null && echoedId !== requestId) {
+                controller.abort();
+                dispose();
+                throw new Error("bridge_response_request_mismatch: response belongs to another request");
+            }
             // Wrap the body-reading accessors so the abort timer is cleared when
             // the body is consumed (the common path) or errors. The wrappers
             // delegate to the original methods; they only add the dispose() side
@@ -1855,8 +2048,10 @@ export class LiveClient {
                 // body WAS claimed, the fallback is a no-op — the abort timer
                 // remains armed to protect the in-progress read.
                 claimTimer = setTimeout(() => {
-                    if (!bodyClaimed)
+                    if (!bodyClaimed) {
+                        controller.abort();
                         dispose();
+                    }
                 }, 100);
                 claimTimer.unref();
             }