summer-engine 2.6.3 → 2.6.5

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

@@ -234,6 +234,7 @@ Sources:
 Uses hybrid search: keywords + semantic similarity. Finds assets by name AND by meaning.
 Returns asset names, types, preview URLs, and import-ready file URLs.
 
+Cloud tool — works WITHOUT the Summer Engine app open.
 Requires authentication (so we can attribute usage and apply per-user rate limits): run 'npx summer-engine login' first.`, {
         query: z.string().describe("Natural language search, e.g. 'low-poly tree', 'sci-fi weapon'. For my_assets, can be empty to list recent."),
         assetType: z.enum(["2d_image", "animation", "3d_model", "audio", "music", "all"]).default("all").describe("Filter by asset type"),
@@ -273,7 +274,9 @@ Use this after generation jobs complete, when the user says "the model I made",
 into the local project.
 
 Returns exact asset IDs plus file/import URLs. Use summer_get_asset for full
-metadata or summer_import_asset_by_id to import a specific result.`, {
+metadata or summer_import_asset_by_id to import a specific result.
+
+Cloud tool — works WITHOUT the Summer Engine app open.`, {
         query: z
             .string()
             .default("")
@@ -304,7 +307,9 @@ metadata or summer_import_asset_by_id to import a specific result.`, {
 Use this after a generation job returns assetId/rigAssetId/animationAssetId, or
 after summer_list_my_assets/search results when you need the stable file URL,
 download URL, viewer URL, metadata, license, visibility, parent chain, or
-provider details.`, {
+provider details.
+
+Cloud tool — works WITHOUT the Summer Engine app open.`, {
         assetId: z.string().describe("Summer ArtAssets id"),
     }, async ({ assetId }) => {
         const result = await getAssetApi(assetId);
@@ -320,7 +325,9 @@ provider details.`, {
 
 Today this usually returns the Cloudinary URL plus Summer's download proxy.
 The response shape is future-proofed for signed URLs, so prefer this tool over
-handing users raw fileUrl when they explicitly ask to download.`, {
+handing users raw fileUrl when they explicitly ask to download.
+
+Cloud tool — works WITHOUT the Summer Engine app open.`, {
         assetId: z.string().describe("Summer ArtAssets id"),
         role: z
             .enum(["primary", "thumbnail"])
@@ -339,7 +346,10 @@ Use this when the asset was just generated, selected from my assets, or returned
 by search. Unlike summer_import_asset, this does not search or guess: it fetches
 the asset by ID, downloads it through Summer Engine, and runs Godot's import
 pipeline. For 3D models, pass parent to instantiate it in the open scene after
-import.`, {
+import.
+
+Requires the Summer Engine app to be open with the project loaded (generation
+itself does not — only this import step does).`, {
         assetId: z.string().describe("Summer ArtAssets id"),
         path: z
             .string()

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

@@ -232,6 +232,7 @@ The 'options' object is passed directly to the AI provider for full control.
 Returns the asset with fileUrl (hosted) and localPath (temp file on disk).
 Use the Read tool on localPath to show the image to the user for approval.
 
+Cloud tool — runs on Summer's servers and works WITHOUT the Summer Engine app open.
 Requires authentication: run 'npx summer-engine login' first.`, {
         prompt: z.string().describe("Description of the image to generate"),
         model: z
@@ -290,6 +291,7 @@ The 'options' object is passed directly to ElevenLabs, so you can set any
 provider-specific parameter: stability, similarity_boost, style, speed, etc.
 
 Returns the generated audio URL and asset metadata.
+Cloud tool — runs on Summer's servers and works WITHOUT the Summer Engine app open.
 Requires authentication: run 'npx summer-engine login' first.`, {
         capability: z
             .string()
@@ -378,6 +380,7 @@ Example:
 By default, waits for completion (up to 5 min) and returns the result directly.
 Set wait=false to get the jobId immediately and poll manually with summer_check_job.
 
+Cloud tool — runs on Summer's servers and works WITHOUT the Summer Engine app open.
 Requires authentication: run 'npx summer-engine login' first.`, {
         prompt: z
             .string()
@@ -449,6 +452,7 @@ If imageUrl is provided, switches to image-to-video mode.
 Pass provider-specific params in 'options' (negative_prompt, num_frames, etc.).
 
 Returns the generated video URL and asset metadata.
+Cloud tool — runs on Summer's servers and works WITHOUT the Summer Engine app open.
 Requires authentication: run 'npx summer-engine login' first.`, {
         prompt: z
             .string()
@@ -498,6 +502,7 @@ waits automatically.
 
 Status values: waiting, active, completed, failed, delayed, unknown.
 
+Cloud tool — runs on Summer's servers and works WITHOUT the Summer Engine app open.
 Requires authentication: run 'npx summer-engine login' first.`, {
         jobId: z.string().describe("The job ID returned by an async generation tool"),
     }, async ({ jobId }) => {
@@ -558,6 +563,7 @@ Custom prompt-driven motion is on the roadmap; not yet shipped. For one-off
 signature moves not on the curated list, fall back to hand-authoring in the
 Godot editor or importing from Mixamo.
 
+Cloud tool — runs on Summer's servers and works WITHOUT the Summer Engine app open.
 Requires authentication: run 'npx summer-engine login' first.`, {
         rigAssetId: z
             .string()

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

@@ -128,7 +128,8 @@ mutating the project.`, {
     server.tool("summer_get_agent_playbook", `AI-first operating guide for Summer Engine MCP.
 
 Call this at the start of a fresh chat before touching scenes.
-It returns the safe workflow, anti-patterns, and recovery steps.`, {}, async () => ({
+It returns the safe workflow, the verification ladder, honesty rules,
+anti-patterns, and recovery steps.`, {}, async () => ({
         content: [
             {
                 type: "text",
@@ -137,9 +138,9 @@ It returns the safe workflow, anti-patterns, and recovery steps.`, {}, async ()
                         "Understand the request and outline a brief plan before reaching for tools.",
                         "Default medium is host file tools: write/edit .gd/.cs/.tscn/.tres/.json/docs/config directly as text.",
                         "Use Summer MCP only when you need the LIVE engine: play/stop, diagnostics, screenshots/verification, navmesh or light bake, runtime inspect, or asset import.",
-                        "Call summer_get_project_context first so you do not guess scene paths or the project language.",
+                        "Call summer_get_project_context first so you do not guess scene paths or the project language. It also BINDS this session to the currently-open project (see projectBinding below).",
                         "Use projectMemory from summer_get_project_context to decide which .summer Markdown files to read before creative/audio/dialogue/level/character work.",
-                        "After writing code, PLAY the scene you just made and read summer_get_diagnostics; iterate until it launches clean instead of waiting for the user to navigate to it.",
+                        "After writing code, VERIFY through the engine (see verificationLadder) instead of waiting for the user to navigate to it.",
                     ],
                     safeDefaults: [
                         "Never guess scene filenames (main.tscn/Main.tscn) -- get them from summer_get_project_context.",
@@ -153,7 +154,54 @@ It returns the safe workflow, anti-patterns, and recovery steps.`, {}, async ()
                         "1. Understand what the user wants (one pass, no tool spelunking first).",
                         "2. Outline the plan fast and briefly; proceed once it is clearly right.",
                         "3. Execute in pure code -- edit .gd/.tscn/.tres as text (GDScript by default, C# only if the project already uses it).",
-                        "4. Play the scene/game (start with the scene you just made), read console + script/debugger errors via summer_get_diagnostics, fix, and repeat until it launches clean.",
+                        "4. Verify through the engine using the verificationLadder below, fix, and repeat until it launches clean.",
+                    ],
+                    // The MCP-native verification ladder. Climb only as high as the
+                    // change demands: a script edit needs rung 1; a gameplay change
+                    // needs rungs 3-4. Each rung is a REAL engine call, not a claim.
+                    verificationLadder: {
+                        "1_compiles": [
+                            "After writing/editing a .gd file, call summer_get_script_errors <path> — compiles without running the game.",
+                            "For a project-wide sweep of editor + runtime issues, call summer_get_diagnostics (it tells you whether to then read summer_get_console / summer_get_debugger_errors).",
+                        ],
+                        "2_looks_right": [
+                            "To SEE the result, call summer_screenshot. Pick the target deliberately:",
+                            "  target:'viewport' (default) = the editor's CURRENT open tab, exactly as it looks now. Edit-time check. No game boot.",
+                            "  target:'scene' = an OFFSCREEN render of a scene FILE (pass scenePath). No game boot; physics/particles/animations are STATIC at t=0. Best for 'is the composition/scale right' without disturbing the open tab. It also confesses if the scene has no Camera3D (renders grey/black when played) or no light (lit materials look black) — READ those warnings.",
+                            "  target:'game' = a frame from the RUNNING game (real runtime state). summer_play FIRST. Over a plain local HTTP connection this returns an honest failure (needs the Summer desktop bridge); when it fails, fall back to viewport/scene or ask the user.",
+                        ],
+                        "3_runs": [
+                            "Compose the run-and-check yourself — there is no single 'verify' tool:",
+                            "summer_clear_console  -> clean slate",
+                            "summer_play [scene]   -> boot the game (or a specific scene)",
+                            "summer_get_debugger_errors  -> runtime errors (null refs, missing nodes, physics)",
+                            "summer_screenshot target:'game'  -> optional visual of the live frame",
+                            "summer_stop  -> ALWAYS stop; scene mutations are refused while the game runs",
+                        ],
+                        "4_interactive": [
+                            "To prove input-driven behavior (does jump/move/shoot actually work), you have two routes when the engine build supports them (both go through summer_batch as raw ops — see rawOpsViaBatch):",
+                            "SimulateInput: inject a single action/key/mouse/axis into the RUNNING game, then re-check screenshot/debugger. Requires summer_play first.",
+                            "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. Best for a scripted 'does X happen when I do Y' assertion.",
+                            "If neither op is available on this engine build (failure_reason:'unsupported' or an unknown-op error comes back), do NOT fake it — ask the user to try the interaction and report what they see.",
+                        ],
+                    },
+                    // HONESTY — mirror the in-product agent's vision rules. A capture is
+                    // a fact, not a formality; a failed capture is itself a result.
+                    honestyRules: [
+                        "NEVER describe an image you did not actually receive. If summer_screenshot returned isError or a text-only fallback (no image block), say the capture failed and why — do not invent what the frame 'probably' shows.",
+                        "A failed or blocked capture is a RESULT, not a dead end: report it, then climb down the ladder (scene->viewport) or ask the user for a screenshot.",
+                        "Describe only what is actually in the returned frame. Do not pad with expected content.",
+                        "target:'scene' is STATIC (t=0) and may use a synthetic camera — do not claim animation/particles/gameplay motion from it, and heed its no-camera / no-light / synthetic-camera warnings.",
+                        "Pass structured engine failures (failure_reason, terminalState, errorClass) through to the user verbatim — never soften 'unsupported' or 'bridge_required' into a vague 'it didn't work'.",
+                    ],
+                    // The session is pinned to the project open when you first called
+                    // summer_get_project_context. This keeps a mutation from landing in
+                    // the WRONG project after an in-place project switch.
+                    projectBinding: [
+                        "summer_get_project_context binds this session to the currently-open project and is the deliberate (re)bind point.",
+                        "If the engine later switches projects in place, mutating ops are REJECTED with identity_mismatch (nothing is applied — your edit did NOT land in the wrong project).",
+                        "summer_screenshot adds a projectMismatch WARNING when the engine's live project no longer matches this binding — the frame may be from the wrong project; do not trust it until you rebind.",
+                        "To intentionally follow the switch, call summer_get_project_context again to rebind, then retry.",
                     ],
                     liveEngineFlow: [
                         "Use this flow ONLY when you genuinely need live engine state (navmesh/light bake, instancing into an already-open scene, runtime inspect):",
@@ -164,11 +212,24 @@ It returns the safe workflow, anti-patterns, and recovery steps.`, {}, async ()
                         "summer_save_scene",
                         "summer_get_diagnostics",
                     ],
+                    // summer_batch forwards each {op, ...} verbatim to the engine, so
+                    // 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.",
+                        "SimulateInput (drive the RUNNING game): summer_batch ops:[{op:'SimulateInput', type:'action', action:'jump', pressed:true}]. type is 'action' | 'key' | 'mouse_click' | 'axis'. summer_play first. Structured failure_reasons (incl 'unsupported' on older builds) come back verbatim — surface them.",
+                        "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}.",
+                        "These are runtime ops, not scene mutations — the batch undo group is a harmless no-op for them.",
+                    ],
                     recovery: [
                         "If you see 'no scene open': run summer_open_main_scene.",
                         "If open_scene fails: re-check mainScene from summer_get_project_context.",
-                        "If save fails: verify scene is open and game is not running.",
+                        "If save fails: verify scene is open and game is not running (summer_is_running / summer_stop).",
+                        "If a mutation is rejected with identity_mismatch: the engine switched projects — call summer_get_project_context to rebind (only if you meant to follow it), then retry.",
                         "If a .tscn you wrote keeps reverting: the editor has that scene open -- reload or close the tab, then write again.",
+                        "If a run op or SimulateInput returns 'unsupported' / an unknown-op error: this engine build predates it — fall back to summer_play + summer_get_debugger_errors, or ask the user to interact.",
+                    ],
+                    debugging: [
+                        "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.",
                     ],
                 }, null, 2),
             },
@@ -194,6 +255,11 @@ Use this first in every fresh chat to avoid guessing scene filenames or editing
         const projectName = getProjectName(projectState, health);
         const mainScene = getMainScene(projectState);
         const currentScene = getCurrentScene(projectState, 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
+        // new project; subsequent edits then target it instead of being rejected.
+        const boundProjectIdHash = await client.rebind();
         return {
             health,
             project: projectState,
@@ -202,6 +268,7 @@ Use this first in every fresh chat to avoid guessing scene filenames or editing
             projectPath,
             currentScene,
             mainScene,
+            boundProjectIdHash,
             projectMemory: getProjectMemorySummary(projectPath),
             guidance: mainScene
                 ? "Use `summer_open_scene` with `mainScene` if no scene is open."

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

@@ -201,7 +201,7 @@ Example: inspect a light to see its energy, color, shadow settings before changi
 Use when you need the sub-properties of a resource attached to a node. For example, summer_inspect_node tells you a MeshInstance3D has a "StandardMaterial3D" material — this tool tells you that material's albedo_color, metallic, roughness, etc.`, {
         path: z.string().describe("Resource path, e.g. 'res://materials/ground.tres' or 'res://models/player.glb'"),
     }, async ({ path }) => withEngine(async (client) => client.inspectResource(path)));
-    server.tool("summer_batch", `Execute multiple operations in a single call, grouped into one undo step.
+    server.tool("summer_batch", `Execute multiple operations in a single call, grouped into one undo step. Each op is forwarded to the engine VERBATIM, so this is also how you reach engine ops that have no dedicated tool.
 
 The user can undo everything with a single Ctrl+Z. Use this when building something that involves multiple nodes and properties — e.g., creating a player character with collision, camera, and properties.
 
@@ -209,7 +209,11 @@ Each op in the array uses the same format as the individual tools:
 - {"op": "AddNode", "parent": "/", "type": "MeshInstance3D", "name": "Floor"}
 - {"op": "SetProp", "path": "Floor", "key": "position", "value": "Vector3(0, -1, 0)"}
 - {"op": "SetProp", "path": "Floor", "key": "mesh", "value": "PlaneMesh"}
-- {"op": "SetResourceProperty", "nodePath": "Floor", "resourceProperty": "mesh", "subProperty": "size", "value": "Vector2(20, 20)"}`, {
+- {"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().`, {
         ops: z.array(z.record(z.unknown())).describe("Array of operation objects, each with 'op' plus its parameters"),
     }, async ({ ops }) => withEngine(async (client) => client.executeOps(ops, { groupUndo: true })));
 }

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

@@ -13,16 +13,68 @@ export function registerVisualTools(server) {
 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.
 
 target:
-  "viewport" (default) — the editor's current 3D/2D scene view. Works without running the game. Use for edit-time checks of how the scene looks.
-  "game" — a frame from the running game. The game must be started first (summer_play). Use to verify runtime behavior.
+  "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.
+  "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. On macOS the game often runs in a floating window that cannot be captured; if a game capture fails, prefer "viewport", or ask the user to share a screenshot.`, {
+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.`, {
         target: z
-            .enum(["viewport", "game"])
+            .enum(["viewport", "scene", "game"])
             .optional()
             .default("viewport")
-            .describe('"viewport" = editor scene view (default), "game" = running game frame'),
-    }, async ({ target }) => withEngine(async (client) => target === "game" ? client.gameSnapshot() : client.viewportSnapshot(), {
+            .describe('"viewport" = editor current view (default), "scene" = offscreen render of a scene file, "game" = running game frame'),
+        scenePath: z
+            .string()
+            .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"])
+            .optional()
+            .describe('target:"scene" only. Camera framing preset. Default: auto.'),
+        size: z
+            .array(z.number().int().positive())
+            .length(2)
+            .optional()
+            .describe('target:"scene" only. Output image [width, height] in pixels.'),
+        nodePath: z
+            .string()
+            .optional()
+            .describe('target:"scene" only. Scene-tree node path to frame on.'),
+    }, async ({ target, scenePath, framing, size, nodePath }) => withEngine(async (client) => {
+        if (target === "game")
+            return client.gameSnapshot();
+        if (target === "scene")
+            return client.scenePreview({
+                scenePath,
+                framing,
+                size: size,
+                nodePath,
+            });
+        return client.viewportSnapshot();
+    }, {
+        // Game capture is structurally blocked over local HTTP today (409
+        // bridge_required). Treat that as a clean, honest failure rather than a
+        // truncated generic error — fail loud (isError) so the model does not
+        // proceed as if it saw the game. Written so that when the engine starts
+        // answering over HTTP (P4.4) `failureReason` never fires and the normal
+        // image path below just works.
+        onResult: (snap) => {
+            if (target === "game" && snap.failureReason === "bridge_required") {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: "Game capture is not available over this connection (requires the Summer desktop app bridge). " +
+                                "Use target:'viewport' for the editor view, target:'scene' for an offscreen scene render, " +
+                                "or ask the user to describe / screenshot the running game.\n\n" +
+                                `Engine reason: ${snap.error ?? "unsupported_transport"}`,
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+            return null;
+        },
         toContent: (snap) => {
             // withEngine only calls toContent on success (ok:true, error cleared
             // by extractOpError). Missing image bytes on a "success" is still
@@ -38,13 +90,36 @@ Static frame only — one moment, not motion. On macOS the game often runs in a
                 ];
             }
             const dims = snap.width && snap.height ? `${snap.width}x${snap.height}` : "unknown size";
-            const label = target === "game" ? "Running game frame" : "Editor viewport";
+            const label = target === "game"
+                ? "Running game frame"
+                : target === "scene"
+                    ? "Scene preview (offscreen render, physics/animations static)"
+                    : "Editor viewport";
+            const warnings = [];
+            // Project-drift warning (item 4): the engine may have switched
+            // projects since this session bound — this frame could be from the
+            // WRONG project.
+            if (snap.projectMismatch) {
+                warnings.push("WARNING: the engine is now on a DIFFERENT project than this session is bound to — this frame may be from the wrong project. Call summer_get_project_context to rebind before trusting it.");
+            }
+            // Scene-preview confession fields (P4.3): a scene with no camera plays
+            // grey/black.
+            if (target === "scene") {
+                if (snap.sceneHasCamera === false) {
+                    warnings.push("WARNING: this scene has no Camera3D — it will render grey/black when played.");
+                }
+                if (snap.sceneHadLight === false) {
+                    warnings.push("WARNING: this scene has no light — lit materials may appear black when played.");
+                }
+                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.");
+                }
+            }
+            const caption = `${label} (${dims}). 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" },
-                {
-                    type: "text",
-                    text: `${label} (${dims}). Saved to ${snap.localPath ?? "n/a"}. Review the image above and describe what you actually see.`,
-                },
+                { type: "text", text: caption },
             ];
         },
     }));

package/dist/mcp/tools/with-engine.d.ts

@@ -11,12 +11,29 @@ type ToolResult = {
     content: ToolResultContent[];
     isError?: boolean;
 };
+/** Diagnostics stamped by withEngine onto its ToolResult under a non-enumerable
+ *  key so the server.ts result logger can emit a single structured stderr line
+ *  per tool call WITHOUT every one of the ~31 callers having to thread its own
+ *  tool name through. Never serialized to the model (non-enumerable). */
+export interface WithEngineMeta {
+    terminalState?: string;
+    errorClass?: string;
+    failureReason?: string;
+    retried: boolean;
+    boundProjectIdHash?: string;
+}
+export declare const WITH_ENGINE_META: unique symbol;
 /** Options for {@link withEngine}. `toContent` maps a successful engine result
  *  to MCP content blocks — used by the screenshot tool to hand the raw frame
  *  back as an image block instead of JSON-stringified text. Only runs on genuine
- *  success (after extractOpError clears); failures still surface as text. */
+ *  success (after extractOpError clears); failures still surface as text.
+ *
+ *  `onResult` runs FIRST on a genuine success and may short-circuit to a custom
+ *  ToolResult (e.g. a fail-loud message for a structurally-blocked capture).
+ *  Return null to fall through to toContent / the default JSON text. */
 export interface WithEngineOptions<T> {
     toContent?: (result: T) => ToolResultContent[];
+    onResult?: (result: T) => ToolResult | null;
 }
 /**
  * Decide whether an engine result envelope represents a FAILURE, and if so
@@ -33,14 +50,22 @@ export interface WithEngineOptions<T> {
  */
 export declare function extractOpError(result: unknown): string | null;
 /**
- * A thrown transport error is safe to retry only when the engine provably never
- * applied the op: a stale-token rejection (401/403, after the engine rotated its
- * api-token on relaunch) or an unreachable/closed port (connection refused/reset,
- * after the engine moved ports or is mid-restart). A timeout or any 5xx may have
- * mutated, so those surface instead of risking a double-apply on retry.
+ * An auth failure is the ONE class of thrown error that is provably pre-apply:
+ * the engine rejects on the Bearer-token check (tool_net_thread.cpp::_validate_auth)
+ * BEFORE the op is queued or applied, so reconnecting with the fresh api-token and
+ * retrying cannot double-apply a mutation. This is exactly the stale-token case
+ * after the engine rotates its api-token on relaunch.
+ *
+ * Deliberately NARROW. A generic connection error (ECONNREFUSED / "fetch failed")
+ * thrown from inside the tool closure is NOT retriable here, because it may be a
+ * disconnect mid-operation where a mutation already partially applied — and the
+ * MCP sends no idempotency key the engine can dedup on, so a blind retry would
+ * re-apply it. The restart-between-calls case is handled proactively by
+ * getClient()'s credential-drift check; the connect/preflight-failure case is
+ * retried separately in withEngine (nothing is submitted there).
  *
  * Exported for unit tests.
  */
-export declare function isReconnectableThrow(err: unknown): boolean;
+export declare function isAuthError(err: unknown): boolean;
 export declare function withEngine<T>(fn: (client: Awaited<ReturnType<typeof getClient>>) => Promise<T>, opts?: WithEngineOptions<T>): Promise<ToolResult>;
 export {};

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

@@ -1,5 +1,14 @@
 import { getClient, resetClient } from "../server.js";
 import { recordMcpSession } from "../../lib/telemetry.js";
+export const WITH_ENGINE_META = Symbol("summerWithEngineMeta");
+function attachMeta(result, meta) {
+    Object.defineProperty(result, WITH_ENGINE_META, {
+        value: meta,
+        enumerable: false,
+        configurable: true,
+    });
+    return result;
+}
 // 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
@@ -17,6 +26,23 @@ const TERMINAL_STATE_MESSAGES = {
     denied: "Operation denied (terminalState: denied). Nothing was applied.",
     canceled: "Operation canceled (terminalState: canceled). Nothing was applied.",
 };
+/** Pull the failure classifiers off an engine envelope for logging (best-effort,
+ *  shape-tolerant). Does not decide success/failure — that stays in
+ *  extractOpError. */
+function readClassifiers(result) {
+    if (!result || typeof result !== "object")
+        return {};
+    const op = result;
+    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,
+    };
+}
 /**
  * Decide whether an engine result envelope represents a FAILURE, and if so
  * return a model-visible message. Returns null only for genuine success.
@@ -56,45 +82,35 @@ export function extractOpError(result) {
     }
     return null;
 }
-// Terminal states where the engine GUARANTEES the op never landed, so dropping
-// the cached client and retrying once is safe (no double-mutation). Everything
-// else — timed_out (may still be running), content_mismatch / denied / canceled
-// (intentional) — must surface, never silently retry.
-const RECONNECTABLE_TERMINAL_STATES = new Set([
-    "not_connected",
-    "identity_mismatch",
-]);
-function terminalStateOf(result) {
-    if (!result || typeof result !== "object")
-        return null;
-    const ts = result.terminalState;
-    return typeof ts === "string" && ts.length > 0 ? ts : null;
-}
 /**
- * A thrown transport error is safe to retry only when the engine provably never
- * applied the op: a stale-token rejection (401/403, after the engine rotated its
- * api-token on relaunch) or an unreachable/closed port (connection refused/reset,
- * after the engine moved ports or is mid-restart). A timeout or any 5xx may have
- * mutated, so those surface instead of risking a double-apply on retry.
+ * An auth failure is the ONE class of thrown error that is provably pre-apply:
+ * the engine rejects on the Bearer-token check (tool_net_thread.cpp::_validate_auth)
+ * BEFORE the op is queued or applied, so reconnecting with the fresh api-token and
+ * retrying cannot double-apply a mutation. This is exactly the stale-token case
+ * after the engine rotates its api-token on relaunch.
+ *
+ * Deliberately NARROW. A generic connection error (ECONNREFUSED / "fetch failed")
+ * thrown from inside the tool closure is NOT retriable here, because it may be a
+ * disconnect mid-operation where a mutation already partially applied — and the
+ * MCP sends no idempotency key the engine can dedup on, so a blind retry would
+ * re-apply it. The restart-between-calls case is handled proactively by
+ * getClient()'s credential-drift check; the connect/preflight-failure case is
+ * retried separately in withEngine (nothing is submitted there).
  *
  * Exported for unit tests.
  */
-export function isReconnectableThrow(err) {
+export function isAuthError(err) {
     const m = (err instanceof Error ? err.message : String(err)).toLowerCase();
-    if (m.includes("timed out") || m.includes("timeout") || m.includes("aborted")) {
-        return false;
-    }
-    return (m.includes("401") ||
-        m.includes("403") ||
-        m.includes("unauthorized") ||
-        m.includes("econnrefused") ||
-        m.includes("econnreset") ||
-        m.includes("fetch failed") ||
-        m.includes("not running") ||
-        m.includes("not responding"));
+    return m.includes("401") || m.includes("403") || m.includes("unauthorized");
 }
 function buildActionHint(message) {
     const normalized = message.toLowerCase();
+    if (normalized.includes("identity_mismatch") ||
+        normalized.includes("projectidhash mismatch") ||
+        normalized.includes("projectid mismatch") ||
+        normalized.includes("wrong project/instance")) {
+        return "Summer Engine is now on a DIFFERENT project than this session is bound to — nothing was applied (your edit did NOT land in the wrong project). If you meant to work on the now-open project, call `summer_get_project_context` to rebind to it, then retry. If not, switch the engine back to the original project first.";
+    }
     if (normalized.includes("no scene open") || normalized.includes("no edited scene")) {
         return "No scene is currently open. Call `summer_get_project_context` first, then `summer_open_main_scene` (or `summer_open_scene` with a known .tscn path).";
     }
@@ -110,48 +126,69 @@ export async function withEngine(fn, opts) {
     // Best-effort, fire-and-forget: count this MCP session as DAU for attribution.
     // No await, no throw, no quota gating.
     recordMcpSession();
-    // The engine rotates its api-token and can move ports on every launch, so a
-    // restart that lands DURING a tool call shows up as a stale-token 401, an
-    // ECONNREFUSED on the old port, or a soft not_connected / identity_mismatch
-    // terminal state. Drop the cached client and retry ONCE so a transient drop
-    // heals itself (getClient reconnects with the fresh creds) instead of
-    // surfacing as a "disconnected" error. Only provably-not-applied failures are
-    // retried — see RECONNECTABLE_TERMINAL_STATES / isReconnectableThrow.
+    // The engine rotates its api-token (and can move ports) on every launch. The
+    // proactive credential-drift check in getClient() reconnects when a restart
+    // happened BETWEEN calls; this loop only covers the race where the restart
+    // lands DURING a call. We retry ONLY where nothing could have been applied:
+    //   - a connect/preflight failure (getClient threw — request never submitted)
+    //   - a stale-token 401/403 (engine rejects at auth, before queue/apply)
+    // A generic connection error thrown from inside fn() is NOT retried: it may be
+    // a disconnect mid-operation where a mutation already partially applied, and
+    // the MCP sends no idempotency key the engine can dedup on. A soft failure
+    // terminal state (e.g. identity_mismatch from a project switch) is surfaced,
+    // never silently retried — a retry cannot fix a project switch.
     const MAX_ATTEMPTS = 2;
     let lastError;
+    let retried = false;
+    let boundProjectIdHash;
     for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) {
+        if (attempt > 1)
+            retried = true;
+        let client;
+        try {
+            client = await getClient();
+        }
+        catch (err) {
+            // Pre-submission: the request never went out, so reconnect and retry.
+            resetClient();
+            lastError = err;
+            if (attempt < MAX_ATTEMPTS)
+                continue;
+            break;
+        }
+        boundProjectIdHash =
+            typeof client.getBoundProjectIdHash === "function"
+                ? client.getBoundProjectIdHash()
+                : undefined;
         try {
-            const client = await getClient();
             const result = await fn(client);
             const opError = extractOpError(result);
             if (opError) {
-                const ts = terminalStateOf(result);
-                if (ts && RECONNECTABLE_TERMINAL_STATES.has(ts) && attempt < MAX_ATTEMPTS) {
-                    resetClient();
-                    lastError = new Error(opError);
-                    continue;
-                }
                 const hint = buildActionHint(opError);
                 const message = hint ? `${opError}\n\nHint: ${hint}` : opError;
-                return { content: [{ type: "text", text: message }], isError: true };
+                return attachMeta({ content: [{ type: "text", text: message }], isError: true }, { ...readClassifiers(result), retried, boundProjectIdHash });
+            }
+            const meta = { ...readClassifiers(result), retried, boundProjectIdHash };
+            if (opts?.onResult) {
+                const short = opts.onResult(result);
+                if (short)
+                    return attachMeta(short, meta);
             }
             if (opts?.toContent) {
-                return { content: opts.toContent(result) };
+                return attachMeta({ content: opts.toContent(result) }, meta);
             }
-            return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+            return attachMeta({ content: [{ type: "text", text: JSON.stringify(result, null, 2) }] }, meta);
         }
         catch (err) {
-            // A thrown error means the cached client may be pointed at a dead/rotated
-            // engine — always drop it (prior behavior). Retry once only for
-            // connection-class throws that provably did not mutate.
+            // Drop the cached client (it may point at a dead/rotated engine). Retry
+            // once only for a provably pre-apply auth failure; anything else surfaces.
             resetClient();
             lastError = err;
-            if (attempt < MAX_ATTEMPTS && isReconnectableThrow(err)) {
+            if (attempt < MAX_ATTEMPTS && isAuthError(err))
                 continue;
-            }
             break;
         }
     }
     const msg = lastError instanceof Error ? lastError.message : String(lastError);
-    return { content: [{ type: "text", text: msg }], isError: true };
+    return attachMeta({ content: [{ type: "text", text: msg }], isError: true }, { errorClass: "transport", retried, boundProjectIdHash });
 }