@beremaran/godot-agent-loop 1.0.1 → 1.1.0

package/agent-plugin/.claude-plugin/plugin.json

@@ -2,7 +2,7 @@
   "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "godot-agent-loop",
   "displayName": "Godot Agent Loop",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "description": "Build, playtest, and prove Godot games with an MCP automation loop.",
   "author": {
     "name": "Berke Arslan"

package/agent-plugin/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "godot-agent-loop",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "description": "Build, playtest, and prove Godot games with an MCP automation loop.",
   "author": {
     "name": "Berke Arslan",

package/agent-plugin/.mcp.json

@@ -4,7 +4,7 @@
       "command": "npx",
       "args": [
         "-y",
-        "@beremaran/godot-agent-loop@1.0.1"
+        "@beremaran/godot-agent-loop@1.1.0"
       ],
       "env": {
         "GODOT_MCP_TOOL_SURFACE": "compact"

package/agent-plugin/adapter-manifest.json

@@ -2,15 +2,15 @@
   "$schema": "../docs/agent-adapter.schema.json",
   "name": "godot-agent-loop",
   "displayName": "Godot Agent Loop",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "description": "Build, playtest, and prove Godot games with an MCP automation loop.",
   "package": "@beremaran/godot-agent-loop",
   "mcp": {
-    "command": ["npx", "-y", "@beremaran/godot-agent-loop@1.0.1"],
+    "command": ["npx", "-y", "@beremaran/godot-agent-loop@1.1.0"],
     "environment": {
       "GODOT_MCP_TOOL_SURFACE": "compact"
     },
-    "defaultToolCount": 39,
+    "defaultToolCount": 40,
     "discoveryTool": "godot_tools"
   },
   "skills": [

package/agent-plugin/pi/extension.ts

@@ -98,7 +98,7 @@ export default function godotAgentLoopPi(pi: ExtensionAPI) {
     try {
       const launch = resolvePiServerLaunch();
       const next = new Client(
-        { name: 'godot-agent-loop-pi', version: '1.0.1' },
+        { name: 'godot-agent-loop-pi', version: '1.1.0' },
         {
           capabilities: {},
           listChanged: {

package/agent-plugin/skills/build-godot-game/SKILL.md

@@ -9,6 +9,9 @@ Use the MCP tools for project changes and engine evidence. Do not add MCP
 autoloads, addons, or bridge files; `run_project` installs and removes its runtime
 bridge automatically.
 
+Godot Agent Loop supports Godot 4.7 or later. Report an older project/engine as
+outside the supported boundary before authoring.
+
 ## Workflow
 
 1. Inspect before writing.
@@ -17,25 +20,43 @@ bridge automatically.
    - Call `create_project` only when `project.godot` is absent.
    - Define the playable loop, controls, visible feedback, and objective before
      choosing nodes.
+   - If the user wants to watch, call `editor_session` with `ensure` before
+     authoring. Continue detached only when the returned state requires it, and
+     report every fallback or unsaved conflict.
 2. Author the smallest complete game.
-   - Use `create_scene` and `add_node` for the scene tree.
+   - Prefer `editor_transaction` or editor-routed `create_scene`, `add_node`,
+     node mutation, and supported resource tools while attached. Group one
+     coherent human-readable change into one undo step.
    - Use `create_script` or `write_file`, then `attach_script`.
+   - Persist meaningful game hierarchy and resources in scenes. Use scripts for
+     behavior; build most persistent nodes in `_ready()` only when procedural
+     generation is requested or justified, and report that choice.
    - Use `manage_input_map` for named actions and `set_main_scene` for startup.
    - Use `godot_tools` `search` then `describe` when a specialized node/resource
      tool is needed; invoke it with `godot_tools` `call`.
 3. Validate static artifacts.
    - Call `validate_scripts` and fix every error.
    - Re-read the scene and project settings rather than trusting write responses.
+   - Run `analyze_project_integrity` and require
+     `main_scene_structure.meaningful_persisted_structure`, unless an explicit
+     procedural design was passed as `allowProceduralMainScene`.
 4. Run and exercise the game.
-   - Call `run_project`, wait for connection, then inspect with
+   - Call realtime `run_project` for watched play, then inspect with
      `game_get_scene_tree`, `game_get_ui`, and `game_screenshot`.
-   - Inject the documented controls with `game_key_press`, `game_click`, or the
-     relevant input tool. Observe state before and after input.
+   - Prefer `game_wait_until` and `game_scenario` over repeated polling. Inject
+     controls, observe state before and after input, and keep waits bounded.
 5. Assert and finish.
    - Prefer `verify_project` for bounded node/log/screenshot assertions and
      `run_project_tests` for project tests.
    - Prove both ordinary play and the win/lose transition independently.
    - Inspect `get_debug_output` and `game_get_errors`; stop the project when done.
 
+Before adding high-volume particles, trails, lights, shockwaves, fireworks, or
+audio voices, establish an explicit frame/object/voice budget. For external
+assets, verify source and license, record attribution or CC0 status, and confirm
+the imported asset independently loads and renders or plays.
+
 Keep the project tree game-only. Remove temporary probes, screenshots, and test
-artifacts unless the user requested them as deliverables.
+artifacts and MCP-owned transient bridges unless requested as deliverables.
+Never remove a user's persistent addon. Report warnings, leaks, fallbacks,
+unsupported metrics, and subjective polish that still needs human review.

package/agent-plugin/skills/debug-godot-game/SKILL.md

@@ -8,11 +8,14 @@ description: Diagnose and fix a Godot 4 game that crashes, logs errors, renders
 Preserve the failing evidence, isolate one cause, make the smallest repair, and
 rerun the original reproduction. Do not begin with speculative edits.
 
+Godot Agent Loop supports Godot 4.7 or later. Report an older project/engine as
+outside the supported boundary before diagnosing engine behavior.
+
 ## Workflow
 
 1. Reproduce.
-   - Call `run_project` and repeat the user's input with `game_key_press`,
-     `game_click`, or the relevant input tool.
+   - Call realtime `run_project` for visual/timing complaints. Capture a
+     baseline, then repeat the user's exact input or bounded `game_scenario`.
    - Capture `get_debug_output`, `game_get_errors`, `game_get_logs`, scene/UI
      state, and a screenshot when rendering is involved.
 2. Classify the boundary.
@@ -21,17 +24,27 @@ rerun the original reproduction. Do not begin with speculative edits.
      (discover it through `godot_tools` when hidden).
    - Runtime state: use `game_get_scene_tree`, `game_get_ui`, and
      `game_get_node_info`.
-   - Timing/input: use deterministic `game_wait`, then query input or time tools
-     through `godot_tools` if needed.
+   - Timing/input: use `game_wait_until`; use deterministic waits only for
+     repeatable simulation checks, not as evidence of displayed frame pacing.
 3. Form one falsifiable hypothesis. Gather a second observation that distinguishes
    it from the nearest alternative. Use privileged property/method inspection only
    when the user enabled the `reflection` group; avoid `game_eval` by default.
+   - Change one independent variable per trial and rerun the same stress path.
+     Never infer one cause after disabling particles, shockwaves, audio, camera
+     shake, and other systems together.
+   - Test camera shake and any persistent per-frame effect independently.
+   - For a visual freeze or stutter, collect realtime FPS/frame-time and
+     process/render/GPU availability. Simulation counters alone are insufficient;
+     report GPU time as unavailable when the platform does not expose it.
 4. Stop the project before editing persistent files. Apply the minimal fix with
    the matching scene, script, resource, or settings tool.
 5. Validate and rerun.
    - Run static validation first.
-   - Repeat the exact failing input and observation.
+   - Repeat the exact baseline/stress/recovery input and observation.
    - Use `verify_project` or `run_project_tests` for stable regression evidence.
    - Confirm errors are gone and adjacent behavior still works.
-6. Stop the project and remove temporary probes. Report the root cause, changed
-   artifact, reproduction, and independent passing evidence.
+6. Stop the project and remove temporary probes and MCP-owned transient bridge
+   artifacts. Report the root cause, isolated variable, changed artifact,
+   reproduction, independent passing evidence, every warning/error/ObjectDB or
+   orphan diagnostic, cleanup result, fallback, and unsupported metric. Never
+   remove a user's persistent addon.

package/agent-plugin/skills/ship-godot-game/SKILL.md

@@ -8,6 +8,9 @@ description: Prepare and verify a Godot 4 game for a reproducible release. Use f
 Treat shipping as an evidence gate. Preserve the project until every requested
 target has a reproducible artifact and a recorded independent check.
 
+Godot Agent Loop supports Godot 4.7 or later. Do not claim release readiness on
+an older engine through this workflow.
+
 ## Workflow
 
 1. Establish the release boundary.
@@ -21,11 +24,15 @@ target has a reproducible artifact and a recorded independent check.
      imports without deleting source assets.
    - Inspect enabled addons with `manage_addon`; do not update or remove
      user-managed addons unless the user explicitly requests it.
+   - Require meaningful persisted main-scene structure or record the explicit
+     procedural design exception. Record every editor/file-backed fallback.
 3. Prove project behavior.
    - Discover and run project tests with `run_project_tests`.
    - Use `verify_project` for bounded startup, scene, log, and screenshot
      assertions. Exercise required win, lose, menu, save, or input paths.
-   - Inspect `game_get_errors` and debug output, then stop the project.
+   - Prefer bounded scenarios and waits. Inspect `game_get_errors`, debug output,
+     performance metric availability, warnings, and live/static leak evidence,
+     then stop the project.
 4. Verify build-specific requirements.
    - Run `verify_dotnet_project` for C# projects and require a successful restore
      and build with the selected Godot .NET version.
@@ -38,9 +45,12 @@ target has a reproducible artifact and a recorded independent check.
      visible behavior with the acceptance criteria.
 6. Tear down and report.
    - Stop all MCP-owned projects/editors and remove only generated probes,
-     temporary exports, screenshots, and logs that are not deliverables.
+     temporary exports, screenshots, logs, and MCP-owned transient bridge files
+     that are not deliverables. Never remove a user's persistent addon.
    - Recheck the project tree and processes. Report exact commands, versions,
-     targets, hashes or sizes, assertions, limitations, and any unverified target.
+     targets, hashes or sizes, assertions, fallbacks, warnings/leaks, cleanup
+     state, unsupported metrics, subjective/manual-review gaps, limitations, and
+     any unverified target.
 
 Never claim an unavailable platform, signing identity, export template, or .NET
 toolchain passed. Separate locally proven artifacts from CI-only or manual gates.

package/agent-plugin/skills/verify-godot-change/SKILL.md

@@ -8,28 +8,43 @@ description: Verify a Godot 4 project change with static checks and independent
 Turn the requested behavior into observable acceptance criteria before running
 the game. A successful mutation response is not evidence that the change works.
 
+Godot Agent Loop supports Godot 4.7 or later. Report verification on an older
+engine as outside the supported boundary.
+
 ## Workflow
 
 1. Check saved state.
    - Use `validate_script` or `validate_scripts` for code.
    - Use `read_scene`, `read_project_settings`, or `read_file` to confirm the
      intended artifact persisted.
+   - Run `analyze_project_integrity` when scene structure changed. Flag a trivial
+     scripted main scene unless procedural construction is an explicit design.
 2. Prefer compound verification.
    - Use `verify_project` for bounded startup, node/group/log assertions,
      optional screenshot evidence, and deterministic teardown.
    - Use `run_project_tests` with `discover` before `run` when tests exist.
+   - Prefer `game_wait_until` and `game_scenario` for bounded interaction evidence
+     rather than assembling short polling loops.
 3. Exercise interactive behavior when a compound assertion is insufficient.
-   - Call `run_project`, then observe the baseline with `game_get_scene_tree`,
+   - Call realtime `run_project` for behavior a person watches, then observe the baseline with `game_get_scene_tree`,
      `game_get_ui`, `game_get_node_info`, and/or `game_screenshot`.
    - Inject input with `game_key_press`, `game_click`, or a specialized input tool
      discovered through `godot_tools`.
-   - Wait only as long as the behavior requires with `game_wait`, then make the
+   - Wait only as long as the behavior requires with `game_wait_until`, then make the
      same observation again and compare the changed state.
 4. Check negative evidence.
    - Inspect `game_get_errors`, `get_debug_output`, and relevant logs.
    - Verify unrelated state still works when the change has regression risk.
+   - Treat warnings, ObjectDB leaks, orphan/resource diagnostics, bridge cleanup
+     failures, fallbacks, and unavailable metrics as evidence to resolve or
+     disclose, even when the positive assertion passes.
 5. Stop the project and report the exact assertions and evidence. If any
    acceptance criterion remains unobserved, say verification is incomplete.
 
+Separate objective evidence (persisted values, node state, logs, timing,
+rendered pixels) from subjective review (feel, audio quality, composition, and
+polish). A structural check or screenshot proves neither aesthetics nor sound;
+label those as manual review when no human judgment was obtained.
+
 Use privileged reflection only when the required group is already enabled; do
 not replace observable gameplay evidence with `game_eval`.

package/build/authoring-session-manager.js

@@ -37,6 +37,14 @@ export class AuthoringSessionManager {
     }
     async execute(backend, params, projectPath) {
         return this.serialize(async () => {
+            const editorAttempt = await this.options.tryEditorOperation?.(backend.command, params, projectPath);
+            if (editorAttempt?.handled) {
+                if (!editorAttempt.result) {
+                    throw new Error('Editor authoring router handled an operation without returning a result');
+                }
+                return editorAttempt.result;
+            }
+            const editorFallbackReason = editorAttempt?.fallbackReason;
             await this.ensureSession(projectPath);
             const state = this.current;
             if (!state?.connection.isConnected) {
@@ -63,13 +71,28 @@ export class AuthoringSessionManager {
                 if (isMutatingAuthoringCommand(backend.command, params)) {
                     const scenePath = affectedScenePath(params);
                     const focusPath = authoringFocusPath(backend.command, params);
-                    this.options.onProjectWrite?.({
+                    const syncResult = await this.options.onProjectWrite?.({
                         project_path: projectPath,
                         command: backend.command,
                         ...(scenePath === undefined ? {} : { scene_path: toResourcePath(scenePath) }),
                         ...(typeof params.resourcePath === 'string' ? { resource_path: toResourcePath(params.resourcePath) } : {}),
                         ...(focusPath === undefined ? {} : { focus_path: focusPath }),
                     });
+                    if (syncResult) {
+                        return {
+                            stdout: JSON.stringify({
+                                ...payload,
+                                backend: 'authoring-session',
+                                sync_status: syncResult.sync_status ?? 'failed',
+                                editor_session: syncResult.editor_session ?? null,
+                                fallback_reason: editorFallbackReason ?? syncResult.fallback_reason ?? null,
+                                observed_target_state: syncResult.observed_target_state ?? null,
+                            }),
+                            stderr: '',
+                            exitCode: 0,
+                            signal: null,
+                        };
+                    }
                 }
                 return {
                     stdout: typeof payload.stdout === 'string' ? payload.stdout : JSON.stringify(payload),

package/build/domain-tool-registries.js

@@ -30,9 +30,13 @@ export function createLifecycleToolRegistry(handlers) {
     return {
         'godot_tools': args => handlers.handleGodotTools(args),
         'launch_editor': args => handlers.handleLaunchEditor(args),
+        'editor_session': args => handlers.handleEditorSession(args),
         'editor_control': args => handlers.handleEditorControl(args),
+        'editor_transaction': args => handlers.handleEditorTransaction(args),
         'run_project': args => handlers.handleRunProject(args),
         'verify_project': args => handlers.handleVerifyProject(args),
+        'game_wait_until': args => handlers.handleGameWaitUntil(args),
+        'game_scenario': args => handlers.handleGameScenario(args),
         'get_debug_output': () => handlers.handleGetDebugOutput(),
         'stop_project': () => handlers.handleStopProject(),
         'get_godot_version': () => handlers.handleGetGodotVersion(),
@@ -92,7 +96,7 @@ export function createProjectToolRegistry(handlers) {
 }
 export function createGameToolRegistry(handlers) {
     return {
-        'game_screenshot': () => handlers.handleGameScreenshot(),
+        'game_screenshot': args => handlers.handleGameScreenshot(args),
         'game_visual_regression': args => handlers.handleGameVisualRegression(args),
         'game_click': args => handlers.handleGameClick(args),
         'game_key_press': args => handlers.handleGameKeyPress(args),

package/build/editor-authoring-router.js

@@ -0,0 +1,228 @@
+/** Maps legacy authoring commands onto atomic, undoable editor transactions. */
+export class EditorAuthoringRouter {
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    async tryExecute(command, params, projectPath) {
+        const resourceRequest = editorResourceTransactionFor(command, params);
+        const request = resourceRequest ?? editorTransactionFor(command, params);
+        if (!request) {
+            return {
+                handled: false,
+                fallbackReason: `The editor backend does not support ${command}; using the declared authoring fallback`,
+            };
+        }
+        let session = await this.options.status(projectPath);
+        // A cooperative-lock probe or busy editor frame can briefly drop the TCP
+        // session. Reattach when discovery still identifies a live editor, but do
+        // not delay ordinary headless authoring when no editor record exists.
+        if (!session.connected && session.editor_pid !== null) {
+            session = await this.options.ensure(projectPath, 5_000);
+        }
+        if (!session.connected) {
+            return {
+                handled: false,
+                fallbackReason: `Editor session unavailable (${session.state})${session.reason ? `: ${session.reason}` : ''}`,
+            };
+        }
+        try {
+            const response = await this.options.send(projectPath, resourceRequest ? 'resource_transaction' : 'transaction', request, 30_000);
+            if (typeof response.error === 'string' && response.error.length > 0) {
+                return failedAttempt(`Editor transaction failed: ${response.error}`, response);
+            }
+            if (response.success !== true) {
+                return failedAttempt('Editor transaction returned an invalid result', response);
+            }
+            return {
+                handled: true,
+                result: {
+                    stdout: JSON.stringify({
+                        ...response,
+                        backend: 'editor',
+                        sync_status: 'acknowledged',
+                        editor_session: session,
+                        fallback_reason: null,
+                    }),
+                    stderr: '',
+                    exitCode: 0,
+                    signal: null,
+                },
+            };
+        }
+        catch (error) {
+            // The transaction may already have reached Godot. Never retry it through
+            // another backend, because doing so could duplicate a partial mutation.
+            return failedAttempt(`Editor transaction transport failed after dispatch: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+}
+function editorResourceTransactionFor(command, params) {
+    const resourcePath = stringParam(params, 'resourcePath');
+    if (!resourcePath)
+        return null;
+    if (command === 'authoring_create_resource') {
+        const resourceType = stringParam(params, 'resourceType');
+        if (!resourceType)
+            return null;
+        return {
+            resource_path: toResourcePath(resourcePath),
+            resource_type: resourceType,
+            name: `Create ${resourceType}`,
+            properties: objectParam(params, 'properties') ?? {},
+        };
+    }
+    if (command === 'authoring_manage_resource' && params.action === 'modify') {
+        return {
+            resource_path: toResourcePath(resourcePath),
+            name: `Modify ${resourcePath.split('/').at(-1) ?? 'resource'}`,
+            properties: objectParam(params, 'properties') ?? {},
+        };
+    }
+    return null;
+}
+function failedAttempt(message, details) {
+    return {
+        handled: true,
+        result: {
+            stdout: '',
+            stderr: details ? `${message}: ${JSON.stringify(details)}` : message,
+            exitCode: 1,
+            signal: null,
+        },
+    };
+}
+function editorTransactionFor(command, params) {
+    const scenePath = stringParam(params, 'scenePath');
+    if (!scenePath)
+        return null;
+    const base = {
+        scene_path: toResourcePath(scenePath),
+        save: true,
+    };
+    switch (command) {
+        case 'authoring_create_scene':
+            return {
+                ...base,
+                name: 'Create scene',
+                root_type: stringParam(params, 'rootNodeType') ?? 'Node2D',
+                operations: [{ op: 'save' }],
+                focus_path: '.',
+            };
+        case 'authoring_add_node': {
+            const nodeName = stringParam(params, 'nodeName');
+            const parentPath = normalizeNodePath(stringParam(params, 'parentNodePath') ?? '.');
+            if (!nodeName)
+                return null;
+            return {
+                ...base,
+                name: `Add ${nodeName}`,
+                operations: [{
+                        op: 'add_node',
+                        parent_path: parentPath,
+                        node_type: stringParam(params, 'nodeType') ?? 'Node',
+                        node_name: nodeName,
+                        properties: objectParam(params, 'properties') ?? {},
+                    }],
+                focus_path: joinNodePath(parentPath, nodeName),
+            };
+        }
+        case 'authoring_modify_node': {
+            const nodePath = normalizeNodePath(stringParam(params, 'nodePath') ?? '.');
+            return {
+                ...base,
+                name: `Modify ${nodePath}`,
+                operations: [{ op: 'set_properties', node_path: nodePath, properties: objectParam(params, 'properties') ?? {} }],
+                focus_path: nodePath,
+            };
+        }
+        case 'authoring_remove_node': {
+            const nodePath = normalizeNodePath(stringParam(params, 'nodePath') ?? '.');
+            return {
+                ...base,
+                name: `Remove ${nodePath}`,
+                operations: [{ op: 'remove_node', node_path: nodePath }],
+                focus_path: parentNodePath(nodePath),
+            };
+        }
+        case 'authoring_attach_script': {
+            const nodePath = normalizeNodePath(stringParam(params, 'nodePath') ?? '.');
+            const scriptPath = stringParam(params, 'scriptPath');
+            if (!scriptPath)
+                return null;
+            return {
+                ...base,
+                name: `Attach script to ${nodePath}`,
+                operations: [{ op: 'attach_script', node_path: nodePath, script_path: toResourcePath(scriptPath) }],
+                focus_path: nodePath,
+            };
+        }
+        case 'authoring_save_scene':
+            if (stringParam(params, 'newPath'))
+                return null;
+            return { ...base, name: 'Save scene', operations: [{ op: 'save' }], focus_path: '.' };
+        case 'authoring_manage_scene_structure':
+            return manageStructureTransaction(base, params);
+        default:
+            return null;
+    }
+}
+function manageStructureTransaction(base, params) {
+    const action = stringParam(params, 'action');
+    const nodePath = normalizeNodePath(stringParam(params, 'nodePath') ?? '.');
+    if (action === 'rename') {
+        const newName = stringParam(params, 'newName');
+        if (!newName)
+            return null;
+        return {
+            ...base,
+            name: `Rename ${nodePath}`,
+            operations: [{ op: 'rename_node', node_path: nodePath, name: newName }],
+            focus_path: joinNodePath(parentNodePath(nodePath), newName),
+        };
+    }
+    if (action === 'duplicate') {
+        return {
+            ...base,
+            name: `Duplicate ${nodePath}`,
+            operations: [{ op: 'duplicate_node', node_path: nodePath }],
+        };
+    }
+    if (action === 'move') {
+        const newParentPath = stringParam(params, 'newParentPath');
+        if (!newParentPath)
+            return null;
+        const normalizedParent = normalizeNodePath(newParentPath);
+        return {
+            ...base,
+            name: `Move ${nodePath}`,
+            operations: [{ op: 'reparent_node', node_path: nodePath, new_parent_path: normalizedParent }],
+            focus_path: joinNodePath(normalizedParent, nodePath.split('/').at(-1) ?? nodePath),
+        };
+    }
+    return null;
+}
+function stringParam(params, key) {
+    const value = params[key];
+    return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+function objectParam(params, key) {
+    const value = params[key];
+    return value && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+function toResourcePath(path) {
+    return path.startsWith('res://') ? path : `res://${path.replace(/^\/+/, '')}`;
+}
+function normalizeNodePath(path) {
+    const normalized = path.replace(/^\/?root\/?/, '').replace(/^\.\//, '').replace(/\/$/, '');
+    return normalized.length > 0 ? normalized : '.';
+}
+function parentNodePath(path) {
+    const slash = path.lastIndexOf('/');
+    return slash < 0 ? '.' : path.slice(0, slash);
+}
+function joinNodePath(parent, child) {
+    return parent === '.' ? child : `${parent.replace(/\/$/, '')}/${child}`;
+}

package/build/editor-bridge-protocol.js

@@ -1 +1,2 @@
-export const EDITOR_BRIDGE_PROTOCOL_VERSION = '1';
+/** Protocol 2 replaces fixed environment credentials with per-editor discovery. */
+export const EDITOR_BRIDGE_PROTOCOL_VERSION = '2';

package/build/editor-connection.js

@@ -2,6 +2,8 @@ import { createConnection } from 'node:net';
 import { EDITOR_BRIDGE_PROTOCOL_VERSION } from './editor-bridge-protocol.js';
 export class EditorBridgeCompatibilityError extends Error {
 }
+export class EditorRequestTimeoutError extends Error {
+}
 /** Authenticated newline-delimited bridge to the optional EditorPlugin. */
 export class EditorConnection {
     options;
@@ -16,16 +18,40 @@ export class EditorConnection {
     }
     async send(command, params = {}, timeoutMs = 10_000) {
         await this.ensureConnected(timeoutMs);
-        if (command !== 'handshake')
-            await this.ensureHandshake(timeoutMs);
+        if (command === 'handshake')
+            return this.authenticate(timeoutMs);
+        await this.authenticate(timeoutMs);
         return this.request(command, params, timeoutMs);
     }
+    async authenticate(timeoutMs = 10_000) {
+        await this.ensureConnected(timeoutMs);
+        if (!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}`);
+                }
+                return result;
+            });
+        }
+        try {
+            return await this.handshaking;
+        }
+        catch (error) {
+            this.disconnect();
+            throw error;
+        }
+    }
     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`));
+                reject(new EditorRequestTimeoutError(`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`);
@@ -41,27 +67,6 @@ export class EditorConnection {
         }
         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;

package/build/editor-mutation-guard.js

@@ -13,8 +13,10 @@ export class EditorMutationGuard {
     async check(name, args) {
         if (!isToolCallMutating(name, args))
             return undefined;
+        if (typeof args.projectPath !== 'string')
+            return undefined;
         try {
-            const state = await this.readDriverState(EDITOR_DRIVER_STATE_COMMAND, {}, EDITOR_DRIVER_STATE_TIMEOUT_MS);
+            const state = await this.readDriverState(args.projectPath, EDITOR_DRIVER_STATE_COMMAND, {}, EDITOR_DRIVER_STATE_TIMEOUT_MS);
             if (state.paused === true)
                 return createErrorResponse(AGENT_MUTATIONS_PAUSED_MESSAGE);
         }