@godot-mcp/control-plane 0.0.0 → 0.1.0

package/dist/runtime/runtimeService.js

@@ -0,0 +1,919 @@
+import { randomUUID } from "node:crypto";
+import { realpath } from "node:fs/promises";
+import { isAbsolute, join, relative, sep } from "node:path";
+import { canonicalJson, DebugStopResultSchema, InputOperationResultSchema, MonitorSnapshotSchema, ProfileJobReceiptSchema, ProfileResultSchema, RuntimeLaunchPinsSchema } from "@godot-mcp/protocol";
+import { GodotMcpException } from "../errors.js";
+import { resolveProjectPath } from "../project/pathPolicy.js";
+import { DebuggerClientError } from "./debuggerClient.js";
+import { DebugTokenStore, DebugTokenStoreError } from "./debugTokenStore.js";
+import { createRuntimeDescriptor, } from "./runtimeDescriptor.js";
+import { assertLoopbackListenerOwnedByProcess, assertLoopbackListenersOwnedByProcess, OwnedGodotProcess, } from "./runtimeProcess.js";
+import { inputTraceEvents, traceSha256 } from "./inputReceipt.js";
+class AuthenticatedDebuggerClient {
+    command;
+    handle;
+    connected = true;
+    stopped = false;
+    stopSequence = 0;
+    constructor(command, handle) {
+        this.command = command;
+        this.handle = handle;
+    }
+    async request(command, adapterArguments, timeoutMs = 10_000) {
+        if (!this.connected)
+            throw runtimeError("TRANSPORT_ERROR", "Authenticated debugger channel is closed", true);
+        const response = await this.command("debug_adapter", { handle: this.handle, command, adapterArguments }, timeoutMs);
+        if (!isRecord(response))
+            throw runtimeError("GODOT_RUNTIME_ERROR", "Authenticated debugger returned a malformed response");
+        if (command === "pause") {
+            const body = isRecord(response.body) ? response.body : {};
+            this.stopped = true;
+            this.stopSequence = Math.max(this.stopSequence, integerOr(body.sequence, this.stopSequence + 1));
+        }
+        else if (command === "continue" || command === "next" || command === "stepIn") {
+            this.stopped = false;
+        }
+        await this.refresh();
+        return response;
+    }
+    async nextStop(afterSequence, timeoutMs) {
+        const response = await this.command("debug_adapter", {
+            handle: this.handle,
+            command: "wait",
+            adapterArguments: { afterSequence, timeoutMs },
+        }, timeoutMs + 250);
+        if (!isRecord(response) || !Number.isInteger(response.sequence) || typeof response.reason !== "string") {
+            throw runtimeError("GODOT_RUNTIME_ERROR", "Authenticated debugger returned a malformed stop event");
+        }
+        const eventSequence = Number(response.sequence);
+        await this.refresh();
+        return { sequence: eventSequence, reason: response.reason, body: { reason: response.reason, threadId: 1 } };
+    }
+    snapshot() {
+        return { connected: this.connected, stopped: this.stopped, stopSequence: this.stopSequence };
+    }
+    markRunning(afterSequence = this.stopSequence) {
+        if (this.stopSequence <= afterSequence)
+            this.stopped = false;
+    }
+    async refresh() {
+        if (!this.connected)
+            return;
+        const response = await this.command("debug_adapter", {
+            handle: this.handle,
+            command: "status",
+            adapterArguments: {},
+        });
+        if (!isRecord(response) || typeof response.connected !== "boolean" || typeof response.stopped !== "boolean" || !Number.isInteger(response.stopSequence)) {
+            throw runtimeError("GODOT_RUNTIME_ERROR", "Authenticated debugger returned malformed status");
+        }
+        this.connected = response.connected;
+        this.stopped = response.stopped;
+        this.stopSequence = Number(response.stopSequence);
+    }
+    async close() {
+        this.connected = false;
+    }
+}
+function runtimeError(code, message, retryable = false) {
+    return new GodotMcpException({
+        code,
+        message,
+        retryable,
+        correlationId: randomUUID(),
+        partialEffects: false,
+        rollback: "not_needed",
+    });
+}
+export class RuntimeService {
+    dependencies;
+    state = "idle";
+    generation = 0;
+    handle = null;
+    scenePath = null;
+    process = null;
+    processStopped = false;
+    descriptor = null;
+    closePromise;
+    disconnectPromise;
+    launchPromise;
+    cleanupPromise;
+    debuggerCleaned = true;
+    lifecycleEpoch = 0;
+    closed = false;
+    operationTail = Promise.resolve();
+    debuggerClient = null;
+    debuggerGeneration = 0;
+    debuggerSessionId = null;
+    debugTokens = new DebugTokenStore();
+    breakpointSources = new Map();
+    opaqueProfileId = null;
+    constructor(dependencies) {
+        this.dependencies = dependencies;
+    }
+    snapshot() {
+        return {
+            state: this.state,
+            handle: this.handle ? { ...this.handle } : null,
+            scenePath: this.scenePath,
+            process: this.process ? { pid: this.process.pid, fingerprint: this.process.fingerprint } : null,
+        };
+    }
+    launch(input) {
+        if (this.closed)
+            return Promise.reject(runtimeError("CONFLICT", "Runtime service is closed"));
+        if (this.disconnectPromise)
+            return Promise.reject(runtimeError("CONFLICT", "Runtime service is disconnecting"));
+        if (this.launchPromise)
+            return Promise.reject(runtimeError("CONFLICT", "A runtime launch is already in progress"));
+        if (!["idle", "stopped"].includes(this.state))
+            return Promise.reject(runtimeError("CONFLICT", "A runtime is already active"));
+        const epoch = this.lifecycleEpoch;
+        const activeLaunch = this.launchGeneration(input, epoch).finally(() => {
+            if (this.launchPromise === activeLaunch)
+                this.launchPromise = undefined;
+        });
+        this.launchPromise = activeLaunch;
+        return activeLaunch;
+    }
+    async launchGeneration(input, epoch) {
+        const sessionId = this.dependencies.sessionId();
+        if (!sessionId)
+            throw runtimeError("NOT_ATTACHED", "Godot editor addon is not attached", true);
+        this.generation += 1;
+        this.handle = { runId: randomUUID(), generation: this.generation };
+        this.scenePath = input.scenePath;
+        this.processStopped = false;
+        try {
+            await this.cleanupDebugger(true);
+            this.assertLaunchCurrent(epoch);
+            this.state = "preparing";
+            const descriptorInput = {
+                project: this.dependencies.project,
+                sessionId,
+                runId: this.handle.runId,
+                generation: this.handle.generation,
+                scenePath: input.scenePath,
+                ...(input.pins ? { pins: input.pins } : {}),
+            };
+            this.descriptor = await (this.dependencies.createDescriptor ?? createRuntimeDescriptor)(descriptorInput);
+            const descriptor = this.descriptor;
+            this.assertLaunchCurrent(epoch);
+            this.debuggerCleaned = false;
+            const prepared = await this.dependencies.prepare({ descriptor: descriptor.descriptor });
+            this.assertLaunchCurrent(epoch);
+            if (!Number.isInteger(prepared.debugPort) || prepared.debugPort < 1 || prepared.debugPort > 65_535) {
+                throw runtimeError("GODOT_RUNTIME_ERROR", "Editor reported an invalid debugger port");
+            }
+            if (this.dependencies.requireAuthenticatedDebuggerMetadata && (prepared.editorPid === undefined || prepared.debugTransport !== "authenticated-editor-session")) {
+                throw runtimeError("AUTHENTICATION_FAILED", "Authenticated editor debugger transport and process identity are required for runtime debugging");
+            }
+            if (prepared.editorPid !== undefined) {
+                if (!Number.isInteger(prepared.editorPid) || prepared.editorPid < 1) {
+                    throw runtimeError("GODOT_RUNTIME_ERROR", "Editor reported an invalid process identity");
+                }
+                const verifyListener = this.dependencies.verifyEditorListener ?? this.dependencies.verifyDebuggerListener ?? assertLoopbackListenerOwnedByProcess;
+                await assertLoopbackListenersOwnedByProcess(prepared.editorPid, [prepared.debugPort], verifyListener);
+                this.assertLaunchCurrent(epoch);
+            }
+            this.state = "launching";
+            const launch = this.dependencies.launchProcess ?? ((launchInput) => OwnedGodotProcess.launch(launchInput));
+            this.process = await launch({
+                godotBin: this.dependencies.godotBin ?? process.env.GODOT_BIN ?? "godot",
+                projectRoot: this.dependencies.project.rootRealPath,
+                debugPort: prepared.debugPort,
+                descriptorPath: descriptor.path,
+                ...(input.pins ? { pins: input.pins } : {}),
+            });
+            this.assertLaunchCurrent(epoch);
+            const ownedProcess = this.process;
+            void ownedProcess.wait().then(() => this.onProcessExit(ownedProcess), () => this.onProcessExit(ownedProcess));
+            this.state = "authenticating";
+            const ready = await this.dependencies.command("await_ready", { handle: this.handle }, input.startupTimeoutMs);
+            this.assertLaunchCurrent(epoch);
+            if (typeof ready !== "object" ||
+                ready === null ||
+                !("pid" in ready) ||
+                Number(ready.pid) !== this.process.pid) {
+                throw runtimeError("AUTHENTICATION_FAILED", "Authenticated runtime PID does not match the owned process");
+            }
+            if (input.pins) {
+                const observedPins = RuntimeLaunchPinsSchema.safeParse(ready.observedPins);
+                if (!observedPins.success || canonicalJson(observedPins.data) !== canonicalJson(input.pins)) {
+                    throw runtimeError("AUTHENTICATION_FAILED", "Runtime did not apply the authenticated deterministic launch pins");
+                }
+            }
+            const readySessionId = Number(ready.debuggerSessionId);
+            if (this.dependencies.requireAuthenticatedDebuggerMetadata && (!Number.isInteger(readySessionId) || readySessionId < 0)) {
+                throw runtimeError("AUTHENTICATION_FAILED", "Authenticated runtime omitted its debugger session identity");
+            }
+            this.debuggerSessionId = Number.isInteger(readySessionId) && readySessionId >= 0 ? readySessionId : null;
+            if (this.dependencies.requireAuthenticatedDebuggerMetadata) {
+                await this.dependencies.command("certify_owner_pid", { handle: this.handle, ownerPid: this.process.pid }, 5_000);
+            }
+            await descriptor.consume?.();
+            this.assertLaunchCurrent(epoch);
+            if (this.processStopped) {
+                throw runtimeError("GODOT_RUNTIME_ERROR", "Owned runtime exited before launch completed");
+            }
+            if (prepared.debugTransport === "authenticated-editor-session" && this.debuggerSessionId !== null) {
+                this.attachAuthenticatedDebugger();
+            }
+            this.state = "running";
+            return { handle: { ...this.handle }, root: ready };
+        }
+        catch (error) {
+            this.state = "failed";
+            await this.cleanup();
+            throw error;
+        }
+    }
+    execute(input) {
+        return this.runExclusive(() => this.executeExclusive(input));
+    }
+    async executeExclusive(input) {
+        if (input.operation.startsWith("debug_")) {
+            this.assertHandle(input.handle);
+            try {
+                return await this.executeDebug(input);
+            }
+            catch (error) {
+                throw normalizeDebugError(error);
+            }
+        }
+        if (input.operation === "monitor_snapshot" || input.operation.startsWith("profile_")) {
+            this.assertHandle(input.handle);
+            return this.executePerformance(input);
+        }
+        if (input.operation === "status") {
+            if (input.handle)
+                this.assertHandleIdentity(input.handle);
+            if (!this.handle || !["running", "paused"].includes(this.state))
+                return this.snapshot();
+            const runtimeStatus = await this.dependencies.command("status", { handle: this.handle });
+            if (typeof runtimeStatus !== "object" || runtimeStatus === null)
+                return this.snapshot();
+            if ("paused" in runtimeStatus && typeof runtimeStatus.paused === "boolean") {
+                this.state = runtimeStatus.paused ? "paused" : "running";
+            }
+            return { ...this.snapshot(), ...runtimeStatus };
+        }
+        this.assertHandle(input.handle);
+        if (input.operation === "stop") {
+            this.state = "stopping";
+            let stopError;
+            try {
+                await this.dependencies.command("stop", { ...input });
+            }
+            catch (error) {
+                stopError = error;
+            }
+            try {
+                await this.cleanup();
+            }
+            catch (error) {
+                this.state = "failed";
+                throw error;
+            }
+            if (stopError)
+                throw stopError;
+            return this.snapshot();
+        }
+        const timeoutMs = input.operation === "wait" ? input.timeoutMs + 1_000 : undefined;
+        const result = await this.dependencies.command(input.operation, { ...input }, timeoutMs);
+        if (input.operation === "pause")
+            this.state = "paused";
+        if (input.operation === "resume")
+            this.state = "running";
+        return result;
+    }
+    async executePerformance(input) {
+        if (input.operation === "monitor_snapshot") {
+            return MonitorSnapshotSchema.parse(await this.dependencies.command(input.operation, { ...input }));
+        }
+        if (input.operation === "profile_start") {
+            const receipt = ProfileJobReceiptSchema.parse(await this.dependencies.command(input.operation, { ...input }));
+            this.opaqueProfileId = receipt.jobToken;
+            return receipt;
+        }
+        if (this.opaqueProfileId === null || input.jobToken !== this.opaqueProfileId) {
+            throw runtimeError("STALE_HANDLE", "Profile job token is stale or unknown");
+        }
+        if (input.operation === "profile_result") {
+            const result = ProfileResultSchema.parse(await this.dependencies.command(input.operation, { ...input }));
+            if (result.evidence.jobToken !== input.jobToken) {
+                throw runtimeError("STALE_HANDLE", "Profile evidence belongs to a different job");
+            }
+            return result;
+        }
+        const receipt = ProfileJobReceiptSchema.parse(await this.dependencies.command(input.operation, { ...input }));
+        if (receipt.jobToken !== input.jobToken) {
+            throw runtimeError("STALE_HANDLE", "Profile receipt belongs to a different job");
+        }
+        return receipt;
+    }
+    attachAuthenticatedDebugger() {
+        this.debuggerClient = new AuthenticatedDebuggerClient(this.dependencies.command, { ...this.handle });
+        this.debuggerGeneration += 1;
+        this.debugTokens.clear();
+        this.breakpointSources.clear();
+    }
+    async executeDebug(input) {
+        await this.assertDebuggerBinding();
+        await this.debuggerClient?.refresh?.();
+        if (this.debuggerClient && !this.debuggerClient.snapshot().stopped)
+            this.debugTokens.clear();
+        if (input.operation === "debug_status") {
+            const snapshot = this.debuggerClient?.snapshot() ?? { connected: false, stopped: false, stopSequence: 0 };
+            const breakpointCount = [...this.breakpointSources.values()].reduce((total, lines) => total + lines.length, 0);
+            return { ...snapshot, breakpointCount };
+        }
+        const debuggerClient = this.requireDebuggerClient();
+        switch (input.operation) {
+            case "debug_wait": {
+                const stopped = await debuggerClient.nextStop(input.afterSequence, input.timeoutMs);
+                const live = debuggerClient.snapshot();
+                if (live.stopped && live.stopSequence === stopped.sequence)
+                    this.bindDebugStop(stopped.sequence);
+                else
+                    this.debugTokens.clear();
+                return projectDebugStop(stopped);
+            }
+            case "debug_pause":
+                if (debuggerClient.snapshot().stopped)
+                    throw runtimeError("PRECONDITION_FAILED", "Godot debugger is already stopped");
+                await debuggerClient.request("pause", { threadId: 1 });
+                return debuggerClient.snapshot();
+            case "debug_continue":
+                if (!debuggerClient.snapshot().stopped)
+                    throw runtimeError("PRECONDITION_FAILED", "Godot debugger must be stopped before continuing");
+                const continueSequence = debuggerClient.snapshot().stopSequence;
+                await debuggerClient.request("continue", { threadId: 1 });
+                debuggerClient.markRunning(continueSequence);
+                this.debugTokens.clear();
+                return debuggerClient.snapshot();
+            case "debug_step_over":
+                return this.stepDebugger(debuggerClient, "next");
+            case "debug_step_into":
+                return this.stepDebugger(debuggerClient, "stepIn");
+            case "debug_breakpoints_set":
+                return this.setDebugBreakpoints(debuggerClient, input);
+            case "debug_stack":
+                return this.debugStack(debuggerClient, input.offset, input.limit);
+            case "debug_variables": {
+                const stopSequence = this.bindDebugStop();
+                const frameId = this.debugTokens.resolveFrame(input.frameToken);
+                const reference = await this.scopeReference(debuggerClient, frameId, input.scope, stopSequence);
+                return this.readVariables(debuggerClient, reference, 1, input.offset, input.limit, stopSequence);
+            }
+            case "debug_children": {
+                const stopSequence = this.bindDebugStop();
+                const record = this.debugTokens.resolveVariable(input.variableToken);
+                return this.readVariables(debuggerClient, record.variablesReference, record.depth + 1, input.offset, input.limit, stopSequence);
+            }
+            case "debug_watch": {
+                const stopSequence = this.bindDebugStop();
+                const frameId = this.debugTokens.resolveFrame(input.frameToken);
+                const watches = [];
+                for (const selector of input.selectors)
+                    watches.push(await this.resolveWatch(debuggerClient, frameId, selector, stopSequence));
+                return { watches };
+            }
+        }
+    }
+    requireDebuggerClient() {
+        if (!this.debuggerClient || !this.debuggerClient.snapshot().connected) {
+            throw runtimeError("PRECONDITION_FAILED", "The authenticated Godot debugger is unavailable for the active runtime", true);
+        }
+        return this.debuggerClient;
+    }
+    async assertDebuggerBinding() {
+        if (this.debuggerSessionId === null || !this.handle)
+            return;
+        const status = await this.dependencies.command("debug_binding_status", { handle: this.handle });
+        if (!isRecord(status) || status.unambiguous !== true || status.activeSessionCount !== 1 || status.debuggerSessionId !== this.debuggerSessionId) {
+            this.debugTokens.clear();
+            throw runtimeError("AUTHENTICATION_FAILED", "The Godot debugger target is not the uniquely authenticated runtime session");
+        }
+    }
+    bindDebugStop(stopSequence) {
+        const debuggerClient = this.requireDebuggerClient();
+        const snapshot = debuggerClient.snapshot();
+        const sequence = stopSequence ?? snapshot.stopSequence;
+        if (!snapshot.stopped || sequence < 1 || snapshot.stopSequence !== sequence || !this.handle) {
+            this.debugTokens.clear();
+            throw runtimeError("PRECONDITION_FAILED", "Godot runtime is not stopped in a debuggable frame");
+        }
+        this.debugTokens.bind({
+            runId: this.handle.runId,
+            generation: this.handle.generation,
+            debuggerGeneration: this.debuggerGeneration,
+            stopSequence: sequence,
+        });
+        return sequence;
+    }
+    async stepDebugger(debuggerClient, command) {
+        const snapshot = debuggerClient.snapshot();
+        if (!snapshot.stopped)
+            throw runtimeError("PRECONDITION_FAILED", "Godot debugger must be stopped before stepping");
+        await debuggerClient.request(command, { threadId: 1 });
+        debuggerClient.markRunning(snapshot.stopSequence);
+        this.debugTokens.clear();
+        const stopped = await debuggerClient.nextStop(snapshot.stopSequence, 10_000);
+        this.bindDebugStop(stopped.sequence);
+        return projectDebugStop(stopped);
+    }
+    async setDebugBreakpoints(debuggerClient, input) {
+        const grouped = new Map();
+        for (const breakpoint of input.breakpoints) {
+            if (breakpoint.sourcePath.toLowerCase().startsWith("res://addons/godot_mcp/")) {
+                throw runtimeError("INVALID_REQUEST", "Debugger breakpoints cannot target the Godot MCP addon");
+            }
+            const absolutePath = await realpath(await resolveProjectPath(this.dependencies.project, breakpoint.sourcePath, "read"));
+            if (isPathInsideCaseInsensitive(join(this.dependencies.project.rootRealPath, "addons", "godot_mcp"), absolutePath)) {
+                throw runtimeError("INVALID_REQUEST", "Debugger breakpoints cannot target the Godot MCP addon");
+            }
+            const entries = grouped.get(absolutePath) ?? [];
+            entries.push(breakpoint);
+            grouped.set(absolutePath, entries);
+        }
+        const previous = new Map([...this.breakpointSources].map(([path, lines]) => [path, [...lines]]));
+        const sources = new Set([...previous.keys(), ...grouped.keys()]);
+        const results = [];
+        const applied = [];
+        try {
+            for (const absolutePath of sources) {
+                const entries = grouped.get(absolutePath) ?? [];
+                applied.push(absolutePath);
+                const response = await debuggerClient.request("setBreakpoints", {
+                    source: { name: absolutePath.split(sep).at(-1), path: absolutePath },
+                    breakpoints: entries.map((entry) => ({ line: entry.line })),
+                });
+                const returned = bodyArray(response, "breakpoints");
+                for (const [index, entry] of entries.entries()) {
+                    const raw = isRecord(returned[index]) ? returned[index] : {};
+                    results.push({
+                        sourcePath: entry.sourcePath,
+                        requestedLine: entry.line,
+                        verified: raw.verified === true,
+                        resolvedLine: integerOr(raw.line, entry.line),
+                        ...(typeof raw.message === "string" ? { message: raw.message.slice(0, 512) } : {}),
+                    });
+                }
+            }
+        }
+        catch (error) {
+            let rollbackFailed = false;
+            for (const absolutePath of applied.reverse()) {
+                try {
+                    const lines = previous.get(absolutePath) ?? [];
+                    await debuggerClient.request("setBreakpoints", {
+                        source: { name: absolutePath.split(sep).at(-1), path: absolutePath },
+                        breakpoints: lines.map((line) => ({ line })),
+                    });
+                }
+                catch {
+                    rollbackFailed = true;
+                }
+            }
+            if (rollbackFailed) {
+                await this.stopProcess().catch(() => undefined);
+                await this.cleanup().catch(() => undefined);
+                this.state = "failed";
+                throw runtimeError("TRANSPORT_ERROR", "Breakpoint replacement failed and could not be rolled back", true);
+            }
+            throw error;
+        }
+        this.breakpointSources.clear();
+        for (const [absolutePath, entries] of grouped) {
+            if (entries.length > 0)
+                this.breakpointSources.set(absolutePath, entries.map((entry) => entry.line));
+        }
+        return { breakpoints: results };
+    }
+    async debugStack(debuggerClient, offset, limit) {
+        const stopSequence = this.bindDebugStop();
+        const response = await debuggerClient.request("stackTrace", { threadId: 1, startFrame: offset, levels: limit });
+        this.bindDebugStop(stopSequence);
+        const rawFrames = bodyArray(response, "stackFrames").slice(0, limit);
+        const frames = rawFrames.flatMap((raw) => {
+            if (!isRecord(raw) || !Number.isInteger(raw.id))
+                return [];
+            const rawSourcePath = isRecord(raw.source) && typeof raw.source.path === "string" ? raw.source.path : undefined;
+            if (rawSourcePath?.toLowerCase().startsWith("res://addons/godot_mcp/"))
+                return [];
+            const source = rawSourcePath
+                ? this.projectSourcePath(rawSourcePath)
+                : undefined;
+            return [{
+                    frameToken: this.debugTokens.issueFrame(Number(raw.id)),
+                    name: boundedText(raw.name, "<anonymous>", 512),
+                    ...(source === undefined ? {} : { sourcePath: source }),
+                    line: integerOr(raw.line, 0),
+                    column: integerOr(raw.column, 0),
+                }];
+        });
+        const body = isRecord(response.body) ? response.body : {};
+        const totalFrames = Number.isInteger(body.totalFrames)
+            ? Math.min(64, Math.max(0, Number(body.totalFrames)))
+            : Math.min(64, offset + rawFrames.length);
+        return { frames, totalFrames };
+    }
+    async scopeReference(debuggerClient, frameId, scope, stopSequence) {
+        const response = await debuggerClient.request("scopes", { frameId });
+        this.bindDebugStop(stopSequence);
+        const match = bodyArray(response, "scopes").find((entry) => isRecord(entry) && typeof entry.name === "string" && entry.name.toLowerCase() === scope);
+        if (!isRecord(match) || !Number.isInteger(match.variablesReference) || Number(match.variablesReference) < 1) {
+            throw runtimeError("PRECONDITION_FAILED", `Godot debugger did not return the ${scope} scope`);
+        }
+        return Number(match.variablesReference);
+    }
+    async readVariables(debuggerClient, variablesReference, depth, offset, limit, stopSequence) {
+        if (depth > 8)
+            throw runtimeError("PRECONDITION_FAILED", "Debugger variable depth limit exceeded");
+        const response = await this.requestVariables(debuggerClient, { variablesReference, start: offset, count: limit });
+        this.bindDebugStop(stopSequence);
+        const all = bodyArray(response, "variables");
+        const selected = all.slice(0, limit);
+        const body = isRecord(response.body) ? response.body : {};
+        const total = Number.isInteger(body.totalVariables)
+            ? Math.min(2_048, Math.max(0, Number(body.totalVariables)))
+            : Math.min(2_048, offset + all.length);
+        this.debugTokens.consumeVariableEntries(selected.length);
+        return {
+            variables: selected.map((entry) => this.formatVariable(entry, depth)),
+            offset,
+            returned: selected.length,
+            total,
+            truncated: body.truncated === true || all.length > selected.length || offset + selected.length < total,
+        };
+    }
+    formatVariable(rawValue, depth) {
+        const raw = isRecord(rawValue) ? rawValue : {};
+        const childReference = Number.isInteger(raw.variablesReference) ? Number(raw.variablesReference) : 0;
+        const value = truncateUtf8(typeof raw.value === "string" ? raw.value : String(raw.value ?? ""), 4_096);
+        const variableToken = childReference > 0 && depth < 8
+            ? this.debugTokens.issueVariable(childReference, depth)
+            : undefined;
+        const selectorMetadata = { selectorKind: "unsupported" };
+        if (raw.selectorKind === "string" &&
+            typeof raw.selectorValue === "string" &&
+            raw.selectorValue.length > 0 &&
+            !raw.selectorValue.includes("\0") &&
+            Buffer.byteLength(raw.selectorValue, "utf8") <= 128) {
+            selectorMetadata.selectorKind = "string";
+            selectorMetadata.selectorValue = raw.selectorValue;
+        }
+        else if (raw.selectorKind === "number" &&
+            Number.isInteger(raw.selectorValue) &&
+            Number(raw.selectorValue) >= 0 &&
+            Number(raw.selectorValue) <= 1_000_000) {
+            selectorMetadata.selectorKind = "number";
+            selectorMetadata.selectorValue = Number(raw.selectorValue);
+        }
+        return {
+            name: boundedText(raw.name, "<unnamed>", 128),
+            type: boundedText(raw.type, "unknown", 128),
+            value: value.text,
+            valueTruncated: raw.valueTruncated === true || value.truncated,
+            hasChildren: childReference > 0,
+            expandable: variableToken !== undefined,
+            ...selectorMetadata,
+            ...(variableToken === undefined ? {} : { variableToken }),
+        };
+    }
+    async resolveWatch(debuggerClient, frameId, selector, stopSequence) {
+        let reference = await this.scopeReference(debuggerClient, frameId, selector.scope, stopSequence);
+        let current;
+        for (const [depthIndex, segment] of selector.path.entries()) {
+            const response = await this.requestVariables(debuggerClient, { variablesReference: reference, start: 0, count: 256 });
+            this.bindDebugStop(stopSequence);
+            const all = bodyArray(response, "variables");
+            const bounded = all.slice(0, 256);
+            this.debugTokens.consumeVariableEntries(bounded.length);
+            current = bounded.find((entry) => {
+                if (!isRecord(entry))
+                    return false;
+                const segmentKind = typeof segment;
+                if (entry.selectorKind === segmentKind)
+                    return entry.selectorValue === segment;
+                return entry.selectorKind === undefined && segmentKind === "string" && entry.name === segment;
+            });
+            const body = isRecord(response.body) ? response.body : {};
+            if (!current)
+                return { selector, status: body.truncated === true || all.length > bounded.length ? "truncated" : "missing" };
+            if (depthIndex === selector.path.length - 1) {
+                return { selector, status: "found", variable: this.formatVariable(current, depthIndex + 1) };
+            }
+            if (!isRecord(current) || !Number.isInteger(current.variablesReference) || Number(current.variablesReference) < 1) {
+                return { selector, status: "missing" };
+            }
+            reference = Number(current.variablesReference);
+        }
+        return { selector, status: "missing" };
+    }
+    async requestVariables(debuggerClient, argumentsValue) {
+        return debuggerClient.request("variables", argumentsValue);
+    }
+    projectSourcePath(absolutePath) {
+        if (absolutePath.startsWith("res://")) {
+            if (absolutePath.toLowerCase().startsWith("res://addons/godot_mcp/"))
+                return undefined;
+            return absolutePath;
+        }
+        const projectRelative = relative(this.dependencies.project.rootRealPath, absolutePath);
+        if (projectRelative === "" || projectRelative === ".." || projectRelative.startsWith(`..${sep}`) || isAbsolute(projectRelative))
+            return undefined;
+        return `res://${projectRelative.split(sep).join("/")}`;
+    }
+    capture(input) {
+        return this.runExclusive(() => this.captureExclusive(input));
+    }
+    input(input) {
+        return this.runExclusive(() => this.inputExclusive(input));
+    }
+    async inputExclusive(input) {
+        this.assertHandle(input.handle);
+        const timeoutMs = input.operation === "sequence" || input.operation === "replay"
+            ? input.timeoutMs + 1_000
+            : undefined;
+        const raw = await this.dependencies.command("input", { handle: input.handle, input }, timeoutMs);
+        const result = InputOperationResultSchema.parse(raw);
+        if (result.receipt.handle.runId !== input.handle.runId ||
+            result.receipt.handle.generation !== input.handle.generation ||
+            result.receipt.operation !== input.operation)
+            throw runtimeError("GODOT_RUNTIME_ERROR", "Runtime input receipt identity does not match the request");
+        const events = input.operation === "record_stop" ? result.trace.events : inputTraceEvents(input);
+        const expectedDeterministic = input.operation === "replay" || (input.operation === "sequence" && input.mode === "deterministic");
+        const recordingMismatch = input.operation === "record_start"
+            ? !result.receipt.recording
+            : input.operation === "record_stop" && result.receipt.recording;
+        const eventReceiptsMatch = result.receipt.events.every((eventReceipt, index) => {
+            const event = events[index];
+            return event !== undefined &&
+                eventReceipt.index === index &&
+                eventReceipt.kind === event.event.type &&
+                eventReceipt.scheduledFrame === event.frameOffset;
+        });
+        if (result.receipt.eventCount !== events.length ||
+            result.receipt.deliveredCount !== events.length ||
+            result.receipt.events.length !== events.length ||
+            result.receipt.deterministic !== expectedDeterministic ||
+            recordingMismatch ||
+            result.receipt.traceSha256 !== traceSha256({ schemaVersion: 1, events }) ||
+            !eventReceiptsMatch)
+            throw runtimeError("GODOT_RUNTIME_ERROR", "Runtime input receipt does not match the requested trace");
+        return result;
+    }
+    async captureExclusive(input) {
+        this.assertHandle(input.handle);
+        if (!this.dependencies.capture)
+            throw runtimeError("GODOT_RUNTIME_ERROR", "Runtime capture transport is unavailable");
+        const frames = [];
+        for (let frameIndex = 0; frameIndex < input.frameCount; frameIndex += 1) {
+            const response = await this.dependencies.capture({
+                operation: "capture",
+                handle: input.handle,
+                maxWidth: input.maxWidth,
+                maxHeight: input.maxHeight,
+                frameIndex,
+                waitFrames: frameIndex === 0 ? 0 : input.intervalFrames,
+                advancePaused: input.advancePaused,
+            }, 15_000);
+            if (!response.binary || response.binarySha256 !== response.data.sha256) {
+                throw runtimeError("GODOT_RUNTIME_ERROR", "Runtime capture omitted verified PNG bytes");
+            }
+            frames.push({ data: response.binary, metadata: response.data });
+        }
+        return { frames };
+    }
+    close() {
+        this.closed = true;
+        if (!this.closePromise) {
+            const activeClose = this.disconnect();
+            this.closePromise = activeClose;
+            void activeClose.catch(() => {
+                if (this.closePromise === activeClose)
+                    this.closePromise = undefined;
+            });
+        }
+        return this.closePromise;
+    }
+    disconnect() {
+        if (this.disconnectPromise)
+            return this.disconnectPromise;
+        this.lifecycleEpoch += 1;
+        const activeDisconnect = (async () => {
+            await this.launchPromise?.catch(() => undefined);
+            await this.runExclusive(() => this.cleanup());
+        })();
+        this.disconnectPromise = activeDisconnect;
+        void activeDisconnect.finally(() => {
+            if (this.disconnectPromise === activeDisconnect)
+                this.disconnectPromise = undefined;
+        }).catch(() => undefined);
+        return activeDisconnect;
+    }
+    assertHandle(handle) {
+        this.assertHandleIdentity(handle);
+        if (!["running", "paused"].includes(this.state))
+            throw runtimeError("CONFLICT", "Runtime is not controllable in its current state");
+    }
+    assertHandleIdentity(handle) {
+        if (!this.handle || handle.runId !== this.handle.runId || handle.generation !== this.handle.generation) {
+            throw runtimeError("STALE_HANDLE", "Runtime handle is stale");
+        }
+    }
+    runExclusive(operation) {
+        const result = this.operationTail.then(operation);
+        this.operationTail = result.then(() => undefined, () => undefined);
+        return result;
+    }
+    assertLaunchCurrent(epoch) {
+        if (this.closed || epoch !== this.lifecycleEpoch) {
+            throw runtimeError("CONFLICT", "Runtime launch was cancelled by shutdown");
+        }
+    }
+    async stopProcess() {
+        if (!this.process || this.processStopped)
+            return;
+        const ownedProcess = this.process;
+        this.processStopped = true;
+        try {
+            await ownedProcess.stop();
+        }
+        catch (error) {
+            if (this.process === ownedProcess)
+                this.processStopped = false;
+            throw error;
+        }
+    }
+    async cleanup() {
+        if (this.cleanupPromise)
+            return this.cleanupPromise;
+        const activeCleanup = (async () => {
+            this.opaqueProfileId = null;
+            this.debuggerSessionId = null;
+            let cleanupError;
+            try {
+                await this.cleanupDebuggerClient();
+            }
+            catch (error) {
+                cleanupError = error;
+            }
+            if (this.descriptor) {
+                try {
+                    await this.descriptor.cleanup();
+                    this.descriptor = null;
+                }
+                catch (error) {
+                    cleanupError ??= error;
+                }
+            }
+            try {
+                await this.stopProcess();
+            }
+            catch (error) {
+                cleanupError ??= error;
+            }
+            await this.cleanupDebugger(false);
+            if (cleanupError) {
+                this.state = "failed";
+                throw cleanupError;
+            }
+            if (!["stopped", "idle"].includes(this.state))
+                this.state = "stopped";
+        })();
+        this.cleanupPromise = activeCleanup;
+        try {
+            await activeCleanup;
+        }
+        finally {
+            if (this.cleanupPromise === activeCleanup)
+                this.cleanupPromise = undefined;
+        }
+    }
+    async cleanupDebuggerClient() {
+        const debuggerClient = this.debuggerClient;
+        this.debuggerClient = null;
+        this.debugTokens.clear();
+        const sources = [...this.breakpointSources.keys()];
+        this.breakpointSources.clear();
+        if (!debuggerClient)
+            return;
+        let cleanupError;
+        for (const absolutePath of sources) {
+            try {
+                await debuggerClient.request("setBreakpoints", {
+                    source: { name: absolutePath.split(sep).at(-1), path: absolutePath },
+                    breakpoints: [],
+                }, 2_000);
+            }
+            catch (error) {
+                if (!isTerminalDebuggerCleanupError(error))
+                    cleanupError ??= error;
+            }
+        }
+        try {
+            await debuggerClient.request("disconnect", { terminateDebuggee: false }, 2_000);
+        }
+        catch (error) {
+            if (!isTerminalDebuggerCleanupError(error))
+                cleanupError ??= error;
+        }
+        await debuggerClient.close().catch((error) => { cleanupError ??= error; });
+        if (cleanupError)
+            throw cleanupError;
+    }
+    async cleanupDebugger(required) {
+        if (this.debuggerCleaned)
+            return;
+        if (!this.dependencies.cleanup) {
+            this.debuggerCleaned = true;
+            return;
+        }
+        try {
+            await this.dependencies.cleanup();
+            this.debuggerCleaned = true;
+        }
+        catch (error) {
+            if (required)
+                throw error;
+        }
+    }
+    onProcessExit(process) {
+        if (this.process !== process || this.processStopped)
+            return;
+        this.processStopped = true;
+        void this.runExclusive(() => this.cleanup()).catch(() => undefined);
+    }
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function bodyArray(response, key) {
+    if (!isRecord(response.body))
+        return [];
+    const value = response.body[key];
+    return Array.isArray(value) ? value : [];
+}
+function integerOr(value, fallback) {
+    return Number.isInteger(value) ? Number(value) : fallback;
+}
+function isPathInsideCaseInsensitive(parent, candidate) {
+    const relation = relative(parent.toLowerCase(), candidate.toLowerCase());
+    return relation === "" || (relation !== ".." && !relation.startsWith(`..${sep}`) && !isAbsolute(relation));
+}
+function boundedText(value, fallback, maxLength) {
+    const text = typeof value === "string" ? value : fallback;
+    return text.slice(0, maxLength);
+}
+function truncateUtf8(text, maxBytes) {
+    if (Buffer.byteLength(text, "utf8") <= maxBytes)
+        return { text, truncated: false };
+    let result = "";
+    let bytes = 0;
+    for (const character of text) {
+        const characterBytes = Buffer.byteLength(character, "utf8");
+        if (bytes + characterBytes > maxBytes)
+            break;
+        result += character;
+        bytes += characterBytes;
+    }
+    return { text: result, truncated: true };
+}
+function projectDebugStop(event) {
+    const rawReason = event.reason.toLowerCase();
+    const reason = rawReason.includes("breakpoint")
+        ? "breakpoint"
+        : rawReason.includes("exception")
+            ? "exception"
+            : rawReason.includes("step")
+                ? "step"
+                : rawReason.includes("pause")
+                    ? "pause"
+                    : "unknown";
+    return DebugStopResultSchema.parse({ sequence: event.sequence, reason });
+}
+function normalizeDebugError(error) {
+    if (error instanceof GodotMcpException)
+        return error;
+    if (error instanceof DebugTokenStoreError)
+        return runtimeError("STALE_HANDLE", error.message);
+    if (error instanceof DebuggerClientError) {
+        switch (error.code) {
+            case "INVALID_REQUEST":
+                return runtimeError("INVALID_REQUEST", error.message);
+            case "TIMEOUT":
+                return runtimeError("TIMEOUT", error.message, true);
+            case "TRANSPORT_ERROR":
+                return runtimeError("TRANSPORT_ERROR", error.message, true);
+        }
+    }
+    return error instanceof Error ? error : new Error(String(error));
+}
+function isTerminalDebuggerCleanupError(error) {
+    return (error instanceof GodotMcpException && (error.code === "NOT_ATTACHED" || error.code === "TRANSPORT_ERROR")) ||
+        (error instanceof DebuggerClientError && error.code === "TRANSPORT_ERROR");
+}
+//# sourceMappingURL=runtimeService.js.map