unity-open-mcp 1.4.0 → 1.6.0

package/dist/tool-router.js

@@ -1,4 +1,7 @@
-import { testRunOperation, projectCommandOperation } from "./jobs/adapters.js";
+import { randomUUID } from "node:crypto";
+import { testRunOperation, projectCommandOperation, playmodeOperation, pollPlaymodeOperation, playmodeResult, toolOutput, toolResultBody, PLAYMODE_OPERATION_TOOLS, playmodeEstimateMs, playmodeFailureCode } from "./jobs/adapters.js";
+import { PLAYMODE_ROUTES } from "./playmode-routes.js";
+import { routeGameView as settleGameView } from "./game-view-settle.js";
 import { JobManager, JobManagerError } from "./jobs/job-manager.js";
 import { handleJobs } from "./jobs/handler.js";
 import { PROCESS_AGENT_ID, PROCESS_IDENTITY } from "./agent-identity.js";
@@ -29,8 +32,12 @@ 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, EXPECTED_BRIDGE_WIRE_CONTRACT } from "./constants.js";
+import { PORT_ENV_VAR, EXPECTED_BRIDGE_WIRE_CONTRACT, BRIDGE_HOST_SAFE_TIMEOUT_CAP_MS } from "./constants.js";
 import { findUnityForProject, readProcessCommandLine } from "./running-unity.js";
+import { PlaytestRecorder, PlaytestError, PLAYTEST_SESSION_TOOL } from "./playtest/recorder.js";
+import { secretEnvValues } from "./playtest/redact.js";
+import { sessionsRoot } from "./playtest/session-store.js";
+import { PLAYTEST_SESSION_ACTION_KEYS } from "./tools/playtest-session.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
 // (not process.env on every call) so the hot path stays a single branch.
@@ -573,6 +580,11 @@ export class ToolRouter {
                     if (!this.jobs.hasOperation(name))
                         this.jobs.register(name, testRunOperation(clientFor));
                 }
+                else if (PLAYMODE_OPERATION_TOOLS.has(name)) {
+                    // One generic adapter for every tool on the bridge's shared play-mode scheduler.
+                    if (!this.jobs.hasOperation(name))
+                        this.jobs.register(name, playmodeOperation(name, PLAYMODE_OPERATION_TOOLS.get(name), clientFor));
+                }
                 else if (name.startsWith("project.") && !(typeof key === "string" && this.jobs.hasKey(owner, key))) {
                     // A retry whose key already names a job gets that job (or
                     // idempotency_conflict) from start() without the catalog, which may
@@ -602,6 +614,80 @@ export class ToolRouter {
             return localError(error instanceof JobManagerError ? error.code : "invalid_arguments", error instanceof Error ? error.message : String(error));
         }
     }
+    /**
+     * Play-mode operations (`inputsim_gesture`, `playtest_wait`,
+     * `capture_series`): the bridge starts the operation on its shared play-mode
+     * scheduler and answers at once; this route polls POST /playmode-operations
+     * until the terminal result, inside the host-safe window. An operation whose
+     * worst case (`playmodeEstimateMs`: last keyframe / capture, the wait's
+     * timeout, a series' start_on wait + schedule + encoding) exceeds the inline
+     * budget is started as a `jobs` play-mode operation instead and the call
+     * returns that job id. One that outlives the inline poll anyway (gameplay
+     * time, a paused Editor) is cancelled — which releases held input and
+     * restores a wait's time scale — and the error points at the jobs route.
+     */
+    async routePlaymodeOperation(name, args, live, identity) {
+        const spec = PLAYMODE_ROUTES[name];
+        const estimateMs = playmodeEstimateMs(name, args);
+        if (estimateMs > spec.inlineLimitMs) {
+            // The job owns the bridge operation id; a caller's operation_id keeps
+            // its retry meaning as the job's idempotency key.
+            const { operation_id: retryKey, ...jobArgs } = args;
+            const started = await this.routeJobs({ action: "start", tool_or_command: name, args: jobArgs,
+                ...(typeof retryKey === "string" ? { idempotency_key: retryKey } : {}) }, identity);
+            const body = toolResultBody(started);
+            if (started.isError || typeof body.job_id !== "string")
+                return started;
+            return sourceResult({ ...body, note: `${spec.label} can take ${Math.round(estimateMs)} ms (> ${spec.inlineLimitMs} ms inline budget); it runs as a job.`,
+                agentNextSteps: [`Call unity_open_mcp_jobs {"action":"wait","job_id":"${body.job_id}","timeout_ms":30000} until the state is terminal; the result holds ${spec.resultHint}.`] }, "local");
+        }
+        const operationId = typeof args.operation_id === "string" ? args.operation_id : randomUUID();
+        const start = await live.route(name, { ...args, operation_id: operationId });
+        const started = toolOutput(start);
+        if (start.isError || started.error || !started.operation)
+            return injectRouteMeta(start, { route: "live" });
+        const outcome = await pollPlaymodeOperation(live, operationId, {
+            deadlineMs: Math.min(estimateMs + 15_000, BRIDGE_HOST_SAFE_TIMEOUT_CAP_MS - 5_000),
+            pollIntervalMs: estimateMs < 2_000 ? 50 : 100,
+            unreachableMs: 10_000,
+        });
+        const meta = spec.startMeta(started);
+        // The poll's own deadline cancel, acknowledged: the operation stalled (a
+        // paused Editor never ticks it), it did not end by itself.
+        const stalled = outcome.kind === "deadline" || (outcome.kind === "terminal" && outcome.cancelSent && outcome.snapshot.state === "cancelled");
+        if (stalled) {
+            return sourceResult({ error: { code: spec.stalledCode, message: `The ${spec.noun} did not finish inside the inline window (a paused Editor, gameplay time, or a slow frame rate); it was cancelled and its cleanup ${spec.cleanup}.` },
+                operationId, last: outcome.snapshot, agentNextSteps: [`Check that play mode is running (not paused) and the Game view renders, then retry — or run it as a job: unity_open_mcp_jobs {"action":"start","tool_or_command":"${name}","args":{…}}, then wait on the job id.`] }, "live", true);
+        }
+        switch (outcome.kind) {
+            case "lost":
+                return sourceResult({ error: { code: "operation_lost", message: `The bridge lost the ${spec.noun} (domain reload or Editor restart); its cleanup ${spec.cleanup}.` }, operationId }, "live", true);
+            case "unreachable":
+                return sourceResult({ error: { code: "job_status_unavailable", message: outcome.error }, operationId }, "live", true);
+        }
+        if (outcome.kind !== "terminal")
+            throw new Error("unreachable play-mode poll outcome");
+        const snapshot = outcome.snapshot;
+        const result = { ...meta, ...playmodeResult(snapshot) };
+        if (snapshot.state === "succeeded")
+            return sourceResult({ status: "ok", ...result }, "live");
+        const code = playmodeFailureCode(snapshot, spec.failedCode);
+        // The operation's own `error` (a message string) becomes error.message.
+        return sourceResult({ ...result, error: { code, message: String(snapshot.result?.error ?? `${spec.label} ended ${snapshot.reason ?? snapshot.state}; its cleanup ${spec.cleanup}.`) },
+            ...(spec.failureNextSteps(code) ? { agentNextSteps: spec.failureNextSteps(code) } : {}) }, "live", true);
+    }
+    /**
+     * `game_view`: set_resolution / set_device in play mode return once the game
+     * reports the new size — the bridge starts a settle watch on its play-mode
+     * scheduler and this route polls it (then re-reads `get`), or answers
+     * `not_settled`. get / list_devices and edit-mode changes pass through.
+     */
+    async routeGameView(args, live) {
+        const outcome = await settleGameView(live, args);
+        if (outcome.kind === "passthrough")
+            return injectRouteMeta(outcome.result, { route: "live" });
+        return sourceResult(outcome.body, "live", outcome.isError);
+    }
     modelCache = new AssetModelCache();
     /**
      * M28-refactoring Plan 3 (T3.2) — named-tool dispatch map. Replaces the
@@ -628,6 +714,9 @@ export class ToolRouter {
             ["unity_open_mcp_generate_skill", (_l, a) => this.routeGenerateSkill(a)],
             ["unity_open_mcp_manage_tools", (l, a, id) => this.routeManageTools(a, l, id)],
             ["unity_open_mcp_project_commands", (l, a) => this.routeProjectCommands(a, l)],
+            // Playtest session recorder: the log lives here (the server sees every
+            // call); bridge reads go through the normal route as the same owner.
+            [PLAYTEST_SESSION_TOOL, (l, a, id) => this.routePlaytestSession(a, l, id)],
             // Live tool whose release lookups (npm latest, GitHub tag) run HERE so
             // the Editor main thread never blocks on the network.
             ["unity_open_mcp_upgrade", (l, a) => this.routeUpgrade(a, l)],
@@ -636,6 +725,15 @@ export class ToolRouter {
             // the process agent id, whatever _meta.agentId the call carried. Direct,
             // manage_tools(invoke) and port-override calls therefore share one owner.
             ["unity_open_mcp_jobs", (_l, a, id) => this.routeJobs(a, id)],
+            // Gestures, waits and capture series run on the bridge's play-mode
+            // scheduler: start, then poll the operation to its terminal result here
+            // (long ones become a job).
+            ["unity_open_mcp_inputsim_gesture", (l, a, id) => this.routePlaymodeOperation("unity_open_mcp_inputsim_gesture", a, l, id)],
+            ["unity_open_mcp_playtest_wait", (l, a, id) => this.routePlaymodeOperation("unity_open_mcp_playtest_wait", a, l, id)],
+            ["unity_senses_capture_series", (l, a, id) => this.routePlaymodeOperation("unity_senses_capture_series", a, l, id)],
+            // Game view / Simulator changes settle over play-mode frames: poll the
+            // bridge's settle watch here so set_* returns once the game sees the size.
+            ["unity_open_mcp_game_view", (l, a) => this.routeGameView(a, l)],
             ["unity_open_mcp_bridge_status", (l, a) => this.routeBridgeStatus(a, l)],
             // M31 Plan 3 — Editor fd-exhaustion operator surfaces. restart_editor
             // is the reactive kill half (acts AFTER the Editor is hung);
@@ -756,7 +854,142 @@ export class ToolRouter {
     async routeOverride(toolName, args, overrideLive, identity) {
         return this.routeCore(overrideLive, toolName, args, identity);
     }
+    /**
+     * Every entry point funnels through here (direct, manage_tools invoke, port
+     * override). While the caller's agent owner has an open playtest session, a
+     * recorded call (input / wait / capture / project command / play-mode and
+     * Game view changes) is logged around its dispatch; everything else — and
+     * every call when no session is open — goes straight through. The recorder
+     * never changes a result and never fails a call.
+     */
     async routeCore(live, toolName, args, identity) {
+        const recorder = this.playtestRecorder;
+        if (!recorder || recorder.openCount === 0 || toolName === PLAYTEST_SESSION_TOOL)
+            return this.routeDispatch(live, toolName, args, identity);
+        const owner = this.ownerOf(identity);
+        if (!recorder.isRecording(owner))
+            return this.routeDispatch(live, toolName, args, identity);
+        if (toolName === "unity_open_mcp_jobs" && (args.action === "wait" || args.action === "status")) {
+            const observed = await this.routeDispatch(live, toolName, args, identity);
+            try {
+                recorder.observeJob(owner, args, observed);
+            }
+            catch (error) {
+                console.error("[unity-open-mcp] playtest recorder:", error);
+            }
+            return observed;
+        }
+        let handle = null;
+        try {
+            handle = recorder.begin(owner, toolName, args);
+        }
+        catch (error) {
+            console.error("[unity-open-mcp] playtest recorder:", error);
+        }
+        if (!handle)
+            return this.routeDispatch(live, toolName, args, identity);
+        this.eventStream.reconnectNow?.call(this.eventStream);
+        let result;
+        try {
+            result = await this.routeDispatch(live, toolName, args, identity);
+        }
+        catch (error) {
+            try {
+                recorder.finish(handle, args, null, error);
+            }
+            catch (inner) {
+                console.error("[unity-open-mcp] playtest recorder:", inner);
+            }
+            throw error;
+        }
+        try {
+            recorder.finish(handle, args, result);
+        }
+        catch (error) {
+            console.error("[unity-open-mcp] playtest recorder:", error);
+        }
+        return result;
+    }
+    /** The owner a request files sessions (and jobs) under. */
+    ownerOf(identity) {
+        return { project: this.projectPath || "default", agent: identity.agent, ...(identity.port === undefined ? {} : { port: identity.port }) };
+    }
+    playtestRecorder;
+    /** The session recorder, created on first use and fed by the bridge event stream. */
+    get playtest() {
+        if (!this.playtestRecorder) {
+            this.usePlaytestRecorder(new PlaytestRecorder({
+                root: sessionsRoot(),
+                projectPath: this.projectPath || "default",
+                knownSecrets: [this.projectPath ? resolveAuthToken(this.projectPath) : undefined, ...secretEnvValues()],
+                streamConnected: () => this.eventStream.isConnected === true,
+            }));
+        }
+        return this.playtestRecorder;
+    }
+    /** Install a recorder (tests use a temporary root). */
+    usePlaytestRecorder(recorder) {
+        this.playtestRecorder = recorder;
+        this.eventStream.addListener?.call(this.eventStream, event => recorder.onEvent(event));
+    }
+    /**
+     * `unity_open_mcp_playtest_session` — local route. Bridge reads the session
+     * needs (company / product, the Game view state, a player-state snapshot or
+     * diff) go through the normal route as the same owner, and only when the
+     * bridge answers /ping; otherwise the recorder falls back to disk.
+     */
+    async routePlaytestSession(args, live, identity) {
+        const action = String(args.action ?? "");
+        const allowed = PLAYTEST_SESSION_ACTION_KEYS[action];
+        if (!allowed)
+            return localError("invalid_arguments", `Unknown action '${action}'.`);
+        const extra = Object.keys(args).filter(key => key !== "action" && !allowed.includes(key));
+        if (extra.length)
+            return localError("invalid_arguments", `Keys not used by ${action}: ${extra.join(", ")}.`);
+        const recorder = this.playtest;
+        const owner = this.ownerOf(identity);
+        let available;
+        const call = async (tool, toolArgs) => {
+            available ??= await live.isLiveAvailable(1_500);
+            if (!available)
+                return localError("bridge_unavailable", "The Unity bridge is not reachable.");
+            const definition = ALL_TOOLS.find(t => t.name === tool);
+            return this.routeDispatch(live, tool, definition ? withSchemaDefaults(definition, toolArgs) : toolArgs, identity);
+        };
+        const sessionArg = typeof args.session === "string" ? args.session : undefined;
+        try {
+            if (action !== "status" || recorder.isRecording(owner) === false)
+                await recorder.prepare(call);
+            if (action === "start" || action === "resume" || action === "end")
+                this.eventStream.ensureSubscription?.call(this.eventStream);
+            let body;
+            switch (action) {
+                case "start":
+                    body = await recorder.start(owner, args, call);
+                    break;
+                case "mark":
+                    body = recorder.mark(owner, args, sessionArg);
+                    break;
+                case "status":
+                    body = recorder.status(owner);
+                    break;
+                case "resume":
+                    body = recorder.resume(owner, sessionArg);
+                    break;
+                case "end":
+                    body = await recorder.end(owner, args, call);
+                    break;
+                default: body = recorder.list(owner, typeof args.limit === "number" ? args.limit : 10);
+            }
+            return sourceResult(body, "local");
+        }
+        catch (error) {
+            if (error instanceof PlaytestError)
+                return sourceResult({ error: { code: error.code, message: error.message }, ...error.detail }, "local", true);
+            return localError("internal_error", error instanceof Error ? error.message : String(error));
+        }
+    }
+    async routeDispatch(live, toolName, args, identity) {
         // Every entry point funnels through here, so an explicit project_path is
         // retargeted before validation and wiring wherever the call came from.
         if ((toolName === "unity_open_mcp_capabilities" || toolName === "unity_open_mcp_bridge_status") && args.project_path !== undefined)
@@ -3166,15 +3399,24 @@ function pageSceneNodes(body, pageSize, cursor) {
  */
 function flattenSceneBody(body) {
     const out = [];
-    const walk = (node) => {
+    // Rows are flat (no nested `children`), so each carries its hierarchy
+    // `path` — otherwise same-named nodes on a page cannot be told apart or
+    // addressed once a depth limit or truncation desyncs `childCount`.
+    const walk = (node, parentPath) => {
         if (!node || typeof node !== "object")
             return;
         const obj = node;
-        out.push(obj);
-        const children = obj.children;
+        const { children, ...flatNode } = obj;
+        const name = typeof obj.name === "string" ? obj.name : undefined;
+        const path = typeof obj.path === "string"
+            ? obj.path
+            : name === undefined ? undefined : parentPath === undefined ? name : `${parentPath}/${name}`;
+        if (path !== undefined && flatNode.path === undefined)
+            flatNode.path = path;
+        out.push(flatNode);
         if (Array.isArray(children)) {
             for (const child of children)
-                walk(child);
+                walk(child, path);
         }
     };
     // M3 — the bridge nests everything one level down under `body.scene`
@@ -3191,7 +3433,7 @@ function flattenSceneBody(body) {
     const rootField = Array.isArray(scene.roots) ? scene.roots : scene.rootGameObjects;
     if (Array.isArray(rootField)) {
         for (const root of rootField)
-            walk(root);
+            walk(root, undefined);
     }
     return out;
 }