summer-engine 3.8.0 → 4.2.0

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

@@ -192,17 +192,17 @@ Use this when summer_get_diagnostics shows a non-zero \`debugger.warnings\` coun
         const { result } = shapeEngineLogResponse(engineResult, { maxEntries: max_warnings });
         return result;
     }));
-    server.tool("summer_play", `Start running the game in the engine. With no extra parameters the game runs inside Summer Engine's viewport (the 'main' instance) QUIETLY — see below.
+    server.tool("summer_play", `Start the game. With no parameters it runs QUIETLY inside Summer Engine's viewport (the 'main' instance); scene runs one level or UI screen instead of the main scene.
 
-QUIET BY DEFAULT (focus:false, PlayGame agent:true): the user is usually working on the same machine while you build, so a play must not take over their screen. Quiet play makes the EDITOR stay put: it does not switch the main screen to the Game tab, does not grab keyboard focus for the embedded game, ignores the game's later focus report, and skips the render-health self-check that would otherwise misread the untouched Game view as a GPU failure and flip the user's embed setting. Quiet play does NOT hide the game: it still runs embedded in the Game view (visible if the user already has that tab open), it is the running game for summer_is_running / summer_screenshot target:'game' / summer_get_diagnostics, and on engines without the background launch posture it does not change a user who has "Embed Game on Play" turned off — their game opens in its own OS window as always. Engines with the background posture (--summer-background, 0.5.66+) also launch the play child with that flag, so a separate-window game appears without activating or taking focus either. The result echoes agent_quiet:true when honoured; a launch result WITHOUT agent_quiet means the engine predates quiet play and most likely took focus — the tool adds posture_note saying so. focus:true launches like the toolbar Play button (Game tab + focus): use it ONLY when the user is watching and asked to see the game come up.
+QUIET BY DEFAULT (focus:false, PlayGame agent:true): the user usually works on the same machine, so the EDITOR stays put. It does not switch to the Game tab or take keyboard focus (nor follow the game's later focus report), and skips the render-health self-check that would misread the untouched Game view as a GPU failure and flip the user's embed setting. Quiet play does NOT hide the game: it runs embedded in the Game view (visible if that tab is open) and is the running game for summer_is_running / summer_screenshot target:'game' / summer_get_diagnostics. With "Embed Game on Play" off the game gets its own OS window; engines with --summer-background (0.5.66+) open it without taking focus. The result echoes agent_quiet:true when honoured; without agent_quiet the engine predates quiet play and most likely took focus (posture_note says so). focus:true launches like the toolbar Play button (Game tab + focus): ONLY when the user is watching and asked to see the game come up.
 
-After starting, confirm boot with summer_is_running (boot time varies — never sleep a guessed delay), then summer_get_diagnostics for runtime errors. You can run a specific scene instead of the main scene — useful for testing individual levels or UI screens.
+After starting, confirm boot with summer_is_running (boot time varies; never sleep a guessed delay), then summer_get_diagnostics for runtime errors.
 
-DETERMINISTIC RUNS (newer engines): seed / fixed_fps / time_scale pin THIS launch only (nothing is persisted). seed pins the game's GLOBAL RNG (randi/randf/randi_range/randf_range/randfn, Array.shuffle/pick_random) — it does NOT pin RandomNumberGenerator instances, scripts that call randomize(), rand_from_seed, wall-clock reads, or thread/IO/audio timing. fixed_fps decouples scene time from the wall clock so frame-count-derived state lands on the same frame run to run. The result's \`determinism\` block says whether the pins were applied (applied:false carries a reason: already_running, editor_run_args_override, launch_not_started) and restates seed_scope. If the result has NO determinism block although you sent a pin, the engine predates the params and the run is NOT reproducible — the tool says so; do not claim otherwise. Omitting every pin and instance parameter is exactly the v1 launch.
+DETERMINISTIC RUNS (newer engines): seed / fixed_fps / time_scale pin THIS launch only, nothing persisted. seed pins the GLOBAL RNG only (not RandomNumberGenerator instances, randomize(), rand_from_seed, wall-clock, thread/IO/audio timing). The result's \`determinism\` block says whether the pins applied (applied:false carries a reason: already_running, editor_run_args_override, launch_not_started) and restates seed_scope. NO determinism block although you sent a pin = the engine predates the params and the run is NOT reproducible (the tool says so); never claim otherwise.
 
-PLAYTEST LAUNCH (engine runtime-control build): instance + mode:'offscreen' spawn a disposable hidden instance (at most 3) that summer_game_probe / summer_game_input / summer_game_control / summer_runtime_* address by name — run two variants side by side for an A/B. deterministic:true (offscreen only) launches with --fixed-fps 60 --summer-seed --audio-driver Dummy and is what lets summer_game_input action:'replay' accept a seed; speed sets the user time scale on session start. The instance result reports session_attached; poll summer_game_control action:'instances' until attached:true before addressing it. Then: probe -> act -> step/probe -> assert (the agent-playtesting skill). Failure reasons: too_many_instances, instance_exists, session_timeout (child never attached — check summer_get_console), unsupported_mode, main_scene_not_configured. A game already running answers playing:true with determinism.applied:false — summer_stop first to apply seed/fixed_fps.
+PLAYTEST LAUNCH (engine runtime-control build): instance + mode:'offscreen' spawn a disposable hidden instance (at most 3) that summer_game_probe / summer_game_input / summer_game_control / summer_runtime_* address by name; two side by side make an A/B. deterministic:true (offscreen only) is what lets summer_game_input action:'replay' accept a seed. Poll summer_game_control action:'instances' until attached:true (the result reports session_attached) before addressing it. Then probe -> act -> step/probe -> assert (the agent-playtesting skill). Failure reasons: too_many_instances, instance_exists, session_timeout (child never attached; check summer_get_console), unsupported_mode, main_scene_not_configured. A game already running answers playing:true with determinism.applied:false: summer_stop first to apply seed/fixed_fps.
 
-MULTIPLAYER — LOCAL PLAY (Summer multiplayer games; engine with Local Play): players:N starts the game's authority headless plus N clients on this machine, each joining through the game's OWN Summer.client.join(SummerJoinTarget.queue(...)) — no account, login, Docker, CLI or local-only game code. The scenes and queue come from the project's summer.build.json and its WorldDefinition (client_entry_point + the headless_engine component entry_point); queue picks another declared queue — pass queue WITHOUT players to start that queue's minPlayers (a 4-player queue starts 4), or players to choose; spectators adds spectator clients. local_play.warnings flags a roster outside the queue's minPlayers..maxPlayers. The result's local_play block lists every process (label, role, persona) and the port; failure_reason local_play_unavailable says exactly what to declare. Every process attaches to the editor debugger: screenshots, input and summer_game_* go to the FIRST client, the authority's output is in summer_get_console, and summer_stop stops them all. A join for a different queue fails with a message naming both queues. It is not a proof of sign-in, matchmaking or hosted admission (staging). No local_play block although you sent players means the engine predates Local Play and ran ONE client — the tool says so.`, {
+MULTIPLAYER — LOCAL PLAY (engine with Local Play; the multiplayer-testing skill): players:N starts the game's authority headless plus N clients on this machine, each joining through the game's OWN Summer.client.join(SummerJoinTarget.queue(...)): no account, login, Docker, CLI or local-only game code. Scenes and queue come from summer.build.json's WorldDefinition (client_entry_point, the headless_engine component entry_point). queue picks another declared queue; queue WITHOUT players starts its minPlayers; spectators adds spectator clients. local_play.warnings flags a roster outside minPlayers..maxPlayers. The local_play block lists every process (label, role, persona) and the port; failure_reason local_play_unavailable says what to declare. Every process attaches to the editor debugger: screenshots, input and summer_game_* go to the FIRST client, the authority's output is in summer_get_console, summer_stop stops them all. A join for a different queue fails naming both queues. Not a proof of sign-in, matchmaking or hosted admission (staging). No local_play block although you sent players = the engine predates Local Play and ran ONE client; the tool says so.`, {
         scene: z.string().optional().describe("Scene to run instead of main scene, e.g. 'res://levels/test_level.tscn'"),
         ...playGameExtensionSchema,
     }, async (args) => {

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

@@ -7,17 +7,17 @@ WHEN — the three asset classes neither generation nor the free library serve w
 - modular kits with exact dimensions and snapping (walls, pipes, fences, rails: array + boolean + bevel, one shared material) — generation cannot hold size and style across 30 pieces;
 - VFX meshes (shatter pieces, curve sweeps, trails, LOD chains) — one-liners in bpy, absent in the engine;
 - post-processing a generated model (decimate -> UV unwrap -> bake) before it goes into the scene.
-WHEN NOT: a generic prop (barrel, crate, chair) -> summer_search_assets / summer_import_asset first, then summer_generate_3d; a character or any organic shape -> summer_generate_3d (scripted organic modelling is the documented failure mode); a blockout or placeholder -> summer_run_script primitives/CSG, instant and in-scene. Route with the asset-strategy skill; the fabricating-assets skill carries the bpy rules and recipes.
+WHEN NOT: a generic prop (barrel, crate, chair) -> summer_search_assets / summer_import_asset first, then summer_generate_3d; a character or any organic shape -> summer_generate_3d (scripted organic modelling is the documented failure mode); a blockout or placeholder -> summer_run_script primitives/CSG, instant and in-scene. Route with the asset-strategy skill; the fabricating-assets skill carries the bpy rules, recipes and the fix for each failure_reason.
 
-SCRIPT CONTRACT: 'source' is plain bpy code. Pre-bound names: bpy, bmesh, mathutils, math, Vector, Matrix, Euler. The script must CREATE mesh objects and leave them linked in the scene — do NOT export and do NOT quit (the engine's bootstrap exports for you: modifiers applied at export, Geometry Nodes realized, +Y-up conversion, materials carried as Principled BSDF only, a procedural Base Color baked to a 2K texture; procedural Metallic/Roughness/Normal/Emission are NOT baked and come back in 'warnings'). Objects hidden or render-disabled are treated as helpers (boolean cutters, guides) and are not exported — they are listed in 'skipped'. Model in metres. MESH/CURVE/SURFACE/META/FONT export as meshes, EMPTY/ARMATURE keep hierarchy, cameras and lights are dropped. Name your objects — they become node names.
+SCRIPT CONTRACT: 'source' is plain bpy that must CREATE mesh objects and leave them linked in the scene — do NOT export and do NOT quit. The engine's bootstrap exports for you: modifiers applied, Geometry Nodes realized, +Y-up conversion, materials as Principled BSDF only, a procedural Base Color baked to a 2K texture; procedural Metallic/Roughness/Normal/Emission are NOT baked (see 'warnings'). Hidden or render-disabled objects are helpers (boolean cutters, guides), not exported, listed in 'skipped'. Model in metres. MESH/CURVE/SURFACE/META/FONT export as meshes, EMPTY/ARMATURE keep hierarchy, cameras and lights are dropped. Name your objects — they become node names.
 
-REQUIRES BLENDER on the user's machine (4.2 LTS or newer). Resolution order: 'blender_path' -> SUMMER_BLENDER_BIN in the editor's environment -> Editor Settings filesystem/import/blender/blender_path (shared with .blend import) -> PATH, well-known install dirs, ~/.summer/tools/blender-*. Not found -> failure_reason blender_not_found with the exact fix and every path that was checked; relay it to the user as a one-line decision, never guess a path and never install anything on their behalf.
+REQUIRES BLENDER 4.2 LTS or newer. Resolution: 'blender_path' -> SUMMER_BLENDER_BIN in the editor's environment -> Editor Settings filesystem/import/blender/blender_path -> PATH, well-known install dirs, ~/.summer/tools/blender-*. Not found -> failure_reason blender_not_found with the exact fix and every path checked; relay it to the user as a one-line decision; never guess a path or install anything for them.
 
-ONE fabrication runs at a time per editor (failure_reason busy — wait for the result, never fire two in parallel). Budget max_seconds 15-600 (default 120) covers Blender boot + script + bakes + export; the client waits max_seconds + 60 s. Blind until import: there is no viewport feedback while the script runs, so keep scripts deterministic (fixed seeds) and verify afterwards.
+ONE fabrication runs at a time per editor (failure_reason busy: wait for the result, never fire two in parallel). There is no viewport feedback while the script runs, so keep scripts deterministic (fixed seeds) and verify afterwards.
 
-Returns {ok, ran, blender_version, blender_path, out_path, objects[{name,type,vertices,faces,triangles,materials,modifiers}], object_count, dimensions{x,y,z} (+Y up, source scale), warnings[], baked[], skipped[], output[], errors[], exit_code, duration_ms, checkpoint} plus imported_node_path / scale_applied / instance_dimensions with import_to_scene, and no_rewind_point:true when no checkpoint exists. Failures carry failure_reason: blender_not_found | blender_launch_failed | script_error (traceback_tail + script_line — fix the bpy against the reported blender_version and re-run; bpy APIs change across majors) | timeout (raise max_seconds or split the job) | export_empty (no exportable object — check hide/render flags and collection links) | export_failed | export_missing | import_failed / instantiate_failed (the .glb IS at out_path — summer_instantiate_scene it yourself; the importer's message is in summer_get_console) | busy | cancelled.
+Returns blender_version, blender_path, out_path, objects[{name, type, vertices, faces, triangles, materials, modifiers}], object_count, dimensions{x,y,z} (+Y up, source scale), warnings, baked, skipped, output, errors, exit_code, duration_ms, checkpoint; with import_to_scene also imported_node_path / scale_applied / instance_dimensions; no_rewind_point:true when no checkpoint exists. failure_reason: blender_not_found | blender_launch_failed | script_error (traceback_tail + script_line; fix the bpy for the reported blender_version) | timeout (raise max_seconds or split the job) | export_empty (check hide/render flags and collection links) | export_failed | export_missing | import_failed / instantiate_failed (the .glb IS at out_path: summer_instantiate_scene it yourself; importer message in summer_get_console) | busy | cancelled.
 
-THE LOOP: summer_world_snapshot BEFORE (keep snapshot_id) -> summer_fabricate_3d with import_to_scene (+ target_size for real-world scale) -> read dimensions/warnings/skipped -> summer_snapshot_diff + summer_screenshot -> iterate. Never claim a visual result without the screenshot. If this engine build predates FabricateMesh, the result is a structured engine_lacks_op failure (nothing is sent): use summer_generate_3d / summer_search_assets, or update Summer Engine.`, fabricateArgsSchema.shape, async (args) => withEngine(async (client) => {
+THE LOOP: summer_world_snapshot BEFORE (keep snapshot_id) -> summer_fabricate_3d with import_to_scene (+ target_size for real-world scale) -> read dimensions/warnings/skipped -> summer_snapshot_diff + summer_screenshot -> iterate. Never claim a visual result without the screenshot. An engine build without FabricateMesh returns a structured engine_lacks_op failure (nothing is sent): use summer_generate_3d / summer_search_assets, or update Summer Engine.`, fabricateArgsSchema.shape, async (args) => withEngine(async (client) => {
         const missing = missingEngineOpResult(client, "FabricateMesh", FABRICATE_FALLBACK);
         if (missing)
             return missing;

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

@@ -8,7 +8,8 @@ import { getAuthToken } from "../../core/auth.js";
 import { resolveGatewayUrl } from "../../core/config.js";
 import { readJsonResponse } from "../../core/util/http.js";
 import { asRecord, stringFrom } from "../../core/util/json.js";
-import { TOOLKIT_VERSION as CLI_VERSION } from "../../core/version.js";
+import { summerRequestHeaders } from "../../core/agent-host.js";
+import { codedFailure, codeForStatus, describeNetworkError, networkDetails, NOT_SIGNED_IN, SIGN_IN_AGAIN_RECOVERY, } from "../../core/error-codes.js";
 const TOOL_BY_ENDPOINT = {
     "/api/mcp/generate/image": "summer_generate_image",
     "/api/mcp/generate/audio": "summer_generate_audio",
@@ -72,13 +73,18 @@ async function readLenientJson(res) {
         return json;
     return text ? { message: text.slice(0, 1000) } : {};
 }
+/** The coded failure for a non-OK reply: 401 (token expired) and 402 (no
+ *  credits) carry the shared codes. */
+function statusFailure(status) {
+    const code = codeForStatus(status);
+    if (!code)
+        return {};
+    return code === "not_signed_in" ? { code, recovery: SIGN_IN_AGAIN_RECOVERY } : { code };
+}
 async function mcpGenerate(endpoint, body, timeoutMs = 120_000) {
     const token = await getAuthToken();
     if (!token) {
-        return {
-            error: "Not signed in. Run in your terminal:\n  npx -y summer-engine@latest login\nOr open: https://www.summerengine.com/login",
-            status: 401,
-        };
+        return { error: NOT_SIGNED_IN, status: 401, code: "not_signed_in" };
     }
     const gatewayUrl = await resolveGatewayUrl();
     let res;
@@ -86,36 +92,27 @@ async function mcpGenerate(endpoint, body, timeoutMs = 120_000) {
         res = await fetch(`${gatewayUrl}${endpoint}`, {
             method: "POST",
             headers: {
+                ...summerRequestHeaders({ tool: TOOL_BY_ENDPOINT[endpoint], surface: "mcp" }),
                 Authorization: `Bearer ${token}`,
                 "Content-Type": "application/json",
-                "X-Summer-Client": "summer-cli",
-                "X-Summer-Client-Version": CLI_VERSION,
-                "X-Summer-Client-Surface": "mcp",
                 "X-Summer-MCP-Endpoint": endpoint,
-                "X-Summer-MCP-Tool": TOOL_BY_ENDPOINT[endpoint] ?? "unknown",
             },
             body: JSON.stringify(body),
             signal: AbortSignal.timeout(timeoutMs),
         });
     }
     catch (err) {
-        const msg = err instanceof Error ? err.message : String(err);
-        return { error: `Generation request failed: ${msg}`, status: 0 };
+        return { error: `Generation request failed: ${describeNetworkError(err)}`, status: 0, code: "unavailable", data: networkDetails(err) };
     }
     const data = await readLenientJson(res);
     if (!res.ok) {
         let message = formattedApiErrorMessage(res.status, data);
-        if (res.status === 402) {
-            // One link: the Add credits step in Studio (no plan needed). Newer servers already put it in the message.
-            const base = String(data.message || "Not enough credits.");
-            message = base.includes("/studio/credits") ? base : `${base}\nAdd credits: https://summerengine.com/studio/credits`;
-        }
-        if (res.status === 401) {
-            message =
-                (data.message || "Auth token expired.") +
-                    "\nRe-authenticate:\n  npx -y summer-engine@latest login";
-        }
-        return { error: message, data: { ...data, status: res.status }, status: res.status };
+        // The next step (Add credits, sign in again) rides in `recovery`.
+        if (res.status === 402)
+            message = String(data.message || "Not enough credits.");
+        if (res.status === 401)
+            message = String(data.message || "Auth token expired.");
+        return { error: message, data: { ...data, status: res.status }, status: res.status, ...statusFailure(res.status) };
     }
     return { data, status: res.status };
 }
@@ -127,19 +124,15 @@ async function mcpGet(endpoint, searchParams, timeoutMs = 30_000) {
     try {
         res = await fetch(`${gatewayUrl}${endpoint}${suffix}`, {
             headers: {
+                ...summerRequestHeaders({ tool: TOOL_BY_ENDPOINT[endpoint], surface: "mcp" }),
                 ...(token ? { Authorization: `Bearer ${token}` } : {}),
-                "X-Summer-Client": "summer-cli",
-                "X-Summer-Client-Version": CLI_VERSION,
-                "X-Summer-Client-Surface": "mcp",
                 "X-Summer-MCP-Endpoint": endpoint,
-                "X-Summer-MCP-Tool": TOOL_BY_ENDPOINT[endpoint] ?? "unknown",
             },
             signal: AbortSignal.timeout(timeoutMs),
         });
     }
     catch (err) {
-        const msg = err instanceof Error ? err.message : String(err);
-        return { error: `Request failed: ${msg}`, status: 0 };
+        return { error: `Request failed: ${describeNetworkError(err)}`, status: 0, code: "unavailable", data: networkDetails(err) };
     }
     const data = await readLenientJson(res);
     if (!res.ok) {
@@ -147,6 +140,8 @@ async function mcpGet(endpoint, searchParams, timeoutMs = 30_000) {
             error: formattedApiErrorMessage(res.status, data),
             data: { ...data, status: res.status },
             status: res.status,
+            // Without a token a 401 means "sign in", not "sign in again".
+            ...(!token && res.status === 401 ? { code: "not_signed_in" } : statusFailure(res.status)),
         };
     }
     return { data, status: res.status };
@@ -158,18 +153,18 @@ async function mcpGet(endpoint, searchParams, timeoutMs = 30_000) {
 async function pollJob(jobId, maxWaitMs = 600_000, intervalMs = 5_000) {
     const token = await getAuthToken();
     if (!token)
-        return { error: "Not signed in" };
+        return { error: NOT_SIGNED_IN, code: "not_signed_in" };
     const gatewayUrl = await resolveGatewayUrl();
     const deadline = Date.now() + maxWaitMs;
     while (Date.now() < deadline) {
         try {
             const res = await fetch(`${gatewayUrl}/api/mcp/jobs/${encodeURIComponent(jobId)}`, {
-                headers: { Authorization: `Bearer ${token}` },
+                headers: { ...summerRequestHeaders({ surface: "mcp" }), Authorization: `Bearer ${token}` },
                 signal: AbortSignal.timeout(15_000),
             });
-            const data = await res.json();
+            const data = await readLenientJson(res);
             if (!res.ok)
-                return { error: data.message || "Poll failed", data };
+                return { error: data.message || "Poll failed", data, ...statusFailure(res.status) };
             if (data.status === "completed")
                 return { data };
             if (data.status === "failed")
@@ -182,23 +177,32 @@ async function pollJob(jobId, maxWaitMs = 600_000, intervalMs = 5_000) {
             }
         }
         catch (err) {
-            const msg = err instanceof Error ? err.message : String(err);
-            return { error: `Poll error: ${msg}` };
+            return { error: `Poll error: ${describeNetworkError(err)}`, code: "unavailable", data: networkDetails(err) };
         }
     }
     return { error: `Timed out after ${maxWaitMs / 1000}s. Use summer_check_job({ jobId: "${jobId}" }) to check later.` };
 }
-function errorResult(message, extra) {
+/** A failed tool call. With a shared code (core/error-codes.ts) the body is
+ *  `{ok:false, code, error, recovery, …, message}`; otherwise the older
+ *  `{error:true, …, message}`. */
+function errorResult(message, extra, coded) {
+    const body = coded?.code
+        ? codedFailure(coded.code, message, { ...extra, message }, coded.recovery)
+        : { error: true, ...extra, message };
     return {
         content: [
             {
                 type: "text",
-                text: JSON.stringify({ error: true, ...extra, message }, null, 2),
+                text: JSON.stringify(body, null, 2),
             },
         ],
         isError: true,
     };
 }
+/** The step after a generation job starts (the hosted tools answer the same way). */
+function checkJobNext(jobId) {
+    return `The job runs on Summer's servers. Poll summer_check_job({ jobId: "${jobId}" }) every 15-30 seconds until status is "completed".`;
+}
 function successResult(data) {
     return {
         content: [
@@ -232,7 +236,7 @@ handoff that MCP cannot perform automatically; do not pretend that stage ran.`,
             params.set("id", workflowId);
         const result = await mcpGet("/api/mcp/workflows", params);
         if (result.error)
-            return errorResult(result.error, result.data);
+            return errorResult(result.error, result.data, result);
         return successResult(result.data);
     });
     // ========================================================================
@@ -252,7 +256,7 @@ Cloud tool — runs on Summer's servers and works WITHOUT the Summer Engine app
 Requires authentication: run 'npx -y summer-engine@latest login' first.`, boardArgsSchema.shape, async (args) => {
         const result = await mcpGet(BOARD_ENDPOINT, boardQuery(args), 45_000);
         if (result.error)
-            return errorResult(result.error, result.data);
+            return errorResult(result.error, result.data, result);
         return { content: boardContent(result.data ?? {}) };
     });
     // ========================================================================
@@ -307,7 +311,7 @@ Requires authentication: run 'npx -y summer-engine@latest login' first.`, imageG
             options,
         }, IMAGE_GENERATION_TIMEOUT_MS);
         if (result.error) {
-            return errorResult(result.error, result.data);
+            return errorResult(result.error, result.data, result);
         }
         // Download to temp so the AI can Read and show the image
         const imageUrl = result.data?.asset?.fileUrl || result.data?.asset?.thumbnailUrl;
@@ -343,7 +347,7 @@ Requires authentication: run 'npx -y summer-engine@latest login' first.`, {
     }, async ({ assetId }) => {
         const result = await mcpGenerate("/api/mcp/generate/slice-asset-sheet", { assetId }, 300_000);
         if (result.error) {
-            return errorResult(result.error, result.data);
+            return errorResult(result.error, result.data, result);
         }
         return successResult({
             ...result.data,
@@ -442,7 +446,7 @@ Requires authentication: run 'npx -y summer-engine@latest login' first.`, {
             body.options = options;
         const result = await mcpGenerate("/api/mcp/generate/audio", body);
         if (result.error) {
-            return errorResult(result.error, result.data);
+            return errorResult(result.error, result.data, result);
         }
         return successResult(result.data);
     });
@@ -533,8 +537,9 @@ For a complete animated humanoid package, pass rig=true plus animationNames or
 actionIds. This routes through the shared character pipeline instead of a
 one-off mesh job.
 
-By default, waits for completion (up to 10 min) and returns the result directly.
-Set wait=false to get the jobId immediately and poll manually with summer_check_job.
+Returns a jobId within seconds. Poll summer_check_job with it until status is
+"completed" (most models take 1-5 minutes; tell the user it is running and keep
+working meanwhile). wait=true blocks up to 10 minutes instead.
 
 Cloud tool — runs on Summer's servers and works WITHOUT the Summer Engine app open.
 Requires authentication: run 'npx -y summer-engine@latest login' first.`, {
@@ -589,8 +594,8 @@ Requires authentication: run 'npx -y summer-engine@latest login' first.`, {
             .describe("Character height used by auto-rigging"),
         wait: z
             .boolean()
-            .default(true)
-            .describe("Wait for completion (default true, up to 10 min). Set false to get jobId immediately."),
+            .default(false)
+            .describe("Block until the job finishes (up to 10 min) and return the result. Default false returns the jobId at once; poll summer_check_job."),
         options: z
             .record(z.any())
             .optional()
@@ -616,17 +621,17 @@ Requires authentication: run 'npx -y summer-engine@latest login' first.`, {
             options: mergedOptions,
         });
         if (result.error) {
-            return errorResult(result.error, result.data);
+            return errorResult(result.error, result.data, result);
         }
         const jobId = result.data?.jobId;
-        // If not waiting or no jobId, return immediately
+        // The job runs on Summer's servers; the agent polls summer_check_job.
         if (!wait || !jobId) {
-            return successResult(result.data);
+            return successResult(jobId ? { ...result.data, next: checkJobNext(jobId) } : result.data);
         }
-        // Auto-poll until done
+        // wait=true: block until done
         const pollResult = await pollJob(jobId);
         if (pollResult.error) {
-            return errorResult(pollResult.error, { ...pollResult.data, jobId });
+            return errorResult(pollResult.error, { ...pollResult.data, jobId }, pollResult);
         }
         return successResult({
             ...pollResult.data,
@@ -688,7 +693,7 @@ Requires authentication: run 'npx -y summer-engine@latest login' first.`, {
             options,
         });
         if (result.error) {
-            return errorResult(result.error, result.data);
+            return errorResult(result.error, result.data, result);
         }
         return successResult(result.data);
     });
@@ -697,9 +702,10 @@ Requires authentication: run 'npx -y summer-engine@latest login' first.`, {
     // ========================================================================
     server.tool("summer_check_job", `Check the status of an async generation job.
 
-Use this when you called summer_generate_3d with wait=false, or need to re-check
-a job that timed out. Most of the time you won't need this — summer_generate_3d
-waits automatically.
+summer_generate_3d and summer_generate_motion return a jobId; call this with it
+every 15-30 seconds until status is "completed" or "failed". A completed job
+carries the result: assetId (3D), rigAssetId (rig=true), animationAssetId or
+result.assets (motion), with file URLs. Import with summer_import_asset_by_id.
 
 Status values: waiting, active, completed, failed, delayed, unknown.
 
@@ -709,24 +715,24 @@ Requires authentication: run 'npx -y summer-engine@latest login' first.`, {
     }, async ({ jobId }) => {
         const token = await getAuthToken();
         if (!token) {
-            return errorResult("Not signed in. Run: npx -y summer-engine@latest login");
+            return errorResult(NOT_SIGNED_IN, undefined, { code: "not_signed_in" });
         }
+        let res;
         try {
             const gatewayUrl = await resolveGatewayUrl();
-            const res = await fetch(`${gatewayUrl}/api/mcp/jobs/${encodeURIComponent(jobId)}`, {
-                headers: { Authorization: `Bearer ${token}` },
+            res = await fetch(`${gatewayUrl}/api/mcp/jobs/${encodeURIComponent(jobId)}`, {
+                headers: { ...summerRequestHeaders({ surface: "mcp" }), Authorization: `Bearer ${token}` },
                 signal: AbortSignal.timeout(15_000),
             });
-            const data = await res.json();
-            if (!res.ok) {
-                return errorResult(data.message || data.error || "Failed to check job status", data);
-            }
-            return successResult(data);
         }
         catch (err) {
-            const msg = err instanceof Error ? err.message : String(err);
-            return errorResult(`Job status check failed: ${msg}`);
+            return errorResult(`Job status check failed: ${describeNetworkError(err)}`, networkDetails(err), { code: "unavailable" });
+        }
+        const data = await readLenientJson(res);
+        if (!res.ok) {
+            return errorResult(data.message || data.error || "Failed to check job status", data, statusFailure(res.status));
         }
+        return successResult(data);
     });
     // ========================================================================
     // summer_generate_motion
@@ -763,9 +769,9 @@ Each clip (meshy: each motion; text-to-motion: each prompt x take) is billed.
 State the clip list and estimated cost and confirm with the user before
 spending.
 
-By default, waits for completion (up to 10 min) and returns the result directly.
-Set wait=false to get the jobId immediately and poll with summer_check_job.
-Import finished clips with summer_import_asset_by_id.
+Returns a jobId within seconds. Poll summer_check_job with it until status is
+"completed" (wait=true blocks up to 10 minutes instead). Import finished clips
+with summer_import_asset_by_id.
 
 Errors: backend_unavailable means text-to-motion is not enabled on this server
 yet — use meshy-library for humanoids and do not retry. Job failures starting
@@ -782,16 +788,16 @@ Requires authentication: run 'npx -y summer-engine@latest login' first.`, motion
         const result = await mcpGenerate("/api/mcp/generate/motion", built.body);
         if (result.error) {
             const hint = motionErrorHint(result.data?.error);
-            return errorResult(result.error, hint ? { ...result.data, hint } : result.data);
+            return errorResult(result.error, hint ? { ...result.data, hint } : result.data, result);
         }
         const jobId = result.data?.jobId;
         if (!args.wait || !jobId) {
-            return successResult(result.data);
+            return successResult(jobId ? { ...result.data, next: checkJobNext(jobId) } : result.data);
         }
         const pollResult = await pollJob(jobId);
         if (pollResult.error) {
             const hint = motionJobFailureHint(pollResult.error);
-            return errorResult(pollResult.error, { ...pollResult.data, jobId, ...(hint ? { hint } : {}) });
+            return errorResult(pollResult.error, { ...pollResult.data, jobId, ...(hint ? { hint } : {}) }, pollResult);
         }
         return successResult({
             ...pollResult.data,

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

@@ -5,12 +5,17 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
  * share ONE implementation. The MCP surface contributes the boot drift notice
  * it owns. Exported for tests.
  */
-export declare function buildAgentPlaybook(): Record<string, unknown>;
-export declare function renderAgentPlaybook(): string;
+export declare function buildAgentPlaybook(options?: ProjectToolsOptions): Record<string, unknown>;
+export declare function renderAgentPlaybook(options?: ProjectToolsOptions): string;
+/** What the session's profile serves. `engine: false` (the assets profile)
+ *  turns the playbook and the task plan into their no-engine versions. */
+export interface ProjectToolsOptions {
+    engine?: boolean;
+}
 /**
  * Register the playbook as an MCP PROMPT as well, so hosts that surface
  * prompts (prompt pickers, slash commands) get the operating guide natively
  * without knowing to call the tool. Same content, second doorway.
  */
-export declare function registerPlaybookPrompt(server: McpServer): void;
-export declare function registerProjectTools(server: McpServer): void;
+export declare function registerPlaybookPrompt(server: McpServer, options?: ProjectToolsOptions): void;
+export declare function registerProjectTools(server: McpServer, options?: ProjectToolsOptions): void;

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

@@ -38,37 +38,42 @@ function getScenePathFromSceneState(sceneState) {
  * share ONE implementation. The MCP surface contributes the boot drift notice
  * it owns. Exported for tests.
  */
-export function buildAgentPlaybook() {
+export function buildAgentPlaybook(options = {}) {
     return buildCoreAgentPlaybook({
         summerUpdateNotice: getCachedBootDriftNotice()?.text ?? null,
+        engine: options.engine,
     });
 }
-export function renderAgentPlaybook() {
-    return JSON.stringify(buildAgentPlaybook(), null, 2);
+export function renderAgentPlaybook(options = {}) {
+    return JSON.stringify(buildAgentPlaybook(options), null, 2);
 }
 /**
  * Register the playbook as an MCP PROMPT as well, so hosts that surface
  * prompts (prompt pickers, slash commands) get the operating guide natively
  * without knowing to call the tool. Same content, second doorway.
  */
-export function registerPlaybookPrompt(server) {
+export function registerPlaybookPrompt(server, options = {}) {
     server.registerPrompt("summer_agent_playbook", {
-        title: "Summer Engine agent playbook",
-        description: "AI-first operating guide for the Summer Engine MCP tools: observe-first loop, screenshot before/after every mutation, content routing (reuse -> import -> generate -> script last), physical invariants, cost rules, verification ritual, honesty rules, and recovery steps.",
+        title: options.engine === false ? "Summer assets playbook" : "Summer Engine agent playbook",
+        description: options.engine === false
+            ? "Operating guide for the Summer assets tools without Summer Engine: ask what the asset is for, reuse before generating, confirm spend, check the preview, hand over the file."
+            : "AI-first operating guide for the Summer Engine MCP tools: observe-first loop, screenshot before/after every mutation, content routing (reuse -> import -> generate -> script last), physical invariants, cost rules, verification ritual, honesty rules, and recovery steps.",
     }, async () => ({
         messages: [
             {
                 role: "user",
                 content: {
                     type: "text",
-                    text: "Operate Summer Engine by this playbook for the rest of the session:\n\n" +
-                        renderAgentPlaybook(),
+                    text: (options.engine === false
+                        ? "Work with the Summer assets tools by this playbook for the rest of the session:\n\n"
+                        : "Operate Summer Engine by this playbook for the rest of the session:\n\n") +
+                        renderAgentPlaybook(options),
                 },
             },
         ],
     }));
 }
-export function registerProjectTools(server) {
+export function registerProjectTools(server, options = {}) {
     server.tool("summer_start_game_task", `Start here for any substantial AI game-building task.
 
 Takes the user's goal and returns the recommended Summer workflow: skill routes,
@@ -102,6 +107,7 @@ mutating the project.`, {
                     target,
                     assetPolicy,
                     verification,
+                    engine: options.engine,
                 }), null, 2),
             },
         ],
@@ -115,7 +121,7 @@ ladder, honesty rules, anti-patterns, and recovery steps.`, {}, async () => ({
         content: [
             {
                 type: "text",
-                text: renderAgentPlaybook(),
+                text: renderAgentPlaybook(options),
             },
         ],
     }));

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

@@ -268,42 +268,31 @@ The full read is about 5 KB. To read only what you need, pass fields: property n
 Two forms, pass exactly one:
 - path: a resource FILE ('res://materials/ground.tres', a mesh 'res://kit/meshes/wall_01.res', 'res://models/player.glb'), loaded read-only in the editor. A Mesh returns its AABB, surface_count and per surface the primitive, vertex and index counts, attributes, triangles and material (class, path or embedded, albedo for standard materials), plus the unique materials and blend shapes. A scene or model (.tscn/.glb/.gltf) returns its node count, the first 40 nodes with type, instanced scene and mesh, and its meshes; summer_inspect_asset measures it (AABB, planes, ports). Every other resource (and a mesh) returns its editor properties that differ from the class default (props), with props_at_default counting the rest.
 - nodePath + property: a resource a node of the ACTIVE scene tab holds, e.g. nodePath 'Floor', property 'mesh'. For example, summer_inspect_node tells you a MeshInstance3D has a "StandardMaterial3D" material_override — this form returns its albedo_color, metallic, roughness, etc.`, inspectResourceInputShape, async (args) => withEngine(async (client) => inspectResource(client, args)));
-    server.tool("summer_batch", `Execute multiple operations in a single call. Each op is forwarded to the engine VERBATIM, so this is also how you reach engine ops that have no dedicated tool.
+    server.tool("summer_batch", `Execute multiple operations (a multi-node build) in a single call. Each op is forwarded to the engine VERBATIM: this is also how you reach engine ops without a dedicated tool.
 
-UNDO: when nothing in the list forces a split (see the single-op contract below), the whole batch is ONE undo step — the user undoes everything with a single Ctrl+Z. When single-only ops are present the list is split into sequential requests and EACH chunk is its own undo step (one Ctrl+Z per chunk; the receipt shows the chunks). Use this when building something that involves multiple nodes and properties — e.g., creating a player character with collision, camera, and properties.
+UNDO: when nothing in the list forces a split (see SPLITS), the whole batch is ONE undo step (one Ctrl+Z). Single-only ops split the list into sequential requests, and EACH chunk is its own undo step (the receipt shows the chunks).
 
-Each op in the array uses the same format as the individual tools:
+Ops use the individual tools' format:
 - {"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)"}
 
-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.
+SPLITS AND SAVE: scenePath selects every mutation target. Send OpenScene (a UI action) separately, never mixed with scene mutations. The tool appends one final SaveScene when the batch mutates a scene; a SaveScene you supply must appear exactly once, as the final op. The engine requires SaveScene, InstantiateScene, ReplaceNode, SimulateInput, the runtime reads (GetRuntimeSceneTree/GetRuntimeNode) and the Run*/Import* ops to travel alone, so the tool splits the list around them; if a later chunk fails, the receipt names the earlier ops that already applied.
 
-A raw ReplaceNode with scene is refused (it saves the old scene reference); use summer_replace_node.
-A raw ConnectSignal is refused (the engine connects without CONNECT_PERSIST, so the file never holds it); use summer_connect_signal.
+RAW RUNTIME OPS (structured failure_reason passes through verbatim):
+- RunVerification: a hidden, disposable game instance runs a GDScript probe and dies, never touching 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() without a name is a script error. Mount scenes deferred (add_child.call_deferred) or the capture can be black; summer_get_agent_playbook has the probe rules.
+- SimulateInput: inject an action/key/mouse/axis into the RUNNING game (summer_play first), sent ALONE: {"op": "SimulateInput", "type": "action", "action": "jump", "pressed": true}. failure_reason "not_running" = start the game first; "unsupported" = the game build predates the handler: use RunVerification or ask the user.
 
-REPARENTNODE KEEPS ITS SUBTREE AND IS VERIFIED: the engine's ReparentNode re-owns only the moved node, so its children and grandchildren were dropped from the saved file. A batch with ReparentNode saves first, reads the saved .tscn, sends each ReparentNode in its own request with an in-place ReparentNode (same parent, same index) per scene-owned descendant to give it back to the scene, then reads the saved file again: persisted:true / verified:true only when every moved node and descendant is at its new path; otherwise an error with failure_reason not_persisted. A move onto a parent that already has a child of that name is refused (failure_reason name_collision). The scenePath must be a .tscn, and Undo cannot share the batch.
+REFUSED: a raw ReplaceNode with scene (it saves the old scene reference; use summer_replace_node) and a raw ConnectSignal (no CONNECT_PERSIST, so the file never holds it; use summer_connect_signal).
 
-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. The engine requires
-SaveScene, InstantiateScene, ReplaceNode, SimulateInput, the runtime reads
-(GetRuntimeSceneTree/GetRuntimeNode), 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 (NOT one step for the whole batch), and if a later chunk fails the receipt
-reports exactly which earlier ops already applied.
+REPARENTNODE KEEPS ITS SUBTREE AND IS VERIFIED: the engine op re-owns only the moved node and drops its descendants from the saved file, so the tool saves, sends each ReparentNode alone plus an in-place ReparentNode per scene-owned descendant, then reads the saved .tscn back: persisted:true / verified:true only when every moved node and descendant is at its new path, else failure_reason not_persisted. A move onto a parent with a same-named child is refused (name_collision). scenePath must be a .tscn; Undo cannot share the batch.
 
-PLACED INSTANCES: an InstantiateScene op may also carry position, rotation_degrees, scale ([x, y, z] or "Vector3(...)") or transform ("Transform3D(...)"); the tool sets them on the created node. One op per piece. Other ops are forwarded verbatim. Cost: each InstantiateScene is its own engine request (the engine requires it); the transforms of a run of InstantiateScene ops are then sent together (up to 200 per request) before the next other op, so N placed pieces plus the save cost about N + 2 requests and N + 2 undo steps. Every later op (a SetProp, SnapToSurface, the save) sees the pieces already placed; if an InstantiateScene fails, the pieces created before it still get their transforms.
+PLACED INSTANCES: an InstantiateScene op may carry position, rotation_degrees, scale ([x, y, z] or "Vector3(...)") or transform ("Transform3D(...)"), set on the created node; one op per piece. Each InstantiateScene is its own request and the transforms of a run follow together (up to 200 per request), so N pieces plus the save cost about N + 2 requests and undo steps. Later ops (SetProp, SnapToSurface, the save) see the pieces placed; if one fails, the pieces before it still get their transforms.
 
-RECEIPTS: receipt "summary" returns only counts, failures [{index, op, error}] (index = position in your ops list), created node paths and renames, under 5 KB with any cut declared. Use it for any batch over a few ops; the full receipt of a large batch overflows the tool-output limit.
+RECEIPTS: receipt "summary" returns only counts, failures [{index, op, error}] (index into your ops), created node paths and renames, under 5 KB with any cut declared. Use it for any batch over a few ops: a large full receipt overflows the tool-output limit.
 
-scenePersistence.saved means the SaveScene ran; it does not prove what the file
-holds. verified:true is set only where the tool read the saved file back.`, {
+scenePersistence.saved means the SaveScene ran, not what the file holds; verified:true is set only where the tool read the file back.`, {
         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"),
         receipt: z