@beremaran/godot-agent-loop 1.0.1 → 1.1.0

package/build/tool-handlers/lifecycle-tool-handlers.js

@@ -4,15 +4,30 @@ import { existsSync } from 'fs';
 import { join } from 'path';
 import { execFile } from 'child_process';
 import { promisify } from 'util';
-import { createErrorResponse, errorMessage, normalizeParameters, validatePath } from '../utils.js';
+import { convertCamelToSnakeCase, createErrorResponse, errorMessage, normalizeParameters, validatePath } from '../utils.js';
 import { GODOT_VERSION_OPTIONS } from '../godot-subprocess.js';
-import { deterministicSessionArguments, deterministicSessionEnvironment } from '../session-timing.js';
+import { deterministicSessionArguments, deterministicSessionEnvironment, realtimeSessionArguments, realtimeSessionEnvironment, timingPolicy, } from '../session-timing.js';
 import { describeCatalogTool, searchToolCatalog } from '../tool-surface.js';
 const execFileAsync = promisify(execFile);
+const SCENARIO_INPUT_TOOLS = new Set([
+    'game_key_press', 'game_key_hold', 'game_key_release', 'game_click', 'game_mouse_move',
+    'game_scroll', 'game_mouse_drag', 'game_gamepad', 'game_input_action',
+]);
+const SCENARIO_OBSERVE_TOOLS = new Set([
+    'game_get_scene_tree', 'game_get_ui', 'game_get_node_info', 'game_get_property',
+    'game_get_errors', 'game_get_logs', 'game_get_camera', 'game_get_audio', 'game_performance',
+]);
+function waitSuccess(condition, startedAt, attempts, observed) {
+    return { satisfied: true, condition, elapsed_ms: Date.now() - startedAt, attempts, last_observed: observed };
+}
+function sameJson(left, right) {
+    return JSON.stringify(left) === JSON.stringify(right);
+}
 /** Implements editor launch, project runtime, and Godot version tools. */
 export class LifecycleToolHandlers {
     context;
     processGeneration = 0;
+    editorEnsureTails = new Map();
     constructor(context) {
         this.context = context;
     }
@@ -47,6 +62,47 @@ export class LifecycleToolHandlers {
         return createErrorResponse('action must be search, describe, or call.');
     }
     async handleLaunchEditor(args) {
+        return this.ensureEditor(normalizeParameters(args), true);
+    }
+    async handleEditorSession(args) {
+        args = normalizeParameters(args || {});
+        if (!args.projectPath || !['ensure', 'status', 'disconnect'].includes(args.action)) {
+            return createErrorResponse('projectPath and action ensure, status, or disconnect are required.');
+        }
+        if (!validatePath(args.projectPath) || !this.context.isPathAllowed(args.projectPath)) {
+            return createErrorResponse('Project path is outside the allowed roots');
+        }
+        if (!existsSync(join(args.projectPath, 'project.godot'))) {
+            return createErrorResponse(`Not a valid Godot project: ${args.projectPath}`);
+        }
+        if (args.action === 'disconnect') {
+            const session = this.context.disconnectEditorSession?.(args.projectPath);
+            if (!session)
+                return createErrorResponse('Editor session registry is unavailable.');
+            return this.editorSessionResponse(session);
+        }
+        if (args.action === 'status') {
+            const session = await this.context.getEditorSessionStatus?.(args.projectPath);
+            if (!session)
+                return createErrorResponse('Editor session registry is unavailable.');
+            return this.editorSessionResponse(session);
+        }
+        return this.ensureEditor(args, args.launchIfNeeded === true);
+    }
+    ensureEditor(args, launchIfNeeded) {
+        const projectPath = typeof args.projectPath === 'string' ? args.projectPath : '';
+        const existing = this.editorEnsureTails.get(projectPath);
+        if (existing)
+            return existing;
+        const pending = this.ensureEditorUnserialized(args, launchIfNeeded);
+        this.editorEnsureTails.set(projectPath, pending);
+        void pending.finally(() => {
+            if (this.editorEnsureTails.get(projectPath) === pending)
+                this.editorEnsureTails.delete(projectPath);
+        });
+        return pending;
+    }
+    async ensureEditorUnserialized(args, launchIfNeeded) {
         args = normalizeParameters(args);
         if (!args.projectPath)
             return createErrorResponse('Project path is required');
@@ -54,34 +110,59 @@ export class LifecycleToolHandlers {
             return createErrorResponse('Invalid project path');
         if (!this.context.isPathAllowed(args.projectPath))
             return createErrorResponse('Project path is outside the allowed roots');
+        if (!existsSync(join(args.projectPath, 'project.godot'))) {
+            return createErrorResponse(`Not a valid Godot project: ${args.projectPath}`);
+        }
         try {
+            const timeoutMs = Math.round((typeof args.timeoutSeconds === 'number' ? args.timeoutSeconds : 2) * 1_000);
+            const discovered = await this.context.ensureEditorSession?.(args.projectPath, timeoutMs);
+            if (discovered?.connected)
+                return this.editorSessionResponse({ ...discovered, reused: true, spawned: false });
+            if (!launchIfNeeded) {
+                return this.editorSessionResponse(discovered ?? {
+                    state: 'no_editor', project_path: args.projectPath, connected: false, reused: false, spawned: false,
+                    editor_pid: null, editor_start_identity: null, port: null, protocol_version: null,
+                    addon_version: null, godot_version: null, created_at: null,
+                    reason: 'No discoverable compatible editor. Install and enable the persistent addon, or retry with launchIfNeeded.',
+                });
+            }
             const godotPath = await this.requireGodotPath();
             if (!godotPath)
                 return createErrorResponse('Could not find a valid Godot executable path');
-            if (!existsSync(join(args.projectPath, 'project.godot')))
-                return createErrorResponse(`Not a valid Godot project: ${args.projectPath}`);
-            this.context.logDebug(`Launching Godot editor for project: ${args.projectPath}`);
+            this.context.logDebug(`No reusable editor found; launching Godot editor for project: ${args.projectPath}`);
             const editorPlugin = this.context.installEditorPlugin?.(args.projectPath);
             const editorArgs = ['-e', '--path', args.projectPath];
             const editorProcess = spawn(godotPath, editorArgs, {
                 stdio: 'pipe', env: { ...process.env, ...this.context.getRuntimeEnvironment(), ...(this.context.getEditorEnvironment?.() ?? {}) },
             });
             editorProcess.on('error', (err) => { console.error('Failed to start Godot editor:', err); });
-            const editorEnvironment = this.context.getEditorEnvironment?.() ?? {};
-            return { content: [{ type: 'text', text: JSON.stringify({
-                            launched: true,
-                            project_path: args.projectPath,
-                            editor_plugin: true,
-                            plugin_owned: editorPlugin?.owned ?? false,
-                            plugin_distribution: editorPlugin?.distribution ?? 'unavailable',
-                            editor_protocol_version: editorPlugin?.protocolVersion ?? null,
-                            editor_bridge_port: editorEnvironment.GODOT_MCP_EDITOR_PORT ?? null,
-                        }, null, 2) }] };
+            const attached = await this.context.ensureEditorSession?.(args.projectPath, 20_000);
+            if (!attached?.connected) {
+                return createErrorResponse(`Editor launched but bridge did not become ready: ${attached?.state ?? 'registry_unavailable'}${attached?.reason ? ` (${attached.reason})` : ''}`);
+            }
+            return this.editorSessionResponse({
+                ...attached,
+                reused: false,
+                spawned: true,
+                plugin_owned: editorPlugin?.owned ?? false,
+                plugin_distribution: editorPlugin?.distribution ?? 'unavailable',
+            });
         }
         catch (error) {
-            return createErrorResponse(`Failed to launch Godot editor: ${this.errorMessage(error)}`);
+            const message = this.errorMessage(error);
+            if (message.includes('protocol is incompatible')) {
+                return this.editorSessionResponse({
+                    state: 'addon_upgrade_restart_required', project_path: args.projectPath, connected: false,
+                    reused: false, spawned: false, editor_pid: null, editor_start_identity: null, port: null,
+                    protocol_version: null, addon_version: null, godot_version: null, created_at: null, reason: message,
+                });
+            }
+            return createErrorResponse(`Failed to ensure Godot editor: ${message}`);
         }
     }
+    editorSessionResponse(session) {
+        return { content: [{ type: 'text', text: JSON.stringify({ editor_session: session }, null, 2) }] };
+    }
     async handleEditorControl(args) {
         args = normalizeParameters(args || {});
         const allowed = ['inspect', 'select', 'save', 'reload', 'open_scene', 'set_property', 'rename_node', 'undo', 'redo'];
@@ -91,6 +172,9 @@ export class LifecycleToolHandlers {
         if (!validatePath(args.projectPath) || !this.context.isPathAllowed(args.projectPath)) {
             return createErrorResponse('Project path is outside the allowed roots');
         }
+        if (args.scenePath !== undefined && !this.isEditorPathAllowed(args.projectPath, args.scenePath)) {
+            return createErrorResponse('scenePath is outside the project root');
+        }
         const params = {};
         for (const key of ['nodePaths', 'scenePath', 'nodePath', 'property', 'value', 'name']) {
             if (args[key] !== undefined)
@@ -99,7 +183,7 @@ export class LifecycleToolHandlers {
         try {
             if (!this.context.sendEditorCommand)
                 return createErrorResponse('Editor bridge is not configured. Launch the editor through launch_editor first.');
-            const result = await this.context.sendEditorCommand(args.action, params, 15_000);
+            const result = await this.context.sendEditorCommand(args.projectPath, args.action, params, 15_000);
             if (result.error)
                 return createErrorResponse(`editor_control failed: ${typeof result.error === 'string' ? result.error : JSON.stringify(result.error)}`);
             return { content: [{ type: 'text', text: JSON.stringify({ project_path: args.projectPath, action: args.action, ...result }, null, 2) }] };
@@ -108,6 +192,56 @@ export class LifecycleToolHandlers {
             return createErrorResponse(`editor_control failed: ${this.errorMessage(error)}`);
         }
     }
+    async handleEditorTransaction(args) {
+        args = normalizeParameters(args || {});
+        if (!args.projectPath || !args.scenePath || !args.name || !Array.isArray(args.operations) || args.operations.length === 0) {
+            return createErrorResponse('projectPath, scenePath, name, and at least one operation are required.');
+        }
+        if (!validatePath(args.projectPath) || !this.context.isPathAllowed(args.projectPath)) {
+            return createErrorResponse('Project path is outside the allowed roots');
+        }
+        if (!this.isEditorPathAllowed(args.projectPath, args.scenePath)) {
+            return createErrorResponse('scenePath is outside the project root');
+        }
+        for (const [index, operation] of args.operations.entries()) {
+            if (!operation || typeof operation !== 'object')
+                continue;
+            for (const key of ['scenePath', 'scriptPath', 'resourcePath']) {
+                if (operation[key] !== undefined && !this.isEditorPathAllowed(args.projectPath, operation[key])) {
+                    return createErrorResponse(`operations[${index}].${key} is outside the project root`);
+                }
+            }
+        }
+        if (!this.context.sendEditorCommand)
+            return createErrorResponse('Editor session registry is unavailable.');
+        try {
+            const params = convertCamelToSnakeCase({
+                scenePath: args.scenePath,
+                name: args.name,
+                rootType: args.rootType,
+                operations: args.operations,
+                focusPath: args.focusPath,
+                save: args.save !== false,
+            });
+            const result = await this.context.sendEditorCommand(args.projectPath, 'transaction', params, 30_000);
+            if (result.error) {
+                return createErrorResponse(`editor_transaction failed: ${typeof result.error === 'string' ? result.error : JSON.stringify(result.error)}`);
+            }
+            const editorSession = await this.context.getEditorSessionStatus?.(args.projectPath);
+            return { content: [{ type: 'text', text: JSON.stringify({
+                            project_path: args.projectPath,
+                            backend: 'editor',
+                            editor_session: editorSession ?? null,
+                            sync_status: 'acknowledged',
+                            fallback_reason: null,
+                            observed_target_state: result.observed_target_state ?? null,
+                            ...result,
+                        }, null, 2) }] };
+        }
+        catch (error) {
+            return createErrorResponse(`editor_transaction failed: ${this.errorMessage(error)}`);
+        }
+    }
     async handleRunProject(args) {
         args = normalizeParameters(args);
         if (!args.projectPath)
@@ -148,33 +282,47 @@ export class LifecycleToolHandlers {
             // bad script hung the whole session. Errors still print with a full
             // backtrace without it, and the editor binary already runs projects as a
             // debug build.
-            const commandArgs = [...deterministicSessionArguments(), '--path', args.projectPath];
-            if (args.scene && (!this.context.isRelativePathAllowed || this.context.isRelativePathAllowed(args.projectPath, args.scene)))
+            const mode = args.timingMode === 'deterministic' ? 'deterministic' : 'realtime';
+            const commandArgs = [
+                ...(mode === 'deterministic' ? deterministicSessionArguments() : realtimeSessionArguments()),
+                '--path', args.projectPath,
+            ];
+            if (args.scene && this.context.isRelativePathAllowed(args.projectPath, args.scene))
                 commandArgs.push(args.scene);
             this.context.logDebug(`Running Godot project: ${args.projectPath}`);
             const processGeneration = ++this.processGeneration;
             this.context.startProjectProcess(godotPath, commandArgs, () => { this.handleProjectExit(processGeneration); }, {
                 ...this.context.getRuntimeEnvironment(),
-                ...deterministicSessionEnvironment(),
+                ...(mode === 'deterministic' ? deterministicSessionEnvironment() : realtimeSessionEnvironment()),
             });
             this.context.connectToGame(args.projectPath).catch(error => {
                 this.context.logDebug(`Failed to connect to game interaction server: ${error}`);
             });
-            return {
-                content: [{
-                        type: 'text',
-                        text: `Godot project started in debug mode. Use get_debug_output to see output. Game interaction server connecting on port ${this.context.getInteractionPort()}...`,
-                    }],
-            };
+            return { content: [{ type: 'text', text: JSON.stringify({
+                            started: true,
+                            project_path: args.projectPath,
+                            scene: args.scene ?? null,
+                            interaction_port: this.context.getInteractionPort(),
+                            timing_policy: timingPolicy(mode),
+                            message: 'Godot project started in debug mode; use get_debug_output for process output.',
+                        }, null, 2) }] };
         }
         catch (error) {
             return createErrorResponse(`Failed to run Godot project: ${this.errorMessage(error)}`);
         }
     }
+    isEditorPathAllowed(projectPath, relativePath) {
+        return typeof relativePath === 'string'
+            && this.context.isRelativePathAllowed(projectPath, relativePath);
+    }
     async handleVerifyProject(args) {
         args = normalizeParameters(args || {});
         const teardown = args.teardown !== false;
-        const started = await this.handleRunProject({ projectPath: args.projectPath, ...(args.scene ? { scene: args.scene } : {}) });
+        const started = await this.handleRunProject({
+            projectPath: args.projectPath,
+            ...(args.scene ? { scene: args.scene } : {}),
+            timingMode: 'deterministic',
+        });
         if (started.isError === true)
             return started;
         const evidence = {
@@ -183,6 +331,7 @@ export class LifecycleToolHandlers {
             assertions: [],
             screenshot: null,
             teardown,
+            timing_policy: timingPolicy('deterministic'),
         };
         let passed = true;
         try {
@@ -245,6 +394,191 @@ export class LifecycleToolHandlers {
             ...(passed ? {} : { isError: true }),
         };
     }
+    async handleGameWaitUntil(args) {
+        args = normalizeParameters(args || {});
+        const result = await this.waitUntilEvidence(args);
+        return {
+            content: [{ type: 'text', text: JSON.stringify(result, null, 2) }],
+            ...(result.satisfied === true ? {} : { isError: true }),
+        };
+    }
+    async handleGameScenario(args) {
+        args = normalizeParameters(args || {});
+        if (!args.name || !Array.isArray(args.steps) || args.steps.length === 0) {
+            return createErrorResponse('name and at least one scenario step are required.');
+        }
+        if (!this.context.isGameConnected())
+            return createErrorResponse('Not connected to a running Godot project.');
+        const startedAt = Date.now();
+        const deadline = startedAt + Math.round((typeof args.timeoutSeconds === 'number' ? args.timeoutSeconds : 60) * 1_000);
+        const evidence = [];
+        let passed = true;
+        let failure = null;
+        for (let index = 0; index < args.steps.length; index++) {
+            if (Date.now() >= deadline) {
+                passed = false;
+                failure = 'Scenario timeout expired';
+                break;
+            }
+            const step = args.steps[index];
+            const stepStartedAt = Date.now();
+            const item = { index, type: step.type, label: step.label ?? null };
+            try {
+                if (step.type === 'wait' || step.type === 'assert') {
+                    const condition = normalizeParameters((step.condition ?? {}));
+                    const remaining = Math.max(0.05, (deadline - Date.now()) / 1_000);
+                    const requestedTimeout = typeof condition.timeoutSeconds === 'number' ? condition.timeoutSeconds : remaining;
+                    const result = await this.waitUntilEvidence({ ...condition, timeoutSeconds: Math.min(remaining, requestedTimeout) });
+                    item.result = result;
+                    if (result.satisfied !== true) {
+                        passed = false;
+                        failure = `Step ${index} condition was not satisfied`;
+                    }
+                }
+                else if (step.type === 'screenshot') {
+                    const response = await this.context.sendGameCommand('screenshot', {}, Math.max(1, deadline - Date.now()));
+                    if ('error' in response)
+                        throw new Error(response.error.message);
+                    const result = response.result;
+                    const bytes = Buffer.from(result.data ?? '', 'base64');
+                    item.result = {
+                        captured: bytes.length > 0, width: result.width, height: result.height, bytes: bytes.length,
+                        sha256: createHash('sha256').update(bytes).digest('hex'), preview_omitted: true,
+                    };
+                }
+                else if (step.type === 'performance') {
+                    const response = await this.context.sendGameCommand('get_performance', {
+                        action: 'sample', sample_count: 1,
+                    }, Math.max(1, deadline - Date.now()));
+                    if ('error' in response)
+                        throw new Error(response.error.message);
+                    item.result = response.result;
+                }
+                else if (step.type === 'input' || step.type === 'observe') {
+                    const allowed = step.type === 'input' ? SCENARIO_INPUT_TOOLS : SCENARIO_OBSERVE_TOOLS;
+                    const tool = typeof step.tool === 'string' ? step.tool : step.type === 'input' ? 'game_key_press' : 'game_get_scene_tree';
+                    if (!allowed.has(tool))
+                        throw new Error(`Scenario ${step.type} tool is not allowed: ${tool}`);
+                    if (!this.context.dispatchTool)
+                        throw new Error('Scenario tool dispatch is unavailable');
+                    const response = await this.context.dispatchTool(tool, (step.arguments ?? {}));
+                    if (response.isError === true)
+                        throw new Error(response.content.map(content => 'text' in content ? content.text : content.type).join('; '));
+                    item.result = response.content.map(content => content.type === 'image'
+                        ? { type: 'image', mime_type: 'mimeType' in content ? content.mimeType : 'image/png', preview_omitted: true }
+                        : { type: content.type, text: 'text' in content ? String(content.text).slice(0, 2_000) : '' });
+                }
+                else {
+                    throw new Error(`Unsupported scenario step type: ${String(step.type)}`);
+                }
+            }
+            catch (error) {
+                passed = false;
+                failure = `Step ${index} failed: ${this.errorMessage(error)}`;
+                item.error = this.errorMessage(error);
+            }
+            item.duration_ms = Date.now() - stepStartedAt;
+            evidence.push(item);
+            if (!passed)
+                break;
+        }
+        const teardown = { attempted: true };
+        try {
+            const restored = await this.context.sendGameCommand('time_scale', { action: 'set', time_scale: 1 }, 2_000);
+            teardown.time_scale_restored = !('error' in restored);
+        }
+        catch (error) {
+            teardown.time_scale_restored = false;
+            teardown.error = this.errorMessage(error);
+            passed = false;
+        }
+        return {
+            content: [{ type: 'text', text: JSON.stringify({
+                        name: args.name, passed, failure, step_count: evidence.length,
+                        duration_ms: Date.now() - startedAt, steps: evidence, teardown,
+                    }, null, 2) }],
+            ...(passed ? {} : { isError: true }),
+        };
+    }
+    async waitUntilEvidence(args) {
+        const condition = args.condition;
+        if (!['connection', 'node', 'property', 'signal', 'log', 'scene'].includes(condition)) {
+            return { satisfied: false, error: 'condition must be connection, node, property, signal, log, or scene' };
+        }
+        const timeoutMs = Math.round((typeof args.timeoutSeconds === 'number' ? args.timeoutSeconds : 10) * 1_000);
+        const pollMs = typeof args.pollIntervalMs === 'number' ? args.pollIntervalMs : 100;
+        const startedAt = Date.now();
+        const deadline = startedAt + timeoutMs;
+        let attempts = 0;
+        let lastObserved = null;
+        if (condition === 'signal') {
+            if (!args.nodePath || !args.signal)
+                return { satisfied: false, error: 'nodePath and signal are required' };
+            const response = await this.context.sendGameCommand('await_signal', {
+                node_path: args.nodePath, signal_name: args.signal, timeout: timeoutMs / 1_000,
+            }, timeoutMs + 1_000);
+            return 'error' in response
+                ? { satisfied: false, condition, elapsed_ms: Date.now() - startedAt, attempts: 1, last_observed: response.error }
+                : { satisfied: true, condition, elapsed_ms: Date.now() - startedAt, attempts: 1, last_observed: response.result };
+        }
+        while (Date.now() <= deadline) {
+            attempts += 1;
+            if (condition === 'connection') {
+                lastObserved = { connected: this.context.isGameConnected() };
+                if (this.context.isGameConnected())
+                    return waitSuccess(condition, startedAt, attempts, lastObserved);
+            }
+            else if (condition === 'log') {
+                const output = this.context.getActiveProcess()?.output.join('\n') ?? '';
+                lastObserved = { tail: output.slice(-2_000) };
+                if (typeof args.text === 'string' && output.includes(args.text))
+                    return waitSuccess(condition, startedAt, attempts, lastObserved);
+            }
+            else {
+                if (!this.context.isGameConnected())
+                    lastObserved = { connected: false };
+                else {
+                    const command = condition === 'node' ? 'get_node_info' : condition === 'property' ? 'get_property' : 'get_scene_tree';
+                    const params = condition === 'node' ? { node_path: args.nodePath }
+                        : condition === 'property' ? { node_path: args.nodePath, property: args.property }
+                            : {};
+                    let response = null;
+                    try {
+                        response = await this.context.sendGameCommand(command, params, Math.min(5_000, Math.max(1, deadline - Date.now())));
+                    }
+                    catch (error) {
+                        // A poll issued at the edge of the deadline can consume its own
+                        // remaining transport budget. That is timeout evidence, not an
+                        // MCP handler crash, and must not erase the last successful read.
+                        if (lastObserved === null)
+                            lastObserved = { error: this.errorMessage(error) };
+                    }
+                    if (response) {
+                        lastObserved = 'error' in response ? { error: response.error } : response.result;
+                        if (condition === 'node' && !('error' in response))
+                            return waitSuccess(condition, startedAt, attempts, lastObserved);
+                        if (condition === 'property' && !('error' in response)) {
+                            const result = response.result;
+                            if (sameJson(result.value, args.value))
+                                return waitSuccess(condition, startedAt, attempts, lastObserved);
+                        }
+                        if (condition === 'scene' && !('error' in response)) {
+                            const result = response.result;
+                            if (result.current_scene === args.scenePath)
+                                return waitSuccess(condition, startedAt, attempts, lastObserved);
+                        }
+                    }
+                }
+            }
+            if (Date.now() >= deadline)
+                break;
+            await new Promise(resolve => setTimeout(resolve, Math.min(pollMs, deadline - Date.now())));
+        }
+        return {
+            satisfied: false, condition, elapsed_ms: Date.now() - startedAt, attempts,
+            timeout_ms: timeoutMs, last_observed: lastObserved,
+        };
+    }
     async evaluateVerificationAssertion(assertion) {
         if (assertion.kind === 'node_exists') {
             if (!assertion.nodePath)

package/build/tool-handlers/project-handler-services.js

@@ -629,7 +629,7 @@ export class ProjectIntegrityService {
         if ('error' in inventory)
             return createErrorResponse(inventory.error);
         if (args.action === 'analyze')
-            return { content: [{ type: 'text', text: JSON.stringify(this.analyze(args.projectPath, inventory.files), null, 2) }] };
+            return { content: [{ type: 'text', text: JSON.stringify(this.analyze(args.projectPath, inventory.files, args.allowProceduralMainScene === true), null, 2) }] };
         if (args.action === 'leaks') {
             const report = this.analyze(args.projectPath, inventory.files);
             return { content: [{ type: 'text', text: JSON.stringify({
@@ -685,7 +685,7 @@ export class ProjectIntegrityService {
         };
         return walk(projectPath) ? { files: files.sort() } : { error: `Project exceeds maxFiles limit (${maxFiles}).` };
     }
-    analyze(projectPath, files) {
+    analyze(projectPath, files, allowProceduralMainScene = false) {
         const fileSet = new Set(files);
         const graph = {};
         const uidOwners = new Map();
@@ -714,7 +714,47 @@ export class ProjectIntegrityService {
             duplicate_uids: [...uidOwners.entries()].filter(([, owners]) => new Set(owners).size > 1)
                 .map(([uid, owners]) => ({ uid, files: [...new Set(owners)] })),
             cycles: this.cycles(graph), orphan_resources: files.filter(file => !incoming.has(file) && !roots.has(file)),
-            orphan_nodes: orphanNodes, limits: { max_files: files.length },
+            orphan_nodes: orphanNodes,
+            main_scene_structure: this.mainSceneStructure(projectPath, projectConfig, allowProceduralMainScene),
+            limits: { max_files: files.length },
+        };
+    }
+    mainSceneStructure(projectPath, projectConfig, allowProceduralMainScene) {
+        const configured = /run\/main_scene\s*=\s*"res:\/\/([^"]+)"/.exec(projectConfig)?.[1];
+        if (!configured)
+            return { configured: false, warning: 'main_scene_not_configured' };
+        const scenePath = join(projectPath, configured);
+        if (!existsSync(scenePath) || extname(configured).toLowerCase() !== '.tscn') {
+            return { configured: true, scene_path: configured, inspectable: false, warning: 'main_scene_not_text_inspectable' };
+        }
+        const scene = readFileSync(scenePath, 'utf8');
+        const nodeCount = [...scene.matchAll(/^\[node\s+/gm)].length;
+        const scriptRefs = new Map([...scene.matchAll(/^\[ext_resource\s+type="Script"\s+path="res:\/\/([^"]+)"\s+id="([^"]+)"/gm)]
+            .map(match => [match[2], match[1]]));
+        const rootBlock = /^\[node\s+[^\]]+\]\s*\n([\s\S]*?)(?=^\[|$)/m.exec(scene)?.[1] ?? '';
+        const rootScriptId = /script\s*=\s*ExtResource\("([^"]+)"\)/.exec(rootBlock)?.[1];
+        const rootScriptPath = rootScriptId ? scriptRefs.get(rootScriptId) : undefined;
+        const rootScript = rootScriptPath && existsSync(join(projectPath, rootScriptPath))
+            ? readFileSync(join(projectPath, rootScriptPath), 'utf8')
+            : '';
+        const constructsAtStartup = /func\s+_ready\s*\([^)]*\)[\s\S]{0,12000}\b(?:add_child|instantiate|new)\s*\(/.test(rootScript);
+        const trivial = nodeCount <= 1;
+        const warning = trivial && constructsAtStartup && !allowProceduralMainScene
+            ? 'trivial_main_scene_with_procedural_startup_hierarchy'
+            : null;
+        return {
+            configured: true,
+            scene_path: configured,
+            inspectable: true,
+            persisted_node_count: nodeCount,
+            root_script: rootScriptPath ?? null,
+            constructs_persistent_hierarchy_at_startup: constructsAtStartup,
+            explicit_procedural_requirement: allowProceduralMainScene,
+            meaningful_persisted_structure: !trivial || allowProceduralMainScene,
+            warning,
+            recommendation: warning
+                ? 'Persist meaningful game hierarchy/resources in the scene, or rerun with allowProceduralMainScene only when procedural construction is intentional.'
+                : null,
         };
     }
     findOrphanNodes(scene, content, output) {
@@ -1420,9 +1460,8 @@ export class AddonManagementService {
         const matched = expected === null || result.stdout.includes(expected);
         const rawDiagnostics = `${result.stdout}\n${result.stderr}`.split(/\r?\n/)
             .filter(line => /SCRIPT ERROR|Parse Error|\bERROR:/i.test(line)).slice(0, 256);
-        const godot44 = result.stdout.includes('Godot Engine v4.4.');
-        const knownDiagnostics = godot44 ? rawDiagnostics.filter(line => /progress dialog \(task\)|tasks\.has\(p_task\)/i.test(line)) : [];
-        const diagnostics = rawDiagnostics.filter(line => !knownDiagnostics.includes(line));
+        const knownDiagnostics = [];
+        const diagnostics = rawDiagnostics;
         return { ...result, ok: result.ok && matched && diagnostics.length === 0,
             expected_output: expected, output_matched: matched, diagnostics, known_diagnostics: knownDiagnostics };
     }

package/build/tool-handlers/project-tool-handlers.js

@@ -8,7 +8,7 @@ import { ProjectConfigurationService, ProjectExportService, ProjectFileIOService
 const execFileAsync = promisify(execFile);
 const CI_EXPORT_PLATFORMS = new Set(['windows', 'linux', 'macos', 'web']);
 const DOCKER_BASE_IMAGES = new Set(['ubuntu:22.04', 'ubuntu:24.04']);
-const GODOT_EXPORT_VERSION = /^4\.\d+(?:\.\d+)?(?:-stable)?$/;
+const GODOT_EXPORT_VERSION = /^4\.(?:[7-9]|\d{2,})(?:\.\d+)?(?:-stable)?$/;
 const EXPORT_PRESET_NAME = /^[A-Za-z0-9][A-Za-z0-9 _./-]{0,127}$/;
 const INPUT_EVENT_KEY_PREFIX = 'Object(InputEventKey,"resource_local_to_scene":false,"resource_name":"","device":-1,"window_id":0,"alt_pressed":false,"shift_pressed":false,"ctrl_pressed":false,"meta_pressed":false,"pressed":false,"keycode":0';
 const INPUT_EVENT_KEY_SUFFIX = ',"key_label":0,"unicode":0,"location":0,"echo":false,"script":null)';
@@ -56,7 +56,7 @@ export function mergeInputMapAction(content, actionName, deadzone, physicalKeyco
 }
 function validateGodotExportVersion(version) {
     if (typeof version !== 'string' || !GODOT_EXPORT_VERSION.test(version)) {
-        return 'godotVersion must be a supported Godot 4 version such as "4.3-stable".';
+        return 'godotVersion must be a supported Godot 4.7+ version such as "4.7-stable".';
     }
     return null;
 }
@@ -1387,7 +1387,7 @@ export class ProjectToolHandlers {
                 return { content: [{ type: 'text', text: content }] };
             }
             else if (args.action === 'create') {
-                const godotVersion = args.godotVersion || '4.3-stable';
+                const godotVersion = args.godotVersion || '4.7-stable';
                 const versionError = validateGodotExportVersion(godotVersion);
                 if (versionError)
                     return createErrorResponse(versionError);
@@ -1429,7 +1429,7 @@ export class ProjectToolHandlers {
                 return { content: [{ type: 'text', text: content }] };
             }
             else if (args.action === 'create') {
-                const godotVersion = args.godotVersion || '4.3-stable';
+                const godotVersion = args.godotVersion || '4.7-stable';
                 const baseImage = args.baseImage || 'ubuntu:22.04';
                 let exportPreset = args.exportPreset || 'Linux/X11';
                 const versionError = validateGodotExportVersion(godotVersion);

package/build/tool-manifest.js

@@ -18,6 +18,13 @@ export const toolManifest = {
         actions: null,
         privileged: false,
     },
+    editor_session: {
+        domain: 'lifecycle',
+        handler: 'handleEditorSession',
+        backend: { kind: 'process' },
+        actions: ['ensure', 'status', 'disconnect'],
+        privileged: false,
+    },
     editor_control: {
         domain: 'lifecycle',
         handler: 'handleEditorControl',
@@ -25,6 +32,13 @@ export const toolManifest = {
         actions: ['inspect', 'select', 'save', 'reload', 'open_scene', 'set_property', 'rename_node', 'undo', 'redo'],
         privileged: false,
     },
+    editor_transaction: {
+        domain: 'lifecycle',
+        handler: 'handleEditorTransaction',
+        backend: { kind: 'process' },
+        actions: null,
+        privileged: false,
+    },
     run_project: {
         domain: 'lifecycle',
         handler: 'handleRunProject',
@@ -39,6 +53,20 @@ export const toolManifest = {
         actions: null,
         privileged: false,
     },
+    game_wait_until: {
+        domain: 'lifecycle',
+        handler: 'handleGameWaitUntil',
+        backend: { kind: 'process' },
+        actions: null,
+        privileged: false,
+    },
+    game_scenario: {
+        domain: 'lifecycle',
+        handler: 'handleGameScenario',
+        backend: { kind: 'process' },
+        actions: null,
+        privileged: false,
+    },
     run_project_tests: {
         domain: 'project',
         handler: 'handleRunProjectTests',
@@ -282,7 +310,7 @@ export const toolManifest = {
         domain: 'game',
         handler: 'handleGamePerformance',
         backend: { kind: 'runtime', command: 'get_performance' },
-        actions: ['sample', 'start', 'stop', 'report', 'leaks'],
+        actions: ['sample', 'start', 'stop', 'report', 'leaks', 'stress'],
         privileged: false,
     },
     game_wait: {