@beremaran/godot-agent-loop 1.0.0

package/build/game-command-service.js

@@ -0,0 +1,49 @@
+import { createErrorResponse, convertCamelToSnakeCase, errorMessage, normalizeParameters } from './utils.js';
+/** Shared runtime command boundary for tools that control a running game. */
+export class GameCommandService {
+    processManager;
+    connection;
+    constructor(processManager, connection) {
+        this.processManager = processManager;
+        this.connection = connection;
+    }
+    hasActiveProcess() {
+        return this.processManager.activeProcess !== null;
+    }
+    isConnected() {
+        return this.connection.isConnected;
+    }
+    connectedProjectPath() {
+        return this.connection.connectedProjectPath;
+    }
+    readNewErrors(limit) {
+        return this.processManager.readNewErrors(limit);
+    }
+    readNewLogs(limit) {
+        return this.processManager.readNewLogs(limit);
+    }
+    send(command, params = {}, timeoutMs = 10000) {
+        return this.connection.send(command, params, timeoutMs);
+    }
+    /**
+     * Performs the common runtime checks and formats regular command responses.
+     * Parameter mapping remains in the domain handler, where each tool's
+     * request shape is explicit.
+     */
+    async execute(name, args, buildParams, timeoutMs) {
+        if (!this.hasActiveProcess())
+            return createErrorResponse('No active Godot process. Use run_project first.');
+        if (!this.isConnected())
+            return createErrorResponse('Not connected to game interaction server.');
+        const normalizedArgs = normalizeParameters((args || {}));
+        try {
+            const response = await this.send(name, convertCamelToSnakeCase(buildParams(normalizedArgs)), timeoutMs);
+            if ('error' in response)
+                return createErrorResponse(`${name} failed: ${response.error.message}`);
+            return { content: [{ type: 'text', text: JSON.stringify(response.result, null, 2) }] };
+        }
+        catch (error) {
+            return createErrorResponse(`${name} failed: ${errorMessage(error)}`);
+        }
+    }
+}

package/build/game-connection.js

@@ -0,0 +1,337 @@
+import { createConnection } from 'net';
+import { performance } from 'perf_hooks';
+import { AUTHORING_COMMANDS_CAPABILITY, CANCEL_METHOD, HANDSHAKE_METHOD, PRIVILEGED_RUNTIME_CAPABILITY, PRIVILEGED_RUNTIME_COMMANDS, PRIVILEGED_RUNTIME_COMMAND_GROUPS, RUNTIME_CAPABILITIES, RUNTIME_PROTOCOL_VERSION, SESSION_AUTHENTICATION_CAPABILITY, commandMethod, isAuthoringCommand, isHandshakeResult, isJsonRpcResponse, isSessionCommand, privilegedGroupCapability } from './runtime-protocol.js';
+/** Owns the newline-delimited JSON-RPC 2.0 request lifecycle for a running Godot game. */
+export class GameConnection {
+    socket = null;
+    connected = false;
+    responseBuffer = '';
+    pendingRequests = new Map();
+    projectPath = null;
+    interactionServerInjectedByUs = false;
+    nextRequestId = 1;
+    port;
+    host;
+    initialDelayMs;
+    retryDelayMs;
+    maxAttempts;
+    log;
+    allowPrivilegedCommands;
+    allowedPrivilegedGroups;
+    authSecret;
+    onLifecycleEvent;
+    runtimeCapabilities = [];
+    connectionGeneration = 0;
+    connectingSocket = null;
+    pendingDelay = null;
+    constructor(options = {}) {
+        this.port = options.port ?? 9090;
+        this.host = options.host ?? '127.0.0.1';
+        this.initialDelayMs = options.initialDelayMs ?? 2000;
+        this.retryDelayMs = options.retryDelayMs ?? 500;
+        // Cold editor imports and shader compilation can exceed the old seven-second
+        // connection window on fresh CI machines. Keep retrying for roughly 90s,
+        // while connect() still aborts immediately when the process exits.
+        this.maxAttempts = options.maxAttempts ?? 180;
+        this.log = options.log ?? (() => undefined);
+        this.allowPrivilegedCommands = options.allowPrivilegedCommands ?? false;
+        this.allowedPrivilegedGroups = new Set(options.allowedPrivilegedGroups ?? []);
+        this.authSecret = options.authSecret;
+        this.onLifecycleEvent = options.onLifecycleEvent ?? (() => undefined);
+    }
+    get interactionPort() { return this.port; }
+    get isConnected() { return this.connected; }
+    get connectedProjectPath() { return this.projectPath; }
+    supportsCapability(capability) { return this.runtimeCapabilities.includes(capability); }
+    /** Records whether this server added the interaction autoload for the active project. */
+    recordInteractionServerInstallation(installed) {
+        this.interactionServerInjectedByUs = installed;
+    }
+    /** Returns and clears ownership so removal is performed at most once. */
+    consumeInteractionServerOwnership() {
+        const ownedByMcp = this.interactionServerInjectedByUs;
+        this.interactionServerInjectedByUs = false;
+        return ownedByMcp;
+    }
+    /** Clears the project association after its interaction server has been removed. */
+    clearConnectedProject() {
+        this.projectPath = null;
+    }
+    async connect(projectPath, isProcessActive) {
+        const generation = ++this.connectionGeneration;
+        this.cancelPendingDelay();
+        this.destroySocket();
+        this.connected = false;
+        this.responseBuffer = '';
+        this.rejectAllPending(this.connectionError(null, 'Connection superseded'));
+        this.projectPath = projectPath;
+        if (!await this.delay(this.initialDelayMs, generation))
+            return;
+        for (let attempt = 1; attempt <= this.maxAttempts; attempt++) {
+            if (!this.isCurrentGeneration(generation))
+                return;
+            if (!isProcessActive()) {
+                this.logEvent('connection_aborted', { reason: 'process_not_running' });
+                return;
+            }
+            try {
+                const connected = await this.connectOnce(attempt, generation);
+                if (!connected || !this.isCurrentGeneration(generation))
+                    return;
+                return;
+            }
+            catch {
+                if (!this.isCurrentGeneration(generation))
+                    return;
+                this.logEvent('connection_retry', {
+                    attempt, max_attempts: this.maxAttempts, retry_delay_ms: this.retryDelayMs,
+                });
+                if (!await this.delay(this.retryDelayMs, generation))
+                    return;
+            }
+        }
+        if (this.isCurrentGeneration(generation)) {
+            console.error(JSON.stringify({
+                component: 'godot-agent-loop-server', event: 'connection_failed', attempts: this.maxAttempts,
+            }));
+        }
+    }
+    disconnect() {
+        this.connectionGeneration++;
+        this.cancelPendingDelay();
+        this.destroySocket();
+        this.connected = false;
+        this.responseBuffer = '';
+        this.runtimeCapabilities = [];
+        this.rejectAllPending(this.connectionError(null, 'Disconnected'));
+    }
+    rejectAllPending(response) {
+        for (const resolver of this.pendingRequests.values())
+            resolver(response);
+        this.pendingRequests.clear();
+    }
+    resolveResponse(parsed) {
+        if (this.pendingRequests.size === 0 || !isJsonRpcResponse(parsed))
+            return;
+        if (typeof parsed.id !== 'number' || !this.pendingRequests.has(parsed.id))
+            return;
+        const resolver = this.pendingRequests.get(parsed.id);
+        this.pendingRequests.delete(parsed.id);
+        resolver(parsed);
+    }
+    async send(command, params = {}, timeoutMs = 10000) {
+        if (!isSessionCommand(command))
+            throw new Error(`'${command}' is not a command in the published session contract`);
+        if (isAuthoringCommand(command) && !this.runtimeCapabilities.includes(AUTHORING_COMMANDS_CAPABILITY)) {
+            throw new Error(`runtime does not expose the harness-owned ${AUTHORING_COMMANDS_CAPABILITY} capability`);
+        }
+        const isPrivileged = PRIVILEGED_RUNTIME_COMMANDS.includes(command);
+        if (isPrivileged) {
+            const privilegedCommand = command;
+            const group = PRIVILEGED_RUNTIME_COMMAND_GROUPS[privilegedCommand];
+            if (!this.allowPrivilegedCommands && !this.allowedPrivilegedGroups.has(group)) {
+                throw new Error(`Privileged runtime command '${command}' is disabled. Enable group '${group}' with GODOT_MCP_PRIVILEGED_GROUPS or opt in to all privileged commands.`);
+            }
+            const capability = privilegedGroupCapability(group);
+            if (!this.runtimeCapabilities.includes(PRIVILEGED_RUNTIME_CAPABILITY)
+                && !this.runtimeCapabilities.includes(capability)) {
+                throw new Error(`runtime did not authorize privileged group '${group}'`);
+            }
+        }
+        if (!this.connected || !this.socket)
+            throw new Error('Not connected to game interaction server. Is the game running?');
+        return this.request(commandMethod(command), params, timeoutMs);
+    }
+    request(method, params, timeoutMs) {
+        const id = this.nextRequestId++;
+        const isCommand = method.startsWith('godot.runtime.')
+            && method !== HANDSHAKE_METHOD && method !== CANCEL_METHOD;
+        const correlationId = isCommand ? `mcp_${id}` : undefined;
+        const wireParams = correlationId === undefined ? params : { ...params, _mcp_correlation_id: correlationId };
+        const payload = JSON.stringify({ jsonrpc: '2.0', method, params: wireParams, id }) + '\n';
+        const startedAt = performance.now();
+        const command = method.slice('godot.runtime.'.length);
+        const target = requestTarget(params);
+        if (correlationId !== undefined) {
+            this.logEvent('request_started', { correlation_id: correlationId, method });
+            this.emitLifecycle({ event: 'request_started', correlation_id: correlationId, command, target });
+        }
+        return new Promise((resolve, reject) => {
+            const timeout = setTimeout(() => {
+                if (!this.pendingRequests.delete(id))
+                    return;
+                this.requestCancellation(id);
+                if (correlationId !== undefined) {
+                    const durationMs = Math.max(0, Math.round(performance.now() - startedAt));
+                    this.logEvent('request_timed_out', { correlation_id: correlationId, method, timeout_ms: timeoutMs, duration_ms: durationMs });
+                    this.emitLifecycle({
+                        event: 'request_timed_out', correlation_id: correlationId, command, target,
+                        outcome: 'timeout', duration_ms: durationMs,
+                    });
+                }
+                reject(new Error(`Game request '${method}' timed out after ${timeoutMs / 1000}s`));
+            }, timeoutMs);
+            this.pendingRequests.set(id, response => {
+                clearTimeout(timeout);
+                if (correlationId !== undefined) {
+                    const durationMs = Math.max(0, Math.round(performance.now() - startedAt));
+                    const outcome = 'error' in response ? 'error' : 'success';
+                    this.logEvent('request_finished', {
+                        correlation_id: correlationId, method,
+                        outcome, duration_ms: durationMs,
+                        ...('error' in response ? { error_code: response.error.code } : {}),
+                    });
+                    this.emitLifecycle({
+                        event: 'request_finished', correlation_id: correlationId, command, target,
+                        outcome, duration_ms: durationMs,
+                        ...('error' in response ? { error_code: response.error.code } : {}),
+                    });
+                }
+                resolve(response);
+            });
+            this.socket.write(payload);
+        });
+    }
+    connectOnce(attempt, generation) {
+        return new Promise((resolve, reject) => {
+            const socket = createConnection({ host: this.host, port: this.port }, () => {
+                if (!this.isCurrentGeneration(generation)) {
+                    socket.destroy();
+                    resolve(false);
+                    return;
+                }
+                this.connectingSocket = null;
+                this.socket = socket;
+                this.connected = true;
+                this.responseBuffer = '';
+                this.runtimeCapabilities = [];
+                this.pendingRequests.clear();
+                this.logEvent('connection_opened', { attempt });
+                socket.on('data', data => { if (this.isCurrentSocket(socket, generation))
+                    this.handleData(data); });
+                socket.on('close', () => {
+                    this.logEvent('connection_closed');
+                    if (!this.isCurrentSocket(socket, generation))
+                        return;
+                    this.connected = false;
+                    this.socket = null;
+                    this.rejectAllPending(this.connectionError(null, 'Connection closed'));
+                });
+                socket.on('error', () => { this.logEvent('connection_error'); });
+                this.negotiateProtocol().then(() => {
+                    resolve(true);
+                }).catch(error => {
+                    socket.destroy();
+                    reject(error instanceof Error ? error : new Error(String(error)));
+                });
+            });
+            this.connectingSocket = socket;
+            socket.on('error', error => { if (this.isCurrentGeneration(generation))
+                reject(error);
+            else
+                resolve(false); });
+            socket.on('close', () => { if (!this.isCurrentGeneration(generation))
+                resolve(false); });
+        });
+    }
+    async negotiateProtocol() {
+        const requestedCapabilities = [...RUNTIME_CAPABILITIES];
+        if (this.authSecret !== undefined)
+            requestedCapabilities.push(SESSION_AUTHENTICATION_CAPABILITY);
+        if (this.allowPrivilegedCommands)
+            requestedCapabilities.push(PRIVILEGED_RUNTIME_CAPABILITY);
+        for (const group of this.allowedPrivilegedGroups)
+            requestedCapabilities.push(privilegedGroupCapability(group));
+        const response = await this.request(HANDSHAKE_METHOD, {
+            protocolVersion: RUNTIME_PROTOCOL_VERSION,
+            capabilities: requestedCapabilities,
+            ...(this.authSecret === undefined ? {} : { secret: this.authSecret }),
+        }, 5000);
+        if ('error' in response)
+            throw new Error(response.error.message);
+        if (!isHandshakeResult(response.result))
+            throw new Error('invalid handshake result');
+        const handshake = response.result;
+        if (handshake.protocolVersion !== RUNTIME_PROTOCOL_VERSION)
+            throw new Error(`unsupported runtime protocol version ${handshake.protocolVersion}`);
+        const missing = RUNTIME_CAPABILITIES.filter(capability => !handshake.capabilities.includes(capability));
+        if (missing.length > 0)
+            throw new Error(`runtime does not support ${missing.join(', ')}`);
+        if (this.authSecret !== undefined && !handshake.capabilities.includes(SESSION_AUTHENTICATION_CAPABILITY)) {
+            throw new Error('runtime did not confirm session authentication');
+        }
+        if (this.allowPrivilegedCommands && !handshake.capabilities.includes(PRIVILEGED_RUNTIME_CAPABILITY)) {
+            throw new Error(`runtime does not support privileged runtime commands; enable ${PRIVILEGED_RUNTIME_CAPABILITY} in the Godot interaction server`);
+        }
+        for (const group of this.allowedPrivilegedGroups) {
+            if (!handshake.capabilities.includes(PRIVILEGED_RUNTIME_CAPABILITY)
+                && !handshake.capabilities.includes(privilegedGroupCapability(group))) {
+                throw new Error(`runtime does not support privileged group '${group}'`);
+            }
+        }
+        this.runtimeCapabilities = handshake.capabilities;
+    }
+    isCurrentGeneration(generation) { return generation === this.connectionGeneration; }
+    isCurrentSocket(socket, generation) { return this.isCurrentGeneration(generation) && this.socket === socket; }
+    delay(milliseconds, generation) {
+        return new Promise(resolve => {
+            const timer = setTimeout(() => { this.pendingDelay = null; resolve(this.isCurrentGeneration(generation)); }, milliseconds);
+            this.pendingDelay = { timer, resolve };
+        });
+    }
+    cancelPendingDelay() {
+        if (this.pendingDelay !== null) {
+            clearTimeout(this.pendingDelay.timer);
+            this.pendingDelay.resolve(false);
+            this.pendingDelay = null;
+        }
+    }
+    destroySocket() {
+        const sockets = [this.socket, this.connectingSocket];
+        this.socket = null;
+        this.connectingSocket = null;
+        for (const socket of sockets)
+            socket?.destroy();
+    }
+    /** Best-effort cooperative cancellation; servers acknowledge it separately. */
+    requestCancellation(requestId) {
+        if (!this.connected || !this.socket)
+            return;
+        const id = this.nextRequestId++;
+        this.socket.write(`${JSON.stringify({ jsonrpc: '2.0', method: CANCEL_METHOD, params: { request_id: requestId }, id })}\n`);
+    }
+    handleData(data) {
+        this.responseBuffer += data.toString();
+        while (this.responseBuffer.includes('\n')) {
+            const newlinePos = this.responseBuffer.indexOf('\n');
+            const line = this.responseBuffer.substring(0, newlinePos).trim();
+            this.responseBuffer = this.responseBuffer.substring(newlinePos + 1);
+            if (!line)
+                continue;
+            try {
+                this.resolveResponse(JSON.parse(line));
+            }
+            catch {
+                this.logEvent('response_parse_failed', { response_bytes: Buffer.byteLength(line) });
+            }
+        }
+    }
+    logEvent(event, details = {}) {
+        this.log(JSON.stringify({ component: 'godot-agent-loop-server', event, ...details }));
+    }
+    emitLifecycle(event) {
+        try {
+            this.onLifecycleEvent(event);
+        }
+        catch { /* Observation must never break command delivery. */ }
+    }
+    connectionError(id, message) { return { jsonrpc: '2.0', id, error: { code: -32000, message } }; }
+}
+function requestTarget(params) {
+    for (const key of ['node_path', 'scene_path', 'resource_path', 'parent_path', 'group', 'action']) {
+        const value = params[key];
+        if (typeof value === 'string' && value.length > 0)
+            return value.slice(0, 256);
+    }
+    return 'game';
+}

package/build/godot-executable.js

@@ -0,0 +1,156 @@
+import { execFile } from 'child_process';
+import { existsSync } from 'fs';
+import { normalize } from 'path';
+import { promisify } from 'util';
+import { GODOT_VERSION_OPTIONS } from './godot-subprocess.js';
+const execFileAsync = promisify(execFile);
+/**
+ * Resolves and validates the executable used by Godot-facing services.
+ *
+ * Keeping this mutable state in one service prevents tool handlers from
+ * coordinating a pair of get-path/detect-path callbacks themselves.
+ */
+export class GodotExecutableService {
+    validator;
+    strictPathValidation;
+    logDebug;
+    godotPath = null;
+    constructor(validator, strictPathValidation, logDebug = () => undefined) {
+        this.validator = validator;
+        this.strictPathValidation = strictPathValidation;
+        this.logDebug = logDebug;
+    }
+    get path() {
+        return this.godotPath;
+    }
+    set path(path) {
+        this.godotPath = path;
+    }
+    isValidSync(path) {
+        return this.validator.isValidSync(path);
+    }
+    isValid(path) {
+        return this.validator.isValid(path);
+    }
+    async detect() {
+        this.godotPath = await detectGodotExecutablePath({
+            currentPath: this.godotPath,
+            strictPathValidation: this.strictPathValidation,
+            isValid: path => this.isValid(path),
+            logDebug: this.logDebug,
+        });
+        return this.godotPath;
+    }
+    async requirePath() {
+        if (!this.godotPath)
+            await this.detect();
+        return this.godotPath;
+    }
+    async setPath(path) {
+        const normalizedPath = normalize(path);
+        if (!await this.isValid(normalizedPath))
+            return false;
+        this.godotPath = normalizedPath;
+        this.logDebug(`Godot path set to: ${normalizedPath}`);
+        return true;
+    }
+}
+export class GodotExecutableValidator {
+    logDebug;
+    validatedPaths = new Map();
+    constructor(logDebug = () => undefined) {
+        this.logDebug = logDebug;
+    }
+    isValidSync(path) {
+        try {
+            this.logDebug(`Quick-validating Godot path: ${path}`);
+            return path === 'godot' || existsSync(path);
+        }
+        catch (error) {
+            this.logDebug(`Invalid Godot path: ${path}, error: ${error}`);
+            return false;
+        }
+    }
+    async isValid(path) {
+        const cached = this.validatedPaths.get(path);
+        if (cached !== undefined)
+            return cached;
+        try {
+            this.logDebug(`Validating Godot path: ${path}`);
+            if (path !== 'godot' && !existsSync(path)) {
+                this.logDebug(`Path does not exist: ${path}`);
+                this.validatedPaths.set(path, false);
+                return false;
+            }
+            await execFileAsync(path, ['--version'], GODOT_VERSION_OPTIONS);
+            this.logDebug(`Valid Godot path: ${path}`);
+            this.validatedPaths.set(path, true);
+            return true;
+        }
+        catch (error) {
+            this.logDebug(`Invalid Godot path: ${path}, error: ${error}`);
+            this.validatedPaths.set(path, false);
+            return false;
+        }
+    }
+}
+export async function detectGodotExecutablePath(options) {
+    const logDebug = options.logDebug ?? (() => undefined);
+    if (options.currentPath && await options.isValid(options.currentPath)) {
+        logDebug(`Using existing Godot path: ${options.currentPath}`);
+        return options.currentPath;
+    }
+    if (process.env.GODOT_PATH) {
+        const environmentPath = normalize(process.env.GODOT_PATH);
+        logDebug(`Checking GODOT_PATH environment variable: ${environmentPath}`);
+        if (await options.isValid(environmentPath)) {
+            logDebug(`Using Godot path from environment: ${environmentPath}`);
+            return environmentPath;
+        }
+        // An explicit executable selection is authoritative. Falling through to a
+        // different auto-detected engine makes a stale or deliberately invalid
+        // configuration silently target the wrong binary. GodotServer.run() applies
+        // the strict/compatibility policy after this returns: strict mode exits,
+        // while compatibility mode keeps structured tool failures available.
+        logDebug(`GODOT_PATH environment variable is invalid: ${environmentPath}`);
+        return environmentPath;
+    }
+    const platform = process.platform;
+    logDebug(`Auto-detecting Godot path for platform: ${platform}`);
+    const possiblePaths = getCandidatePaths(platform);
+    for (const candidate of possiblePaths) {
+        const normalizedPath = normalize(candidate);
+        if (await options.isValid(normalizedPath)) {
+            logDebug(`Found Godot at: ${normalizedPath}`);
+            return normalizedPath;
+        }
+    }
+    logDebug(`Warning: Could not find Godot in common locations for ${platform}`);
+    console.error(`[SERVER] Could not find Godot in common locations for ${platform}`);
+    console.error("[SERVER] Set GODOT_PATH=/path/to/godot environment variable or pass { godotPath: '/path/to/godot' } in the config to specify the correct path.");
+    if (options.strictPathValidation) {
+        throw new Error('Could not find a valid Godot executable. Set GODOT_PATH or provide a valid path in config.');
+    }
+    const fallback = normalize(platform === 'win32'
+        ? 'C:\\Program Files\\Godot\\Godot.exe'
+        : platform === 'darwin'
+            ? '/Applications/Godot.app/Contents/MacOS/Godot'
+            : '/usr/bin/godot');
+    logDebug(`Using default path: ${fallback}, but this may not work.`);
+    console.error(`[SERVER] Using default path: ${fallback}, but this may not work.`);
+    console.error('[SERVER] This fallback behavior will be removed in a future version. Set strictPathValidation: true to opt-in to the new behavior.');
+    return fallback;
+}
+function getCandidatePaths(platform) {
+    const paths = ['godot'];
+    if (platform === 'darwin') {
+        paths.push('/Applications/Godot.app/Contents/MacOS/Godot', '/Applications/Godot_4.app/Contents/MacOS/Godot', `${process.env.HOME}/Applications/Godot.app/Contents/MacOS/Godot`, `${process.env.HOME}/Applications/Godot_4.app/Contents/MacOS/Godot`, `${process.env.HOME}/Library/Application Support/Steam/steamapps/common/Godot Engine/Godot.app/Contents/MacOS/Godot`);
+    }
+    else if (platform === 'win32') {
+        paths.push('C:\\Program Files\\Godot\\Godot.exe', 'C:\\Program Files (x86)\\Godot\\Godot.exe', 'C:\\Program Files\\Godot_4\\Godot.exe', 'C:\\Program Files (x86)\\Godot_4\\Godot.exe', `${process.env.USERPROFILE}\\Godot\\Godot.exe`);
+    }
+    else if (platform === 'linux') {
+        paths.push('/usr/bin/godot', '/usr/local/bin/godot', '/snap/bin/godot', `${process.env.HOME}/.local/bin/godot`);
+    }
+    return paths;
+}

package/build/godot-process-manager.js

@@ -0,0 +1,112 @@
+import { spawn } from 'child_process';
+import { GODOT_GRACEFUL_SHUTDOWN_TIMEOUT_MS, GODOT_PROCESS_LOG_LINE_LIMIT, } from './godot-subprocess.js';
+/** Owns the active Godot child process and its captured output. */
+export class GodotProcessManager {
+    log;
+    logLineLimit;
+    gracefulShutdownTimeoutMs;
+    spawnProcess;
+    activeProcess = null;
+    lastErrorIndex = 0;
+    lastLogIndex = 0;
+    constructor(log = () => undefined, logLineLimit = GODOT_PROCESS_LOG_LINE_LIMIT, gracefulShutdownTimeoutMs = GODOT_GRACEFUL_SHUTDOWN_TIMEOUT_MS, spawnProcess = spawn) {
+        this.log = log;
+        this.logLineLimit = logLineLimit;
+        this.gracefulShutdownTimeoutMs = gracefulShutdownTimeoutMs;
+        this.spawnProcess = spawnProcess;
+    }
+    get active() {
+        return this.activeProcess !== null;
+    }
+    start(options) {
+        const child = this.spawnProcess(options.executable, options.args, {
+            stdio: 'pipe',
+            env: options.env === undefined ? undefined : { ...process.env, ...options.env },
+        });
+        const record = { process: child, output: [], errors: [] };
+        this.activeProcess = record;
+        this.resetCursors();
+        child.stdout?.on('data', (data) => {
+            const lines = data.toString().split('\n');
+            this.appendLines(record.output, lines, 'logs');
+            for (const line of lines)
+                if (line.trim())
+                    this.log(`[Godot stdout] ${line}`);
+        });
+        child.stderr?.on('data', (data) => {
+            const lines = data.toString().split('\n');
+            this.appendLines(record.errors, lines, 'errors');
+            for (const line of lines)
+                if (line.trim())
+                    this.log(`[Godot stderr] ${line}`);
+        });
+        child.on('exit', (code) => {
+            this.log(`Godot process exited with code ${code}`);
+            if (this.activeProcess?.process === child)
+                this.activeProcess = null;
+            options.onExit?.(code);
+        });
+        child.on('error', (error) => {
+            if (this.activeProcess?.process === child)
+                this.activeProcess = null;
+            options.onError?.(error);
+        });
+        return record;
+    }
+    stop() {
+        const record = this.activeProcess;
+        if (!record)
+            return null;
+        this.activeProcess = null;
+        this.resetCursors();
+        let exited = false;
+        const forceKill = setTimeout(() => {
+            if (!exited) {
+                this.log(`Godot process did not exit after ${this.gracefulShutdownTimeoutMs}ms; forcing termination`);
+                record.process.kill('SIGKILL');
+            }
+        }, this.gracefulShutdownTimeoutMs);
+        if (typeof record.process.on === 'function') {
+            record.process.on('exit', () => {
+                exited = true;
+                clearTimeout(forceKill);
+            });
+        }
+        record.process.kill('SIGTERM');
+        return record;
+    }
+    seedActiveProcess(process) {
+        this.activeProcess = process;
+    }
+    readNewErrors(limit = 1000) {
+        if (!this.activeProcess)
+            return { items: [], remaining: 0 };
+        const end = Math.min(this.lastErrorIndex + limit, this.activeProcess.errors.length);
+        const items = this.activeProcess.errors.slice(this.lastErrorIndex, end);
+        this.lastErrorIndex = end;
+        return { items, remaining: this.activeProcess.errors.length - end };
+    }
+    readNewLogs(limit = 1000) {
+        if (!this.activeProcess)
+            return { items: [], remaining: 0 };
+        const end = Math.min(this.lastLogIndex + limit, this.activeProcess.output.length);
+        const items = this.activeProcess.output.slice(this.lastLogIndex, end);
+        this.lastLogIndex = end;
+        return { items, remaining: this.activeProcess.output.length - end };
+    }
+    resetCursors() {
+        this.lastErrorIndex = 0;
+        this.lastLogIndex = 0;
+    }
+    appendLines(target, lines, stream) {
+        target.push(...lines);
+        const excess = target.length - this.logLineLimit;
+        if (excess > 0) {
+            target.splice(0, excess);
+            if (stream === 'logs')
+                this.lastLogIndex = Math.max(0, this.lastLogIndex - excess);
+            else
+                this.lastErrorIndex = Math.max(0, this.lastErrorIndex - excess);
+        }
+    }
+}

package/build/godot-subprocess.js

@@ -0,0 +1,23 @@
+/** Shared resource limits for short-lived Godot CLI invocations. */
+export const GODOT_COMMAND_TIMEOUT_MS = 30_000;
+export const GODOT_VERSION_TIMEOUT_MS = 10_000;
+export const GODOT_EXPORT_TIMEOUT_MS = 120_000;
+export const GODOT_COMMAND_MAX_BUFFER_BYTES = 16 * 1024 * 1024;
+export const GODOT_COMMAND_OPTIONS = {
+    timeout: GODOT_COMMAND_TIMEOUT_MS,
+    maxBuffer: GODOT_COMMAND_MAX_BUFFER_BYTES,
+    encoding: 'utf8',
+};
+export const GODOT_VERSION_OPTIONS = {
+    timeout: GODOT_VERSION_TIMEOUT_MS,
+    maxBuffer: GODOT_COMMAND_MAX_BUFFER_BYTES,
+    encoding: 'utf8',
+};
+export const GODOT_EXPORT_OPTIONS = {
+    timeout: GODOT_EXPORT_TIMEOUT_MS,
+    maxBuffer: GODOT_COMMAND_MAX_BUFFER_BYTES,
+    encoding: 'utf8',
+};
+/** Long-running game processes retain only recent output to protect server memory. */
+export const GODOT_PROCESS_LOG_LINE_LIMIT = 1_000;
+export const GODOT_GRACEFUL_SHUTDOWN_TIMEOUT_MS = 5_000;