summer-engine 2.6.5 → 2.7.0

package/dist/mcp/tools/generate-tools.js

@@ -13,6 +13,8 @@ const TOOL_BY_ENDPOINT = {
     "/api/mcp/generate/3d": "summer_generate_3d",
     "/api/mcp/generate/video": "summer_generate_video",
     "/api/mcp/generate/motion": "summer_generate_motion",
+    "/api/mcp/generate/slice-asset-sheet": "summer_slice_asset_sheet",
+    "/api/mcp/workflows": "summer_get_studio_workflow",
 };
 // ---------------------------------------------------------------------------
 // Shared helpers
@@ -129,6 +131,37 @@ async function mcpGenerate(endpoint, body, timeoutMs = 120_000) {
     }
     return { data, status: res.status };
 }
+async function mcpGet(endpoint, searchParams, timeoutMs = 30_000) {
+    const token = await getAuthToken();
+    const suffix = searchParams?.size ? `?${searchParams.toString()}` : "";
+    let res;
+    try {
+        res = await fetch(`${GATEWAY_URL}${endpoint}${suffix}`, {
+            headers: {
+                ...(token ? { Authorization: `Bearer ${token}` } : {}),
+                "X-Summer-Client": "summer-cli",
+                "X-Summer-Client-Version": CLI_VERSION,
+                "X-Summer-Client-Surface": "mcp",
+                "X-Summer-MCP-Endpoint": endpoint,
+                "X-Summer-MCP-Tool": TOOL_BY_ENDPOINT[endpoint] ?? "unknown",
+            },
+            signal: AbortSignal.timeout(timeoutMs),
+        });
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return { error: `Request failed: ${msg}`, status: 0 };
+    }
+    const data = await readJsonResponse(res);
+    if (!res.ok) {
+        return {
+            error: formattedApiErrorMessage(res.status, data),
+            data: { ...data, status: res.status },
+            status: res.status,
+        };
+    }
+    return { data, status: res.status };
+}
 /**
  * Download an image URL to a temp file so the AI can Read it and show the user.
  */
@@ -153,7 +186,7 @@ async function downloadToTemp(url, prefix, ext = "png") {
  * Poll a job until completed, failed, or timeout.
  * Returns the final job status object.
  */
-async function pollJob(jobId, maxWaitMs = 300_000, intervalMs = 5_000) {
+async function pollJob(jobId, maxWaitMs = 600_000, intervalMs = 5_000) {
     const token = await getAuthToken();
     if (!token)
         return { error: "Not signed in" };
@@ -210,6 +243,28 @@ function successResult(data) {
 // Registration
 // ---------------------------------------------------------------------------
 export function registerGenerateTools(server) {
+    // ========================================================================
+    // summer_get_studio_workflow
+    // ========================================================================
+    server.tool("summer_get_studio_workflow", `Discover the same Guided workflow recipes shown in Summer Engine Studio.
+
+Call without workflowId to list every workflow and its support level. Call with
+an id to get the exact starter prompt, ordered steps, required MCP tools, and
+honest limitations. A "manual" support level means Studio still has a visual
+handoff that MCP cannot perform automatically; do not pretend that stage ran.`, {
+        workflowId: z
+            .string()
+            .optional()
+            .describe("Guided workflow id, e.g. sprite-sheet, character-pack, asset-pack, or component-compiler"),
+    }, async ({ workflowId }) => {
+        const params = new URLSearchParams();
+        if (workflowId)
+            params.set("id", workflowId);
+        const result = await mcpGet("/api/mcp/workflows", params);
+        if (result.error)
+            return errorResult(result.error, result.data);
+        return successResult(result.data);
+    });
     // ========================================================================
     // summer_generate_image
     // ========================================================================
@@ -277,6 +332,35 @@ Requires authentication: run 'npx summer-engine login' first.`, {
         });
     });
     // ========================================================================
+    // summer_slice_asset_sheet
+    // ========================================================================
+    server.tool("summer_slice_asset_sheet", `Detect and crop every distinct game asset from an existing image asset sheet.
+
+Use the assetId returned by summer_generate_image (or another Summer image asset).
+The same guided workflow used in Studio removes the sheet background when needed,
+detects named/category-aware bounding boxes, crops each item, and uploads the slices.
+
+Returns source dimensions plus the generated slice URLs, names, categories, bounding
+boxes, and widget metadata when the sheet contains UI controls.
+
+Cloud tool — runs on Summer's servers and works WITHOUT the Summer Engine app open.
+Requires authentication: run 'npx summer-engine login' first.`, {
+        assetId: z
+            .string()
+            .describe("Summer image asset ID to slice, usually returned by summer_generate_image"),
+    }, async ({ assetId }) => {
+        const result = await mcpGenerate("/api/mcp/generate/slice-asset-sheet", { assetId }, 300_000);
+        if (result.error) {
+            return errorResult(result.error, result.data);
+        }
+        return successResult({
+            ...result.data,
+            sliceCount: Array.isArray(result.data?.slices)
+                ? result.data.slices.length
+                : 0,
+        });
+    });
+    // ========================================================================
     // summer_generate_audio
     // ========================================================================
     server.tool("summer_generate_audio", `Generate audio using AI providers via Summer Engine Studio.
@@ -377,7 +461,16 @@ Example:
   })
   // Returns jobId; poll until result includes { assetId, rigAssetId }.
 
-By default, waits for completion (up to 5 min) and returns the result directly.
+Single-image generation automatically assesses whether the source is suitable
+for 3D. If needed, Summer prepares an isolated object view or rig-safe character
+pose before conversion. Set referencePreparation="always" or "never" only when
+you intentionally want to override that shared Studio behavior.
+
+For a complete animated humanoid package, pass rig=true plus animationNames or
+actionIds. This routes through the shared character pipeline instead of a
+one-off mesh job.
+
+By default, waits for completion (up to 10 min) and returns the result directly.
 Set wait=false to get the jobId immediately and poll manually with summer_check_job.
 
 Cloud tool — runs on Summer's servers and works WITHOUT the Summer Engine app open.
@@ -398,21 +491,66 @@ Requires authentication: run 'npx summer-engine login' first.`, {
             .string()
             .optional()
             .describe("Source image URL for image-to-3d or texture"),
+        imageUrls: z
+            .array(z.string())
+            .max(4)
+            .optional()
+            .describe("Up to four views for multi-image-to-3d"),
+        title: z.string().optional().describe("Asset or character title"),
+        idempotencyKey: z
+            .string()
+            .optional()
+            .describe("Stable retry key so the same logical request is not billed or queued twice"),
+        assetIntent: z
+            .enum(["character", "object"])
+            .optional()
+            .describe("Controls whether hidden reference preparation targets a rig-safe character pose or isolated object view"),
+        referencePreparation: z
+            .enum(["auto", "always", "never"])
+            .default("auto")
+            .describe("Shared Studio reference-preparation policy; auto is recommended"),
+        rig: z.boolean().default(false).describe("Auto-rig the generated model"),
+        animationNames: z
+            .array(z.string())
+            .optional()
+            .describe("Animation names for the shared animated-character pipeline, e.g. Idle, Walk, Run, Jump"),
+        actionIds: z
+            .array(z.number().int().min(0).max(696))
+            .optional()
+            .describe("Exact Meshy action ids for the shared animated-character pipeline"),
+        riggingHeightMeters: z
+            .number()
+            .positive()
+            .max(10)
+            .optional()
+            .describe("Character height used by auto-rigging"),
         wait: z
             .boolean()
             .default(true)
-            .describe("Wait for completion (default true, up to 5 min). Set false to get jobId immediately."),
+            .describe("Wait for completion (default true, up to 10 min). Set false to get jobId immediately."),
         options: z
             .record(z.any())
             .optional()
             .describe("Provider-specific params (target_polycount, topology, art_style, etc.)"),
-    }, async ({ prompt, kind, model, imageUrl, wait, options }) => {
+    }, async ({ prompt, kind, model, imageUrl, imageUrls, title, idempotencyKey, assetIntent, referencePreparation, rig, animationNames, actionIds, riggingHeightMeters, wait, options, }) => {
+        const mergedOptions = {
+            ...(options ?? {}),
+            ...(imageUrls ? { imageUrls } : {}),
+            ...(assetIntent ? { assetIntent } : {}),
+            referencePreparation,
+            ...(rig ? { rig: true } : {}),
+            ...(animationNames ? { animationNames } : {}),
+            ...(actionIds ? { actionIds } : {}),
+            ...(riggingHeightMeters !== undefined ? { riggingHeightMeters } : {}),
+        };
         const result = await mcpGenerate("/api/mcp/generate/3d", {
             prompt,
             kind,
             model,
             imageUrl,
-            options,
+            title,
+            idempotencyKey,
+            options: mergedOptions,
         });
         if (result.error) {
             return errorResult(result.error, result.data);

package/dist/mcp/tools/project-tools.js

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import { ASSET_POLICIES, GAME_TASK_MODES, GAME_TASK_TARGETS, VERIFICATION_LEVELS, buildGameTaskPlan, } from "../../lib/game-task-plan.js";
+import { getCachedBootDriftNotice } from "../../lib/mcp-boot-notice.js";
 import { getProjectMemorySummary } from "../../lib/project-memory.js";
 import { withEngine } from "./with-engine.js";
 function asRecord(value) {
@@ -134,18 +135,19 @@ anti-patterns, and recovery steps.`, {}, async () => ({
             {
                 type: "text",
                 text: JSON.stringify({
+                    summerUpdateNotice: getCachedBootDriftNotice()?.text ?? null,
                     startupChecklist: [
                         "Understand the request and outline a brief plan before reaching for tools.",
-                        "Default medium is host file tools: write/edit .gd/.cs/.tscn/.tres/.json/docs/config directly as text.",
-                        "Use Summer MCP only when you need the LIVE engine: play/stop, diagnostics, screenshots/verification, navmesh or light bake, runtime inspect, or asset import.",
+                        "Use summer_read_file, summer_write_file, and summer_replace_text for project text files so reads and guarded writes stay bound to the open engine project.",
+                        "Use Summer MCP for project mutations and live-engine work: scenes, resources, play/stop, diagnostics, screenshots/verification, bake, runtime inspection, and asset import.",
                         "Call summer_get_project_context first so you do not guess scene paths or the project language. It also BINDS this session to the currently-open project (see projectBinding below).",
                         "Use projectMemory from summer_get_project_context to decide which .summer Markdown files to read before creative/audio/dialogue/level/character work.",
                         "After writing code, VERIFY through the engine (see verificationLadder) instead of waiting for the user to navigate to it.",
                     ],
                     safeDefaults: [
                         "Never guess scene filenames (main.tscn/Main.tscn) -- get them from summer_get_project_context.",
-                        "Edit files (including .tscn/.tres) with host file tools by default. Reach for MCP scene-ops only for live-engine needs (bake, play, runtime inspect) or when you want the editor to manage node ids / instancing.",
-                        "If you hand-edit a .tscn that is OPEN in the editor, reload it there afterward -- the editor's open tab can overwrite your file (clobber).",
+                        "Use summer_replace_text for existing project text and summer_write_file with create_only:true for new files; overwrites require the sha256 from summer_read_file.",
+                        "For live scene hierarchy and inspector changes, prefer scene tools. Guarded text writes support .tscn/.tres, and the engine schedules editor reloads after they land.",
                         "Write GDScript by default; use C# only if the project already uses it.",
                         "Never remove multiple top-level nodes unless the user explicitly requests destructive edits.",
                         "Never change priority: locked .summer memory, voice IDs, canon, or provider bindings without explicit user confirmation.",
@@ -153,7 +155,7 @@ anti-patterns, and recovery steps.`, {}, async () => ({
                     buildFlow: [
                         "1. Understand what the user wants (one pass, no tool spelunking first).",
                         "2. Outline the plan fast and briefly; proceed once it is clearly right.",
-                        "3. Execute in pure code -- edit .gd/.tscn/.tres as text (GDScript by default, C# only if the project already uses it).",
+                        "3. Execute through identity-bound MCP mutations -- guarded text tools for files, scene tools for live hierarchy/inspector work (GDScript by default, C# only if the project already uses it).",
                         "4. Verify through the engine using the verificationLadder below, fix, and repeat until it launches clean.",
                     ],
                     // The MCP-native verification ladder. Climb only as high as the
@@ -172,11 +174,10 @@ anti-patterns, and recovery steps.`, {}, async () => ({
                         ],
                         "3_runs": [
                             "Compose the run-and-check yourself — there is no single 'verify' tool:",
-                            "summer_clear_console  -> clean slate",
                             "summer_play [scene]   -> boot the game (or a specific scene)",
                             "summer_get_debugger_errors  -> runtime errors (null refs, missing nodes, physics)",
                             "summer_screenshot target:'game'  -> optional visual of the live frame",
-                            "summer_stop  -> ALWAYS stop; scene mutations are refused while the game runs",
+                            "summer_stop  -> stop when runtime verification is finished; editor scene mutations are not categorically blocked by a running game, but an existing game instance may need a restart to observe them",
                         ],
                         "4_interactive": [
                             "To prove input-driven behavior (does jump/move/shoot actually work), you have two routes when the engine build supports them (both go through summer_batch as raw ops — see rawOpsViaBatch):",
@@ -204,12 +205,12 @@ anti-patterns, and recovery steps.`, {}, async () => ({
                         "To intentionally follow the switch, call summer_get_project_context again to rebind, then retry.",
                     ],
                     liveEngineFlow: [
-                        "Use this flow ONLY when you genuinely need live engine state (navmesh/light bake, instancing into an already-open scene, runtime inspect):",
+                        "Use this flow when you genuinely need live engine state (navmesh/light bake, scene mutation, runtime inspect):",
                         "summer_get_project_context",
-                        "summer_open_main_scene (if needed)",
-                        "summer_get_scene_tree",
-                        "summer_add_node / summer_set_prop / summer_set_resource_property",
-                        "summer_save_scene",
+                        "Choose the exact res:// scenePath. OpenScene is a user-visible tab action, not a mutation prerequisite.",
+                        "summer_get_scene_tree with scenePath when that exact scene is already loaded; omit it only for the visible tab.",
+                        "summer_add_node / summer_set_prop / summer_set_resource_property with scenePath",
+                        "Mutation tools append one final SaveScene; use summer_save_scene only for a standalone save/save-as.",
                         "summer_get_diagnostics",
                     ],
                     // summer_batch forwards each {op, ...} verbatim to the engine, so
@@ -221,11 +222,12 @@ anti-patterns, and recovery steps.`, {}, async () => ({
                         "These are runtime ops, not scene mutations — the batch undo group is a harmless no-op for them.",
                     ],
                     recovery: [
-                        "If you see 'no scene open': run summer_open_main_scene.",
+                        "If a scene mutation reports missing_scene_path: pass the exact res:// scenePath and retry.",
+                        "If a scene target cannot load: repair the named missing/invalid dependency, then retry the same scenePath.",
                         "If open_scene fails: re-check mainScene from summer_get_project_context.",
-                        "If save fails: verify scene is open and game is not running (summer_is_running / summer_stop).",
+                        "If save fails: use the returned scenePath/error to repair the exact cause. A running game alone is not a generic scene-mutation blocker.",
                         "If a mutation is rejected with identity_mismatch: the engine switched projects — call summer_get_project_context to rebind (only if you meant to follow it), then retry.",
-                        "If a .tscn you wrote keeps reverting: the editor has that scene open -- reload or close the tab, then write again.",
+                        "If a guarded file mutation is rejected with content mismatch: call summer_read_file again, review the new content, and retry with its new sha256 only if the edit is still valid.",
                         "If a run op or SimulateInput returns 'unsupported' / an unknown-op error: this engine build predates it — fall back to summer_play + summer_get_debugger_errors, or ask the user to interact.",
                     ],
                     debugging: [
@@ -270,10 +272,11 @@ Use this first in every fresh chat to avoid guessing scene filenames or editing
             mainScene,
             boundProjectIdHash,
             projectMemory: getProjectMemorySummary(projectPath),
+            summerUpdateNotice: getCachedBootDriftNotice()?.text ?? null,
             guidance: mainScene
                 ? "Use `summer_open_scene` with `mainScene` if no scene is open."
                 : "Main scene not found in project state. Open a known scene path explicitly.",
-            fileEditingGuidance: "Edit files (including .gd/.cs/.tscn/.tres/.json/docs) with host file tools by default. Use MCP only for live engine state: play/stop, diagnostics, screenshots/verification, navmesh or light bake, runtime inspect, and asset import. If you edit a .tscn that is open in the editor, reload it there afterward so the editor's tab does not overwrite your changes.",
+            fileEditingGuidance: "Use summer_read_file plus summer_replace_text or guarded summer_write_file for project files, including .gd/.cs/.tscn/.tres/.json/docs. New files require create_only:true; overwrites require the sha256 receipt from summer_read_file. Prefer scene tools for live hierarchy/inspector changes.",
         };
     }));
     server.tool("summer_open_main_scene", `Open the project's configured main scene from project settings.
@@ -315,10 +318,12 @@ Example: Bind jump to Space and W:
         ];
         return client.executeOps(ops);
     }));
-    server.tool("summer_get_scene_tree", `Get the full scene tree structure of the currently open scene.
-
-Use this before structural edits (add/remove/replace).
-If you get "no edited scene", call summer_open_main_scene first.`, {}, async () => withEngine(async (client) => client.getSceneState()));
+    server.tool("summer_get_scene_tree", `Get a scene tree. Pass scenePath to read that exact in-memory/open scene;
+omit it only when you intentionally want the currently visible editor scene.
+Scene mutations load their explicit target, so a follow-up targeted read does
+not require OpenScene.`, {
+        scenePath: z.string().optional().describe("Exact res:// scene path to inspect"),
+    }, async ({ scenePath }) => withEngine(async (client) => client.getSceneState(scenePath)));
     server.tool("summer_import_from_url", `Download a file from a URL and import it into the project. Triggers Godot's full import pipeline — generates .import files, extracts textures from .glb models, creates materials.
 
 Use this for:

package/dist/mcp/tools/scene-tools.js

@@ -2,6 +2,27 @@ import { z } from "zod";
 import { withEngine } from "./with-engine.js";
 import { readFile } from "fs/promises";
 import { join } from "path";
+function sceneMutationOps(ops) {
+    const saveIndexes = ops
+        .map((op, index) => op.op === "SaveScene" ? index : -1)
+        .filter((index) => index >= 0);
+    if (saveIndexes.length > 1) {
+        throw new Error("A scene mutation batch may contain only one SaveScene");
+    }
+    if (saveIndexes.length === 1) {
+        if (saveIndexes[0] !== ops.length - 1) {
+            throw new Error("SaveScene must be the final operation in a scene mutation batch");
+        }
+        return ops;
+    }
+    return [...ops, { op: "SaveScene" }];
+}
+function executeSceneMutation(client, scenePath, ops, options) {
+    return client.executeIdentityBoundOps(sceneMutationOps(ops), {
+        ...(options ?? {}),
+        scenePath,
+    });
+}
 async function readMainSceneFromProject(projectPath) {
     if (!projectPath)
         return null;
@@ -14,6 +35,20 @@ async function readMainSceneFromProject(projectPath) {
         return null;
     }
 }
+function requireSuccessfulOps(result, context) {
+    const receipt = (result ?? {});
+    const results = Array.isArray(receipt.results)
+        ? receipt.results
+        : [];
+    const failed = results.find((entry) => entry?.ok === false);
+    if (receipt.status === "error" || failed) {
+        const error = (typeof failed?.error === "string" && failed.error) ||
+            (typeof receipt.error === "string" && receipt.error) ||
+            `${context} failed`;
+        throw new Error(error);
+    }
+    return receipt;
+}
 export function registerSceneTools(server) {
     server.tool("summer_create_scene", `Create a new empty scene file safely.
 
@@ -45,19 +80,22 @@ Recommended workflow:
             throw new Error("No scene open and could not resolve main scene. Call summer_get_project_context first, then open a known scene.");
         }
         await client.executeOps([{ op: "OpenScene", path: templateScene }]);
-        const tree = (await client.getSceneState());
+        const tree = (await client.getSceneState(templateScene));
         const children = tree.data?.children ?? tree.children ?? [];
         const removeOps = children
             .map((c) => c.path)
             .filter((p) => typeof p === "string" && p.length > 0)
             .map((p) => ({ op: "RemoveNode", path: `./${p}` }));
-        if (removeOps.length > 0) {
-            await client.executeOps(removeOps, { groupUndo: true });
-        }
-        await client.executeOps([{ op: "SetProp", path: ".", key: "name", value: rootName }]);
-        await client.executeOps([{ op: "SaveScene", path }]);
+        const createOps = [
+            ...removeOps,
+            { op: "SetProp", path: ".", key: "name", value: rootName },
+            { op: "SaveScene", path },
+        ];
+        const createReceipt = requireSuccessfulOps(await executeSceneMutation(client, templateScene, createOps, {
+            groupUndo: true,
+        }), `Creating ${path}`);
         if (currentScene && currentScene !== path) {
-            await client.executeOps([{ op: "OpenScene", path: currentScene }]);
+            requireSuccessfulOps(await client.executeOps([{ op: "OpenScene", path: currentScene }]), `Restoring ${currentScene}`);
         }
         return {
             ok: true,
@@ -65,14 +103,13 @@ Recommended workflow:
             rootName,
             templateScene,
             restoredScene: currentScene,
+            receipt: createReceipt,
         };
     }));
     server.tool("summer_add_node", `Add a new node to the scene tree.
 
-Preflight (fresh chat):
-1) summer_get_project_context
-2) summer_open_main_scene (if no scene open)
-3) summer_get_scene_tree
+Pass the exact res:// scenePath to mutate. The scene does not need to be the
+active editor tab.
 
 Common node types:
 - 3D: Node3D, MeshInstance3D, CharacterBody3D, RigidBody3D, StaticBody3D, Camera3D, DirectionalLight3D, OmniLight3D, SpotLight3D, WorldEnvironment, CollisionShape3D, Area3D
@@ -81,10 +118,11 @@ Common node types:
 - Audio: AudioStreamPlayer, AudioStreamPlayer3D
 
 The parent path uses "./" prefix for relative paths from scene root. E.g., "./World" means the "World" child of the root node.`, {
+        scenePath: z.string().describe("Target scene path, e.g. 'res://main.tscn'"),
         parent: z.string().describe("Parent node path, e.g. './World' or './World/Enemies'"),
         type: z.string().describe("Godot node type, e.g. 'MeshInstance3D', 'CharacterBody3D'"),
         name: z.string().describe("Name for the new node, e.g. 'Player', 'MainCamera'"),
-    }, async ({ parent, type, name }) => withEngine(async (client) => client.executeOps([{ op: "AddNode", parent, type, name }])));
+    }, async ({ scenePath, parent, type, name }) => withEngine(async (client) => executeSceneMutation(client, scenePath, [{ op: "AddNode", parent, type, name }])));
     server.tool("summer_set_prop", `Set a property on a node. This is the primary way to configure nodes after adding them.
 
 VALUE FORMAT — Godot string syntax for complex types:
@@ -106,29 +144,37 @@ COMMON PROPERTIES:
 - shadow_enabled: true — for lights
 - light_energy: 1.5 — light intensity
 - fov: 75.0 — camera field of view`, {
+        scenePath: z.string().describe("Target scene path, e.g. 'res://main.tscn'"),
         path: z.string().describe("Node path, e.g. './World/Player'"),
         key: z.string().describe("Property name, e.g. 'position', 'mesh', 'visible'"),
         value: z.union([z.string(), z.number(), z.boolean()]).describe("Value in Godot string format for complex types, native JSON for primitives"),
-    }, async ({ path, key, value }) => withEngine(async (client) => client.executeOps([{ op: "SetProp", path, key, value }])));
+    }, async ({ scenePath, path, key, value }) => withEngine(async (client) => executeSceneMutation(client, scenePath, [{ op: "SetProp", path, key, value }])));
     server.tool("summer_set_resource_property", `Set a nested property on a resource attached to a node.
 
 Use when you need to modify a sub-property of a resource, like:
 - CollisionShape3D shape size: nodePath="./Player/CollisionShape3D", resourceProperty="shape", subProperty="size", value="Vector3(1, 2, 1)"
 - Material albedo color: nodePath="./Floor", resourceProperty="material_override", subProperty="albedo_color", value="Color(0.2, 0.5, 0.2, 1)"
 - Mesh size: nodePath="./Box", resourceProperty="mesh", subProperty="size", value="Vector3(2, 2, 2)"`, {
+        scenePath: z.string().describe("Target scene path, e.g. 'res://main.tscn'"),
         nodePath: z.string().describe("Node path, e.g. './Player/CollisionShape3D'"),
         resourceProperty: z.string().describe("Resource property on the node, e.g. 'shape', 'mesh', 'material_override'"),
         subProperty: z.string().describe("Property on the resource, e.g. 'size', 'radius', 'albedo_color'"),
         value: z.union([z.string(), z.number(), z.boolean()]).describe("Value in Godot string format"),
-    }, async ({ nodePath, resourceProperty, subProperty, value }) => withEngine(async (client) => client.executeOps([
+    }, async ({ scenePath, nodePath, resourceProperty, subProperty, value }) => withEngine(async (client) => executeSceneMutation(client, scenePath, [
         { op: "SetResourceProperty", nodePath, resourceProperty, subProperty, value },
     ])));
-    server.tool("summer_remove_node", "Remove a node from the scene tree. All children are removed too. Cannot remove the root node. Supports undo. Destructive operation: do not delete multiple top-level nodes unless the user explicitly requests destructive changes.", { path: z.string().describe("Node path to remove, e.g. './World/OldEnemy'") }, async ({ path }) => withEngine(async (client) => client.executeOps([{ op: "RemoveNode", path }])));
-    server.tool("summer_save_scene", "Save the current scene to disk. Call this after making scene changes to persist them. Without saving, changes only exist in the editor's memory.", { path: z.string().optional().describe("Save-as path for creating a new scene file, e.g. 'res://levels/level2.tscn'") }, async ({ path }) => withEngine(async (client) => {
+    server.tool("summer_remove_node", "Remove a node from the scene tree. All children are removed too. Cannot remove the root node. Supports undo. Destructive operation: do not delete multiple top-level nodes unless the user explicitly requests destructive changes.", {
+        scenePath: z.string().describe("Target scene path, e.g. 'res://main.tscn'"),
+        path: z.string().describe("Node path to remove, e.g. './World/OldEnemy'"),
+    }, async ({ scenePath, path }) => withEngine(async (client) => executeSceneMutation(client, scenePath, [{ op: "RemoveNode", path }])));
+    server.tool("summer_save_scene", "Save an explicit scene to disk. Mutation tools already append one save; use this for a standalone save or save-as.", {
+        scenePath: z.string().describe("Scene to save, e.g. 'res://main.tscn'"),
+        path: z.string().optional().describe("Optional save-as path, e.g. 'res://levels/level2.tscn'"),
+    }, async ({ scenePath, path }) => withEngine(async (client) => {
         const op = { op: "SaveScene" };
         if (path)
             op.path = path;
-        return client.executeOps([op]);
+        return executeSceneMutation(client, scenePath, [op]);
     }));
     server.tool("summer_open_scene", `Open a scene file in the editor. Use this to switch between scenes.
 
@@ -142,14 +188,15 @@ Do not guess paths. Prefer:
 - Compose scenes from smaller scenes (e.g., add a "Player" scene into a "Level" scene)
 
 The scene must already exist in the project. Use summer_import_from_url first if importing from external sources.`, {
+        scenePath: z.string().describe("Target scene to receive the instance, e.g. 'res://main.tscn'"),
         parent: z.string().describe("Parent node path, e.g. './World'"),
         scene: z.string().describe("Scene/model path, e.g. 'res://player.tscn' or 'res://models/tree.glb'"),
         name: z.string().optional().describe("Override the instance name"),
-    }, async ({ parent, scene, name }) => withEngine(async (client) => {
+    }, async ({ scenePath, parent, scene, name }) => withEngine(async (client) => {
         const op = { op: "InstantiateScene", parent, scene };
         if (name)
             op.name = name;
-        return client.executeOps([op]);
+        return executeSceneMutation(client, scenePath, [op]);
     }));
     server.tool("summer_connect_signal", `Connect a signal between two nodes. Signals are Godot's event system — they notify when something happens.
 
@@ -161,11 +208,12 @@ Common signals:
 - "input_event" — CollisionObject received input
 
 The receiver node must have a script with the specified method.`, {
+        scenePath: z.string().describe("Target scene path, e.g. 'res://main.tscn'"),
         emitter: z.string().describe("Node that fires the signal, e.g. './Player/HitArea'"),
         signal: z.string().describe("Signal name, e.g. 'body_entered'"),
         receiver: z.string().describe("Node with the handler script, e.g. './Player'"),
         method: z.string().describe("Method name in the receiver's script, e.g. '_on_hit_area_body_entered'"),
-    }, async ({ emitter, signal, receiver, method }) => withEngine(async (client) => client.executeOps([
+    }, async ({ scenePath, emitter, signal, receiver, method }) => withEngine(async (client) => executeSceneMutation(client, scenePath, [
         { op: "ConnectSignal", emitter, signal, receiver, method },
     ])));
     server.tool("summer_select_node", "Select a node in the editor's scene tree and show it in the inspector panel. Useful for focusing the editor on a specific node.", {
@@ -178,16 +226,17 @@ The receiver node must have a script with the specified method.`, {
         return client.executeOps([op]);
     }));
     server.tool("summer_replace_node", "Replace a node with a different type or scene, preserving its position in the tree and its children. Useful for changing a StaticBody3D to a RigidBody3D, or swapping a placeholder with a proper prefab.", {
+        scenePath: z.string().describe("Target scene path, e.g. 'res://main.tscn'"),
         path: z.string().describe("Node path to replace"),
         type: z.string().optional().describe("New node type, e.g. 'RigidBody3D'"),
         scene: z.string().optional().describe("Scene to replace with, e.g. 'res://enemies/boss.tscn'"),
-    }, async ({ path, type, scene }) => withEngine(async (client) => {
+    }, async ({ scenePath, path, type, scene }) => withEngine(async (client) => {
         const op = { op: "ReplaceNode", path };
         if (type)
             op.type = type;
         if (scene)
             op.scene = scene;
-        return client.executeOps([op]);
+        return executeSceneMutation(client, scenePath, [op]);
     }));
     server.tool("summer_inspect_node", `Get all editable properties of a node with their current values, types, and resource info.
 
@@ -213,7 +262,35 @@ Each op in the array uses the same format as the individual tools:
 
 RAW RUNTIME OPS (interactive verification — engine-build dependent; structured failure_reason incl "unsupported" passes through verbatim):
 - SimulateInput — drive the RUNNING game (summer_play first): {"op": "SimulateInput", "type": "action", "action": "jump", "pressed": true}. type is "action" | "key" | "mouse_click" | "axis".
-- RunVerification — spawn a hidden, disposable game instance that runs a GDScript probe and dies (never touches the editor): {"op": "RunVerification", "probe_source": "extends SummerProbeBase\\nfunc _ready(): await super._ready(); report('ok', true); finish()", "max_seconds": 20}. Returns {ok, results, frames, out_dir}. Probe API: report()/save_frame()/press()/key()/finish().`, {
+- RunVerification — spawn a hidden, disposable game instance that runs a GDScript probe and dies (never touches the editor): {"op": "RunVerification", "probe_source": "extends SummerProbeBase\\nfunc _ready(): await super._ready(); report('ok', true); finish()", "max_seconds": 20}. Returns {ok, results, frames, out_dir}. Probe API: report()/save_frame()/press()/key()/finish().
+
+Do not mix OpenScene with scene mutations in one batch. OpenScene is a UI action;
+send it separately. scenePath selects every mutation target. The tool appends one
+final SaveScene when the batch mutates a scene; if supplied explicitly, SaveScene
+must appear exactly once and be the final operation.`, {
+        scenePath: z.string().optional().describe("Required when ops contains scene mutations; exact res:// target scene path"),
         ops: z.array(z.record(z.unknown())).describe("Array of operation objects, each with 'op' plus its parameters"),
-    }, async ({ ops }) => withEngine(async (client) => client.executeOps(ops, { groupUndo: true })));
+    }, async ({ scenePath, ops }) => withEngine(async (client) => {
+        const rawFileMutation = ops.find((op) => {
+            const kind = String(op.op ?? "");
+            return kind === "WriteFile" || kind === "ReplaceText";
+        });
+        if (rawFileMutation) {
+            throw new Error(`summer_batch does not accept raw ${String(rawFileMutation.op)} operations. ` +
+                "Use summer_write_file or summer_replace_text so project identity, content guards, and same-file ordering are enforced.");
+        }
+        const sceneMutations = new Set([
+            "AddNode", "RemoveNode", "MoveNode", "ReparentNode", "ReplaceNode",
+            "SetProp", "SetResourceProperty", "ConnectSignal", "DisconnectSignal",
+            "InstantiateScene", "SaveScene", "Undo",
+        ]);
+        const needsScenePath = ops.some((op) => sceneMutations.has(String(op.op ?? "")));
+        if (needsScenePath && !scenePath) {
+            throw new Error("summer_batch requires scenePath when ops contains scene mutations");
+        }
+        const options = { groupUndo: true, ...(scenePath ? { scenePath } : {}) };
+        return needsScenePath
+            ? executeSceneMutation(client, scenePath, ops, options)
+            : client.executeOps(ops, options);
+    }));
 }

package/dist/mcp/tools/with-engine.js

@@ -19,7 +19,10 @@ const SUCCESS_TERMINAL_STATES = new Set(["applied", "no_op"]);
 // `error` string (queue-full / lease-reject / identity-mismatch / no-progress
 // timeout frequently arrive with terminalState set and results[] absent).
 const TERMINAL_STATE_MESSAGES = {
-    timed_out: "Engine operation timed out (terminalState: timed_out). Nothing was applied.",
+    timed_out: "Engine operation timed out. Its final state is unknown; inspect the target before retrying.",
+    still_queued: "Summer Engine accepted the operation, but it was still queued when the client stopped waiting. It may still run; do not retry blindly.",
+    still_running: "Summer Engine accepted and started the operation, but no final receipt arrived. It may still be running or may already have applied; inspect the target before retrying.",
+    uncertain: "Summer Engine did not provide a final operation receipt. The current state is uncertain; inspect the target before retrying.",
     not_connected: "Summer Engine is not connected (terminalState: not_connected). Nothing was applied.",
     identity_mismatch: "Operation rejected — wrong project/instance (terminalState: identity_mismatch). Nothing was mutated.",
     content_mismatch: "Operation rejected — content changed since last read (terminalState: content_mismatch). Nothing was applied.",
@@ -117,9 +120,6 @@ function buildActionHint(message) {
     if (normalized.includes("failed to open scene")) {
         return "Scene path could not be opened. Call `summer_get_project_context` to get `mainScene`, then open that exact path. Avoid guessing scene filenames.";
     }
-    if (normalized.includes("writefile cannot edit .tscn/.scn")) {
-        return "Write .gd/.cs/.json/docs/simple config files with normal file-edit tools. Use Summer MCP for live scene state, inspector/node edits, imports, play/stop, diagnostics, and visual verification.";
-    }
     return null;
 }
 export async function withEngine(fn, opts) {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "summer-engine",
-  "version": "2.6.5",
-  "description": "Summer CLI and MCP server for Summer Engine, the AI game engine. Install the engine, connect Claude Code, Cursor, Codex, Gemini, and other agents, and build real games. Skills, hooks, and plugins included.",
+  "version": "2.7.0",
+  "description": "Local Summer CLI and MCP server for Summer Engine. Install and run the engine, connect Claude Code, Cursor, Codex, Gemini, and other agents, and build real games with bundled skills, hooks, and plugins.",
   "keywords": [
     "summer-engine",
     "summer-cli",
@@ -27,6 +27,10 @@
     "type": "git",
     "url": "git+https://github.com/SummerEngine/summer-engine-agent.git"
   },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
   "license": "MIT",
   "author": "Summer Engine <founders@summerengine.com>",
   "type": "module",