summer-engine 2.8.0 → 2.8.1

package/CHANGELOG.md

@@ -2,7 +2,25 @@
 
 All notable changes to summer-engine will be documented here. Following [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and [Semantic Versioning](https://semver.org/).
 
-## [Unreleased]
+## [2.8.1] — 2026-08-18 — "Scene mutations work again on engine 0.5.60+"
+
+### Added
+- `summer_get_scene_tree` accepts optional `depth` and `limit` params (engine defaults: depth 2, limit 200 — a 102-node scene silently truncated to 61 nodes at the defaults). The engine only honors them on scene-targeted reads, so the tool resolves the current scene path first when needed and says so when it can't. `summer_get_project_context` accepts an optional `settingsPrefix` and, without one, trims `project.data.entries` to a curated prefix set (application/, display/, input/, physics/, rendering/) instead of returning the full ~188KB settings dump — the payload declares the trim via `settingsTruncated`/`totalSettings`/`settingsHint`.
+- `summer_screenshot` scene captures accept `nodePath` (frame a specific node, honest `node_not_found` failure) and new framing directions `back`/`left`/`right`; captions report the resolved framing and any render retries. Requires engine 0.5.62+ to take effect — older engines silently ignore the new fields.
+- `summer_get_diagnostics` returns a prioritized bounded view (errors first, then warnings, capped info tail) with honest suppression counters, plus `includeAll: true` for the untrimmed payload. Severity + recency + caps only — no noise-pattern matching.
+- `scripts/compat-smoke.sh`: a latest-MCP × candidate-engine release gate that drives the real built MCP server against a live engine and fails loudly on batch-contract incompatibilities (the class of bug that broke 2.7.0–2.8.0 × engine 0.5.60+). Run it before every engine release and every npm publish.
+
+### Fixed
+- `summer_create_scene` no longer uses the destructive temporary-template strategy (open current scene → delete its children → save-as → restore). It now writes a minimal `.tscn` through the identity-bound engine `WriteFile` with a create-only guard, never touches the open scene, verifies by reading the file back, and gained a `rootType` param (Node3D/Node2D/Control). `allow_temporary_scene_mutation` remains accepted as a deprecated no-op.
+- **Scene mutations were completely broken against engine 0.5.60/0.5.61.** The engine now requires `SaveScene`, `InstantiateScene`, `ReplaceNode`, `SimulateInput`, and the `Run*`/`Import*`/`Git*` ops to travel as their own single-op request, and rejects any multi-op batch containing one of them wholesale (`failure_reason: "unsupported_transport"`). Since 2.7.0 appended `SaveScene` to every mutation batch, every `summer_add_node`/`summer_set_prop`/`summer_batch`/`summer_create_scene` call was rejected before anything executed. Mutation batches are now automatically split into sequential requests around single-only ops; all receipts are preserved and merged, and a mutation that applied followed by a save that failed is reported honestly (including which ops already applied and which were not sent).
+- Engine failures no longer hide the precise rejection. `extractOpError` previously returned a generic `"Engine operation failed (terminalState: failed)"` without inspecting `results[]`; it now surfaces the failed op's own error and `failure_reason` (envelope or per-op, either spelling), rendered as JSON when a classifier is present so agents can key on `failure_reason` reliably.
+- `save_frame` is documented with its required `name` argument everywhere (`save_frame()` with no args is a probe script error), plus the deferred scene-mount pattern that avoids black frames.
+- SimulateInput guidance corrected: it IS reachable over MCP/CLI as a single op against the running game (`failure_reason: "not_running"`/`"unsupported"` are the real failure modes); `"unsupported_transport"` only means it was batched with other ops. The previous claim that it needs the in-editor bridge on every build was stale.
+- The scene-preview synthetic-camera note no longer claims the scene has no camera — the engine always synthesizes the preview camera; `sceneHasCamera` is the authoritative signal and keeps its own warning.
+- `summer login` waits 15 minutes on one session id (was 2) with periodic reminders, covering first-time account creation + email confirmation. The gateway never expires a pending session, so the single id stays valid the whole window.
+- Removed the stale "Engine mirror only" banner from the README (it shipped to npm and the public repo, and its claims were wrong).
+
+## [2.8.0] — 2026-08-17 — "Multi-editor MCP routing"
 
 ### Added
 - MCP discovers every live Summer editor through `~/.summer/instances/` and automatically binds local tools to the editor whose project contains the agent's current working directory.

package/README.md

@@ -1,7 +1,5 @@
 # Summer Engine: the AI game engine
 
-> **Engine mirror only.** This directory is intentionally marked `private` and must never be published to npm. Review and reconcile changes into [SummerEngine/summer-engine-agent](https://github.com/SummerEngine/summer-engine-agent), which is the only npm release source.
-
 Build real 2D and 3D Summer games with Summer Engine, the Summer SDK, and
 GDScript. The agent layer can help author code and scenes, but creators remain
 in control of changes and release decisions. Local export support depends on
@@ -324,7 +322,7 @@ summer_batch ops:[{op:"RunVerification", probe_source:"…", max_seconds:20}]
                                       → {ok, results, frames, out_dir}
 ```
 
-Unlike `--headless`, that instance has a real renderer, so `save_frame()` writes an actual image. Probe API: `report()` / `save_frame()` / `dump_tree()` / `press()` / `key()` / `finish()`. **`press()` and `key()` are coroutines — `await` them.** Every project scaffolded by `summer create` ships a working example at `tests/autopilot/`.
+Unlike `--headless`, that instance has a real renderer, so `save_frame("name")` writes an actual image (the name argument is required). Probe API: `report(name, value)` / `save_frame(name)` / `dump_tree()` / `press(action)` / `key(keycode)` / `finish()`. **`press()` and `key()` are coroutines — `await` them.** Every project scaffolded by `summer create` ships a working example at `tests/autopilot/`.
 
 `SimulateInput` is **not** reachable from MCP or the CLI, on any build. It needs the in-editor chat bridge's async reply channel; every queued caller is answered `{ok:false, failure_reason:"unsupported_transport"}`. Use the probe.
 

package/dist/commands/login.js

@@ -4,7 +4,13 @@ import open from "open";
 import { getAuthToken, getCreatorToken, saveCreatorToken, saveLoginSession, } from "../lib/auth.js";
 import { getCreatorApiUrl, getGatewayUrl } from "../lib/config.js";
 const POLL_INTERVAL_MS = 2000;
-const POLL_TIMEOUT_MS = 120000;
+// One generous window on ONE session id. First-time users may need to create an
+// account and confirm an email before they can approve the CLI. The gateway
+// never expires a pending session (the completed payload waits under this id
+// for pickup), so the worst mistake would be rotating ids mid-wait — the user
+// would approve the original browser tab while we poll a different session.
+const POLL_TIMEOUT_MS = 900000;
+const HEARTBEAT_MS = 30000;
 export const loginCommand = new Command("login")
     .description("Sign in to Summer Engine via your browser")
     .option("--creator", "Connect a separately scoped Summercraft creator token for publishing")
@@ -121,9 +127,15 @@ export async function runLogin(overrides = {}) {
     deps.log("Waiting for authentication...");
     const pollUrl = `${gatewayUrl}/api/auth/cli-login?session=${encodeURIComponent(sessionId)}`;
     const startTime = deps.now();
+    let lastHeartbeat = startTime;
     let lastError = null;
     while (deps.now() - startTime < POLL_TIMEOUT_MS) {
         await deps.sleep(POLL_INTERVAL_MS);
+        if (deps.now() - lastHeartbeat >= HEARTBEAT_MS) {
+            lastHeartbeat = deps.now();
+            deps.log('Still waiting — finish signing in (or creating your account) in the browser, then click "Yes, Sign In". Same link: ' +
+                loginUrl);
+        }
         try {
             const res = await deps.fetch(pollUrl, {
                 signal: AbortSignal.timeout(5000),
@@ -161,5 +173,5 @@ export async function runLogin(overrides = {}) {
             lastError = err instanceof Error ? err.message : "Network error";
         }
     }
-    throw new Error(`Login timed out after 120 seconds.${lastError ? ` Last error: ${lastError}` : ""} Recovery: run "summer login" again, complete "Yes, Sign In" in the browser, and return to the terminal within two minutes.`);
+    throw new Error(`Login timed out after ${Math.round(POLL_TIMEOUT_MS / 60000)} minutes.${lastError ? ` Last error: ${lastError}` : ""} Recovery: run "summer login" again and complete "Yes, Sign In" in the browser tab it opens.`);
 }

package/dist/lib/api-client.d.ts

@@ -29,6 +29,15 @@ export type EngineSnapshot = {
     sceneHasCamera?: boolean;
     sceneHadLight?: boolean;
     usedSyntheticCamera?: boolean;
+    /** Scene-preview only: the framing the engine actually rendered with
+     *  ("auto" resolves to "iso"). */
+    framing?: string;
+    /** Scene-preview only: path (relative to the scene root) of the node the
+     *  camera framed when nodePath was given. */
+    framedNode?: string;
+    /** Scene-preview only: how many blank-readback retries the engine needed
+     *  before the capture produced a non-blank frame (0 = clean first read). */
+    renderRetries?: number;
     /** Set true when the bound projectIdHash no longer matches the engine's live
      *  health hash at capture time — the frame may be from the WRONG project
      *  (item 4, client-side drift check). */
@@ -86,8 +95,11 @@ export declare class EngineApiClient {
      */
     executeIdentityBoundOps(ops: Record<string, unknown>[], options?: Record<string, unknown>): Promise<unknown>;
     readProjectFile(path: string, maxBytes?: number): Promise<unknown>;
-    getSceneState(scenePath?: string): Promise<unknown>;
-    getProjectState(): Promise<unknown>;
+    getSceneState(scenePath?: string, options?: {
+        depth?: number;
+        limit?: number;
+    }): Promise<unknown>;
+    getProjectState(prefix?: string): Promise<unknown>;
     getDiagnostics(): Promise<unknown>;
     inspectNode(path: string): Promise<unknown>;
     inspectResource(path: string): Promise<unknown>;
@@ -117,13 +129,18 @@ export declare class EngineApiClient {
      * Offscreen scene render via the `ScenePreview` op over /api/ops (no game
      * boot; physics/animations are static). Mirrors the web previewScene op input
      * (snapshot-tools.ts): { op:'ScenePreview', scene_path?, framing?, size?,
-     * node_path? } — scene_path optional, engine defaults to the open scene. The
-     * result carries image_base64 + mime (+ width/height) plus the P4.3 confession
-     * fields (scene_has_camera / scene_had_light / used_synthetic_camera).
+     * node? } — scene_path optional, engine defaults to the open scene. `node` is
+     * the canonical focus-node arg (the engine also accepts the legacy web wire
+     * name `node_path`); an unresolvable node fails with failure_reason
+     * "node_not_found". framing "auto" is an alias of "iso"; the engine also
+     * accepts "top"/"front"/"back"/"left"/"right" and echoes the resolved framing.
+     * The result carries image_base64 + mime (+ width/height) plus the P4.3
+     * confession fields (scene_has_camera / scene_had_light /
+     * used_synthetic_camera) and framing / framed_node / render_retries.
      */
     scenePreview(input?: {
         scenePath?: string;
-        framing?: "auto" | "top" | "front" | "iso";
+        framing?: "auto" | "iso" | "top" | "front" | "back" | "left" | "right";
         size?: [number, number];
         nodePath?: string;
     }): Promise<EngineSnapshot>;

package/dist/lib/api-client.js

@@ -330,14 +330,33 @@ export class EngineApiClient {
         });
         return this.request("GET", `/api/state/read-file?${query.toString()}`);
     }
-    async getSceneState(scenePath) {
-        const query = scenePath
-            ? `?scene=${encodeURIComponent(scenePath)}`
-            : "";
+    async getSceneState(scenePath, options) {
+        // depth/limit only take effect on targeted (scene=) reads: the engine
+        // routes those through the live command queue and forwards every query
+        // param into StateProvider::scene_state (tool_net_thread.cpp
+        // _parse_state_args). An UNtargeted read is answered from a pre-published
+        // snapshot built with the defaults (depth 2, limit 200) and its query
+        // params are ignored — callers who need depth/limit must pass scenePath
+        // (summer_get_scene_tree resolves the current scene path for this).
+        const parts = [];
+        if (scenePath)
+            parts.push(`scene=${encodeURIComponent(scenePath)}`);
+        if (options?.depth !== undefined)
+            parts.push(`depth=${options.depth}`);
+        if (options?.limit !== undefined)
+            parts.push(`limit=${options.limit}`);
+        const query = parts.length ? `?${parts.join("&")}` : "";
         return this.request("GET", `/api/state/scene${query}`);
     }
-    async getProjectState() {
-        return this.request("GET", "/api/state/project");
+    async getProjectState(prefix) {
+        // ?prefix= is sent for forward-compatibility, but current engine builds
+        // IGNORE it: /api/state/project is always served from the snapshot, which
+        // is published with empty args (local_api_server.cpp
+        // _maybe_publish_snapshot), so StateProvider::project_state never sees the
+        // query. Callers that need a prefix subset must also filter client-side
+        // (summer_get_project_context does).
+        const query = prefix ? `?prefix=${encodeURIComponent(prefix)}` : "";
+        return this.request("GET", `/api/state/project${query}`);
     }
     async getDiagnostics() {
         return this.request("GET", "/api/state/diagnostics");
@@ -475,6 +494,9 @@ export class EngineApiClient {
             sceneHasCamera: boolFrom(payload.scene_has_camera),
             sceneHadLight: boolFrom(payload.scene_had_light),
             usedSyntheticCamera: boolFrom(payload.used_synthetic_camera),
+            framing: stringFrom(payload.framing),
+            framedNode: stringFrom(payload.framed_node),
+            renderRetries: numberFrom(payload.render_retries),
             projectMismatch,
             metadata: withoutImageData(payload),
         };
@@ -525,9 +547,14 @@ export class EngineApiClient {
      * Offscreen scene render via the `ScenePreview` op over /api/ops (no game
      * boot; physics/animations are static). Mirrors the web previewScene op input
      * (snapshot-tools.ts): { op:'ScenePreview', scene_path?, framing?, size?,
-     * node_path? } — scene_path optional, engine defaults to the open scene. The
-     * result carries image_base64 + mime (+ width/height) plus the P4.3 confession
-     * fields (scene_has_camera / scene_had_light / used_synthetic_camera).
+     * node? } — scene_path optional, engine defaults to the open scene. `node` is
+     * the canonical focus-node arg (the engine also accepts the legacy web wire
+     * name `node_path`); an unresolvable node fails with failure_reason
+     * "node_not_found". framing "auto" is an alias of "iso"; the engine also
+     * accepts "top"/"front"/"back"/"left"/"right" and echoes the resolved framing.
+     * The result carries image_base64 + mime (+ width/height) plus the P4.3
+     * confession fields (scene_has_camera / scene_had_light /
+     * used_synthetic_camera) and framing / framed_node / render_retries.
      */
     async scenePreview(input) {
         const opInput = { op: "ScenePreview" };
@@ -539,7 +566,7 @@ export class EngineApiClient {
         if (input?.size)
             opInput.size = input.size;
         if (input?.nodePath)
-            opInput.node_path = input.nodePath;
+            opInput.node = input.nodePath;
         let response;
         try {
             // executeOps stamps the bound identity so a drifted project is rejected

package/dist/mcp/tools/debug-tools.d.ts

@@ -1,2 +1,14 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+/**
+ * Prioritized, bounded view of the engine diagnostics payload:
+ * - console.messages reordered: errors first, then warnings, then a capped tail
+ *   of info/std/editor noise (engine order is newest-first; that order is
+ *   preserved within each severity bucket, so the kept tail is the most recent).
+ * - debugger.errors_data untouched; debugger.warnings_data capped to the most
+ *   recent DEBUGGER_WARNING_CAP entries (engine emits newest-first).
+ * - a `_view` block with honest counters and a hint pointing at includeAll.
+ * Shape-tolerant: anything unexpected passes through unchanged.
+ * Exported for unit tests.
+ */
+export declare function prioritizeDiagnostics(payload: unknown): unknown;
 export declare function registerDebugTools(server: McpServer): void;

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

@@ -2,16 +2,115 @@ import { z } from "zod";
 import { withEngine } from "./with-engine.js";
 import { shapeEngineLogResponse } from "../../lib/log-filters.js";
 import { createDebugReportArtifact } from "../../lib/debug-report.js";
+// summer_get_diagnostics view shaping. The engine serves /api/state/diagnostics
+// from a pre-published snapshot (empty args — query params are NOT forwarded on
+// that route), so trimming has to happen here. The snapshot defaults bury
+// task-specific failures under baseline info noise (50 console messages, up to
+// 100 debugger entries); this reorders by severity and caps ONLY the
+// low-severity bodies. All counts stay intact and honest. No pattern-matching
+// against specific noise strings — severity + recency + caps only.
+const CONSOLE_NOISE_TAIL_CAP = 10;
+const DEBUGGER_WARNING_CAP = 20;
+/**
+ * Prioritized, bounded view of the engine diagnostics payload:
+ * - console.messages reordered: errors first, then warnings, then a capped tail
+ *   of info/std/editor noise (engine order is newest-first; that order is
+ *   preserved within each severity bucket, so the kept tail is the most recent).
+ * - debugger.errors_data untouched; debugger.warnings_data capped to the most
+ *   recent DEBUGGER_WARNING_CAP entries (engine emits newest-first).
+ * - a `_view` block with honest counters and a hint pointing at includeAll.
+ * Shape-tolerant: anything unexpected passes through unchanged.
+ * Exported for unit tests.
+ */
+export function prioritizeDiagnostics(payload) {
+    if (!payload || typeof payload !== "object")
+        return payload;
+    const root = payload;
+    if (!root.data || typeof root.data !== "object")
+        return payload;
+    const data = root.data;
+    const shapedData = { ...data };
+    let totalConsole = 0;
+    let shownConsole = 0;
+    let suppressedInfo = 0;
+    if (data.console && typeof data.console === "object") {
+        const c = data.console;
+        totalConsole = typeof c.total === "number" ? c.total : 0;
+        if (Array.isArray(c.messages)) {
+            const errors = [];
+            const warnings = [];
+            const rest = [];
+            for (const m of c.messages) {
+                const type = m && typeof m === "object" ? m.type : undefined;
+                if (type === "error")
+                    errors.push(m);
+                else if (type === "warning")
+                    warnings.push(m);
+                else
+                    rest.push(m);
+            }
+            const keptRest = rest.slice(0, CONSOLE_NOISE_TAIL_CAP);
+            suppressedInfo = rest.length - keptRest.length;
+            const messages = [...errors, ...warnings, ...keptRest];
+            shownConsole = messages.length;
+            shapedData.console = { ...c, messages, returned: messages.length };
+        }
+    }
+    let totalDebugger = 0;
+    let shownDebugger = 0;
+    let suppressedDebuggerWarnings = 0;
+    if (data.debugger && typeof data.debugger === "object") {
+        const g = data.debugger;
+        totalDebugger =
+            (typeof g.errors === "number" ? g.errors : 0) +
+                (typeof g.warnings === "number" ? g.warnings : 0);
+        const errorsData = Array.isArray(g.errors_data) ? g.errors_data : [];
+        if (Array.isArray(g.warnings_data)) {
+            const keptWarnings = g.warnings_data.slice(0, DEBUGGER_WARNING_CAP);
+            suppressedDebuggerWarnings = g.warnings_data.length - keptWarnings.length;
+            shownDebugger = errorsData.length + keptWarnings.length;
+            shapedData.debugger = { ...g, warnings_data: keptWarnings };
+        }
+        else {
+            shownDebugger = errorsData.length;
+        }
+    }
+    return {
+        ...root,
+        data: shapedData,
+        _view: {
+            mode: "prioritized",
+            totalConsole,
+            shownConsole,
+            suppressedInfo,
+            totalDebugger,
+            shownDebugger,
+            suppressedDebuggerWarnings,
+            hint: "All counts are complete; only low-severity message bodies were trimmed. Re-call with includeAll: true for the untrimmed payload, or use summer_get_console / summer_get_debugger_warnings for targeted reads.",
+        },
+    };
+}
 export function registerDebugTools(server) {
     server.tool("summer_get_diagnostics", `Quick overview of all errors and warnings from both the editor console and the runtime debugger. Returns error counts and a guidance message.
 
 ALWAYS call this FIRST before diving into summer_get_console or summer_get_debugger_errors. It tells you where to look.
 
+By default the response is a prioritized view: errors first, then warnings, then a small capped tail of recent info/std noise. Counts (console totals, debugger totals) are always complete — only low-severity message bodies are trimmed, and a "_view" block reports exactly what was suppressed. Pass includeAll: true for the full untrimmed engine payload.
+
 Typical workflow after making changes:
 1. summer_get_diagnostics — are there issues?
 2. If errors: summer_get_console or summer_get_debugger_errors for details
 3. Fix the issues
-4. summer_get_diagnostics again to verify`, {}, async () => withEngine(async (client) => client.getDiagnostics()));
+4. summer_get_diagnostics again to verify`, {
+        includeAll: z
+            .boolean()
+            .optional()
+            .default(false)
+            .describe("Return the full engine diagnostics payload untrimmed (no severity reordering, no info-noise cap)."),
+    }, async ({ includeAll }) => withEngine(async (client) => {
+        const raw = await client.getDiagnostics();
+        return includeAll ? raw : prioritizeDiagnostics(raw);
+    }));
     server.tool("summer_get_console", `Read recent messages from the editor's Output panel.
 
 Output is post-processed for token economy: consecutive identical messages collapse into one entry with a "(×N)" count suffix, and the response carries a "_filter" summary so you can see what was hidden. Use errors_only=true (default) to drop info/std noise; use raw=true to bypass all shaping.

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

@@ -88,6 +88,62 @@ function getCurrentScene(projectState, sceneState, health) {
         pickString(healthRoot, ["scene", "scenePath", "scene_path"]) ??
         null);
 }
+function getScenePathFromSceneState(sceneState) {
+    const root = asRecord(sceneState);
+    return (pickString(asRecord(root?.provenance), ["scenePath", "scene_path"]) ??
+        pickString(asRecord(root?.data), ["scenePath", "scene_path"]) ??
+        null);
+}
+/** Default prefix set kept in summer_get_project_context when no settingsPrefix
+ *  is given. The full settings dump measured 188KB (~47k tokens) on a real
+ *  project; these prefixes cover what agents actually key on (main scene,
+ *  window size, input actions, physics, renderer). */
+const CONTEXT_SETTINGS_PREFIXES = [
+    "application/",
+    "display/",
+    "input/",
+    "physics/",
+    "rendering/",
+];
+/**
+ * Bound the project-state payload. The engine ignores ?prefix= on
+ * /api/state/project (snapshot-served with empty args — see
+ * ApiClient.getProjectState), so ALL filtering here is client-side:
+ * - settingsPrefix given: keep only entries under that prefix.
+ * - no prefix: keep only the curated CONTEXT_SETTINGS_PREFIXES.
+ * Trimming is always declared in the payload (settingsTruncated /
+ * totalSettings / hint); everything outside data.entries is preserved.
+ */
+function trimProjectSettings(projectState, settingsPrefix) {
+    const root = asRecord(projectState);
+    const data = asRecord(root?.data);
+    const entries = data?.entries;
+    if (!root || !data || !Array.isArray(entries))
+        return projectState;
+    const keyOf = (entry) => stringFrom(asRecord(entry)?.key);
+    const kept = settingsPrefix
+        ? entries.filter((entry) => keyOf(entry)?.startsWith(settingsPrefix) ?? false)
+        : entries.filter((entry) => {
+            const key = keyOf(entry);
+            return key !== null && CONTEXT_SETTINGS_PREFIXES.some((p) => key.startsWith(p));
+        });
+    return {
+        ...root,
+        data: {
+            ...data,
+            entries: kept,
+            settingsTruncated: kept.length < entries.length,
+            totalSettings: entries.length,
+            returnedSettings: kept.length,
+            ...(settingsPrefix
+                ? { settingsPrefix }
+                : {
+                    settingsPrefixesIncluded: [...CONTEXT_SETTINGS_PREFIXES],
+                    settingsHint: "Settings were trimmed to the curated prefixes above to bound payload size. Pass settingsPrefix (e.g. 'audio/' or 'layer_names/') to read another settings group.",
+                }),
+        },
+    };
+}
 export function registerProjectTools(server) {
     server.tool("summer_start_game_task", `Start here for any substantial AI game-building task.
 
@@ -180,12 +236,12 @@ anti-patterns, and recovery steps.`, {}, async () => ({
                             "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), use RunVerification. It is the ONLY interactive route available to MCP, and it is a real one — do NOT hand this rung to the user.",
+                            "To prove input-driven behavior (does jump/move/shoot actually work), prefer RunVerification — a scripted, repeatable probe. SimulateInput is also reachable as a single op against the RUNNING game (see rawOpsViaBatch); do NOT hand this rung to the user while either route works.",
                             "RunVerification: spawn a hidden, disposable game instance that runs a GDScript probe (press inputs, read state, save frames) and dies — never touches the user's editor. Returns results.json + frames. Send it as a raw op through summer_batch (see rawOpsViaBatch).",
-                            "Unlike the editor's own --headless mode, the verify instance renders REAL PIXELS, so save_frame() writes a real image and Performance.TIME_FPS reports a real number.",
+                            "Unlike the editor's own --headless mode, the verify instance renders REAL PIXELS, so save_frame('name') writes a real image and Performance.TIME_FPS reports a real number. save_frame REQUIRES a name argument — save_frame() with no args is a script error (probe fails).",
+                            "Mount probe scenes DEFERRED: get_tree().root.add_child.call_deferred(instance); await get_tree().process_frame; await settle(). A direct add_child during _ready can hit the parent-busy guard and 'succeed' while capturing a black frame.",
                             "press()/key() are COROUTINES — 'await press(\"move_right\", 500)' or the hold never elapses and the input does nothing.",
                             "Assert on physics-frame-derived state (positions after N 'await get_tree().physics_frame'), which is reproducible. press(hold_ms) waits on wall clock, so distance-travelled jitters run to run — assert 'moved more than X', never an exact value.",
-                            "SimulateInput is NOT reachable from MCP — see rawOpsViaBatch. Do not attempt it as a fallback.",
                         ],
                     },
                     // HONESTY — mirror the in-product agent's vision rules. A capture is
@@ -219,8 +275,9 @@ anti-patterns, and recovery steps.`, {}, async () => ({
                     // engine ops that have no dedicated tool are still reachable.
                     rawOpsViaBatch: [
                         "summer_batch runs an array of raw engine ops in one undo group; each op is passed through untouched, so newer engine ops with no dedicated tool are still callable.",
-                        "RunVerification (hidden probe instance): summer_batch ops:[{op:'RunVerification', probe_source:'<gdscript>', max_seconds:20}]. probe_source extends SummerProbeBase and uses report()/save_frame()/press()/key()/finish(); returns {ok, results, frames, out_dir} or {ok:false, failure_reason: spawn_failed|timeout|bad_args|no_project|probe_not_node}.",
-                        "SimulateInput is NOT reachable this way, on any engine build. It needs the in-editor chat bridge's async reply channel; every queued caller (MCP, CLI) is answered with {ok:false, failure_reason:'unsupported_transport'}. Use RunVerification's press()/key() instead.",
+                        "RunVerification (hidden probe instance): summer_batch ops:[{op:'RunVerification', probe_source:'<gdscript>', max_seconds:20}]. probe_source extends SummerProbeBase and uses report(name, value)/save_frame(name)/press(action)/key(keycode)/finish(); returns {ok, results, frames, out_dir} or {ok:false, failure_reason: spawn_failed|timeout|bad_args|no_project|probe_not_node}. save_frame REQUIRES a name argument.",
+                        "SimulateInput (drive the RUNNING game — summer_play first): summer_batch ops:[{op:'SimulateInput', type:'action', action:'jump', pressed:true}], sent ALONE as the only op. failure_reason 'not_running' = start the game first; 'unsupported' = the running game build predates the handler — use RunVerification instead.",
+                        "SINGLE-OP CONTRACT: the engine rejects any multi-op batch containing SaveScene, InstantiateScene, ReplaceNode, SimulateInput, ViewportSnapshot, GameSnapshot, Run*/Import* or Git* ops (failure_reason 'unsupported_transport', nothing executes). summer_batch splits these into sequential requests for you; when composing raw batches keep them as their own call anyway.",
                         "WriteFile and ReplaceText are rejected here by design — use summer_write_file / summer_replace_text so project identity, content guards and same-file ordering are enforced.",
                         "You do not need an engine op to run a shell command: your own host already has a shell. The engine binary that runs project scripts is at OS.get_executable_path() (on macOS, /Applications/Summer.app/Contents/MacOS/Summer); see the summer-cli headless-scripting skill.",
                         "These are runtime ops, not scene mutations — the batch undo group is a harmless no-op for them.",
@@ -233,7 +290,7 @@ anti-patterns, and recovery steps.`, {}, async () => ({
                         "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 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 returns 'unsupported' / an unknown-op error: this engine build predates it — fall back to summer_play + summer_get_debugger_errors.",
-                        "If SimulateInput returns 'unsupported_transport': that is permanent for MCP, not a build gap. Rewrite the check as a RunVerification probe.",
+                        "If any op returns 'unsupported_transport': it was batched with other ops. Resend it as the ONLY op in the request (nothing from the rejected batch was applied).",
                     ],
                     debugging: [
                         "Set SUMMER_MCP_DEBUG=1 in the MCP server's environment to log a structured stderr line per tool call (tool, ok, durationMs, terminalState, errorClass, failureReason, retried, boundProjectIdHash). With the flag OFF, only failures are logged. Use it to see exactly which op failed and why.",
@@ -249,19 +306,33 @@ anti-patterns, and recovery steps.`, {}, async () => ({
 - main scene path from project settings
 - lightweight .summer project memory summary when project path is available
 
-Use this first in every fresh chat to avoid guessing scene filenames or editing the wrong scene.`, {}, async () => withEngine(async (client) => {
-        const [health, projectState, sceneState] = await Promise.all([
+Use this first in every fresh chat to avoid guessing scene filenames or editing the wrong scene.
+
+Project settings in project.data.entries are trimmed to a curated prefix set
+(application/, display/, input/, physics/, rendering/) to bound payload size —
+the untrimmed dump can exceed 45k tokens. The payload declares the trim
+(settingsTruncated, totalSettings, settingsPrefixesIncluded). Pass
+settingsPrefix to read a specific settings group (e.g. 'audio/') instead.`, {
+        settingsPrefix: z
+            .string()
+            .optional()
+            .describe("Only return project settings whose key starts with this prefix, e.g. 'audio/' or 'application/config/'. Omit for the curated default set."),
+    }, async ({ settingsPrefix }) => withEngine(async (client) => {
+        const [health, fullProjectState, sceneState] = await Promise.all([
             client.health(),
-            client.getProjectState(),
+            client.getProjectState(settingsPrefix),
             client.getSceneState().catch((err) => ({
                 ok: false,
                 error: err instanceof Error ? err.message : String(err),
             })),
         ]);
-        const projectPath = getProjectPath(projectState, health);
-        const projectName = getProjectName(projectState, health);
-        const mainScene = getMainScene(projectState);
-        const currentScene = getCurrentScene(projectState, sceneState, health);
+        // Derived fields read the UNtrimmed state so a narrow settingsPrefix
+        // cannot hide mainScene/projectPath from the context summary.
+        const projectState = trimProjectSettings(fullProjectState, settingsPrefix);
+        const projectPath = getProjectPath(fullProjectState, health);
+        const projectName = getProjectName(fullProjectState, health);
+        const mainScene = getMainScene(fullProjectState);
+        const currentScene = getCurrentScene(fullProjectState, sceneState, health);
         // This tool is the deliberate (re)bind point: capture the currently-open
         // project as the one this session's mutations are pinned to. After an
         // engine project switch the agent calls this to intentionally follow the
@@ -326,9 +397,48 @@ Example: Bind jump to Space and W:
     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.`, {
+not require OpenScene.
+
+The engine defaults to depth 2 and limit 200 nodes and SILENTLY truncates
+deeper hierarchies (the response then carries truncated: true and a visited
+count lower than the real node count). Pass an explicit depth (e.g. 10) to
+read a full tree — a 102-node scene returns only 61 nodes at the defaults.`, {
         scenePath: z.string().optional().describe("Exact res:// scene path to inspect"),
-    }, async ({ scenePath }) => withEngine(async (client) => client.getSceneState(scenePath)));
+        depth: z
+            .number()
+            .int()
+            .positive()
+            .optional()
+            .describe("Maximum tree depth to walk. Engine default is 2 — pass a larger value for deep hierarchies."),
+        limit: z
+            .number()
+            .int()
+            .positive()
+            .optional()
+            .describe("Maximum number of nodes to return. Engine default is 200."),
+    }, async ({ scenePath, depth, limit }) => withEngine(async (client) => {
+        if (depth === undefined && limit === undefined) {
+            return client.getSceneState(scenePath);
+        }
+        // The engine honors depth/limit ONLY on targeted (scene=) reads; an
+        // untargeted read is served from a pre-published snapshot built with
+        // the defaults, and its query params are dropped. Resolve the current
+        // scene path first so depth/limit actually take effect.
+        let target = scenePath;
+        if (!target) {
+            const snapshot = await client.getSceneState();
+            target = getScenePathFromSceneState(snapshot) ?? undefined;
+            if (!target) {
+                const record = asRecord(snapshot);
+                return {
+                    ...(record ?? { snapshot }),
+                    depthLimitApplied: false,
+                    note: "depth/limit were IGNORED: the current scene path could not be resolved, and the engine only honors depth/limit on scene-targeted reads. Pass scenePath explicitly to apply them.",
+                };
+            }
+        }
+        return client.getSceneState(target, { depth, limit });
+    }));
     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

@@ -1,7 +1,20 @@
 import { z } from "zod";
-import { withEngine } from "./with-engine.js";
-import { readFile } from "fs/promises";
-import { join } from "path";
+import { withEngine, extractOpError } from "./with-engine.js";
+// Engine ops that MUST be dispatched as their own single-op request. Mirrors
+// _summer_requires_single_async_dispatch (local_api_server.cpp, engine 0.5.60+):
+// the engine rejects any multi-op batch containing one of these WHOLESALE —
+// nothing in the batch executes, and the batch fails with per-op
+// failure_reason "unsupported_transport"/"skipped". Git ops are covered by the
+// prefix check below.
+const SINGLE_ONLY_OPS = new Set([
+    "SaveScene", "InstantiateScene", "ReplaceNode",
+    "SimulateInput", "ViewportSnapshot", "GameSnapshot",
+    "RunCommand", "RunVerification", "RunEditorScript",
+    "ImportFromUrl", "ImportFromUrlBatch", "ExtractZipFromUrl",
+]);
+function isSingleOnlyOp(kind) {
+    return SINGLE_ONLY_OPS.has(kind) || kind.startsWith("Git");
+}
 function sceneMutationOps(ops) {
     const saveIndexes = ops
         .map((op, index) => op.op === "SaveScene" ? index : -1)
@@ -17,23 +30,72 @@ function sceneMutationOps(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;
-    try {
-        const text = await readFile(join(projectPath, "project.godot"), "utf-8");
-        const match = text.match(/run\/main_scene="([^"]+)"/);
-        return match?.[1] ?? null;
+/** Split an op list into sequential engine requests: consecutive batchable ops
+ *  stay grouped, each single-only op becomes its own request. Order preserved. */
+function chunkOpsForDispatch(ops) {
+    const chunks = [];
+    let current = [];
+    for (const op of ops) {
+        if (isSingleOnlyOp(String(op.op ?? ""))) {
+            if (current.length > 0) {
+                chunks.push(current);
+                current = [];
+            }
+            chunks.push([op]);
+        }
+        else {
+            current.push(op);
+        }
     }
-    catch {
-        return null;
+    if (current.length > 0)
+        chunks.push(current);
+    return chunks;
+}
+/** Execute an op list as sequential engine requests honoring the single-op
+ *  dispatch contract. Receipts from every request are preserved and merged, so
+ *  an op that applied followed by one that failed is reported honestly instead
+ *  of masked. */
+async function executeOpsChunked(send, ops) {
+    const chunks = chunkOpsForDispatch(ops);
+    if (chunks.length === 1)
+        return send(chunks[0]);
+    const receipts = [];
+    const combinedResults = [];
+    for (let i = 0; i < chunks.length; i++) {
+        const receipt = await send(chunks[i]);
+        receipts.push(receipt);
+        const envelope = (receipt ?? {});
+        if (Array.isArray(envelope.results)) {
+            combinedResults.push(...envelope.results);
+        }
+        if (extractOpError(receipt)) {
+            const failedKind = String(chunks[i][0]?.op ?? "batch");
+            const appliedOps = chunks.slice(0, i).flat().map((op) => String(op.op ?? ""));
+            const notSent = chunks.slice(i + 1).flat().map((op) => String(op.op ?? ""));
+            const baseError = (typeof envelope.error === "string" && envelope.error) || `Engine request failed (${failedKind}).`;
+            const honestError = appliedOps.length > 0
+                ? `${baseError} NOTE: ${appliedOps.length} earlier op(s) already applied (${appliedOps.join(", ")})` +
+                    (failedKind === "SaveScene"
+                        ? " — the scene is modified in the editor but NOT saved to disk. Fix the problem, then call summer_save_scene."
+                        : ".") +
+                    (notSent.length > 0 ? ` Not sent: ${notSent.join(", ")}.` : "")
+                : baseError;
+            return {
+                ...envelope,
+                error: honestError,
+                results: combinedResults,
+                receipts,
+            };
+        }
     }
+    const last = (receipts[receipts.length - 1] ?? {});
+    return { ...last, results: combinedResults, requests: chunks.length, receipts };
+}
+/** Scene mutation entry point: appends the transaction-boundary SaveScene, then
+ *  dispatches with the single-op contract (mutations batch together, SaveScene
+ *  and other single-only ops travel alone). */
+function executeSceneMutation(client, scenePath, ops, options) {
+    return executeOpsChunked((chunk) => client.executeIdentityBoundOps(chunk, { ...(options ?? {}), scenePath }), sceneMutationOps(ops));
 }
 function requireSuccessfulOps(result, context) {
     const receipt = (result ?? {});
@@ -49,61 +111,94 @@ function requireSuccessfulOps(result, context) {
     }
     return receipt;
 }
+/** Compose the minimal valid .tscn text scene: header + one root node.
+ *  `uid` and `load_steps` are optional in the engine parser
+ *  (resource_format_text.cpp treats a missing uid as INVALID_ID); the editor
+ *  assigns a uid on first save. */
+function minimalSceneText(rootName, rootType) {
+    return `[gd_scene format=3]\n\n[node name="${rootName}" type="${rootType}"]\n`;
+}
+// Node names reject . : @ / " %; the type must be a plain class name.
+// Both are interpolated into quoted .tscn fields, so validate before composing.
+const VALID_ROOT_NAME = /^[A-Za-z_][A-Za-z0-9_\- ]*$/;
+const VALID_ROOT_TYPE = /^[A-Za-z_][A-Za-z0-9_]*$/;
 export function registerSceneTools(server) {
-    server.tool("summer_create_scene", `Create a new empty scene file safely.
+    server.tool("summer_create_scene", `Create a new empty scene file. Writes a minimal .tscn through the identity-bound engine with a create-only guard: it fails if the path already exists, and it never touches the currently open scene.
 
-IMPORTANT:
-- This tool uses a temporary mutation strategy: it opens a template scene, removes children, saves to a new path, then restores the previous scene.
-- To prevent accidental destructive actions, you MUST explicitly set allow_temporary_scene_mutation=true.
-- If you don't want this strategy, stop and ask the user for manual scene creation in the editor.
+The new scene is on disk but NOT opened. Call summer_open_scene to start editing it, then summer_add_node to build it out.
 
 Recommended workflow:
 1) Call summer_get_project_context
-2) Call summer_open_main_scene (optional)
-3) Call summer_create_scene with a new path`, {
+2) Call summer_create_scene with a new res:// path
+3) Call summer_open_scene with that path`, {
         path: z.string().describe("New scene path, e.g. 'res://scenes/empty_level.tscn'"),
         rootName: z.string().default("Main").describe("Root node name for the new scene"),
+        rootType: z
+            .string()
+            .default("Node3D")
+            .describe("Root node type. Default 'Node3D' (3D scenes); common alternatives: 'Node2D' (2D scenes), 'Control' (UI scenes), 'Node' (logic-only)."),
         allow_temporary_scene_mutation: z
             .boolean()
-            .default(false)
-            .describe("Safety gate. Must be true to proceed."),
-    }, async ({ path, rootName, allow_temporary_scene_mutation }) => withEngine(async (client) => {
-        if (!allow_temporary_scene_mutation) {
-            throw new Error("Refusing to create scene without explicit approval. Re-run with allow_temporary_scene_mutation=true.");
+            .optional()
+            .describe("DEPRECATED, ignored. Scene creation no longer mutates any open scene; kept only so older callers don't break."),
+    }, async ({ path, rootName, rootType }) => withEngine(async (client) => {
+        const safePath = path.trim().replace(/\\/g, "/");
+        if (!safePath.startsWith("res://") || safePath.includes("..")) {
+            throw new Error("Scene path must be a traversal-free res:// project path.");
+        }
+        if (!safePath.endsWith(".tscn")) {
+            throw new Error("New scenes must use the text format: the path must end in .tscn.");
+        }
+        if (!VALID_ROOT_NAME.test(rootName)) {
+            throw new Error(`Invalid rootName "${rootName}": use letters, digits, underscores, hyphens, or spaces, starting with a letter or underscore.`);
+        }
+        if (!VALID_ROOT_TYPE.test(rootType)) {
+            throw new Error(`Invalid rootType "${rootType}": must be a plain class name like 'Node3D', 'Node2D', or 'Control'.`);
         }
-        const health = (await client.health());
-        const currentScene = typeof health.scene === "string" && health.scene.length > 0 ? health.scene : null;
-        const projectPath = typeof health.project_path === "string" ? health.project_path : undefined;
-        const mainScene = await readMainSceneFromProject(projectPath);
-        const templateScene = currentScene || mainScene;
-        if (!templateScene) {
-            throw new Error("No scene open and could not resolve main scene. Call summer_get_project_context first, then open a known scene.");
+        // Same engine-routed guarded write path summer_write_file uses:
+        // identity-bound, and mustNotExist makes the engine refuse (create-only)
+        // if the path already exists. The open scene is never touched.
+        const receipt = requireSuccessfulOps(await client.executeIdentityBoundOps([
+            {
+                op: "WriteFile",
+                path: safePath,
+                content: minimalSceneText(rootName, rootType),
+                mustNotExist: true,
+            },
+        ]), `Creating ${safePath}`);
+        // Post-write verification: read the file back through the engine. The
+        // write receipt already passed; a read-back failure is reported honestly
+        // instead of failing the create or being masked.
+        let verified = false;
+        let verifyError;
+        try {
+            const read = (await client.readProjectFile(safePath, 4096));
+            const content = typeof read?.data?.content === "string" ? read.data.content : null;
+            if (read?.ok === false) {
+                verifyError = String(read.error ?? "engine could not read the file back");
+            }
+            else if (content === null) {
+                verifyError = "engine returned no text content on read-back";
+            }
+            else if (!content.includes(`[node name="${rootName}"`)) {
+                verifyError = "read-back content does not contain the expected root node";
+            }
+            else {
+                verified = true;
+            }
         }
-        await client.executeOps([{ op: "OpenScene", path: templateScene }]);
-        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}` }));
-        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) {
-            requireSuccessfulOps(await client.executeOps([{ op: "OpenScene", path: currentScene }]), `Restoring ${currentScene}`);
+        catch (err) {
+            verifyError = err instanceof Error ? err.message : String(err);
         }
         return {
             ok: true,
-            created: path,
+            created: safePath,
             rootName,
-            templateScene,
-            restoredScene: currentScene,
-            receipt: createReceipt,
+            rootType,
+            verified,
+            ...(verifyError ? { verifyError } : {}),
+            receipt,
+            hint: "The new scene is on disk but not open. Call summer_open_scene to start editing it.",
         };
     }));
     server.tool("summer_add_node", `Add a new node to the scene tree.
@@ -261,13 +356,18 @@ Each op in the array uses the same format as the individual tools:
 - {"op": "SetResourceProperty", "nodePath": "Floor", "resourceProperty": "mesh", "subProperty": "size", "value": "Vector2(20, 20)"}
 
 RAW RUNTIME OPS (interactive verification — structured failure_reason passes through verbatim):
-- 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(). This is the ONLY way to drive input from MCP, and unlike the editor it renders real pixels, so save_frame() produces a real image.
-- SimulateInput is NOT reachable from MCP or the CLI. It requires the in-editor chat bridge's async reply channel; every queued caller gets {"ok": false, "failure_reason": "unsupported_transport"} on every engine build. Do not send it and do not treat that reply as a version problem — use RunVerification's press()/key() instead.
+- RunVerification — spawn a hidden, disposable game instance that runs a GDScript probe and dies (never touches the editor): {"op": "RunVerification", "probe_source": "...", "max_seconds": 20}. Returns {ok, results, frames, out_dir}. Probe API: report(name, value) / save_frame(name) / press(action) / key(keycode) / finish(). save_frame REQUIRES a name argument — save_frame() with no args is a script error. Mount scenes deferred: get_tree().root.add_child.call_deferred(instance); await get_tree().process_frame; await settle() — a direct add_child in _ready can hit the parent-busy guard and capture a black frame.
+- SimulateInput — inject an action/key/mouse/axis into the RUNNING game (summer_play first): {"op": "SimulateInput", "type": "action", "action": "jump", "pressed": true}. It MUST be sent alone (single-op batch). failure_reason "not_running" = start the game first; "unsupported" = the running game build predates the handler — fall back to RunVerification or ask the user.
 
 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.`, {
+must appear exactly once and be the final operation. The engine requires
+SaveScene, InstantiateScene, ReplaceNode, SimulateInput, and the Run*/Import*
+ops to travel as their own request, so this tool automatically splits your op
+list into sequential requests around them — each split chunk is its own undo
+step, and if a later chunk fails the receipt reports exactly which earlier ops
+already applied.`, {
         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 ({ scenePath, ops }) => withEngine(async (client) => {
@@ -291,6 +391,6 @@ must appear exactly once and be the final operation.`, {
         const options = { groupUndo: true, ...(scenePath ? { scenePath } : {}) };
         return needsScenePath
             ? executeSceneMutation(client, scenePath, ops, options)
-            : client.executeOps(ops, options);
+            : executeOpsChunked((chunk) => client.executeOps(chunk, options), ops);
     }));
 }

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

@@ -18,7 +18,7 @@ target:
     It does NOT use the scene's environment/sky, and it injects a synthetic camera and light when the scene has none. The scene's WorldEnvironment — sky, fog, tonemap, glow, SSAO, ambient — is replaced by a flat preview environment. So this target CANNOT verify lighting, mood, or any material property that depends on the environment: change them and the frame comes back identical. For those, boot the game or run a RunVerification probe, whose instance renders the real environment.
   "game" — a frame from the RUNNING game (real runtime state). Start the game first (summer_play). Not available over a plain local connection — needs the Summer desktop app bridge.
 
-Static frame only — one moment, not motion. For a SEQUENCE of frames over time, or for anything lighting-dependent when the desktop bridge is unavailable, use a RunVerification probe's save_frame() — its instance has a real renderer.`, {
+Static frame only — one moment, not motion. For a SEQUENCE of frames over time, or for anything lighting-dependent when the desktop bridge is unavailable, use a RunVerification probe's save_frame(name) — its instance has a real renderer.`, {
         target: z
             .enum(["viewport", "scene", "game"])
             .optional()
@@ -29,9 +29,12 @@ Static frame only — one moment, not motion. For a SEQUENCE of frames over time
             .optional()
             .describe('target:"scene" only. Full scene path, e.g. "res://main.tscn". Omit to render the currently-open scene.'),
         framing: z
-            .enum(["auto", "top", "front", "iso"])
+            .enum(["auto", "iso", "top", "front", "back", "left", "right"])
             .optional()
-            .describe('target:"scene" only. Camera framing preset. Default: auto.'),
+            .describe('target:"scene" only, 3D scenes. Camera direction preset: "iso" = 3/4 diagonal view, ' +
+            '"top" = straight down, "front" = camera at +Z, "back" = camera at -Z, ' +
+            '"left" = camera at -X, "right" = camera at +X. "auto" (default) is an alias of "iso". ' +
+            "The result reports the resolved framing."),
         size: z
             .array(z.number().int().positive())
             .length(2)
@@ -40,7 +43,10 @@ Static frame only — one moment, not motion. For a SEQUENCE of frames over time
         nodePath: z
             .string()
             .optional()
-            .describe('target:"scene" only. Scene-tree node path to frame on.'),
+            .describe('target:"scene" only. Node path relative to the scene root (e.g. "Player/Mesh") to frame ' +
+            "INSTEAD of the whole scene — the camera fits that node's combined bounds (3D visual AABBs " +
+            "or 2D rects, children included). A bare unique name is also found recursively. " +
+            'Fails with failure_reason "node_not_found" when the path does not resolve (no silent whole-scene fallback).'),
     }, async ({ target, scenePath, framing, size, nodePath }) => withEngine(async (client) => {
         if (target === "game")
             return client.gameSnapshot();
@@ -112,11 +118,28 @@ Static frame only — one moment, not motion. For a SEQUENCE of frames over time
                 if (snap.sceneHadLight === false) {
                     warnings.push("WARNING: this scene has no light — lit materials may appear black when played.");
                 }
+                // The engine ALWAYS synthesizes the preview camera (preview_ops.cpp
+                // sets used_synthetic_camera unconditionally) — the flag says nothing
+                // about the scene's own cameras. sceneHasCamera above is the
+                // authoritative "does this scene have a camera" answer.
                 if (snap.usedSyntheticCamera) {
-                    warnings.push("NOTE: this preview used a synthetic camera the engine added just for the render — the scene itself has no camera, so it will NOT frame like this when played.");
+                    warnings.push("NOTE: this preview is framed by a synthetic render camera, NOT the scene's own camera — the played game will not frame like this image.");
                 }
             }
-            const caption = `${label} (${dims}). Saved to ${snap.localPath ?? "n/a"}. Review the image above and describe what you actually see.` +
+            // Scene-preview capture details: resolved framing ("auto" -> "iso"),
+            // which node was framed (confirms nodePath resolved), and how many
+            // blank-readback retries the engine needed (0 = omitted).
+            const details = [];
+            if (target === "scene") {
+                if (snap.framing)
+                    details.push(`framing: ${snap.framing}`);
+                if (snap.framedNode)
+                    details.push(`framed node: ${snap.framedNode}`);
+                if (snap.renderRetries)
+                    details.push(`render retries: ${snap.renderRetries}`);
+            }
+            const detailNote = details.length ? `; ${details.join(", ")}` : "";
+            const caption = `${label} (${dims}${detailNote}). Saved to ${snap.localPath ?? "n/a"}. Review the image above and describe what you actually see.` +
                 (warnings.length ? `\n\n${warnings.join("\n")}` : "");
             return [
                 { type: "image", data: snap.base64, mimeType: snap.mime || "image/jpeg" },

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

@@ -9,6 +9,13 @@ function attachMeta(result, meta) {
     });
     return result;
 }
+function getFailureReason(value) {
+    return typeof value.failureReason === "string"
+        ? value.failureReason
+        : typeof value.failure_reason === "string"
+            ? value.failure_reason
+            : undefined;
+}
 // 0.5.34 Block E contract (publicsummerengine src/lib/tools/contract.ts §0.1).
 // The async lifecycle (async-op-lifecycle.ts pollOpToTerminal) merges
 // terminalState/errorClass onto the apply dict it returns. ONLY these two are
@@ -36,14 +43,11 @@ function readClassifiers(result) {
     if (!result || typeof result !== "object")
         return {};
     const op = result;
+    const failed = op.results?.find((entry) => entry.ok === false);
     return {
         terminalState: typeof op.terminalState === "string" ? op.terminalState : undefined,
         errorClass: typeof op.errorClass === "string" ? op.errorClass : undefined,
-        failureReason: typeof op.failureReason === "string"
-            ? op.failureReason
-            : typeof op.failure_reason === "string"
-                ? op.failure_reason
-                : undefined,
+        failureReason: getFailureReason(op) ?? (failed ? getFailureReason(failed) : undefined),
     };
 }
 /**
@@ -63,25 +67,53 @@ export function extractOpError(result) {
     if (!result || typeof result !== "object")
         return null;
     const op = result;
+    const firstFailed = op.results?.find((r) => r.ok === false);
+    // The engine stamps failure classifiers on the envelope OR per-op inside
+    // results[] (the batch gate does the latter) — read both.
+    const failureReason = getFailureReason(op) ?? (firstFailed ? getFailureReason(firstFailed) : undefined);
+    // Classified failures are rendered as JSON so callers can reliably read
+    // failure_reason instead of scraping a sentence. A plain-text "Hint:" line may
+    // follow the JSON in the final tool text. Unclassified failures stay plain.
+    const classify = (message) => {
+        if (!failureReason)
+            return message;
+        return JSON.stringify({
+            error: message,
+            failure_reason: failureReason,
+            ...(typeof firstFailed?.error === "string" && firstFailed.error.length > 0 && firstFailed.error !== message
+                ? { op_error: firstFailed.error }
+                : {}),
+            ...(typeof firstFailed?.op === "string" ? { op: firstFailed.op } : {}),
+            ...(typeof op.terminalState === "string" ? { terminalState: op.terminalState } : {}),
+            ...(typeof op.errorClass === "string" ? { errorClass: op.errorClass } : {}),
+        }, null, 2);
+    };
     // Failure terminalState takes precedence — it is set by the async lifecycle
     // exactly when the op did not land (timeout, backpressure, lease/identity
-    // rejection, cancellation), often with NO results[] to inspect.
+    // rejection, cancellation), sometimes with NO results[] to inspect. Prefer the
+    // precise engine rejection (envelope error, then the failed op's error) over
+    // the generic terminal-state sentence.
     const ts = op.terminalState;
     if (typeof ts === "string" && ts.length > 0 && !SUCCESS_TERMINAL_STATES.has(ts)) {
-        if (typeof op.error === "string" && op.error.length > 0)
-            return op.error;
-        return TERMINAL_STATE_MESSAGES[ts] ?? `Engine operation failed (terminalState: ${ts}).`;
+        const message = (typeof op.error === "string" && op.error.length > 0 && op.error) ||
+            (typeof firstFailed?.error === "string" && firstFailed.error.length > 0 && firstFailed.error) ||
+            TERMINAL_STATE_MESSAGES[ts] ||
+            `Engine operation failed (terminalState: ${ts}).`;
+        return classify(message);
     }
-    // An explicit ok:false / status:"error" is a failure even when the engine
-    // omitted an error string — surface it rather than mask it (matches the web
-    // contract `isFailureSignal`).
-    if (op.ok === false)
-        return op.error || "Engine operation failed (ok: false).";
-    if (op.status === "error")
-        return op.error || "Engine operation failed (status: error).";
-    const firstFailed = op.results?.find((r) => r.ok === false);
-    if (firstFailed) {
-        return firstFailed.error || `Engine op failed${firstFailed.op ? ` (${firstFailed.op})` : ""}.`;
+    // An explicit ok:false / status:"error" / failed op inside results[] is a
+    // failure even when the engine omitted an error string — surface it rather
+    // than mask it (matches the web contract `isFailureSignal`). The envelope
+    // error is kept when present; the failed op's own error backs it up.
+    if (op.ok === false || op.status === "error" || firstFailed) {
+        const message = (typeof op.error === "string" && op.error.length > 0 && op.error) ||
+            (typeof firstFailed?.error === "string" && firstFailed.error.length > 0 && firstFailed.error) ||
+            (firstFailed
+                ? `Engine op failed${firstFailed.op ? ` (${firstFailed.op})` : ""}.`
+                : op.ok === false
+                    ? "Engine operation failed (ok: false)."
+                    : "Engine operation failed (status: error).");
+        return classify(message);
     }
     return null;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "summer-engine",
-  "version": "2.8.0",
+  "version": "2.8.1",
   "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",