summer-engine 2.8.2 → 3.0.0

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

@@ -1,12 +1,13 @@
-import { createRequire } from "node:module";
 import { z } from "zod";
+import { imageGenerationArgsSchema } from "../../core/capabilities/image-generation.js";
 import { writeFile, mkdir } from "fs/promises";
 import { tmpdir } from "os";
 import { join } from "path";
-import { getAuthToken } from "../../lib/auth.js";
-const require = createRequire(import.meta.url);
-const { version: CLI_VERSION } = require("../../../package.json");
-const GATEWAY_URL = process.env.SUMMER_GATEWAY_URL || "https://www.summerengine.com";
+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";
 const TOOL_BY_ENDPOINT = {
     "/api/mcp/generate/image": "summer_generate_image",
     "/api/mcp/generate/audio": "summer_generate_audio",
@@ -19,14 +20,6 @@ const TOOL_BY_ENDPOINT = {
 // ---------------------------------------------------------------------------
 // Shared helpers
 // ---------------------------------------------------------------------------
-function asRecord(value) {
-    return value && typeof value === "object" && !Array.isArray(value)
-        ? value
-        : null;
-}
-function stringFrom(value) {
-    return typeof value === "string" && value.length > 0 ? value : undefined;
-}
 function formatValidationDetailEntry(entry) {
     const record = asRecord(entry);
     if (!record) {
@@ -68,34 +61,26 @@ function formattedApiErrorMessage(status, data) {
         stringFrom(record?.error) ??
         `Request failed (${status})`);
 }
-async function readJsonResponse(res) {
-    if (typeof res.text !== "function") {
-        if (typeof res.json === "function") {
-            return res.json().catch(() => ({}));
-        }
-        return {};
-    }
-    const text = await res.text().catch(() => "");
-    if (!text)
-        return {};
-    try {
-        return JSON.parse(text);
-    }
-    catch {
-        return { message: text.slice(0, 1000) };
-    }
+/** Lenient body read for Studio generation endpoints: {} for an empty body,
+ *  {message} for a non-JSON one, so callers can always index the result. */
+async function readLenientJson(res) {
+    const { text, json, parsed } = await readJsonResponse(res);
+    if (parsed)
+        return json;
+    return text ? { message: text.slice(0, 1000) } : {};
 }
 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 summer-engine login\nOr open: https://www.summerengine.com/login",
+            error: "Not signed in. Run in your terminal:\n  npx -y summer-engine@latest login\nOr open: https://www.summerengine.com/login",
             status: 401,
         };
     }
+    const gatewayUrl = await resolveGatewayUrl();
     let res;
     try {
-        res = await fetch(`${GATEWAY_URL}${endpoint}`, {
+        res = await fetch(`${gatewayUrl}${endpoint}`, {
             method: "POST",
             headers: {
                 Authorization: `Bearer ${token}`,
@@ -114,7 +99,7 @@ async function mcpGenerate(endpoint, body, timeoutMs = 120_000) {
         const msg = err instanceof Error ? err.message : String(err);
         return { error: `Generation request failed: ${msg}`, status: 0 };
     }
-    const data = await readJsonResponse(res);
+    const data = await readLenientJson(res);
     if (!res.ok) {
         let message = formattedApiErrorMessage(res.status, data);
         if (res.status === 402) {
@@ -125,7 +110,7 @@ async function mcpGenerate(endpoint, body, timeoutMs = 120_000) {
         if (res.status === 401) {
             message =
                 (data.message || "Auth token expired.") +
-                    "\nRe-authenticate:\n  npx summer-engine login";
+                    "\nRe-authenticate:\n  npx -y summer-engine@latest login";
         }
         return { error: message, data: { ...data, status: res.status }, status: res.status };
     }
@@ -134,9 +119,10 @@ async function mcpGenerate(endpoint, body, timeoutMs = 120_000) {
 async function mcpGet(endpoint, searchParams, timeoutMs = 30_000) {
     const token = await getAuthToken();
     const suffix = searchParams?.size ? `?${searchParams.toString()}` : "";
+    const gatewayUrl = await resolveGatewayUrl();
     let res;
     try {
-        res = await fetch(`${GATEWAY_URL}${endpoint}${suffix}`, {
+        res = await fetch(`${gatewayUrl}${endpoint}${suffix}`, {
             headers: {
                 ...(token ? { Authorization: `Bearer ${token}` } : {}),
                 "X-Summer-Client": "summer-cli",
@@ -152,7 +138,7 @@ async function mcpGet(endpoint, searchParams, timeoutMs = 30_000) {
         const msg = err instanceof Error ? err.message : String(err);
         return { error: `Request failed: ${msg}`, status: 0 };
     }
-    const data = await readJsonResponse(res);
+    const data = await readLenientJson(res);
     if (!res.ok) {
         return {
             error: formattedApiErrorMessage(res.status, data),
@@ -190,10 +176,11 @@ async function pollJob(jobId, maxWaitMs = 600_000, intervalMs = 5_000) {
     const token = await getAuthToken();
     if (!token)
         return { error: "Not signed in" };
+    const gatewayUrl = await resolveGatewayUrl();
     const deadline = Date.now() + maxWaitMs;
     while (Date.now() < deadline) {
         try {
-            const res = await fetch(`${GATEWAY_URL}/api/mcp/jobs/${encodeURIComponent(jobId)}`, {
+            const res = await fetch(`${gatewayUrl}/api/mcp/jobs/${encodeURIComponent(jobId)}`, {
                 headers: { Authorization: `Bearer ${token}` },
                 signal: AbortSignal.timeout(15_000),
             });
@@ -284,36 +271,22 @@ Two modes:
 
 Style presets: "realistic" (default), "cartoon", "anime", "none"
 
+For an alpha PNG, set removeBackground: true. Prompt wording alone does not
+guarantee transparency; background removal runs server-side after generation.
+
 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
-            .string()
-            .default("nano-banana-2")
-            .describe("Model name or full provider ID"),
-        style: z
-            .string()
-            .default("realistic")
-            .describe("Style preset: realistic, cartoon, anime, or 'none' to skip"),
-        referenceImageUrl: z
-            .string()
-            .optional()
-            .describe("Source image URL for img2img / edit mode. The prompt describes how to transform this image."),
-        options: z
-            .record(z.any())
-            .optional()
-            .describe("Provider-specific params (guidance_scale, seed, image_size, negative_prompt, etc.)"),
-    }, async ({ prompt, model, style, referenceImageUrl, options }) => {
+Requires authentication: run 'npx -y summer-engine@latest login' first.`, imageGenerationArgsSchema.shape, async ({ prompt, model, style, referenceImageUrl, removeBackground, options }) => {
         const result = await mcpGenerate("/api/mcp/generate/image", {
             prompt,
             model,
             style,
             referenceImageUrl,
+            removeBackground,
             options,
         });
         if (result.error) {
@@ -346,7 +319,7 @@ Returns source dimensions plus the generated slice URLs, names, categories, boun
 boxes, and widget metadata when the sheet contains UI controls.
 
 Cloud tool — runs on Summer's servers and works WITHOUT the Summer Engine app open.
-Requires authentication: run 'npx summer-engine login' first.`, {
+Requires authentication: run 'npx -y summer-engine@latest login' first.`, {
         assetId: z
             .string()
             .describe("Summer image asset ID to slice, usually returned by summer_generate_image"),
@@ -382,7 +355,7 @@ return a normal 200 with the setting ignored.
 
 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.`, {
+Requires authentication: run 'npx -y summer-engine@latest login' first.`, {
         capability: z
             .string()
             .describe("Type of audio: text_to_speech, sound_effects, music, text_to_dialogue"),
@@ -484,7 +457,7 @@ By default, waits for completion (up to 10 min) and returns the result directly.
 Set wait=false to get the jobId immediately and poll manually with summer_check_job.
 
 Cloud tool — runs on Summer's servers and works WITHOUT the Summer Engine app open.
-Requires authentication: run 'npx summer-engine login' first.`, {
+Requires authentication: run 'npx -y summer-engine@latest login' first.`, {
         prompt: z
             .string()
             .optional()
@@ -601,7 +574,7 @@ 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.`, {
+Requires authentication: run 'npx -y summer-engine@latest login' first.`, {
         prompt: z
             .string()
             .describe("Description of the video content"),
@@ -651,15 +624,16 @@ 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.`, {
+Requires authentication: run 'npx -y summer-engine@latest login' first.`, {
         jobId: z.string().describe("The job ID returned by an async generation tool"),
     }, async ({ jobId }) => {
         const token = await getAuthToken();
         if (!token) {
-            return errorResult("Not signed in. Run: npx summer-engine login");
+            return errorResult("Not signed in. Run: npx -y summer-engine@latest login");
         }
         try {
-            const res = await fetch(`${GATEWAY_URL}/api/mcp/jobs/${encodeURIComponent(jobId)}`, {
+            const gatewayUrl = await resolveGatewayUrl();
+            const res = await fetch(`${gatewayUrl}/api/mcp/jobs/${encodeURIComponent(jobId)}`, {
                 headers: { Authorization: `Bearer ${token}` },
                 signal: AbortSignal.timeout(15_000),
             });
@@ -712,7 +686,7 @@ signature moves not on the curated list, fall back to hand-authoring in the
 Summer Engine 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.`, {
+Requires authentication: run 'npx -y summer-engine@latest login' first.`, {
         rigAssetId: z
             .string()
             .describe("Asset ID of a rigged character (from summer_generate_3d with options.rig=true)"),

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

@@ -0,0 +1,11 @@
+/**
+ * summer_search_library / summer_read_library — the MCP face of the runtime
+ * librarian. Behavior lives in src/core/library-search.ts and
+ * src/core/library-read.ts; `summer tool search-library|read-library`
+ * (src/core/capabilities/tool-dispatch.ts) calls the same functions.
+ * Engine-free: both read the library shipped with this package.
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare const SEARCH_LIBRARY_DESCRIPTION: string;
+export declare const READ_LIBRARY_DESCRIPTION: string;
+export declare function registerLibraryTools(server: McpServer): void;

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

@@ -0,0 +1,42 @@
+import { readLibraryEntry, readLibraryInputShape } from "../../core/library-read.js";
+import { runSearchLibrary, searchLibraryInputShape } from "../../core/library-search.js";
+import { textJson } from "./text-json.js";
+export const SEARCH_LIBRARY_DESCRIPTION = "Search the Summer library — skills, tools, templates, references, examples, collections — by describing the task in plain words " +
+    "('make stylized water', 'the player falls through the floor', 'which tool reads script errors'). " +
+    "This is the FIRST MOVE for any task: even a 1% chance the library covers it means you search, then read the entry you pick with " +
+    "summer_read_library before acting — never act on a summary alone. " +
+    "Ranking: BM25 over ids, summaries, use_when lines and facets with kind-aware priors and related-entry boosts (the same ranker the routing eval gates). " +
+    "When this install ships registry/generated/embeddings.json and the embedding endpoint answers within 1.5s, lexical and semantic rankings are fused " +
+    "(reciprocal rank fusion) and each hit's matched_by says which side found it; offline or without embeddings it is lexical only and never fails for that reason. " +
+    "Returns {query, semantic, count, results: [{id, kind, status, summary, use_when, score, matched_by, mcp_tool_name?}], hint}. " +
+    "Scores compare only within one response. kinds narrows to some of the six kinds; include_preview:false hides preview entries; deprecated entries never surface. " +
+    "No engine needed. Privacy: only when semantic search is active is the query text sent to the Summer gateway to be embedded; nothing else leaves the machine.";
+export const READ_LIBRARY_DESCRIPTION = "Load one library entry by id (<kind>/<slug>, as returned by summer_search_library). " +
+    "Skills: the SKILL.md body plus metadata (status, use_when, related) and how to invoke the skill in your host (bare slug). " +
+    "Tools: how to call it (MCP name, `summer tool <slug> --args`, engine requirement, authority) plus the descriptor. " +
+    "Templates: the pinned repo @ commit and tree digest (or built-in) and the `summer create <slug>` command. References: the markdown body. " +
+    "part: 'skill' = body only, 'resource' = the resource.yaml descriptor only, 'all' (default) = both. " +
+    "The LAST line of every load is the feedback footer `— entry_id: <id>@<content-hash>. If this entry is wrong, stale, or you deviate from it, report via summer_library_feedback.` " +
+    "— copy that entry_id verbatim into summer_library_feedback once you have verified the outcome in-engine. " +
+    "Unknown id -> {ok:false, error:'not_found', nearest:[up to 3 ids]}. No engine needed; reads the library shipped with this package.";
+export function registerLibraryTools(server) {
+    server.tool("summer_search_library", SEARCH_LIBRARY_DESCRIPTION, searchLibraryInputShape, async (args) => {
+        try {
+            return textJson(await runSearchLibrary(args));
+        }
+        catch (error) {
+            return textJson({ ok: false, error: error instanceof Error ? error.message : String(error) }, true);
+        }
+    });
+    server.tool("summer_read_library", READ_LIBRARY_DESCRIPTION, readLibraryInputShape, async (args) => {
+        try {
+            const result = await readLibraryEntry(args.id, args.part ?? "all");
+            if (!result.ok)
+                return textJson(result, true);
+            return { content: [{ type: "text", text: result.text }] };
+        }
+        catch (error) {
+            return textJson({ ok: false, error: error instanceof Error ? error.message : String(error) }, true);
+        }
+    });
+}

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

@@ -0,0 +1,7 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+/**
+ * summer_open — the MCP face of `summer open`. Same behavior as the CLI
+ * (src/core/capabilities/navigation/open.ts runOpen); this file only supplies
+ * the engine client and the browser launcher. Design: docs/design/NAVIGATION-DESIGN.md §3.
+ */
+export declare function registerNavigationTools(server: McpServer): void;

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

@@ -0,0 +1,37 @@
+import open from "open";
+import { getClient } from "../server.js";
+import { getAuthToken } from "../../core/auth.js";
+import { resolveGatewayUrl } from "../../core/config.js";
+import { openArgsShape, runOpen } from "../../core/capabilities/navigation/open.js";
+/**
+ * summer_open — the MCP face of `summer open`. Same behavior as the CLI
+ * (src/core/capabilities/navigation/open.ts runOpen); this file only supplies
+ * the engine client and the browser launcher. Design: docs/design/NAVIGATION-DESIGN.md §3.
+ */
+export function registerNavigationTools(server) {
+    server.tool("summer_open", `Open the exact summerengine.com page or Summer Engine editor surface the user wants to LOOK at, by intent name — or, with open:false, return the URL / engine op without opening anything. The result ALWAYS carries the resolved url or op, also after opening, so you can tell the user where they landed.
+
+WHEN: the user wants to see, check, or decide something: "open my billing page", "show me my published games", "take me to pricing", "open the MCP setup guide for Cursor", "show me the scene", "select the Player node", "open player.gd". NOT for getting a result (add a node, set a property, publish) — use the mutation tools; opening a UI is a user-visible action, do it because the user asked to look, and say what will open.
+
+target: an id (billing, usage, account, settings, team, my-games, game, pricing, download, mcp-guide, templates, asset-store, docs, scene, main-scene, node, script, file, files, scene-tree, inspector, screen-3d, assistant, project-settings, output, debugger, editor-window, …), an intent phrase ("change my plan"), a res:// path (routed by extension: .tscn -> scene, .gd -> script, else file), or a summerengine.com path ("/pricing"). Omit target to LIST every destination with surface/status/requires.
+params: slot values — gameId + section (builds, releases, store-page, analytics, …) for game; guide (agent name: cursor, claude-code, codex, gemini, …) for mcp-guide; username; version; path / node / scene / line / col / tab for editor targets.
+open: false resolves only and returns url (+ login_url when the page needs login) or op; nothing opens, no engine needed.
+
+Result: { ok, action: opened | printed | listed | ambiguous | unsupported | engine_not_running | engine_error | not_found | invalid_params | open_failed | blocked_origin, target (with availability for editor ids), url, login_url, logged_in, opened_url, op, engine, failure_reason, matches, hint }.
+- Web targets that require login open through /login?returnUrl=<path> when this machine holds no Summer login token (logged_in:false) — the destination loads after sign-in.
+- Editor targets need Summer Engine running with the project open; otherwise action engine_not_running with the op that would have been sent and a 'summer run' hint. Nothing was opened.
+- Editor destinations are forwarded to the engine's own navigation table (op Navigate; ids advertised in /api/health capabilities.navigation). On an engine that predates it, scene/node/script/file and the three docks still work through their original ops; anything else answers action unsupported with failure_reason engine_lacks_op and an update hint. Never claim those opened. Listing (no target) shows each editor id's availability from the connected engine.
+- ambiguous: several destinations match; call again with one of matches[].id.
+Only summerengine.com (and subdomains) are ever opened — a gateway configured elsewhere is refused (blocked_origin); res:// paths with .. or other escapes are refused; a machine with no browser gets open_failed with the url to hand over.`, openArgsShape, async (args) => {
+        const result = await runOpen(args, {
+            engine: () => getClient(),
+            openUrl: (url) => open(url),
+            isLoggedIn: async () => (await getAuthToken()) !== null,
+            gatewayUrl: resolveGatewayUrl,
+        });
+        return {
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+            ...(result.ok ? {} : { isError: true }),
+        };
+    });
+}

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

@@ -0,0 +1,20 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+/**
+ * Perception tools. Two signals, two jobs: these ops return STRUCTURED state —
+ * exact node paths, transforms, world AABBs, counts — while summer_screenshot
+ * returns PIXELS. Structured reads prove facts ("the tree is at (4, 0, -2) and
+ * nothing clips"); pixels prove appearance. Run both around every mutation
+ * batch; neither substitutes for the other.
+ *
+ * Every tool here depends on an engine op an older build may lack. Two layers
+ * cover that: a capability pre-flight (missingEngineOpResult — nothing is sent
+ * when /api/health PROVES the op is missing) and, for engines that advertise
+ * nothing, a post-hoc rewrite of the per-op "unknown op" error into the same
+ * upgrade path.
+ */
+/** Amend a classified failure_reason with prescriptive recovery text. The
+ *  structured failure_reason stays intact for programmatic callers; only the
+ *  human/model-facing error string is taught. Shared with visual-tools.ts
+ *  (camera bookmarks). */
+export declare function withFailureReasonHint(result: unknown, hints: Record<string, string>): unknown;
+export declare function registerPerceptionTools(server: McpServer): void;

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

@@ -0,0 +1,146 @@
+import { z } from "zod";
+import { withEngine, missingEngineOpResult, withOldEngineHint } from "./with-engine.js";
+// engine_lacks_op fallbacks: ONE copy for every face (E2E 2026-09-03 F-16).
+import { RUNTIME_NODE_FALLBACK, RUNTIME_TREE_FALLBACK, SNAPSHOT_DIFF_FALLBACK, WORLD_SNAPSHOT_FALLBACK, } from "../../core/capabilities/engine-fallbacks.js";
+/**
+ * Perception tools. Two signals, two jobs: these ops return STRUCTURED state —
+ * exact node paths, transforms, world AABBs, counts — while summer_screenshot
+ * returns PIXELS. Structured reads prove facts ("the tree is at (4, 0, -2) and
+ * nothing clips"); pixels prove appearance. Run both around every mutation
+ * batch; neither substitutes for the other.
+ *
+ * Every tool here depends on an engine op an older build may lack. Two layers
+ * cover that: a capability pre-flight (missingEngineOpResult — nothing is sent
+ * when /api/health PROVES the op is missing) and, for engines that advertise
+ * nothing, a post-hoc rewrite of the per-op "unknown op" error into the same
+ * upgrade path.
+ */
+/** Amend a classified failure_reason with prescriptive recovery text. The
+ *  structured failure_reason stays intact for programmatic callers; only the
+ *  human/model-facing error string is taught. Shared with visual-tools.ts
+ *  (camera bookmarks). */
+export function withFailureReasonHint(result, hints) {
+    if (!result || typeof result !== "object")
+        return result;
+    const envelope = result;
+    const failed = envelope.results?.find((entry) => entry.ok === false);
+    const reason = (typeof envelope.failure_reason === "string" && envelope.failure_reason) ||
+        (typeof envelope.failureReason === "string" && envelope.failureReason) ||
+        failed?.failure_reason ||
+        failed?.failureReason;
+    if (typeof reason !== "string" || !(reason in hints))
+        return result;
+    const engineError = (typeof envelope.error === "string" && envelope.error) || failed?.error || reason;
+    return { ...envelope, error: `${hints[reason]} Engine said: ${engineError}` };
+}
+const GAME_NOT_RUNNING_HINT = "No game is running, so there is no runtime tree to read. Start it with summer_play (wait for it to boot), then re-run this tool. For the EDITED scene's structure use summer_get_scene_tree instead — it needs no running game.";
+const RUNTIME_TRANSPORT_HINT = "This connection cannot carry runtime debugger reads (no async reply channel), or the op was batched with others. Retry it as the ONLY op in the request; if it persists on this transport, probe the running game with a RunVerification probe instead (see the playbook's rawOpsViaBatch).";
+export function registerPerceptionTools(server) {
+    server.tool("summer_world_snapshot", `Compact structured snapshot of the whole EDITED scene — the cheap read to run BEFORE and AFTER every mutation batch. Per node: path, class, transform (pos/rot/scale as Godot literal strings, 3-decimal floats), world AABB (3D visuals), visibility, and 8-hex resource fingerprints (script/materials — detect-change markers, never content). Plus a light summary, camera list, environment fingerprint, and per-class counts.
+
+THE LOOP: summer_world_snapshot (note snapshot_id) -> mutate (summer_run_script / scene tools / imports) -> summer_snapshot_diff from_id:<that id> -> summer_screenshot. The diff proves exactly what changed structurally; the screenshot proves it looks right. This is how you catch a node that silently vanished on save, a transform that landed at the origin, or an AABB clipping through the floor.
+
+Node lists are path-sorted and truncated DETERMINISTICALLY (result carries total_nodes + truncated) so two snapshots stay diffable without phantom adds/removes. The engine retains the last 8 snapshots per session, keyed by snapshot_id. Use this instead of summer_get_scene_tree when you need transforms/AABBs/fingerprints or a diffable baseline; the tree read remains the hierarchy-shaped view. On an engine build that predates GetWorldSnapshot the result is a structured engine_lacks_op failure naming the fallback.`, {
+        scene_path: z
+            .string()
+            .optional()
+            .describe("Scene to snapshot, e.g. 'res://main.tscn'. Omit for the currently edited scene."),
+        max_nodes: z
+            .number()
+            .int()
+            .positive()
+            .optional()
+            .describe("Node cap (engine default 4000). The result declares truncation — never assume a capped list is complete."),
+    }, async ({ scene_path, max_nodes }) => withEngine(async (client) => {
+        const missing = missingEngineOpResult(client, "GetWorldSnapshot", WORLD_SNAPSHOT_FALLBACK);
+        if (missing)
+            return missing;
+        const op = { op: "GetWorldSnapshot" };
+        if (scene_path)
+            op.scene_path = scene_path;
+        if (max_nodes !== undefined)
+            op.max_nodes = max_nodes;
+        const result = await client.executeOps([op]);
+        return withFailureReasonHint(withOldEngineHint(result, "GetWorldSnapshot", WORLD_SNAPSHOT_FALLBACK), {
+            no_scene: "No scene is open to snapshot. Call summer_get_project_context, then summer_open_main_scene (or summer_open_scene with a known .tscn path), then retry.",
+            scene_not_loaded: "scene_path resolves only a LIVE editor tab or an already-cached scene — never a disk load. Open that scene first (summer_open_scene), or omit scene_path to snapshot the currently edited scene.",
+        });
+    }));
+    server.tool("summer_snapshot_diff", `Diff two world snapshots into exactly what changed: added/removed node paths, changed nodes with the fields that moved (pos, scale, material fingerprint, ...), and per-class count deltas. Reads like a receipt — no wading through two full dumps.
+
+Standard use: take summer_world_snapshot BEFORE a mutation batch, mutate, then call this with from_id (to_id omitted = the engine takes a fresh snapshot now). Verify the diff matches your INTENT: exactly the nodes you meant to add were added, nothing you didn't touch changed, nothing vanished. An empty diff after a "successful" mutation is a red flag — the change did not land (wrong scene? unsaved? unowned nodes dropped on save?).
+
+The engine retains the last 8 snapshot ids per session; an expired/unknown id fails with failure_reason "unknown_snapshot" — take a fresh baseline and re-run the mutation check rather than guessing.`, {
+        from_id: z.string().describe("snapshot_id of the BEFORE snapshot (from summer_world_snapshot)."),
+        to_id: z
+            .string()
+            .optional()
+            .describe("snapshot_id of the AFTER snapshot. Omit to snapshot the current state now and diff against that."),
+    }, async ({ from_id, to_id }) => withEngine(async (client) => {
+        const missing = missingEngineOpResult(client, "DiffWorldSnapshot", SNAPSHOT_DIFF_FALLBACK);
+        if (missing)
+            return missing;
+        const op = { op: "DiffWorldSnapshot", from_id };
+        if (to_id)
+            op.to_id = to_id;
+        const result = await client.executeOps([op]);
+        return withFailureReasonHint(withOldEngineHint(result, "DiffWorldSnapshot", SNAPSHOT_DIFF_FALLBACK), {
+            unknown_snapshot: "That snapshot_id is gone (the engine retains only the last 8 per session, and ids do not survive an engine restart). Take a fresh summer_world_snapshot baseline and redo the before/after pair.",
+        });
+    }));
+    server.tool("summer_get_runtime_tree", `Scene tree of the RUNNING GAME — live runtime state, not the edited scene. Use it during playtests to see what actually spawned: dynamically created enemies/projectiles/UI, autoloads, pooled nodes — everything summer_get_scene_tree (an EDITOR read) can never show. Inspecting live keeps the bug alive; stopping the game to look usually resets it.
+
+Returns {tree: {name, class, path, children}, total_nodes, truncated}. Depth/limit are capped and truncation is declared — never assume a capped tree is complete. Drill into one node's live properties with summer_inspect_runtime_node.
+
+Needs a running game: fails with failure_reason "game_not_running" otherwise — start with summer_play, then re-run.`, {
+        path: z
+            .string()
+            .optional()
+            .describe("Subtree root to read, e.g. '/root/Main/Enemies'. Omit for the scene tree root."),
+        depth: z
+            .number()
+            .int()
+            .positive()
+            .optional()
+            .describe("Maximum depth to walk (engine default 3)."),
+        limit: z
+            .number()
+            .int()
+            .positive()
+            .optional()
+            .describe("Maximum nodes to return (engine default 500)."),
+    }, async ({ path, depth, limit }) => withEngine(async (client) => {
+        const missing = missingEngineOpResult(client, "GetRuntimeSceneTree", RUNTIME_TREE_FALLBACK);
+        if (missing)
+            return missing;
+        const op = { op: "GetRuntimeSceneTree" };
+        if (path)
+            op.path = path;
+        if (depth !== undefined)
+            op.depth = depth;
+        if (limit !== undefined)
+            op.limit = limit;
+        const result = await client.executeOps([op]);
+        return withFailureReasonHint(withOldEngineHint(result, "GetRuntimeSceneTree", RUNTIME_TREE_FALLBACK), {
+            game_not_running: GAME_NOT_RUNNING_HINT,
+            unsupported_transport: RUNTIME_TRANSPORT_HINT,
+        });
+    }));
+    server.tool("summer_inspect_runtime_node", `Live properties of ONE node in the RUNNING GAME: {node: {path, class, properties, children_names}} with a curated common-property set (transform, visibility, physics state, ...). The runtime counterpart of summer_inspect_node (which reads the EDITED scene) — use it to answer "what are this enemy's actual stats right now", "where IS the player", "did that flag flip" without stopping the game and losing the state.
+
+Find the path with summer_get_runtime_tree first — runtime paths (e.g. '/root/Main/Enemies/Goblin3') often differ from edited-scene paths because nodes are spawned, renamed, or reparented at runtime.
+
+Needs a running game: fails with failure_reason "game_not_running" otherwise — start with summer_play, then re-run.`, {
+        path: z.string().describe("Runtime node path, e.g. '/root/Main/Player'. Get it from summer_get_runtime_tree."),
+    }, async ({ path }) => withEngine(async (client) => {
+        const missing = missingEngineOpResult(client, "GetRuntimeNode", RUNTIME_NODE_FALLBACK);
+        if (missing)
+            return missing;
+        const result = await client.executeOps([{ op: "GetRuntimeNode", path }]);
+        return withFailureReasonHint(withOldEngineHint(result, "GetRuntimeNode", RUNTIME_NODE_FALLBACK), {
+            game_not_running: GAME_NOT_RUNNING_HINT,
+            unsupported_transport: RUNTIME_TRANSPORT_HINT,
+            node_not_found: "That path does not exist in the RUNNING game (runtime paths are absolute, e.g. '/root/Main/Player', and often differ from the edited scene). List what actually spawned with summer_get_runtime_tree, then retry with a path from its result.",
+        });
+    }));
+}

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

@@ -1,2 +1,16 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+/**
+ * The agent playbook lives in core (src/core/capabilities/agent-playbook.ts)
+ * so this tool, the MCP prompt below, and `summer tool get-agent-playbook`
+ * 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;
+/**
+ * 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;