summer-engine 2.7.0 → 2.8.1

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

@@ -0,0 +1,105 @@
+import { z } from "zod";
+import { CreatorOperationError, listCreatorReleases, publishCreator, readCreatorLogs, } from "../../lib/creator.js";
+import { CONFIG_KEYS, getConfigValue, isConfigKey, readSummerConfig, setConfigValue, unsetConfigValue, } from "../../lib/config.js";
+function textJson(value, isError = false) {
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify(value, null, 2),
+            },
+        ],
+        ...(isError ? { isError: true } : {}),
+    };
+}
+async function creatorResult(operation) {
+    try {
+        return textJson(await operation());
+    }
+    catch (error) {
+        if (error instanceof CreatorOperationError) {
+            return textJson({
+                ok: false,
+                code: error.code,
+                operation: error.operation,
+                message: error.message,
+                recovery: error.recovery,
+            }, true);
+        }
+        return textJson({
+            ok: false,
+            code: "creator_request_invalid",
+            message: error instanceof Error ? error.message : String(error),
+        }, true);
+    }
+}
+export function registerCreatorTools(server) {
+    server.tool("summer_creator_publish", "Publish an exact exported Summer .pck through the versioned Summercraft creator API. First call with confirm=false and present the returned project, version, digest, size, artifact path, channel, and notes; set confirm only after the user approves that exact target. The server independently verifies token scope, ownership, bytes, and review state.", {
+        project: z.string().optional().describe("Project root. Defaults to the current working directory."),
+        artifact: z.string().describe("Exact path to the exported Summer .pck artifact."),
+        version: z.string().describe("Immutable release version."),
+        manifest: z.string().optional().describe("Optional path to a JSON release manifest."),
+        projectId: z.string().optional().describe("Creator project ID. Defaults to ~/.summer/config.json."),
+        channel: z.string().optional().describe("Release channel. Defaults to the configured channel or production."),
+        notes: z.string().optional().describe("Release notes shown during confirmation and recorded in the local audit."),
+        confirm: z.boolean().default(false).describe("Set true only after the user approves the exact release target."),
+    }, async (args) => creatorResult(() => publishCreator({
+        ...args,
+        face: "mcp",
+    })));
+    server.tool("summer_creator_releases", "List real creator-owned releases from the versioned Summercraft creator API. The server independently verifies the exact publish scope and project ownership.", {
+        projectId: z.string().optional().describe("Creator project ID. Defaults to ~/.summer/config.json."),
+        limit: z.number().int().min(1).max(100).default(20),
+        cursor: z.string().optional().describe("Opaque nextCursor from the previous page."),
+    }, async (args) => creatorResult(() => listCreatorReleases({
+        ...args,
+        face: "mcp",
+    })));
+    server.tool("summer_creator_logs", "Read creator runtime logs for a project or release. If the required platform route or token scope is unavailable, returns the exact recovery action instead of placeholder logs.", {
+        projectId: z.string().optional().describe("Creator project ID. Defaults to ~/.summer/config.json."),
+        releaseId: z.string().optional().describe("Optional release ID."),
+        limit: z.number().int().min(1).max(1000).default(100),
+    }, async (args) => creatorResult(() => readCreatorLogs({
+        ...args,
+        face: "mcp",
+    })));
+    server.tool("summer_creator_config", "Read or update the shared non-secret ~/.summer configuration used by the CLI and this MCP. Mutations require confirm=true. Tokens are never returned or accepted by this tool.", {
+        action: z.enum(["list", "get", "set", "unset"]),
+        key: z.enum(CONFIG_KEYS).optional(),
+        value: z.string().optional(),
+        confirm: z.boolean().default(false),
+    }, async ({ action, key, value, confirm }) => creatorResult(async () => {
+        if (action === "list") {
+            const config = await readSummerConfig();
+            return {
+                ok: true,
+                values: Object.fromEntries(CONFIG_KEYS.map((name) => [
+                    name,
+                    getConfigValue(config, name) ?? null,
+                ])),
+            };
+        }
+        if (!key || !isConfigKey(key)) {
+            throw new Error(`A valid key is required. Recovery: use one of ${CONFIG_KEYS.join(", ")}.`);
+        }
+        if (action === "get") {
+            return {
+                ok: true,
+                key,
+                value: getConfigValue(await readSummerConfig(), key) ?? null,
+            };
+        }
+        if (!confirm) {
+            throw new Error(`Changing ${key} requires confirmation. Recovery: show the exact change to the user, then retry with confirm=true.`);
+        }
+        if (action === "set") {
+            if (value === undefined) {
+                throw new Error(`A value is required for ${key}. Recovery: provide value and retry with confirm=true.`);
+            }
+            const config = await setConfigValue(key, value);
+            return { ok: true, key, value: getConfigValue(config, key) };
+        }
+        const config = await unsetConfigValue(key);
+        return { ok: true, key, value: getConfigValue(config, key) ?? null };
+    }));
+}

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

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

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

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

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

@@ -274,7 +274,9 @@ Known models:
   - "nano-banana-2" (default) — High quality, supports txt2img and img2img
   - "gemini-flash" — Google Gemini 2.5 Flash, fast
   - "flux-2" — FLUX.2, good for specific styles
-  - Any fal-ai model ID works as a passthrough
+
+Model ids are an ALLOWLIST, not a passthrough. An unrecognised id is rejected
+with 400 and the response lists every accepted id — it is not silently swapped.
 
 Two modes:
   - txt2img (default): just pass prompt
@@ -371,8 +373,12 @@ Capabilities:
   - "music" — Generate background music. Requires 'prompt'. Optional 'durationSeconds'.
   - "text_to_dialogue" — Multi-voice dialogue. Requires 'inputs' array of {text, voiceId} objects.
 
-The 'options' object is passed directly to ElevenLabs, so you can set any
-provider-specific parameter: stability, similarity_boost, style, speed, etc.
+The 'options' object is spread into the ElevenLabs SDK call at the TOP level, so
+only keys the SDK accepts there have any effect. Voice tuning is NOT top-level and
+is NOT snake_case: pass it as options.voiceSettings with camelCase keys —
+{ voiceSettings: { stability, similarityBoost, style, speed, useSpeakerBoost } }.
+Flat snake_case keys are accepted by the schema, silently dropped by the SDK, and
+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.
@@ -407,7 +413,9 @@ Requires authentication: run 'npx summer-engine login' first.`, {
         options: z
             .record(z.any())
             .optional()
-            .describe("Provider-specific params (stability, similarity_boost, style, speed, etc.)"),
+            .describe("Provider params, spread at the SDK's top level. Voice tuning goes in " +
+            "options.voiceSettings with camelCase keys (stability, similarityBoost, " +
+            "style, speed, useSpeakerBoost); flat snake_case is silently ignored."),
     }, async ({ capability, text, prompt, voiceId, modelId, durationSeconds, inputs, options }) => {
         const body = { capability };
         if (text)
@@ -439,7 +447,9 @@ Available models:
   - "hunyuan" (default) — Hunyuan 3D v3.1 Pro, high quality
   - "trellis" — Trellis 2, fast and detailed
   - "meshy" — Meshy, legacy option
-  - Any fal-ai model ID works as a passthrough
+
+Model ids are an ALLOWLIST, not a passthrough. An unrecognised id is rejected
+with 400 listing the accepted ids.
 
 Available kinds:
   - "text-to-3d" (default) — From text description. Requires 'prompt'.
@@ -699,7 +709,7 @@ Cost: ~$0.10 per clip. Confirm with user before spending.
 
 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.
+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.`, {

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

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