@beremaran/godot-agent-loop 1.0.0

package/agent-plugin/pi/extension.ts

@@ -0,0 +1,136 @@
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
+import type { Tool } from '@modelcontextprotocol/sdk/types.js';
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const PACKAGE_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..', '..');
+const SERVER_ENTRY = join(PACKAGE_ROOT, 'build', 'index.js');
+const ADAPTER_MANIFEST = join(PACKAGE_ROOT, 'agent-plugin', 'adapter-manifest.json');
+
+interface PiServerLaunchOptions {
+  localServerEntry?: string;
+  adapterManifestPath?: string;
+  exists?: (path: string) => boolean;
+}
+
+export function resolvePiServerLaunch(options: PiServerLaunchOptions = {}): { command: string; args: string[] } {
+  const localServerEntry = options.localServerEntry ?? SERVER_ENTRY;
+  if ((options.exists ?? existsSync)(localServerEntry)) {
+    return { command: process.execPath, args: [localServerEntry] };
+  }
+
+  const manifestPath = options.adapterManifestPath ?? ADAPTER_MANIFEST;
+  const manifest = JSON.parse(readFileSync(manifestPath, 'utf8')) as { mcp?: { command?: unknown } };
+  const pinned = manifest.mcp?.command;
+  if (!Array.isArray(pinned) || pinned.length === 0 || !pinned.every(value => typeof value === 'string')) {
+    throw new Error(`Invalid MCP command in ${manifestPath}`);
+  }
+  return { command: pinned[0], args: pinned.slice(1) };
+}
+
+function inheritedEnvironment(): Record<string, string> {
+  const environment = Object.fromEntries(
+    Object.entries(process.env).filter((entry): entry is [string, string] => entry[1] !== undefined),
+  );
+  delete environment.VITEST;
+  environment.NODE_ENV = 'production';
+  return environment;
+}
+
+function resultContent(content: unknown[]): ({ type: 'text'; text: string } | { type: 'image'; data: string; mimeType: string })[] {
+  return content.map(item => {
+    const value = item as Record<string, unknown>;
+    if (value.type === 'text' && typeof value.text === 'string') {
+      return { type: 'text' as const, text: value.text };
+    }
+    if (value.type === 'image' && typeof value.data === 'string' && typeof value.mimeType === 'string') {
+      return { type: 'image' as const, data: value.data, mimeType: value.mimeType };
+    }
+    return { type: 'text' as const, text: JSON.stringify(value) };
+  });
+}
+
+function errorText(content: unknown[]): string {
+  return resultContent(content).map(item => item.type === 'text' ? item.text : `[image: ${item.mimeType}]`).join('\n');
+}
+
+export default function godotAgentLoopPi(pi: ExtensionAPI) {
+  let client: Client | undefined;
+
+  const close = async () => {
+    const active = client;
+    client = undefined;
+    if (active) await active.close().catch(() => undefined);
+  };
+
+  const registerTools = (tools: Tool[]) => {
+    for (const tool of tools) {
+      pi.registerTool({
+        name: tool.name,
+        label: tool.annotations?.title ?? tool.name,
+        description: tool.description ?? `Call the ${tool.name} Godot Agent Loop tool.`,
+        parameters: tool.inputSchema as never,
+        async execute(_toolCallId, params, signal) {
+          if (!client) throw new Error('Godot Agent Loop MCP server is not connected');
+          const result = await client.callTool(
+            { name: tool.name, arguments: params as Record<string, unknown> },
+            undefined,
+            { signal },
+          );
+          if (result.isError) throw new Error(errorText(result.content));
+          return {
+            content: resultContent(result.content),
+            details: {
+              structuredContent: result.structuredContent,
+              metadata: result._meta,
+            },
+          };
+        },
+      });
+    }
+  };
+
+  pi.on('session_start', async (_event, ctx) => {
+    await close();
+    try {
+      const launch = resolvePiServerLaunch();
+      const next = new Client(
+        { name: 'godot-agent-loop-pi', version: '1.0.0' },
+        {
+          capabilities: {},
+          listChanged: {
+            tools: {
+              onChanged(error, result) {
+                if (error) {
+                  ctx.ui.notify(`Godot Agent Loop tool refresh failed: ${error.message}`, 'warning');
+                  return;
+                }
+                if (result) registerTools(result.tools);
+              },
+            },
+          },
+        },
+      );
+      const transport = new StdioClientTransport({
+        command: launch.command,
+        args: launch.args,
+        env: { ...inheritedEnvironment(), GODOT_MCP_TOOL_SURFACE: 'compact' },
+        stderr: 'pipe',
+      });
+      await next.connect(transport);
+      client = next;
+      const listed = await next.listTools();
+      registerTools(listed.tools);
+      ctx.ui.notify(`Godot Agent Loop connected (${listed.tools.length} tools)`, 'info');
+    } catch (error) {
+      await close();
+      const message = error instanceof Error ? error.message : String(error);
+      ctx.ui.notify(`Godot Agent Loop failed to start: ${message}`, 'error');
+    }
+  });
+
+  pi.on('session_shutdown', close);
+}

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

@@ -0,0 +1,41 @@
+---
+name: build-godot-game
+description: Build a new playable Godot 4 game or substantial gameplay slice through Godot Agent Loop. Use for requests to create a game from an empty project or project path, add a complete mechanic, or deliver a playable scene with input, visible state, and win/lose behavior.
+---
+
+# Build a Godot game
+
+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.
+
+## Workflow
+
+1. Inspect before writing.
+   - Call `list_project_files`, `read_project_settings`, and `read_scene` when a
+     project exists.
+   - Call `create_project` only when `project.godot` is absent.
+   - Define the playable loop, controls, visible feedback, and objective before
+     choosing nodes.
+2. Author the smallest complete game.
+   - Use `create_scene` and `add_node` for the scene tree.
+   - Use `create_script` or `write_file`, then `attach_script`.
+   - 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.
+4. Run and exercise the game.
+   - Call `run_project`, wait for connection, 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.
+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.
+
+Keep the project tree game-only. Remove temporary probes, screenshots, and test
+artifacts unless the user requested them as deliverables.

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

@@ -0,0 +1,37 @@
+---
+name: debug-godot-game
+description: Diagnose and fix a Godot 4 game that crashes, logs errors, renders incorrectly, ignores input, has wrong scene state, or fails a gameplay expectation. Use for runtime bugs, script failures, broken scenes/resources, flaky behavior, and regressions that need reproduction before repair.
+---
+
+# Debug a Godot game
+
+Preserve the failing evidence, isolate one cause, make the smallest repair, and
+rerun the original reproduction. Do not begin with speculative edits.
+
+## Workflow
+
+1. Reproduce.
+   - Call `run_project` and repeat the user's input with `game_key_press`,
+     `game_click`, or the relevant input tool.
+   - Capture `get_debug_output`, `game_get_errors`, `game_get_logs`, scene/UI
+     state, and a screenshot when rendering is involved.
+2. Classify the boundary.
+   - Parse/startup: run `validate_scripts` and inspect project/main-scene settings.
+   - Saved scene/resource: use `read_scene`, `read_file`, and `manage_resource`
+     (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.
+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.
+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.
+   - 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.

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

@@ -0,0 +1,46 @@
+---
+name: ship-godot-game
+description: Prepare and verify a Godot 4 game for a reproducible release. Use for export readiness, project test gates, .NET/C# verification, addon and import integrity, export artifact inspection, smoke runs, release evidence, or deterministic teardown before shipping.
+---
+
+# Ship a Godot game
+
+Treat shipping as an evidence gate. Preserve the project until every requested
+target has a reproducible artifact and a recorded independent check.
+
+## Workflow
+
+1. Establish the release boundary.
+   - Inspect project settings, the main scene, export presets, enabled addons,
+     imported assets, and repository status.
+   - Record target platforms, Godot version/build flavor, renderer, .NET needs,
+     expected artifact paths, and any signing or export-template prerequisites.
+2. Validate source and dependencies.
+   - Run `validate_scripts` and `analyze_project_integrity`.
+   - Run `manage_import_pipeline` in inspection mode and resolve missing or stale
+     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.
+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.
+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.
+   - Use `verify_export_readiness` to check templates, presets, dependencies,
+     export output, and supported smoke execution before the final export.
+5. Inspect the artifact independently.
+   - Confirm the output exists at the expected path, has the expected file type
+     and non-zero size, and contains the required sidecar data or pack files.
+   - Smoke-run supported local artifacts and compare logs, exit status, and
+     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.
+   - Recheck the project tree and processes. Report exact commands, versions,
+     targets, hashes or sizes, assertions, 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/ship-godot-game/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Ship Godot Game"
+  short_description: "Verify and prepare a Godot game release"
+  default_prompt: "Use $ship-godot-game to verify export readiness and prepare this Godot game for release."

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

@@ -0,0 +1,35 @@
+---
+name: verify-godot-change
+description: Verify a Godot 4 project change with static checks and independent evidence from the running game. Use after editing scenes, scripts, resources, input, UI, rendering, or gameplay, and when deciding whether a Godot task is genuinely complete.
+---
+
+# Verify a Godot change
+
+Turn the requested behavior into observable acceptance criteria before running
+the game. A successful mutation response is not evidence that the change works.
+
+## 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.
+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.
+3. Exercise interactive behavior when a compound assertion is insufficient.
+   - Call `run_project`, 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
+     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.
+5. Stop the project and report the exact assertions and evidence. If any
+   acceptance criterion remains unobserved, say verification is incomplete.
+
+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

@@ -0,0 +1,237 @@
+import { randomBytes } from 'node:crypto';
+import { createServer } from 'node:net';
+import { GameConnection } from './game-connection.js';
+import { GodotProcessManager } from './godot-process-manager.js';
+import { convertCamelToSnakeCase, errorMessage } from './utils.js';
+import { deterministicSessionArguments, deterministicSessionEnvironment } from './session-timing.js';
+import { RENDERING_CONTEXT_CAPABILITY } from './runtime-protocol.js';
+/** A startup-only error that is safe to route to the subprocess fallback. */
+export class AuthoringSessionUnavailableError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'AuthoringSessionUnavailableError';
+    }
+}
+/** A headed session could not reach a real or virtual desktop renderer. */
+export class RenderingContextUnavailableError extends Error {
+    constructor(message = 'Headed authoring session requires a reachable rendering context. Set DISPLAY or WAYLAND_DISPLAY on Linux, or run under a virtual display such as Xvfb.') {
+        super(message);
+        this.name = 'RenderingContextUnavailableError';
+    }
+}
+/** Owns one serialized, reusable authoring process for the currently edited project. */
+export class AuthoringSessionManager {
+    options;
+    logDebug;
+    processManager;
+    current = null;
+    generation = 0;
+    operationTail = Promise.resolve();
+    constructor(options) {
+        this.options = options;
+        this.logDebug = options.logDebug ?? (() => undefined);
+        this.processManager = options.processManager ?? new GodotProcessManager(this.logDebug);
+    }
+    get activeProjectPath() {
+        return this.current?.projectPath ?? null;
+    }
+    async execute(backend, params, projectPath) {
+        return this.serialize(async () => {
+            await this.ensureSession(projectPath);
+            const state = this.current;
+            if (!state?.connection.isConnected) {
+                throw new AuthoringSessionUnavailableError('Authoring session did not establish its JSON-RPC connection');
+            }
+            try {
+                const response = await state.connection.send(backend.command, convertCamelToSnakeCase(params), 30_000);
+                if ('error' in response) {
+                    const details = response.error.data === undefined ? '' : `: ${JSON.stringify(response.error.data)}`;
+                    return {
+                        stdout: '',
+                        stderr: `${response.error.message}${details}`,
+                        exitCode: 1,
+                        signal: null,
+                    };
+                }
+                const result = response.result;
+                if (!result || typeof result !== 'object') {
+                    return {
+                        stdout: '', stderr: 'Authoring session returned an invalid result', exitCode: 1, signal: null,
+                    };
+                }
+                const payload = result;
+                if (isMutatingAuthoringCommand(backend.command, params)) {
+                    const scenePath = affectedScenePath(params);
+                    const focusPath = authoringFocusPath(backend.command, params);
+                    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 }),
+                    });
+                }
+                return {
+                    stdout: typeof payload.stdout === 'string' ? payload.stdout : JSON.stringify(payload),
+                    stderr: '',
+                    exitCode: 0,
+                    signal: null,
+                };
+            }
+            catch (error) {
+                // Once a request may have reached Godot, retrying it through the
+                // subprocess can duplicate a partial mutation. Report the transport
+                // failure and leave recovery to the caller instead.
+                return {
+                    stdout: '',
+                    stderr: `Authoring session command failed: ${errorMessage(error)}`,
+                    exitCode: 1,
+                    signal: null,
+                };
+            }
+        });
+    }
+    stop() {
+        const state = this.current;
+        if (!state)
+            return;
+        this.current = null;
+        state.connection.disconnect();
+        this.processManager.stop();
+        this.options.installer.remove(state.projectPath, state.ownedInstallation);
+        this.logDebug(`Stopped authoring session for ${state.projectPath}`);
+    }
+    async ensureSession(projectPath) {
+        if (this.current?.projectPath === projectPath
+            && this.current.connection.isConnected
+            && this.processManager.active)
+            return;
+        if (this.options.canStart && !this.options.canStart()) {
+            throw new AuthoringSessionUnavailableError('A user-facing Godot process is active');
+        }
+        this.stop();
+        let ownedInstallation = false;
+        try {
+            const executable = await this.options.resolveGodotPath();
+            const port = await (this.options.allocatePort ?? allocateLoopbackPort)();
+            const secret = (this.options.secretFactory ?? (() => randomBytes(32).toString('base64url')))();
+            ownedInstallation = this.options.installer.install(projectPath);
+            const connection = (this.options.createConnection ?? ((connectionPort, authSecret) => new GameConnection({
+                port: connectionPort,
+                initialDelayMs: 0,
+                retryDelayMs: 50,
+                maxAttempts: 200,
+                authSecret,
+                log: this.logDebug,
+                onLifecycleEvent: this.options.onLifecycleEvent,
+            })))(port, secret);
+            const generation = ++this.generation;
+            const state = { projectPath, ownedInstallation, connection, generation };
+            this.current = state;
+            this.processManager.start({
+                executable,
+                args: [
+                    ...deterministicSessionArguments(),
+                    '--path', projectPath, '--script', this.options.operationsScriptPath, '--serve-authoring',
+                ],
+                env: {
+                    ...deterministicSessionEnvironment(),
+                    GODOT_MCP_RUNTIME_PORT: String(port),
+                    GODOT_MCP_RUNTIME_SECRET: secret,
+                },
+                onExit: () => { this.handleProcessExit(generation); },
+                onError: error => {
+                    this.logDebug(`Authoring session process error: ${error.message}`);
+                    this.handleProcessExit(generation);
+                },
+            });
+            await connection.connect(projectPath, () => this.current === state && this.processManager.active);
+            if (!connection.isConnected) {
+                throw new RenderingContextUnavailableError('Headed authoring session exited before its renderer became reachable. Set DISPLAY or WAYLAND_DISPLAY on Linux, or run under a virtual display such as Xvfb.');
+            }
+            if (!connection.supportsCapability(RENDERING_CONTEXT_CAPABILITY)) {
+                throw new RenderingContextUnavailableError();
+            }
+            this.logDebug(`Started authoring session for ${projectPath} on port ${port}`);
+        }
+        catch (error) {
+            if (this.current)
+                this.stop();
+            else if (ownedInstallation)
+                this.options.installer.remove(projectPath, true);
+            if (error instanceof RenderingContextUnavailableError)
+                throw error;
+            throw new AuthoringSessionUnavailableError(`Could not start authoring session: ${errorMessage(error)}`);
+        }
+    }
+    handleProcessExit(generation) {
+        if (this.current?.generation !== generation)
+            return;
+        const state = this.current;
+        this.current = null;
+        state.connection.disconnect();
+        this.options.installer.remove(state.projectPath, state.ownedInstallation);
+    }
+    serialize(operation) {
+        const result = this.operationTail.then(operation, operation);
+        this.operationTail = result.then(() => undefined, () => undefined);
+        return result;
+    }
+}
+function isMutatingAuthoringCommand(command, params) {
+    if (command === 'authoring_get_uid' || command === 'authoring_read_scene')
+        return false;
+    if (command === 'authoring_manage_resource' || command === 'authoring_manage_theme_resource') {
+        return params.action !== 'read';
+    }
+    if (command === 'authoring_manage_scene_signals')
+        return params.action !== 'list';
+    return true;
+}
+function toResourcePath(path) {
+    return path.startsWith('res://') ? path : `res://${path.replace(/^\/+/, '')}`;
+}
+function affectedScenePath(params) {
+    if (typeof params.newPath === 'string')
+        return params.newPath;
+    return typeof params.scenePath === 'string' ? params.scenePath : undefined;
+}
+function authoringFocusPath(command, params) {
+    if (command === 'authoring_create_scene' || command === 'authoring_save_scene')
+        return '.';
+    if (command === 'authoring_add_node'
+        && typeof params.nodeName === 'string') {
+        const parent = typeof params.parentNodePath === 'string' ? params.parentNodePath : 'root';
+        const relativeParent = parent.replace(/^\/?root\/?/, '').replace(/^\.\/?/, '').replace(/\/$/, '');
+        return relativeParent ? `${relativeParent}/${params.nodeName}` : params.nodeName;
+    }
+    if (typeof params.nodePath !== 'string')
+        return undefined;
+    const relative = params.nodePath.replace(/^\/?root\/?/, '') || '.';
+    if (command !== 'authoring_remove_node')
+        return relative;
+    const slash = relative.lastIndexOf('/');
+    return slash < 0 ? '.' : relative.slice(0, slash);
+}
+/** Reserves an ephemeral loopback port long enough to learn its assigned number. */
+export function allocateLoopbackPort() {
+    return new Promise((resolve, reject) => {
+        const server = createServer();
+        server.once('error', reject);
+        server.listen(0, '127.0.0.1', () => {
+            const address = server.address();
+            if (!address || typeof address === 'string') {
+                server.close();
+                reject(new Error('Could not allocate a loopback port'));
+                return;
+            }
+            const port = address.port;
+            server.close(error => {
+                if (error)
+                    reject(error);
+                else
+                    resolve(port);
+            });
+        });
+    });
+}