@beremaran/godot-agent-loop 1.0.0

package/build/domain-tool-registries.js

@@ -0,0 +1,207 @@
+import { toolDefinitions } from './tool-definitions.js';
+/** Combines domain-owned registries while rejecting duplicate or missing tools. */
+export function composeToolHandlerRegistries(...registries) {
+    const handlers = {};
+    const toolNames = new Set(toolDefinitions.map(tool => tool.name));
+    for (const registry of registries) {
+        for (const [name, handler] of Object.entries(registry)) {
+            if (!toolNames.has(name)) {
+                throw new Error(`Unknown tool handler: ${name}`);
+            }
+            if (handlers[name]) {
+                throw new Error(`Tool handler is registered more than once: ${name}`);
+            }
+            handlers[name] = handler;
+        }
+    }
+    const missing = toolDefinitions
+        .map(tool => tool.name)
+        .filter(name => !handlers[name]);
+    if (missing.length > 0) {
+        throw new Error(`Missing tool handlers: ${missing.join(', ')}`);
+    }
+    return handlers;
+}
+/** Builds the complete registry from independently maintained domain registries. */
+export function createToolHandlers({ game, lifecycle, project, }) {
+    return composeToolHandlerRegistries(createLifecycleToolRegistry(lifecycle), createProjectToolRegistry(project), createGameToolRegistry(game));
+}
+export function createLifecycleToolRegistry(handlers) {
+    return {
+        'godot_tools': args => handlers.handleGodotTools(args),
+        'launch_editor': args => handlers.handleLaunchEditor(args),
+        'editor_control': args => handlers.handleEditorControl(args),
+        'run_project': args => handlers.handleRunProject(args),
+        'verify_project': args => handlers.handleVerifyProject(args),
+        'get_debug_output': () => handlers.handleGetDebugOutput(),
+        'stop_project': () => handlers.handleStopProject(),
+        'get_godot_version': () => handlers.handleGetGodotVersion(),
+    };
+}
+export function createProjectToolRegistry(handlers) {
+    return {
+        'run_project_tests': args => handlers.handleRunProjectTests(args),
+        'manage_import_pipeline': args => handlers.handleManageImportPipeline(args),
+        'analyze_project_integrity': args => handlers.handleAnalyzeProjectIntegrity(args),
+        'verify_export_readiness': args => handlers.handleVerifyExportReadiness(args),
+        'verify_dotnet_project': args => handlers.handleVerifyDotnetProject(args),
+        'manage_addon': args => handlers.handleManageAddon(args),
+        'list_projects': args => handlers.handleListProjects(args),
+        'get_project_info': args => handlers.handleGetProjectInfo(args),
+        'create_scene': args => handlers.handleCreateScene(args),
+        'add_node': args => handlers.handleAddNode(args),
+        'load_sprite': args => handlers.handleLoadSprite(args),
+        'export_mesh_library': args => handlers.handleExportMeshLibrary(args),
+        'save_scene': args => handlers.handleSaveScene(args),
+        'get_uid': args => handlers.handleGetUid(args),
+        'update_project_uids': args => handlers.handleUpdateProjectUids(args),
+        'read_scene': args => handlers.handleReadScene(args),
+        'modify_scene_node': args => handlers.handleModifySceneNode(args),
+        'remove_scene_node': args => handlers.handleRemoveSceneNode(args),
+        'read_project_settings': args => handlers.handleReadProjectSettings(args),
+        'modify_project_settings': args => handlers.handleModifyProjectSettings(args),
+        'list_project_files': args => handlers.handleListProjectFiles(args),
+        'attach_script': args => handlers.handleAttachScript(args),
+        'create_resource': args => handlers.handleCreateResource(args),
+        'read_file': args => handlers.handleReadFile(args),
+        'write_file': args => handlers.handleWriteFile(args),
+        'delete_file': args => handlers.handleDeleteFile(args),
+        'create_directory': args => handlers.handleCreateDirectory(args),
+        'create_project': args => handlers.handleCreateProject(args),
+        'create_csharp_script': args => handlers.handleCreateCsharpScript(args),
+        'manage_autoloads': args => handlers.handleManageAutoloads(args),
+        'manage_input_map': args => handlers.handleManageInputMap(args),
+        'manage_export_presets': args => handlers.handleManageExportPresets(args),
+        'export_project': args => handlers.handleExportProject(args),
+        'rename_file': args => handlers.handleRenameFile(args),
+        'manage_resource': args => handlers.handleManageResource(args),
+        'validate_script': args => handlers.handleValidateScript(args),
+        'validate_scripts': args => handlers.handleValidateScripts(args),
+        'create_script': args => handlers.handleCreateScript(args),
+        'manage_scene_signals': args => handlers.handleManageSceneSignals(args),
+        'manage_layers': args => handlers.handleManageLayers(args),
+        'manage_plugins': args => handlers.handleManagePlugins(args),
+        'manage_shader': args => handlers.handleManageShader(args),
+        'manage_theme_resource': args => handlers.handleManageThemeResource(args),
+        'set_main_scene': args => handlers.handleSetMainScene(args),
+        'manage_scene_structure': args => handlers.handleManageSceneStructure(args),
+        'manage_translations': args => handlers.handleManageTranslations(args),
+        'manage_ci_pipeline': args => handlers.handleManageCiPipeline(args),
+        'manage_docker_export': args => handlers.handleManageDockerExport(args),
+    };
+}
+export function createGameToolRegistry(handlers) {
+    return {
+        'game_screenshot': () => handlers.handleGameScreenshot(),
+        'game_visual_regression': args => handlers.handleGameVisualRegression(args),
+        'game_click': args => handlers.handleGameClick(args),
+        'game_key_press': args => handlers.handleGameKeyPress(args),
+        'game_mouse_move': args => handlers.handleGameMouseMove(args),
+        'game_get_ui': () => handlers.handleGameGetUi(),
+        'game_get_scene_tree': args => handlers.handleGameGetSceneTree(args),
+        'game_eval': args => handlers.handleGameEval(args),
+        'game_get_property': args => handlers.handleGameGetProperty(args),
+        'game_set_property': args => handlers.handleGameSetProperty(args),
+        'game_call_method': args => handlers.handleGameCallMethod(args),
+        'game_get_node_info': args => handlers.handleGameGetNodeInfo(args),
+        'game_instantiate_scene': args => handlers.handleGameInstantiateScene(args),
+        'game_remove_node': args => handlers.handleGameRemoveNode(args),
+        'game_change_scene': args => handlers.handleGameChangeScene(args),
+        'game_pause': args => handlers.handleGamePause(args),
+        'game_performance': args => handlers.handleGamePerformance(args),
+        'game_wait': args => handlers.handleGameWait(args),
+        'game_connect_signal': args => handlers.handleGameConnectSignal(args),
+        'game_disconnect_signal': args => handlers.handleGameDisconnectSignal(args),
+        'game_emit_signal': args => handlers.handleGameEmitSignal(args),
+        'game_play_animation': args => handlers.handleGamePlayAnimation(args),
+        'game_tween_property': args => handlers.handleGameTweenProperty(args),
+        'game_get_nodes_in_group': args => handlers.handleGameGetNodesInGroup(args),
+        'game_find_nodes_by_class': args => handlers.handleGameFindNodesByClass(args),
+        'game_reparent_node': args => handlers.handleGameReparentNode(args),
+        'game_get_errors': args => handlers.handleGameGetErrors(args),
+        'game_get_logs': args => handlers.handleGameGetLogs(args),
+        'game_key_hold': args => handlers.handleGameKeyHold(args),
+        'game_key_release': args => handlers.handleGameKeyRelease(args),
+        'game_scroll': args => handlers.handleGameScroll(args),
+        'game_mouse_drag': args => handlers.handleGameMouseDrag(args),
+        'game_gamepad': args => handlers.handleGameGamepad(args),
+        'game_get_camera': () => handlers.handleGameGetCamera(),
+        'game_set_camera': args => handlers.handleGameSetCamera(args),
+        'game_raycast': args => handlers.handleGameRaycast(args),
+        'game_get_audio': () => handlers.handleGameGetAudio(),
+        'game_spawn_node': args => handlers.handleGameSpawnNode(args),
+        'game_set_shader_param': args => handlers.handleGameSetShaderParam(args),
+        'game_audio_play': args => handlers.handleGameAudioPlay(args),
+        'game_audio_bus': args => handlers.handleGameAudioBus(args),
+        'game_navigate_path': args => handlers.handleGameNavigatePath(args),
+        'game_tilemap': args => handlers.handleGameTilemap(args),
+        'game_add_collision': args => handlers.handleGameAddCollision(args),
+        'game_environment': args => handlers.handleGameEnvironment(args),
+        'game_manage_group': args => handlers.handleGameManageGroup(args),
+        'game_create_timer': args => handlers.handleGameCreateTimer(args),
+        'game_set_particles': args => handlers.handleGameSetParticles(args),
+        'game_create_animation': args => handlers.handleGameCreateAnimation(args),
+        'game_serialize_state': args => handlers.handleGameSerializeState(args),
+        'game_physics_body': args => handlers.handleGamePhysicsBody(args),
+        'game_create_joint': args => handlers.handleGameCreateJoint(args),
+        'game_bone_pose': args => handlers.handleGameBonePose(args),
+        'game_ui_theme': args => handlers.handleGameUiTheme(args),
+        'game_viewport': args => handlers.handleGameViewport(args),
+        'game_debug_draw': args => handlers.handleGameDebugDraw(args),
+        'game_http_request': args => handlers.handleGameHttpRequest(args),
+        'game_websocket': args => handlers.handleGameWebsocket(args),
+        'game_multiplayer': args => handlers.handleGameMultiplayer(args),
+        'game_rpc': args => handlers.handleGameRpc(args),
+        'game_touch': args => handlers.handleGameTouch(args),
+        'game_input_state': args => handlers.handleGameInputState(args),
+        'game_input_action': args => handlers.handleGameInputAction(args),
+        'game_list_signals': args => handlers.handleGameListSignals(args),
+        'game_await_signal': args => handlers.handleGameAwaitSignal(args),
+        'game_script': args => handlers.handleGameScript(args),
+        'game_window': args => handlers.handleGameWindow(args),
+        'game_os_info': args => handlers.handleGameOsInfo(args),
+        'game_time_scale': args => handlers.handleGameTimeScale(args),
+        'game_process_mode': args => handlers.handleGameProcessMode(args),
+        'game_world_settings': args => handlers.handleGameWorldSettings(args),
+        'game_csg': args => handlers.handleGameCsg(args),
+        'game_multimesh': args => handlers.handleGameMultimesh(args),
+        'game_procedural_mesh': args => handlers.handleGameProceduralMesh(args),
+        'game_light_3d': args => handlers.handleGameLight3d(args),
+        'game_mesh_instance': args => handlers.handleGameMeshInstance(args),
+        'game_gridmap': args => handlers.handleGameGridmap(args),
+        'game_3d_effects': args => handlers.handleGame3dEffects(args),
+        'game_gi': args => handlers.handleGameGi(args),
+        'game_path_3d': args => handlers.handleGamePath3d(args),
+        'game_sky': args => handlers.handleGameSky(args),
+        'game_camera_attributes': args => handlers.handleGameCameraAttributes(args),
+        'game_navigation_3d': args => handlers.handleGameNavigation3d(args),
+        'game_physics_3d': args => handlers.handleGamePhysics3d(args),
+        'game_canvas': args => handlers.handleGameCanvas(args),
+        'game_canvas_draw': args => handlers.handleGameCanvasDraw(args),
+        'game_light_2d': args => handlers.handleGameLight2d(args),
+        'game_parallax': args => handlers.handleGameParallax(args),
+        'game_shape_2d': args => handlers.handleGameShape2d(args),
+        'game_path_2d': args => handlers.handleGamePath2d(args),
+        'game_physics_2d': args => handlers.handleGamePhysics2d(args),
+        'game_animation_tree': args => handlers.handleGameAnimationTree(args),
+        'game_animation_control': args => handlers.handleGameAnimationControl(args),
+        'game_skeleton_ik': args => handlers.handleGameSkeletonIk(args),
+        'game_audio_effect': args => handlers.handleGameAudioEffect(args),
+        'game_audio_bus_layout': args => handlers.handleGameAudioBusLayout(args),
+        'game_audio_spatial': args => handlers.handleGameAudioSpatial(args),
+        'game_locale': args => handlers.handleGameLocale(args),
+        'game_ui_control': args => handlers.handleGameUiControl(args),
+        'game_ui_text': args => handlers.handleGameUiText(args),
+        'game_ui_popup': args => handlers.handleGameUiPopup(args),
+        'game_ui_tree': args => handlers.handleGameUiTree(args),
+        'game_ui_item_list': args => handlers.handleGameUiItemList(args),
+        'game_ui_tabs': args => handlers.handleGameUiTabs(args),
+        'game_ui_menu': args => handlers.handleGameUiMenu(args),
+        'game_ui_range': args => handlers.handleGameUiRange(args),
+        'game_render_settings': args => handlers.handleGameRenderSettings(args),
+        'game_resource': args => handlers.handleGameResource(args),
+        'game_visual_shader': args => handlers.handleGameVisualShader(args),
+        'game_terrain': args => handlers.handleGameTerrain(args),
+        'game_video': args => handlers.handleGameVideo(args),
+    };
+}

package/build/editor-bridge-protocol.js

@@ -0,0 +1 @@
+export const EDITOR_BRIDGE_PROTOCOL_VERSION = '1';

package/build/editor-connection.js

@@ -0,0 +1,112 @@
+import { createConnection } from 'node:net';
+import { EDITOR_BRIDGE_PROTOCOL_VERSION } from './editor-bridge-protocol.js';
+export class EditorBridgeCompatibilityError extends Error {
+}
+/** Authenticated newline-delimited bridge to the optional EditorPlugin. */
+export class EditorConnection {
+    options;
+    socket = null;
+    buffer = '';
+    nextId = 1;
+    pending = new Map();
+    connecting = null;
+    handshaking = null;
+    constructor(options) {
+        this.options = options;
+    }
+    async send(command, params = {}, timeoutMs = 10_000) {
+        await this.ensureConnected(timeoutMs);
+        if (command !== 'handshake')
+            await this.ensureHandshake(timeoutMs);
+        return this.request(command, params, timeoutMs);
+    }
+    request(command, params, timeoutMs) {
+        const id = this.nextId++;
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.pending.delete(id);
+                reject(new Error(`Editor request '${command}' timed out after ${timeoutMs / 1000}s`));
+            }, timeoutMs);
+            this.pending.set(id, result => { clearTimeout(timer); resolve(result); });
+            this.socket.write(`${JSON.stringify({ id, command, params, secret: this.options.secret })}\n`);
+        });
+    }
+    disconnect() {
+        this.socket?.destroy();
+        this.socket = null;
+        this.buffer = '';
+        this.handshaking = null;
+        for (const resolve of this.pending.values()) {
+            resolve({ error: 'editor_disconnected' });
+        }
+        this.pending.clear();
+    }
+    async ensureHandshake(timeoutMs) {
+        if (this.handshaking)
+            return this.handshaking;
+        const expected = this.options.protocolVersion ?? EDITOR_BRIDGE_PROTOCOL_VERSION;
+        this.handshaking = this.request('handshake', {
+            protocol_version: expected,
+            server_version: this.options.serverVersion ?? 'unknown',
+        }, timeoutMs).then(result => {
+            if (result.error || result.protocol_version !== expected) {
+                const actual = typeof result.protocol_version === 'string' ? result.protocol_version : 'missing';
+                throw new EditorBridgeCompatibilityError(`Godot Agent Loop editor protocol is incompatible: server ${expected}, addon ${actual}`);
+            }
+        });
+        try {
+            await this.handshaking;
+        }
+        catch (error) {
+            this.disconnect();
+            throw error;
+        }
+    }
+    async ensureConnected(timeoutMs) {
+        if (this.socket)
+            return;
+        if (this.connecting)
+            return this.connecting;
+        this.connecting = new Promise((resolve, reject) => {
+            const socket = createConnection({ host: '127.0.0.1', port: this.options.port });
+            const timer = setTimeout(() => { socket.destroy(); reject(new Error('Editor bridge connection timed out')); }, timeoutMs);
+            socket.once('connect', () => {
+                clearTimeout(timer);
+                this.socket = socket;
+                socket.on('data', data => { this.receive(data.toString('utf8')); });
+                socket.on('close', () => { if (this.socket === socket)
+                    this.disconnect(); });
+                socket.on('error', () => undefined);
+                resolve();
+            });
+            socket.once('error', error => { clearTimeout(timer); reject(error); });
+        });
+        try {
+            await this.connecting;
+        }
+        finally {
+            this.connecting = null;
+        }
+    }
+    receive(data) {
+        this.buffer += data;
+        while (true) {
+            const newline = this.buffer.indexOf('\n');
+            if (newline < 0)
+                return;
+            const line = this.buffer.slice(0, newline).trim();
+            this.buffer = this.buffer.slice(newline + 1);
+            if (!line)
+                continue;
+            try {
+                const parsed = JSON.parse(line);
+                const id = parsed.id;
+                if (typeof id === 'number')
+                    this.pending.get(id)?.(parsed);
+                if (typeof id === 'number')
+                    this.pending.delete(id);
+            }
+            catch { /* malformed bridge data is ignored; the request timeout is authoritative */ }
+        }
+    }
+}

package/build/editor-mutation-guard.js

@@ -0,0 +1,30 @@
+import { isToolCallMutating } from './tool-mutation-policy.js';
+import { createErrorResponse } from './utils.js';
+import { EditorBridgeCompatibilityError } from './editor-connection.js';
+export const EDITOR_DRIVER_STATE_COMMAND = 'driver_state';
+export const EDITOR_DRIVER_STATE_TIMEOUT_MS = 500;
+export const AGENT_MUTATIONS_PAUSED_MESSAGE = 'Agent mutation refused: mutations are paused in the Godot editor. Use Resume Agent in the Agent Activity dock to continue.';
+/** Cooperative, editor-owned gate applied after validation and before dispatch. */
+export class EditorMutationGuard {
+    readDriverState;
+    constructor(readDriverState) {
+        this.readDriverState = readDriverState;
+    }
+    async check(name, args) {
+        if (!isToolCallMutating(name, args))
+            return undefined;
+        try {
+            const state = await this.readDriverState(EDITOR_DRIVER_STATE_COMMAND, {}, EDITOR_DRIVER_STATE_TIMEOUT_MS);
+            if (state.paused === true)
+                return createErrorResponse(AGENT_MUTATIONS_PAUSED_MESSAGE);
+        }
+        catch (error) {
+            if (error instanceof EditorBridgeCompatibilityError) {
+                return createErrorResponse(`Agent mutation refused: ${error.message}`);
+            }
+            // The addon is optional. No reachable editor means there is no human-held
+            // cooperative lock to honor, so normal unattended operation continues.
+        }
+        return undefined;
+    }
+}

package/build/editor-plugin-installer.js

@@ -0,0 +1,220 @@
+import { createHash } from 'node:crypto';
+import { copyFileSync, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { EDITOR_BRIDGE_PROTOCOL_VERSION } from './editor-bridge-protocol.js';
+export const PERSISTENT_EDITOR_ADDON_DIR = 'addons/godot_agent_loop';
+export const TRANSIENT_EDITOR_ADDON_DIR = 'addons/godot_agent_loop_transient';
+const PERSISTENT_PLUGIN_NAME = 'godot_agent_loop';
+const TRANSIENT_PLUGIN_NAME = 'godot_agent_loop_transient';
+const OWNERSHIP_FILE = '.godot-agent-loop-owned.json';
+const OWNERSHIP_ID = 'godot-agent-loop-server';
+function hashFile(path) {
+    return createHash('sha256').update(readFileSync(path)).digest('hex');
+}
+function parseConfigValue(source, key) {
+    const match = new RegExp(`^${key}\\s*=\\s*"([^"]*)"`, 'm').exec(source);
+    return match?.[1];
+}
+function enabledPlugins(source) {
+    const section = /(?:^|\n)\[editor_plugins\]\s*\n([\s\S]*?)(?=\n\[|$)/.exec(source);
+    const line = section?.[1].match(/^enabled\s*=\s*PackedStringArray\((.*)\)\s*$/m);
+    if (!line)
+        return [];
+    return [...line[1].matchAll(/"(?:\\.|[^"])*"/g)].map(match => JSON.parse(match[0]));
+}
+function withEnabledPlugin(source, pluginName) {
+    const plugins = enabledPlugins(source);
+    if (plugins.includes(pluginName))
+        return { content: source, changed: false };
+    plugins.push(pluginName);
+    return { content: writeEnabledPlugins(source, plugins), changed: true };
+}
+function withoutEnabledPlugin(source, pluginName, removeEmptySection) {
+    const plugins = enabledPlugins(source);
+    if (!plugins.includes(pluginName))
+        return source;
+    const remaining = plugins.filter(name => name !== pluginName);
+    if (removeEmptySection && remaining.length === 0) {
+        return source.replace(/(?:^|\n)\[editor_plugins\]\s*\n[\s\S]*?(?=\n\[|$)/, '');
+    }
+    return writeEnabledPlugins(source, remaining);
+}
+function writeEnabledPlugins(source, plugins) {
+    const value = `enabled=PackedStringArray(${plugins.map(name => JSON.stringify(name)).join(', ')})`;
+    const sectionPattern = /((?:^|\n)\[editor_plugins\]\s*\n)([\s\S]*?)(?=\n\[|$)/;
+    const section = sectionPattern.exec(source);
+    if (!section)
+        return `${source.replace(/\s*$/, '')}\n\n[editor_plugins]\n\n${value}\n`;
+    const body = section[2];
+    const nextBody = /^enabled\s*=.*$/m.test(body)
+        ? body.replace(/^enabled\s*=.*$/m, value)
+        : `${body.replace(/\s*$/, '')}\n${value}\n`;
+    return source.replace(sectionPattern, `${section[1]}${nextBody}`);
+}
+export class EditorPluginInstaller {
+    scriptPath;
+    constructor(scriptPath) {
+        this.scriptPath = scriptPath;
+    }
+    install(projectPath) {
+        const projectFile = join(projectPath, 'project.godot');
+        const projectBefore = readFileSync(projectFile, 'utf8');
+        const persistentConfig = join(projectPath, PERSISTENT_EDITOR_ADDON_DIR, 'plugin.cfg');
+        const persistentBaseline = existsSync(persistentConfig)
+            ? this.recoverOwnedTransient(projectPath, projectBefore)
+            : projectBefore;
+        const persistent = this.persistentInstallation(projectPath, persistentBaseline);
+        if (persistent)
+            return persistent;
+        return this.transientInstallation(projectPath, projectBefore);
+    }
+    remove(projectPath, installation) {
+        if (!installation)
+            return { filesRemoved: false, filesPreserved: false };
+        const projectFile = join(projectPath, 'project.godot');
+        if (installation.enabledByServer && existsSync(projectFile)) {
+            const current = readFileSync(projectFile, 'utf8');
+            const restored = current === installation.projectAfter
+                ? installation.projectBefore
+                : withoutEnabledPlugin(current, installation.pluginName, !/(?:^|\n)\[editor_plugins\]\s*\n/.test(installation.projectBefore));
+            if (restored !== current)
+                writeFileSync(projectFile, restored, 'utf8');
+        }
+        if (!installation.owned)
+            return { filesRemoved: false, filesPreserved: true };
+        const addon = join(projectPath, TRANSIENT_EDITOR_ADDON_DIR);
+        if (!this.isUnmodifiedOwnedTransient(addon))
+            return { filesRemoved: false, filesPreserved: existsSync(addon) };
+        rmSync(addon, { recursive: true });
+        return { filesRemoved: true, filesPreserved: false };
+    }
+    persistentInstallation(projectPath, projectBefore) {
+        const addon = join(projectPath, PERSISTENT_EDITOR_ADDON_DIR);
+        const configPath = join(addon, 'plugin.cfg');
+        if (!existsSync(configPath))
+            return undefined;
+        const config = readFileSync(configPath, 'utf8');
+        const script = parseConfigValue(config, 'script');
+        const protocolVersion = parseConfigValue(config, 'protocol_version');
+        if (!script || !existsSync(join(addon, script))) {
+            throw new Error('Godot Agent Loop persistent addon is incomplete: plugin script is missing');
+        }
+        if (protocolVersion !== EDITOR_BRIDGE_PROTOCOL_VERSION) {
+            throw new Error(`Godot Agent Loop editor protocol is incompatible: server ${EDITOR_BRIDGE_PROTOCOL_VERSION}, addon ${protocolVersion ?? 'missing'}`);
+        }
+        const enabled = withEnabledPlugin(projectBefore, PERSISTENT_PLUGIN_NAME);
+        if (enabled.changed)
+            writeFileSync(join(projectPath, 'project.godot'), enabled.content, 'utf8');
+        return {
+            distribution: 'persistent',
+            pluginName: PERSISTENT_PLUGIN_NAME,
+            protocolVersion,
+            owned: false,
+            enabledByServer: enabled.changed,
+            projectBefore,
+            projectAfter: enabled.content,
+        };
+    }
+    recoverOwnedTransient(projectPath, projectSource) {
+        const addon = join(projectPath, TRANSIENT_EDITOR_ADDON_DIR);
+        if (!existsSync(addon))
+            return projectSource;
+        const marker = this.readUnmodifiedOwnedTransient(addon);
+        if (!marker) {
+            throw new Error(`Persistent addon cannot start while a user-managed path exists at ${TRANSIENT_EDITOR_ADDON_DIR}`);
+        }
+        const restored = marker.pluginEnabledBeforeInstall
+            ? projectSource
+            : withoutEnabledPlugin(projectSource, TRANSIENT_PLUGIN_NAME, !marker.editorPluginsSectionExistedBeforeInstall);
+        if (restored !== projectSource)
+            writeFileSync(join(projectPath, 'project.godot'), restored, 'utf8');
+        rmSync(addon, { recursive: true });
+        return restored;
+    }
+    transientInstallation(projectPath, projectBefore) {
+        const addon = join(projectPath, TRANSIENT_EDITOR_ADDON_DIR);
+        let previousMarker;
+        if (existsSync(addon)) {
+            previousMarker = this.readUnmodifiedOwnedTransient(addon);
+            if (!previousMarker) {
+                throw new Error(`Refusing to overwrite user-managed editor addon at ${TRANSIENT_EDITOR_ADDON_DIR}`);
+            }
+            rmSync(addon, { recursive: true });
+        }
+        const pluginEnabledBeforeInstall = previousMarker?.pluginEnabledBeforeInstall
+            ?? enabledPlugins(projectBefore).includes(TRANSIENT_PLUGIN_NAME);
+        const editorPluginsSectionExistedBeforeInstall = previousMarker?.editorPluginsSectionExistedBeforeInstall
+            ?? /(?:^|\n)\[editor_plugins\]\s*\n/.test(projectBefore);
+        try {
+            mkdirSync(addon, { recursive: true });
+            copyFileSync(this.scriptPath, join(addon, 'plugin.gd'));
+            writeFileSync(join(addon, 'plugin.cfg'), [
+                '[plugin]',
+                '',
+                'name="Godot Agent Loop Transient Bridge"',
+                'description="Session-owned authenticated editor bridge"',
+                'author="Godot Agent Loop"',
+                'version="1.0.0"',
+                'script="plugin.gd"',
+                `protocol_version="${EDITOR_BRIDGE_PROTOCOL_VERSION}"`,
+                '',
+            ].join('\n'));
+            const marker = {
+                owner: OWNERSHIP_ID,
+                protocolVersion: EDITOR_BRIDGE_PROTOCOL_VERSION,
+                pluginEnabledBeforeInstall,
+                editorPluginsSectionExistedBeforeInstall,
+                files: {
+                    'plugin.gd': hashFile(join(addon, 'plugin.gd')),
+                    'plugin.cfg': hashFile(join(addon, 'plugin.cfg')),
+                },
+            };
+            writeFileSync(join(addon, OWNERSHIP_FILE), `${JSON.stringify(marker, null, 2)}\n`);
+        }
+        catch (error) {
+            rmSync(addon, { recursive: true, force: true });
+            throw error;
+        }
+        const enabled = withEnabledPlugin(projectBefore, TRANSIENT_PLUGIN_NAME);
+        const cleanupBaseline = previousMarker && !pluginEnabledBeforeInstall
+            ? withoutEnabledPlugin(projectBefore, TRANSIENT_PLUGIN_NAME, !editorPluginsSectionExistedBeforeInstall)
+            : projectBefore;
+        try {
+            if (enabled.changed)
+                writeFileSync(join(projectPath, 'project.godot'), enabled.content, 'utf8');
+        }
+        catch (error) {
+            if (this.isUnmodifiedOwnedTransient(addon))
+                rmSync(addon, { recursive: true });
+            throw error;
+        }
+        return {
+            distribution: 'transient',
+            pluginName: TRANSIENT_PLUGIN_NAME,
+            protocolVersion: EDITOR_BRIDGE_PROTOCOL_VERSION,
+            owned: true,
+            enabledByServer: enabled.changed || Boolean(previousMarker && !pluginEnabledBeforeInstall),
+            projectBefore: cleanupBaseline,
+            projectAfter: enabled.content,
+        };
+    }
+    isUnmodifiedOwnedTransient(addon) {
+        return this.readUnmodifiedOwnedTransient(addon) !== undefined;
+    }
+    readUnmodifiedOwnedTransient(addon) {
+        const markerPath = join(addon, OWNERSHIP_FILE);
+        if (!existsSync(markerPath))
+            return undefined;
+        try {
+            const marker = JSON.parse(readFileSync(markerPath, 'utf8'));
+            if (marker.owner !== OWNERSHIP_ID
+                || typeof marker.pluginEnabledBeforeInstall !== 'boolean'
+                || typeof marker.editorPluginsSectionExistedBeforeInstall !== 'boolean')
+                return undefined;
+            return Object.entries(marker.files).every(([name, hash]) => (existsSync(join(addon, name)) && hashFile(join(addon, name)) === hash)) ? marker : undefined;
+        }
+        catch {
+            return undefined;
+        }
+    }
+}