@beremaran/godot-agent-loop 1.0.1 → 1.1.0

package/build/editor-plugin-installer.js

@@ -154,9 +154,10 @@ export class EditorPluginInstaller {
                 'name="Godot Agent Loop Transient Bridge"',
                 'description="Session-owned authenticated editor bridge"',
                 'author="Godot Agent Loop"',
-                'version="1.0.1"',
+                'version="1.1.0"',
                 'script="plugin.gd"',
                 `protocol_version="${EDITOR_BRIDGE_PROTOCOL_VERSION}"`,
+                'minimum_godot_version="4.7"',
                 '',
             ].join('\n'));
             const marker = {

package/build/editor-session-registry.js

@@ -0,0 +1,392 @@
+import { existsSync, realpathSync, readFileSync, rmSync, statSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { EditorBridgeCompatibilityError, EditorConnection, EditorRequestTimeoutError, } from './editor-connection.js';
+import { EDITOR_BRIDGE_PROTOCOL_VERSION } from './editor-bridge-protocol.js';
+export const EDITOR_SESSION_DIRECTORY = join('.godot', 'godot_agent_loop');
+export const EDITOR_SESSION_FILE = join(EDITOR_SESSION_DIRECTORY, 'editor-session.json');
+/** Secure, reconnectable editor bridges keyed by canonical Godot project path. */
+export class EditorSessionRegistry {
+    options;
+    entries = new Map();
+    trackedProjects = new Set();
+    operationTails = new Map();
+    emittedSignatures = new Map();
+    retryDelaysMs;
+    watcher = null;
+    constructor(options) {
+        this.options = options;
+        this.retryDelaysMs = options.retryDelaysMs ?? [0, 50, 100, 250, 500, 1_000, 2_000];
+    }
+    async ensure(projectPath, timeoutMs = 10_000) {
+        const canonical = canonicalProjectPath(projectPath);
+        return this.serialize(canonical, () => this.ensureDiscovered(canonical, timeoutMs));
+    }
+    async status(projectPath) {
+        const canonical = canonicalProjectPath(projectPath);
+        return this.serialize(canonical, async () => {
+            this.track(canonical);
+            return this.discover(canonical);
+        });
+    }
+    async ensureDiscovered(canonical, timeoutMs) {
+        this.track(canonical);
+        const deadline = Date.now() + Math.max(0, timeoutMs);
+        let last = await this.discover(canonical);
+        let attempt = 0;
+        while (!last.connected && last.state === 'no_editor' && Date.now() < deadline) {
+            const delay = this.retryDelaysMs[Math.min(attempt++, this.retryDelaysMs.length - 1)] ?? 250;
+            if (delay > 0)
+                await new Promise(resolveDelay => setTimeout(resolveDelay, Math.min(delay, Math.max(1, deadline - Date.now()))));
+            last = await this.discover(canonical);
+        }
+        return last;
+    }
+    async send(projectPath, command, params = {}, timeoutMs = 10_000) {
+        const canonical = canonicalProjectPath(projectPath);
+        return this.serialize(canonical, async () => {
+            const session = await this.ensureDiscovered(canonical, Math.min(timeoutMs, 2_000));
+            if (!session.connected)
+                throw new EditorSessionUnavailableError(session);
+            const entry = this.entries.get(canonical);
+            if (!entry)
+                throw new EditorSessionUnavailableError(session);
+            try {
+                const result = await entry.connection.send(command, params, timeoutMs);
+                entry.state = editorStateFromResult(result, entry.state);
+                this.emit(this.publicSession(canonical, entry, true));
+                return result;
+            }
+            catch (error) {
+                // A request can time out while Godot's main thread is briefly busy
+                // importing or saving a resource. The socket remains usable, so keep
+                // the authenticated session instead of forcing a competing reconnect.
+                if (!(error instanceof EditorRequestTimeoutError)) {
+                    entry.connection.disconnect();
+                    this.entries.delete(canonical);
+                }
+                throw error;
+            }
+        });
+    }
+    disconnect(projectPath) {
+        const canonical = canonicalProjectPath(projectPath);
+        const entry = this.entries.get(canonical);
+        entry?.connection.disconnect();
+        this.entries.delete(canonical);
+        this.trackedProjects.delete(canonical);
+        this.emittedSignatures.delete(canonical);
+        const session = emptySession(canonical, 'no_editor', 'Disconnected by caller');
+        this.emit(session);
+        this.stopWatcherIfIdle();
+        return session;
+    }
+    disconnectAll() {
+        for (const entry of this.entries.values())
+            entry.connection.disconnect();
+        this.entries.clear();
+        this.trackedProjects.clear();
+        this.emittedSignatures.clear();
+        if (this.watcher)
+            clearInterval(this.watcher);
+        this.watcher = null;
+    }
+    async discover(canonical) {
+        const recordResult = readDiscoveryRecord(canonical, this.options.processExists ?? processExists);
+        if ('state' in recordResult) {
+            const old = this.entries.get(canonical);
+            old?.connection.disconnect();
+            this.entries.delete(canonical);
+            this.emit(recordResult);
+            return recordResult;
+        }
+        const record = recordResult.record;
+        const existing = this.entries.get(canonical);
+        const sameRecord = existing
+            && existing.record.editor_start_identity === record.editor_start_identity
+            && existing.record.port === record.port;
+        if (sameRecord)
+            return this.publicSession(canonical, existing, true);
+        existing?.connection.disconnect();
+        const connection = this.options.connectionFactory?.(record) ?? new EditorConnection({
+            port: record.port,
+            secret: record.token,
+            protocolVersion: EDITOR_BRIDGE_PROTOCOL_VERSION,
+            serverVersion: this.options.serverVersion,
+        });
+        try {
+            const handshake = await connection.authenticate(2_000);
+            validateHandshake(record, handshake);
+            const state = handshake.paused === true ? 'paused' : 'connected';
+            const entry = { record, connection, state };
+            this.entries.set(canonical, entry);
+            const session = this.publicSession(canonical, entry, true);
+            this.emit(session);
+            return session;
+        }
+        catch (error) {
+            connection.disconnect();
+            if (error instanceof EditorBridgeCompatibilityError) {
+                const session = publicRecord(record, 'protocol_incompatible', false, error.message);
+                this.emit(session);
+                return session;
+            }
+            const pidExists = this.options.processExists ?? processExists;
+            const invalidIdentity = error instanceof EditorSessionIdentityError;
+            const processAlive = pidExists(record.editor_pid);
+            if (invalidIdentity || !processAlive)
+                cleanStaleRecord(canonical);
+            const session = invalidIdentity || !processAlive
+                ? emptySession(canonical, 'no_editor', `Stale editor session removed: ${errorMessage(error)}`)
+                : publicRecord(record, 'no_editor', false, `Live editor session is temporarily unreachable: ${errorMessage(error)}`);
+            this.emit(session);
+            return session;
+        }
+    }
+    publicSession(canonical, entry, reused) {
+        return { ...publicRecord(entry.record, entry.state, true), project_path: canonical, reused };
+    }
+    track(canonical) {
+        this.trackedProjects.add(canonical);
+        if (this.watcher)
+            return;
+        this.watcher = setInterval(() => {
+            for (const projectPath of this.trackedProjects) {
+                // An editor can accept only one agent connection. Do not let the
+                // watcher start a second authentication while an ensure/send is still
+                // establishing or using the project's connection.
+                if (this.operationTails.has(projectPath))
+                    continue;
+                void this.status(projectPath).catch(error => {
+                    this.options.log?.(`Editor discovery failed for ${projectPath}: ${errorMessage(error)}`);
+                });
+            }
+        }, 750);
+        this.watcher.unref();
+    }
+    stopWatcherIfIdle() {
+        if (this.trackedProjects.size > 0 || !this.watcher)
+            return;
+        clearInterval(this.watcher);
+        this.watcher = null;
+    }
+    emit(session) {
+        const signature = `${session.state}:${session.editor_start_identity ?? ''}:${session.connected}`;
+        if (this.emittedSignatures.get(session.project_path) === signature)
+            return;
+        this.emittedSignatures.set(session.project_path, signature);
+        this.options.onStateChange?.(session);
+    }
+    serialize(projectPath, operation) {
+        const previous = this.operationTails.get(projectPath) ?? Promise.resolve();
+        const result = previous.then(operation, operation);
+        const tail = result.then(() => undefined, () => undefined);
+        this.operationTails.set(projectPath, tail);
+        void tail.finally(() => {
+            if (this.operationTails.get(projectPath) === tail)
+                this.operationTails.delete(projectPath);
+        });
+        return result;
+    }
+}
+export class EditorSessionUnavailableError extends Error {
+    session;
+    constructor(session) {
+        super(`Editor session is unavailable (${session.state})${session.reason ? `: ${session.reason}` : ''}`);
+        this.session = session;
+        this.name = 'EditorSessionUnavailableError';
+    }
+}
+export function readDiscoveryRecord(projectPath, pidExists = processExists) {
+    const canonical = canonicalProjectPath(projectPath);
+    const sessionPath = join(canonical, EDITOR_SESSION_FILE);
+    let raw;
+    try {
+        if (process.platform !== 'win32' && (statSync(sessionPath).mode & 0o077) !== 0) {
+            cleanStaleRecord(canonical);
+            return emptySession(canonical, 'no_editor', 'Discovery record permissions were not private');
+        }
+        raw = JSON.parse(readFileSync(sessionPath, 'utf8'));
+    }
+    catch (error) {
+        if (isMissingFile(error))
+            return sessionWithoutDiscoveryRecord(canonical);
+        cleanStaleRecord(canonical);
+        return emptySession(canonical, 'no_editor', `Invalid discovery record: ${errorMessage(error)}`);
+    }
+    if (!isDiscoveryRecord(raw)) {
+        cleanStaleRecord(canonical);
+        return emptySession(canonical, 'no_editor', 'Invalid discovery record schema');
+    }
+    let recordProject;
+    try {
+        recordProject = canonicalProjectPath(raw.project_path);
+    }
+    catch {
+        cleanStaleRecord(canonical);
+        return emptySession(canonical, 'no_editor', 'Discovery record project path is invalid');
+    }
+    if (recordProject !== canonical || !isLoopbackPort(raw.port) || !pidExists(raw.editor_pid)) {
+        cleanStaleRecord(canonical);
+        return {
+            ...sessionWithoutDiscoveryRecord(canonical),
+            reason: 'Stale or cross-project discovery record removed',
+        };
+    }
+    if (raw.protocol_version !== EDITOR_BRIDGE_PROTOCOL_VERSION) {
+        return publicRecord(raw, 'protocol_incompatible', false, `Server protocol ${EDITOR_BRIDGE_PROTOCOL_VERSION}, addon protocol ${raw.protocol_version}`);
+    }
+    return { record: { ...raw, project_path: canonical } };
+}
+function sessionWithoutDiscoveryRecord(projectPath) {
+    const candidates = [
+        { name: 'godot_agent_loop', path: join(projectPath, 'addons', 'godot_agent_loop', 'plugin.cfg') },
+        { name: 'godot_agent_loop_transient', path: join(projectPath, 'addons', 'godot_agent_loop_transient', 'plugin.cfg') },
+    ];
+    const installed = candidates.find(candidate => existsSync(candidate.path));
+    if (!installed) {
+        return emptySession(projectPath, 'addon_missing_restart_required', 'Install and enable addons/godot_agent_loop, then restart Godot once');
+    }
+    let config;
+    try {
+        config = readFileSync(installed.path, 'utf8');
+    }
+    catch (error) {
+        return emptySession(projectPath, 'addon_missing_restart_required', `Installed addon could not be read: ${errorMessage(error)}`);
+    }
+    const protocol = /^protocol_version\s*=\s*"([^"]+)"/m.exec(config)?.[1];
+    if (protocol !== EDITOR_BRIDGE_PROTOCOL_VERSION) {
+        return emptySession(projectPath, 'addon_upgrade_restart_required', `Installed addon protocol ${protocol ?? 'missing'} must be replaced with protocol ${EDITOR_BRIDGE_PROTOCOL_VERSION}, then Godot restarted`);
+    }
+    let projectSource = '';
+    try {
+        projectSource = readFileSync(join(projectPath, 'project.godot'), 'utf8');
+    }
+    catch { /* validation occurs at the tool boundary */ }
+    const enabledSection = /(?:^|\n)\[editor_plugins\]\s*\n([\s\S]*?)(?=\n\[|$)/.exec(projectSource)?.[1] ?? '';
+    const enabledLine = /^enabled\s*=\s*PackedStringArray\((.*)\)\s*$/m.exec(enabledSection)?.[1] ?? '';
+    const enabled = [...enabledLine.matchAll(/"(?:\\.|[^"])*"/g)]
+        .some(match => {
+        try {
+            const value = JSON.parse(match[0]);
+            return value === installed.name || value === `res://addons/${installed.name}/plugin.cfg`;
+        }
+        catch {
+            return false;
+        }
+    });
+    if (!enabled) {
+        return emptySession(projectPath, 'addon_missing_restart_required', `The ${installed.name} addon is installed but disabled; enable it and restart Godot`);
+    }
+    return emptySession(projectPath, 'no_editor', 'A compatible addon is enabled, but no matching editor session is currently discoverable');
+}
+function validateHandshake(record, result) {
+    if (result.error) {
+        throw new Error(typeof result.error === 'string' ? result.error : JSON.stringify(result.error));
+    }
+    if (result.project_path !== record.project_path
+        || result.editor_pid !== record.editor_pid
+        || result.editor_start_identity !== record.editor_start_identity) {
+        throw new EditorSessionIdentityError('Editor handshake identity did not match its discovery record');
+    }
+}
+class EditorSessionIdentityError extends Error {
+}
+function isDiscoveryRecord(value) {
+    if (!value || typeof value !== 'object')
+        return false;
+    const record = value;
+    return typeof record.project_path === 'string'
+        && Number.isInteger(record.editor_pid) && Number(record.editor_pid) > 0
+        && typeof record.editor_start_identity === 'string' && record.editor_start_identity.length > 0
+        && Number.isInteger(record.port)
+        && typeof record.token === 'string' && record.token.length >= 32
+        && typeof record.protocol_version === 'string'
+        && typeof record.addon_version === 'string'
+        && typeof record.godot_version === 'string'
+        && typeof record.created_at === 'string';
+}
+function publicRecord(record, state, connected, reason) {
+    const persistent = existsSync(join(record.project_path, 'addons', 'godot_agent_loop', 'plugin.cfg'));
+    const transient = existsSync(join(record.project_path, 'addons', 'godot_agent_loop_transient', 'plugin.cfg'));
+    return {
+        state,
+        project_path: record.project_path,
+        connected,
+        reused: connected,
+        spawned: false,
+        editor_pid: record.editor_pid,
+        editor_start_identity: record.editor_start_identity,
+        port: record.port,
+        protocol_version: record.protocol_version,
+        addon_version: record.addon_version,
+        godot_version: record.godot_version,
+        created_at: record.created_at,
+        plugin_owned: false,
+        plugin_distribution: persistent ? 'persistent' : transient ? 'transient' : 'unavailable',
+        ...(reason ? { reason } : {}),
+    };
+}
+function emptySession(projectPath, state, reason) {
+    return {
+        state,
+        project_path: 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 ? { reason } : {}),
+    };
+}
+function editorStateFromResult(result, fallback) {
+    const state = result.state;
+    if (typeof state === 'string' && EDITOR_STATES.has(state))
+        return state;
+    if (result.error === 'unsaved_conflict')
+        return 'unsaved_conflict';
+    if (result.paused === true)
+        return 'paused';
+    return fallback === 'paused' ? 'connected' : fallback;
+}
+const EDITOR_STATES = new Set([
+    'connected', 'no_editor', 'addon_missing_restart_required', 'addon_upgrade_restart_required',
+    'protocol_incompatible', 'paused', 'syncing', 'unsaved_conflict',
+]);
+export function canonicalProjectPath(projectPath) {
+    const absolute = resolve(projectPath);
+    try {
+        return realpathSync.native(absolute);
+    }
+    catch {
+        return absolute;
+    }
+}
+function processExists(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return Boolean(error && typeof error === 'object' && 'code' in error && error.code === 'EPERM');
+    }
+}
+function isLoopbackPort(port) {
+    return Number.isInteger(port) && port > 0 && port < 65_536;
+}
+function cleanStaleRecord(projectPath) {
+    try {
+        rmSync(join(projectPath, EDITOR_SESSION_FILE), { force: true });
+    }
+    catch { /* best effort stale cleanup */ }
+}
+function isMissingFile(error) {
+    return Boolean(error && typeof error === 'object' && 'code' in error && error.code === 'ENOENT');
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/build/editor-sync-queue.js

@@ -0,0 +1,135 @@
+import { EditorSessionUnavailableError } from './editor-session-registry.js';
+/** Debounces writes and serializes acknowledged filesystem synchronization per project. */
+export class EditorSyncQueue {
+    options;
+    pending = new Map();
+    tails = new Map();
+    debounceMs;
+    timeoutMs;
+    constructor(options) {
+        this.options = options;
+        this.debounceMs = options.debounceMs ?? 40;
+        this.timeoutMs = options.timeoutMs ?? 15_000;
+    }
+    async enqueue(event) {
+        try {
+            const editorSession = await this.options.status(event.project_path);
+            if (!editorSession.connected)
+                return detachedResult(editorSession);
+        }
+        catch (error) {
+            if (error instanceof EditorSessionUnavailableError)
+                return detachedResult(error.session);
+            return {
+                sync_status: 'failed', editor_session: null, fallback_reason: errorMessage(error),
+                observed_target_state: null, attempts: 1,
+            };
+        }
+        return new Promise(resolve => {
+            const existing = this.pending.get(event.project_path);
+            if (existing) {
+                existing.events.push(event);
+                existing.resolvers.push(resolve);
+                clearTimeout(existing.timer);
+                existing.timer = setTimeout(() => { this.flush(event.project_path); }, this.debounceMs);
+                return;
+            }
+            const batch = {
+                events: [event],
+                resolvers: [resolve],
+                timer: setTimeout(() => { this.flush(event.project_path); }, this.debounceMs),
+            };
+            this.pending.set(event.project_path, batch);
+        });
+    }
+    flush(projectPath) {
+        const batch = this.pending.get(projectPath);
+        if (!batch)
+            return;
+        this.pending.delete(projectPath);
+        const previous = this.tails.get(projectPath) ?? Promise.resolve();
+        const operation = previous.then(() => this.synchronize(projectPath, batch.events));
+        const settled = operation.then(result => {
+            for (const resolve of batch.resolvers)
+                resolve(result);
+        }, error => {
+            const result = {
+                sync_status: 'failed', editor_session: null, fallback_reason: errorMessage(error),
+                observed_target_state: null, attempts: 1,
+            };
+            for (const resolve of batch.resolvers)
+                resolve(result);
+        });
+        const tail = settled.then(() => undefined, () => undefined);
+        this.tails.set(projectPath, tail);
+        void tail.finally(() => {
+            if (this.tails.get(projectPath) === tail)
+                this.tails.delete(projectPath);
+        });
+    }
+    async synchronize(projectPath, events) {
+        const final = events.at(-1);
+        const params = {
+            project_path: projectPath,
+            command: final.command,
+            changes: events.map(event => ({
+                command: event.command,
+                scene_path: event.scene_path ?? null,
+                resource_path: event.resource_path ?? null,
+                focus_path: event.focus_path ?? null,
+            })),
+            ...(final.scene_path ? { scene_path: final.scene_path } : {}),
+            ...(final.resource_path ? { resource_path: final.resource_path } : {}),
+            ...(final.focus_path ? { focus_path: final.focus_path } : {}),
+        };
+        try {
+            const initialSession = await this.options.status(projectPath);
+            if (!initialSession.connected) {
+                return detachedResult(initialSession);
+            }
+            const response = await this.options.send(projectPath, params, this.timeoutMs);
+            const editorSession = await this.options.status(projectPath);
+            const conflict = response.error === 'unsaved_conflict' || response.state === 'unsaved_conflict';
+            return {
+                sync_status: conflict ? 'conflict' : response.success === true ? 'acknowledged' : 'failed',
+                editor_session: editorSession,
+                fallback_reason: conflict ? 'The open scene has unsaved human changes; disk state was not reloaded.'
+                    : response.success === true ? null : errorMessage(response.error ?? 'Editor did not acknowledge synchronization'),
+                observed_target_state: asRecord(response.observed_target_state) ?? response,
+                attempts: 1,
+            };
+        }
+        catch (error) {
+            if (error instanceof EditorSessionUnavailableError) {
+                return {
+                    sync_status: 'detached', editor_session: error.session,
+                    fallback_reason: 'No attached editor was available to acknowledge the persisted mutation.',
+                    observed_target_state: null, attempts: 1,
+                };
+            }
+            const timeout = /timed out/i.test(errorMessage(error));
+            let session = null;
+            try {
+                session = await this.options.status(projectPath);
+            }
+            catch { /* status is supplemental */ }
+            return {
+                sync_status: timeout ? 'timeout' : 'failed', editor_session: session,
+                fallback_reason: errorMessage(error), observed_target_state: null, attempts: 1,
+            };
+        }
+    }
+}
+function detachedResult(editorSession) {
+    return {
+        sync_status: 'detached', editor_session: editorSession,
+        fallback_reason: `No attached editor was available to acknowledge the persisted mutation (${editorSession.state}).`,
+        observed_target_state: null, attempts: 1,
+    };
+}
+function asRecord(value) {
+    return value && typeof value === 'object' && !Array.isArray(value) ? value : null;
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}