summer-engine 2.7.0 → 2.8.1

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.
@@ -120,7 +215,7 @@ Common node types:
 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'"),
+        type: z.string().describe("Summer Engine node type, e.g. 'MeshInstance3D', 'CharacterBody3D'"),
         name: z.string().describe("Name for the new node, e.g. 'Player', 'MainCamera'"),
     }, 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.
@@ -147,7 +242,7 @@ COMMON PROPERTIES:
         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"),
+        value: z.union([z.string(), z.number(), z.boolean()]).describe("Value in Summer Engine variant-string format for complex types, native JSON for primitives"),
     }, 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.
 
@@ -159,7 +254,7 @@ Use when you need to modify a sub-property of a resource, like:
         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"),
+        value: z.union([z.string(), z.number(), z.boolean()]).describe("Value in Summer Engine variant-string format"),
     }, async ({ scenePath, nodePath, resourceProperty, subProperty, value }) => withEngine(async (client) => executeSceneMutation(client, scenePath, [
         { op: "SetResourceProperty", nodePath, resourceProperty, subProperty, value },
     ])));
@@ -260,14 +355,19 @@ Each op in the array uses the same format as the individual tools:
 - {"op": "SetProp", "path": "Floor", "key": "mesh", "value": "PlaneMesh"}
 - {"op": "SetResourceProperty", "nodePath": "Floor", "resourceProperty": "mesh", "subProperty": "size", "value": "Vector2(20, 20)"}
 
-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().
+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": "...", "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

@@ -10,14 +10,15 @@ import { withEngine } from "./with-engine.js";
 export function registerVisualTools(server) {
     server.tool("summer_screenshot", `Capture a frame from Summer Engine and return it as an image you can look at directly.
 
-Use this to visually verify your work: scene layout, asset placement, scale, framing, lighting, materials, missing/untextured assets, or runtime gameplay state. You see the actual pixels — no description layer in between.
+Use this to visually verify your work: scene layout, asset placement, scale, framing, missing/untextured assets, or runtime gameplay state. You see the actual pixels — no description layer in between. Lighting and materials are only truthfully shown by the "viewport" and "game" targets — see the note on "scene" below.
 
 target:
   "viewport" (default) — the editor's CURRENT view (whatever scene/tab is open). No game boot. Use for edit-time checks of how the scene looks right now.
-  "scene" — an OFFSCREEN render of a scene file (no game boot; physics/particles/animations are static at t=0). Optionally pass scenePath/framing/size/nodePath. Use for a quick composed look at a scene without touching the editor's open tab.
+  "scene" — an OFFSCREEN render of a scene file (no game boot; physics/particles/animations are static at t=0). Optionally pass scenePath/framing/size/nodePath. Use for COMPOSITION, SCALE and FRAMING without touching the editor's open tab.
+    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. If a game capture is unavailable, use "viewport" or "scene", or ask the user to share a screenshot of the running game.`, {
+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()
@@ -28,9 +29,12 @@ Static frame only — one moment, not motion. If a game capture is unavailable,
             .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)
@@ -39,7 +43,10 @@ Static frame only — one moment, not motion. If a game capture is unavailable,
         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();
@@ -111,11 +118,28 @@ Static frame only — one moment, not motion. If a game capture is unavailable,
                 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/hooks/session-start.sh

@@ -3,7 +3,7 @@
 #
 # Event:    SessionStart (matcher: startup|clear|compact)
 # Purpose:  Orient Claude on every fresh Summer-enabled session.
-#           Detect Godot project + GameSoul + doctor health, surface a one-line
+#           Detect Summer project + GameSoul + doctor health, surface a one-line
 #           Bob-style greeting as additional context.
 #
 # Input:    JSON on stdin with { session_id, source, model, cwd, ... }
@@ -36,7 +36,7 @@ else
     LINES+=("Summer ready.")
 fi
 
-# Line 2: Godot project + GameSoul one-liner (only if project.godot exists)
+# Line 2: Summer project + GameSoul one-liner (only if project.godot exists)
 if [ -f "${PROJECT_DIR}/project.godot" ]; then
     PROJECT_NAME=$(grep -E '^config/name=' "${PROJECT_DIR}/project.godot" 2>/dev/null \
         | head -1 | sed 's/^config\/name=//;s/^"//;s/"$//')
@@ -48,12 +48,12 @@ if [ -f "${PROJECT_DIR}/project.godot" ]; then
         SOUL_LINE=$(awk 'BEGIN{p=""} /^[^#[:space:]]/ && NF>0 {p=$0; exit} END{print p}' \
             "$SOUL_FILE" 2>/dev/null | cut -c1-120)
         if [ -n "$SOUL_LINE" ]; then
-            LINES+=("Godot project: ${PROJECT_NAME}. GameSoul: ${SOUL_LINE}")
+            LINES+=("Summer project: ${PROJECT_NAME}. GameSoul: ${SOUL_LINE}")
         else
-            LINES+=("Godot project: ${PROJECT_NAME}.")
+            LINES+=("Summer project: ${PROJECT_NAME}.")
         fi
     else
-        LINES+=("Godot project: ${PROJECT_NAME}.")
+        LINES+=("Summer project: ${PROJECT_NAME}.")
     fi
 fi
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "summer-engine",
-  "version": "2.7.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",
@@ -41,6 +41,7 @@
   "files": [
     "dist/",
     "skills/",
+    "references/",
     "commands/",
     "hooks/",
     "assets/",
@@ -65,6 +66,7 @@
     "dev": "tsc --watch",
     "summer": "node dist/bin/summer.js",
     "test": "vitest run",
+    "test:public-language": "vitest run src/lib/public-surface-language.test.ts",
     "test:watch": "vitest",
     "prepublishOnly": "npm run build && npm test"
   },

package/references/collaborative-protocol.md

@@ -0,0 +1,50 @@
+# Collaborative Protocol — "May I write?"
+
+> Every Summer skill must follow this. The agent works *with* the user, not around them.
+
+## The rule
+
+**Before any user-visible write step, the agent must explicitly state what it is about to do and ask permission to proceed.**
+
+This applies to:
+- Creating files (`.gd`, `.tscn`, `.tres`, JSON, configs)
+- Modifying existing files (especially `.gd` and `.tscn`)
+- Running irreversible operations (deletion, reset, force-overwrite)
+- Setting up project-wide settings (`project.godot`)
+- Installing tools, libraries, or templates
+
+Reading is unconditional. Inspection, scene-tree walks, diagnostics — never need permission.
+
+## Phrasing
+
+Plain, short, action-first. Examples:
+
+> May I create `scenes/player.tscn` and add a CharacterBody3D + Camera3D?
+
+> I'm about to overwrite `levels/level_01.tscn`. The current version has 14 nodes — I'll preserve them and add the new lighting setup. Continue?
+
+> May I attach `scripts/player_controller.gd` to `./World/Player`?
+
+> I'm going to bind `move_forward`, `move_back`, `move_left`, `move_right`, `jump`. OK?
+
+## What this prevents
+
+1. **Silent overwrites.** The agent stomps the user's hand-edited script.
+2. **Cascading scope creep.** A "small fix" turns into a 30-file refactor.
+3. **Unclear state.** The user has no idea what changed when something breaks.
+4. **Trust loss.** One unauthorized edit and the user stops trusting the agent.
+
+## What this is NOT
+
+- Not a confirmation dialog for every property change in a single skill execution. Group related writes into one ask: "I'm about to add the player root, attach the controller script, and bind 5 input actions. OK?"
+- Not a request for design input. The skill should know what to do; the ask is for permission, not direction.
+- Not a stop on simple read-only ops or single-property tweaks the user clearly directed.
+
+## Linter check
+
+The `workflow/skill-test/SKILL.md` static linter looks for the phrases:
+- "May I" / "May I write" / "May I create" / "May I attach"
+- "I'm about to"
+- "Continue?" / "OK?" / "Proceed?"
+
+A skill that mutates files but never says any of these fails the linter.