summer-engine 3.8.0 → 4.0.0

package/dist/mcp/tool-surface.js

@@ -0,0 +1,317 @@
+import { z } from "zod";
+import { loadLibraryIndex } from "../core/library-search.js";
+import { PROFILES, TOOLSETS, parseProfile } from "../core/tool-profiles.js";
+/**
+ * The shape of the MCP tool surface: which toolset each tool belongs to, each
+ * local tool's annotations, which results are capped, and which calls count
+ * as single scene edits. Read by server.ts (registration, results) and, with
+ * the profiles in core/tool-profiles.ts, by hosted-mount.ts (which hosted
+ * tools a profile mounts).
+ *
+ * Tool names never change here: a profile only leaves tools out.
+ */
+export { TOOLSETS, PROFILES, PROFILE_TOOL_LIMIT } from "../core/tool-profiles.js";
+const LOCAL_TOOLSETS = {
+    core: [
+        "summer_search_library",
+        "summer_read_library",
+        "summer_library_feedback",
+        "summer_get_agent_playbook",
+        "summer_start_game_task",
+        "summer_open",
+    ],
+    assets: [
+        "summer_generate_3d",
+        "summer_generate_audio",
+        "summer_generate_image",
+        "summer_generate_motion",
+        "summer_generate_sfx_choices",
+        "summer_generate_video",
+        "summer_check_job",
+        "summer_get_choices",
+        "summer_slice_asset_sheet",
+        "summer_get_studio_workflow",
+        "summer_search_assets",
+        "summer_list_my_assets",
+        "summer_get_asset",
+        "summer_get_asset_download_url",
+    ],
+    ship: ["summer_export_game", "summer_export_templates", "summer_publish_build", "summer_capture_gameplay"],
+    ui: ["summer_ui_actions", "summer_ui_activate", "summer_ui_screenshot", "summer_ui_tree"],
+};
+const localToolset = new Map(Object.entries(LOCAL_TOOLSETS).flatMap(([set, names]) => names.map((name) => [name, set])));
+/** Hosted tool names by pattern, first match wins. Unknown names land in `other` (full only). */
+const HOSTED_TOOLSETS = [
+    [/^summer_(account|team)$/, "core"],
+    [/^summer_(remove_background|update_asset|delete_asset|upload_image_\w+)$/, "assets"],
+    [/^summer_tool_\w+$/, "tools"],
+    [/^summer_(store_version_(begin_upload|sign_parts|complete)|build_(begin_upload|sign_parts|complete_upload))$/, "uploads"],
+    [/^summer_(store_\w+|list_games)$/, "ship"],
+    [/^summer_board_\w+$/, "board"],
+    [/^summer_grow_\w+$/, "grow"],
+    [/^summer_studio_\w+$/, "studio"],
+    [/^summer_app_\w+$/, "apps"],
+    [/^summer_(build_\w+|make_game|game|game_\w+|list_projects|get_project)$/, "cloud"],
+];
+/** The toolset a tool belongs to: local tools by the table above, hosted ones by name. */
+export function toolsetOf(name, local) {
+    if (local) {
+        if (localToolset.has(name))
+            return localToolset.get(name);
+        return name.startsWith("summer_app_") ? "apps" : "engine";
+    }
+    if (localToolset.has(name))
+        return localToolset.get(name);
+    return HOSTED_TOOLSETS.find(([pattern]) => pattern.test(name))?.[1] ?? "other";
+}
+const splitList = (value) => (value ?? "")
+    .split(",")
+    .map((part) => part.trim().toLowerCase())
+    .filter(Boolean);
+/**
+ * `summer mcp --profile <p> --toolsets <a,b>` (env SUMMER_PROFILE,
+ * SUMMER_TOOLSETS). Without either: the full profile. `--toolsets` alone
+ * selects those toolsets plus core; with a profile it adds to it. `all` is
+ * every toolset. Unknown names are ignored and reported, never fatal: a
+ * typo must not stop an agent's MCP server from starting.
+ */
+export function resolveToolSelection(options = {}, env = process.env) {
+    const ignored = [];
+    const profileName = (options.profile ?? env.SUMMER_PROFILE ?? "").trim().toLowerCase();
+    const requested = splitList(options.toolsets ?? env.SUMMER_TOOLSETS);
+    const profile = parseProfile(profileName);
+    if (profileName && !profile)
+        ignored.push(profileName);
+    const extra = new Set();
+    let all = false;
+    for (const name of requested) {
+        if (name === "all")
+            all = true;
+        else if (TOOLSETS.includes(name))
+            extra.add(name);
+        else
+            ignored.push(name);
+    }
+    if (all || profile === "full" || (profile === null && extra.size === 0)) {
+        return { profile: "full", toolsets: null, ignored };
+    }
+    if (profile === null)
+        return { profile: "custom", toolsets: new Set(["core", ...extra]), ignored };
+    return { profile, toolsets: new Set([...PROFILES[profile], ...extra]), ignored };
+}
+/** True when the selection keeps this tool. */
+export function selectionIncludes(selection, name, local) {
+    return selection.toolsets === null || selection.toolsets.has(toolsetOf(name, local));
+}
+// ── Annotations ──────────────────────────────────────────────────────────────
+/**
+ * Local tools carry the registry's five `authority` booleans
+ * (library/tools/<slug>/resource.yaml). They say what a tool may touch, not
+ * whether it only reads, so a few sets refine them; the result is the MCP
+ * effect hints clients use for approvals.
+ */
+/** Tools whose only file output is an image or render for the agent; they never change the game. */
+const EVIDENCE_ONLY = new Set([
+    "summer_screenshot",
+    "summer_debug_views",
+    "summer_shot_sheet",
+    "summer_zoom",
+    "summer_scene_audit",
+    "summer_game_probe",
+    "summer_capture_gameplay",
+    "summer_app_screenshot",
+]);
+/** Generation on Summer's servers: costs credits, creates new assets. */
+const SPENDS_CREDITS = new Set([
+    "summer_generate_3d",
+    "summer_generate_audio",
+    "summer_generate_image",
+    "summer_generate_motion",
+    "summer_generate_sfx_choices",
+    "summer_generate_video",
+]);
+/** Network-only tools that change the person's Summer data (the rest of the network tools read). */
+const NETWORK_WRITES = new Set([
+    "summer_app_create",
+    "summer_app_data",
+    "summer_app_page",
+    "summer_app_call",
+    "summer_app_report_gap",
+    "summer_app_update",
+    "summer_slice_asset_sheet",
+]);
+/** Changes that only add something new, or only touch the editor view or the running game. */
+const ADDITIVE_OR_TRANSIENT = new Set([
+    "summer_add_node",
+    "summer_create_scene",
+    "summer_instantiate_scene",
+    "summer_connect_signal",
+    "summer_input_map_bind",
+    "summer_import_asset",
+    "summer_import_asset_by_id",
+    "summer_import_from_url",
+    "summer_import_from_url_batch",
+    "summer_import_hdri",
+    "summer_repeat_along",
+    "summer_fabricate_3d",
+    "summer_frame_nodes",
+    "summer_frame_shot",
+    "summer_save_scene",
+    "summer_enable_plugin",
+    "summer_export_game",
+    "summer_export_templates",
+    "summer_create_debug_report",
+    "summer_library_feedback",
+    "summer_app_create",
+    "summer_app_report_gap",
+    "summer_app_dock",
+    "summer_slice_asset_sheet",
+    "summer_open_scene",
+    "summer_open_main_scene",
+    "summer_select_node",
+    "summer_clear_console",
+    "summer_play",
+    "summer_stop",
+    "summer_game_control",
+    "summer_game_input",
+    "summer_runtime_animate",
+    "summer_runtime_call",
+    "summer_runtime_set",
+    "summer_runtime_spawn",
+]);
+/** Changes where a second identical call has no further effect. */
+const IDEMPOTENT_WRITES = new Set([
+    "summer_set_prop",
+    "summer_set_resource_property",
+    "summer_project_setting",
+    "summer_remove_node",
+    "summer_write_file",
+    "summer_create_scene",
+    "summer_save_scene",
+    "summer_open_scene",
+    "summer_open_main_scene",
+    "summer_select_node",
+    "summer_clear_console",
+    "summer_stop",
+    "summer_enable_plugin",
+    "summer_place_adjacent",
+    "summer_attach_to_surface",
+    "summer_connect_ports",
+    "summer_align_distribute_3d",
+    "summer_snap_to_surface",
+    "summer_camera_bookmark",
+    "summer_frame_nodes",
+    "summer_runtime_set",
+    "summer_export_game",
+    "summer_export_templates",
+    "summer_app_update",
+    "summer_app_dock",
+]);
+/** Every name the refinement sets mention (a test checks each is a real tool). */
+export const ANNOTATION_REFINEMENTS = new Set([
+    ...EVIDENCE_ONLY,
+    ...SPENDS_CREDITS,
+    ...NETWORK_WRITES,
+    ...ADDITIVE_OR_TRANSIENT,
+    ...IDEMPOTENT_WRITES,
+]);
+/** MCP annotations for one local tool from its registry authority. */
+export function annotationsFor(name, authority) {
+    const openWorldHint = Boolean(authority.network || authority.publish);
+    if (authority.publish) {
+        return { readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true };
+    }
+    if (SPENDS_CREDITS.has(name)) {
+        return { readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true };
+    }
+    const writes = !EVIDENCE_ONLY.has(name) &&
+        Boolean(authority.filesystem || authority.editor_mutation || authority.credentials || NETWORK_WRITES.has(name));
+    if (!writes) {
+        return { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint };
+    }
+    return {
+        readOnlyHint: false,
+        destructiveHint: !ADDITIVE_OR_TRANSIENT.has(name),
+        idempotentHint: IDEMPOTENT_WRITES.has(name),
+        openWorldHint,
+    };
+}
+let authorityCache = null;
+/** Registry authority per MCP tool name (registry/generated/index.json). */
+export function registryAuthorities() {
+    if (authorityCache)
+        return authorityCache;
+    const map = new Map();
+    try {
+        for (const entry of loadLibraryIndex()) {
+            if (entry.kind === "tool" && entry.mcp_tool_name && entry.authority)
+                map.set(entry.mcp_tool_name, entry.authority);
+        }
+    }
+    catch {
+        // A broken install still serves tools; they go out without annotations.
+    }
+    authorityCache = map;
+    return map;
+}
+// ── Output caps ──────────────────────────────────────────────────────────────
+/** Default text cap for tools whose results can be large. */
+export const DEFAULT_MAX_CHARACTERS = 4_000;
+/**
+ * Tools whose text results are capped by default, with their default cap.
+ * Scene and runtime trees, console and debugger reads, inspect reads and
+ * library reads. The scene tree and library reads get more room: a median
+ * skill is about 12K characters, and cutting every skill read would double
+ * the core search-then-read loop. Writes, job ids and file reads are never
+ * capped.
+ */
+export const OUTPUT_CAPS = new Map([
+    ["summer_get_scene_tree", 8_000],
+    ["summer_get_runtime_tree", DEFAULT_MAX_CHARACTERS],
+    ["summer_get_console", DEFAULT_MAX_CHARACTERS],
+    ["summer_get_debugger_errors", DEFAULT_MAX_CHARACTERS],
+    ["summer_get_debugger_warnings", DEFAULT_MAX_CHARACTERS],
+    ["summer_inspect_node", DEFAULT_MAX_CHARACTERS],
+    ["summer_inspect_resource", DEFAULT_MAX_CHARACTERS],
+    ["summer_inspect_runtime_node", DEFAULT_MAX_CHARACTERS],
+    ["summer_inspect_asset", DEFAULT_MAX_CHARACTERS],
+    ["summer_read_library", 24_000],
+]);
+/**
+ * A capped tool's input shape plus `maxCharacters`. server.ts adds it at
+ * registration and strips it before the handler runs; the descriptor parity
+ * test applies the same function, so library/tools/<slug>/resource.yaml
+ * lists the argument too.
+ */
+export function withMaxCharactersArg(name, shape) {
+    const cap = OUTPUT_CAPS.get(name);
+    if (cap === undefined || "maxCharacters" in shape)
+        return shape;
+    return {
+        ...shape,
+        maxCharacters: z
+            .number()
+            .int()
+            .min(500)
+            .max(1_000_000)
+            .optional()
+            .describe(`Most characters of text to return (default ${cap}). A longer result is cut and says so.`),
+    };
+}
+// ── Single scene edits ───────────────────────────────────────────────────────
+/** One-change scene tools; a run of them is one summer_run_script. */
+export const SINGLE_EDIT_TOOLS = new Set([
+    "summer_set_prop",
+    "summer_add_node",
+    "summer_remove_node",
+    "summer_set_resource_property",
+    "summer_instantiate_scene",
+    "summer_connect_signal",
+    "summer_replace_node",
+]);
+/** Calls that already batch edits; they end a run of single edits. */
+export const BATCH_EDIT_TOOLS = new Set([
+    "summer_run_script",
+    "summer_batch",
+    "summer_run_editor_script",
+]);

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

@@ -19,7 +19,14 @@ function cloud(name, schema, run) {
     };
 }
 export function registerAppTools(server) {
-    server.tool("summer_app_guide", `Read this before building or changing a Summer App (a tool for the person's team inside Summer Studio, live on their assets, game data and engine): when to build one, Layout vs code, the build loop, manifest schema, SDK reference, UI kit, layout format, design rules and four worked examples. section returns one part.\n\n${CLOUD}`, appGuideArgsSchema.shape, cloud("summer_app_guide", appGuideArgsSchema, appGuide));
+    server.tool("summer_app_guide", `Read this before building or changing a Summer App (a tool for the person's team inside Summer Studio). Start with the default section overview (when to build one, Layout vs code, the build loop, the rules), then read what the app needs: examples (a complete working app to copy), sdk, manifest, kit, design, layout, types (exact SDK TypeScript types).\n\n${CLOUD}`, appGuideArgsSchema.shape, async (args) => {
+        const parsed = appGuideArgsSchema.safeParse(args ?? {});
+        if (!parsed.success)
+            return result({ ok: false, code: "invalid", error: parsed.error.issues[0]?.message ?? "Invalid arguments" });
+        const guide = await appGuide(parsed.data, { request: appsGateway("mcp", "summer_app_guide") });
+        // The guide reads as Markdown, not as one escaped JSON line.
+        return guide.ok === true && typeof guide.markdown === "string" ? { content: [{ type: "text", text: guide.markdown }] } : result(guide);
+    });
     server.tool("summer_app_list", `The Summer Apps in the person's workspaces: id, name, purpose, folder, status (scratch, kept, archived), version, format.\n\n${CLOUD}`, appListArgsSchema.shape, cloud("summer_app_list", appListArgsSchema, appList));
     server.tool("summer_app_create", `Create a new scratch Summer App; their open Summer Studio tab opens it. Without workspaceId it goes to the person's team (the one their Studio tab is on, else their latest team, else personal); the result's workspace says which: tell the person. Read summer_app_guide first. format code (index.html + JS/CSS) or layout (a JSON layout of kit nodes for a quick decision UI). Then summer_app_publish.\n\n${CLOUD}`, appCreateArgsSchema.shape, cloud("summer_app_create", appCreateArgsSchema, appCreate));
     server.tool("summer_app_publish", `Publish a new immutable version of a Summer App: dir (a local folder with index.html at its root) or files [{path, content, encoding}] for code apps, layout for layout apps, plus the manifest. Limits: 10 MB, 300 files, 5 MB per file. The person's Studio tab boots it. An error names the file or rule to fix: fix it and publish again.\n\n${CLOUD}`, appPublishArgsSchema.shape, cloud("summer_app_publish", appPublishArgsSchema, appPublish));
@@ -27,7 +34,7 @@ export function registerAppTools(server) {
     server.tool("summer_app_update", `Rename a Summer App, change its purpose or folder, or set its status: kept (the team keeps it), archived (hidden from the app list; restore with scratch or kept), scratch. Archive the scratch apps you made that the person did not keep.\n\n${CLOUD}`, appUpdateArgsSchema.shape, cloud("summer_app_update", appUpdateArgsSchema, appUpdate));
     server.tool("summer_app_events", `Wait for what a Summer App sends you: summer.agent.send events (kind agent), errors in the app (kind error), feedback (kind feedback), agent tool calls (kind tool). Waits up to timeoutSeconds (max ${MAX_APP_EVENTS_WAIT_SECONDS}) for the first event after the cursor; pass the returned cursor as after next time.\n\n${CLOUD}`, appEventsArgsSchema.shape, cloud("summer_app_events", appEventsArgsSchema, appEvents));
     server.tool("summer_app_page", `Read or use the fields and buttons a Summer App declared while it is open in the person's Studio tab or editor dock: no fill and no press reads the page; fill [{field, value}] and press an action id use it. Critical actions (delete, publish, pay, send) are pressed only by the person. app_not_open when the app is not open.\n\n${CLOUD}`, appPageArgsSchema.shape, cloud("summer_app_page", appPageArgsSchema, appPage));
-    server.tool("summer_app_screenshot", `See a Summer App without the person: Summer renders its current version (or version) headless with the person's data and returns the picture plus what to fix: console lines, uncaught errors, refused calls, whether the SDK connected and rendered, and the fields, buttons and agent tools it declared. Read-only: writes, sends and paid calls are refused, nothing changes. width 390 for a phone, theme dark, fullPage for the whole scroll; out also saves the PNG. Use it after every publish.\n\n${CLOUD}`, appScreenshotArgsSchema.shape, async (args) => {
+    server.tool("summer_app_screenshot", `See a Summer App without the person: Summer renders its current version (or version) headless with the person's data and returns the picture plus what to fix: console lines, uncaught errors, refused calls, whether the SDK connected and rendered, and the fields, buttons and agent tools it declared. Read-only: writes, sends and paid calls are refused, nothing changes. width 390 for a phone, theme dark, fullPage for the whole scroll, steps to click or press something first (a dialog, a second state); out also saves the PNG. It waits until the app's calls settle. Use it after every publish.\n\n${CLOUD}`, appScreenshotArgsSchema.shape, async (args) => {
         const parsed = appScreenshotArgsSchema.safeParse(args ?? {});
         if (!parsed.success)
             return result({ ok: false, code: "invalid", error: parsed.error.issues[0]?.message ?? "Invalid arguments" });

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

@@ -4,14 +4,15 @@ import { resolveGatewayUrl } from "../../core/config.js";
 import { getClient } from "../server.js";
 import { ImportHdriError, importPolyHavenHdri, } from "../../core/capabilities/hdri-import.js";
 import { importResolvedAsset } from "../../core/capabilities/asset-import.js";
+import { summerRequestHeaders } from "../../core/agent-host.js";
+import { codedFailure, describeNetworkError, EngineNotRunningError, networkDetails, NOT_SIGNED_IN, SIGN_IN_AGAIN_RECOVERY, } from "../../core/error-codes.js";
+import { engineNotRunningResult } from "./with-engine.js";
+/** No Summer account token: the same failure for every asset tool. */
+const notSignedIn = { error: "not_logged_in", message: NOT_SIGNED_IN, code: "not_signed_in" };
 async function searchAssetsApi(params) {
     const token = await getAuthToken();
-    if (!token) {
-        return {
-            error: "Not logged in",
-            message: "Not signed in. The user needs to run this in their terminal:\n  npx -y summer-engine@latest login\nOr open: https://www.summerengine.com/login\nAsset search requires a Summer Engine account (free to create).",
-        };
-    }
+    if (!token)
+        return { ...notSignedIn };
     const searchParams = new URLSearchParams();
     searchParams.set("query", params.query);
     if (params.assetType && params.assetType !== "all") {
@@ -30,17 +31,24 @@ async function searchAssetsApi(params) {
     if (params.preview)
         searchParams.set("contactSheet", "true");
     const gatewayUrl = await resolveGatewayUrl();
-    const res = await fetch(`${gatewayUrl}/api/mcp/assets?${searchParams}`, {
-        headers: { Authorization: `Bearer ${token}` },
-        signal: AbortSignal.timeout(15000),
-    });
+    let res;
+    try {
+        res = await fetch(`${gatewayUrl}/api/mcp/assets?${searchParams}`, {
+            headers: { ...summerRequestHeaders({ surface: "mcp" }), Authorization: `Bearer ${token}` },
+            signal: AbortSignal.timeout(15000),
+        });
+    }
+    catch (err) {
+        return { error: "network_error", message: `Asset request failed: ${describeNetworkError(err)}`, code: "unavailable", ...networkDetails(err) };
+    }
     const data = (await res.json());
     if (!res.ok) {
         if (res.status === 401) {
             return {
                 error: "unauthorized",
-                message: (data.message || "Auth token expired.") +
-                    " The user needs to re-authenticate:\n  npx -y summer-engine@latest login --force",
+                message: data.message || "Auth token expired.",
+                code: "not_signed_in",
+                recovery: SIGN_IN_AGAIN_RECOVERY,
             };
         }
         if (res.status === 429) {
@@ -59,18 +67,19 @@ async function searchAssetsApi(params) {
 }
 async function authedGetJson(endpoint, timeoutMs = 15_000) {
     const token = await getAuthToken();
-    if (!token) {
-        return {
-            status: 401,
-            error: "not_logged_in",
-            message: "Not signed in. Run in your terminal:\n  npx -y summer-engine@latest login",
-        };
-    }
+    if (!token)
+        return { status: 401, ...notSignedIn };
     const gatewayUrl = await resolveGatewayUrl();
-    const res = await fetch(`${gatewayUrl}${endpoint}`, {
-        headers: { Authorization: `Bearer ${token}` },
-        signal: AbortSignal.timeout(timeoutMs),
-    });
+    let res;
+    try {
+        res = await fetch(`${gatewayUrl}${endpoint}`, {
+            headers: { ...summerRequestHeaders({ surface: "mcp" }), Authorization: `Bearer ${token}` },
+            signal: AbortSignal.timeout(timeoutMs),
+        });
+    }
+    catch (err) {
+        return { status: 0, error: "network_error", message: `Asset request failed: ${describeNetworkError(err)}`, code: "unavailable", ...networkDetails(err) };
+    }
     const data = (await res.json());
     if (!res.ok) {
         return {
@@ -78,6 +87,7 @@ async function authedGetJson(endpoint, timeoutMs = 15_000) {
             data,
             error: data?.error || "request_failed",
             message: data?.message || "Request failed",
+            ...(res.status === 401 ? { code: "not_signed_in", recovery: SIGN_IN_AGAIN_RECOVERY } : {}),
         };
     }
     return { status: res.status, data };
@@ -85,14 +95,14 @@ async function authedGetJson(endpoint, timeoutMs = 15_000) {
 async function getAssetApi(assetId) {
     const result = await authedGetJson(`/api/mcp/assets/${encodeURIComponent(assetId)}`);
     if (result.error) {
-        return { error: result.error, message: result.message };
+        return { error: result.error, message: result.message, code: result.code, recovery: result.recovery, details: result.details };
     }
     return { asset: result.data?.asset };
 }
 async function getAssetDownloadUrlApi(assetId, role) {
     const result = await authedGetJson(`/api/mcp/assets/${encodeURIComponent(assetId)}/download-url?role=${encodeURIComponent(role)}`);
     if (result.error) {
-        return { error: result.error, message: result.message };
+        return { error: result.error, message: result.message, code: result.code, recovery: result.recovery, details: result.details };
     }
     return { data: result.data };
 }
@@ -106,6 +116,14 @@ function jsonSuccess(data) {
         ],
     };
 }
+/** The body of a failed lookup: `{ok:false, code, error, recovery, message}`
+ *  for the shared failures, else the older `{error, message}`. */
+function failureBody(result, fallback) {
+    const message = result.message || fallback.message;
+    return result.code
+        ? codedFailure(result.code, message, { message, ...(result.details ? { details: result.details } : {}) }, result.recovery)
+        : { error: result.error || fallback.error, message };
+}
 function jsonError(data) {
     return {
         content: [
@@ -146,15 +164,7 @@ Requires authentication (so we can attribute usage and apply per-user rate limit
     }, async ({ query, assetType, limit, source, style, preview, includeCommunity }) => {
         const result = await searchAssetsApi({ query, assetType, limit: Math.min(limit, 20), source, style, preview, includeCommunity });
         if (result.error) {
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: JSON.stringify({ error: result.error, message: result.message }, null, 2),
-                    },
-                ],
-                isError: true,
-            };
+            return jsonError(failureBody(result, { error: "Search failed", message: "Asset search failed" }));
         }
         const sheet = result.contactSheet?.match(/^data:(image\/[a-z]+);base64,(.+)$/);
         return {
@@ -200,7 +210,7 @@ Cloud tool — works WITHOUT the Summer Engine app open.`, {
             source: "my_assets",
         });
         if (result.error) {
-            return jsonError({ error: result.error, message: result.message });
+            return jsonError(failureBody(result, { error: "List failed", message: "Listing your assets failed" }));
         }
         return jsonSuccess({
             assets: result.assets,
@@ -220,10 +230,7 @@ Cloud tool — works WITHOUT the Summer Engine app open.`, {
     }, async ({ assetId }) => {
         const result = await getAssetApi(assetId);
         if (result.error || !result.asset) {
-            return jsonError({
-                error: result.error || "asset_not_found",
-                message: result.message || "Asset not found.",
-            });
+            return jsonError(failureBody(result, { error: "asset_not_found", message: "Asset not found." }));
         }
         return jsonSuccess({ asset: result.asset });
     });
@@ -242,7 +249,7 @@ Cloud tool — works WITHOUT the Summer Engine app open.`, {
     }, async ({ assetId, role }) => {
         const result = await getAssetDownloadUrlApi(assetId, role);
         if (result.error) {
-            return jsonError({ error: result.error, message: result.message });
+            return jsonError(failureBody(result, { error: "request_failed", message: "Request failed" }));
         }
         return jsonSuccess(result.data);
     });
@@ -276,10 +283,7 @@ itself does not — only this import step does).`, {
     }, async ({ assetId, path, parent, scenePath, name }) => {
         const fetched = await getAssetApi(assetId);
         if (fetched.error || !fetched.asset) {
-            return jsonError({
-                error: fetched.error || "asset_not_found",
-                message: fetched.message || "Asset not found.",
-            });
+            return jsonError(failureBody(fetched, { error: "asset_not_found", message: "Asset not found." }));
         }
         try {
             const imported = await importResolvedAsset(await getClient(), {
@@ -297,6 +301,8 @@ itself does not — only this import step does).`, {
             });
         }
         catch (err) {
+            if (err instanceof EngineNotRunningError)
+                return engineNotRunningResult(err);
             const msg = err instanceof Error ? err.message : String(err);
             return jsonError({
                 error: "import_failed",
@@ -319,15 +325,7 @@ Requires authentication. If the user gets an auth error, they need to run 'npx -
     }, async ({ query, parent, scenePath, assetType, source }) => {
         const searchResult = await searchAssetsApi({ query, assetType, limit: 5, source });
         if (searchResult.error) {
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: JSON.stringify({ error: searchResult.error, message: searchResult.message }, null, 2),
-                    },
-                ],
-                isError: true,
-            };
+            return jsonError(failureBody(searchResult, { error: "Search failed", message: "Asset search failed" }));
         }
         const assets = searchResult.assets || [];
         if (assets.length === 0) {
@@ -378,6 +376,8 @@ Requires authentication. If the user gets an auth error, they need to run 'npx -
             };
         }
         catch (err) {
+            if (err instanceof EngineNotRunningError)
+                return engineNotRunningResult(err);
             const msg = err instanceof Error ? err.message : String(err);
             return {
                 content: [
@@ -433,6 +433,8 @@ runs through the engine). No Summer login needed.`, {
                     ...(err.hint ? { hint: err.hint } : {}),
                 });
             }
+            if (err instanceof EngineNotRunningError)
+                return engineNotRunningResult(err);
             const msg = err instanceof Error ? err.message : String(err);
             return jsonError({
                 error: "hdri_import_failed",

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

@@ -27,33 +27,33 @@ export function auditContent(result) {
     return { content };
 }
 export function registerAuditTools(server) {
-    server.tool("summer_scene_audit", `Audit a 3D scene in one fast, read-only call: every node and subnode is walked and likely visual and placement problems come back as a short list, sorted by severity, so you know exactly where to look. Each issue is a flag to LOOK at, never an auto-fix.
+    server.tool("summer_scene_audit", `Audit a 3D scene in one fast, read-only call: it walks every node and subnode and lists likely visual and placement problems, sorted by severity. Each issue is a flag to LOOK at, never an auto-fix.
 
-Checks (each can be picked with checks):
-- through_hole: capped ray grids through every facade line (coplanar wall fronts); clusters of rays that pass the wall AND reach the far side of the building (a door insert narrower than its frame, a missing module, a seam). Walls, structure and inserts close an opening; props do not.
-- exposed_edge: open outline edges of walls and facade members (bands, piers, corner blocks; cached per mesh) that nothing covers within 4-7 mm, seen from walkable space (eye points over open-sky floor cells, flood-filled from the scene's cameras and characters, sight lines not through a building), with a 2-60 cm reveal behind them, or a coplanar sheet continuing within 4 cm (seam) or 35 cm (gap). Warn on band pieces and when depth_step agrees, look otherwise; repeats group per piece type.
-- open_fixture_end: open ends of run pieces (a mesh with two or more open rims of one size: pipe, duct or gutter sections, elbows, tees) that nothing joins within 2.5 cm (sleeve tolerance), seen from walkable space: a missing elbow, coupler, section or end piece (warn). A piece with one rim or rims of different sizes (a cap, a funnel, an outlet) is open by design.
-- depth_step (look): ray rows across each visible facade side at its band levels and every 1.25 m: band recesses and missing runs, seams, modules standing proud, holes with something behind them; a hole next to a through_hole confirms it (warn -> error); runs a door-like opening covers are skipped.
-- floor_gap: down rays over the floor tiles, along their seams, and from each tile edge to a wall within 1 m (bare strips at wall bases), classified by the FIRST surface hit: the void (error); an underlay over the floor's own lower surface such as a drain channel ("covers the floor", warn, not a hole); an underlay through a hole or strip. Areas are the missed rays' own footprints with the strip's size; a tile whose own mesh has holes is one issue for the piece.
-- floating / sunken: support under each prop's footprint; gap over 2 cm, embed over 3 cm, measured against the first surface from above (the tile it is buried in, not the underlay under it); structure and pieces touching a wall well off the ground excluded.
-- interpenetration: each prop's convex hulls against props, walls, structure and inserts; a deepest overlap over 3 cm, then every partner it cuts (up to 3).
-- orientation (look): long props within 1.2 m of a wall more than 15 deg off parallel. It never says which way a piece should face.
-- uv_stretch: per mesh resource, large triangles whose UV-to-world mapping is stretched over 8:1 or collapsed to a line, where an instance shows them (a reveal that inserts normally cover = warn).
-- duplicate: the same scene at the same transform.
-- z_fight: coplanar overlapping faces anywhere, from each mesh's planar face groups: between any two pieces (props, roofs, ledges, side walls, inserts against hosts, decals; opposite-facing only when both are double-sided) and between two surfaces of one mesh (once per mesh), plus the ray samples. Coplanar = a gap under twice the 24-bit depth step at the view distance (the nearest walkable eye point, camera or bookmark; 30 m without one) for the main camera's near/far; ev carries the overlap, gap, tolerance, surfaces, the plane's normal and the axis to nudge (nudge.world, nudge.local: a window can share its head or a jamb with its host, not its front). Warn over 0.05 m2 seen from a viewpoint; the material decides what is demoted to look, with the reason: render_priority, depth or normal offsets, a see-through (alpha) material, no depth test or depth writes.
-- lights: meshes paired with more than the per-object limit of omni or spot lights (Compatibility: 8 each; light cuts off at seams), spot lights with spot_angle_attenuation under 3; shadowed light counts.
-- transform: NaN, negative or non-uniform scale, a piece far out of bounds, and pieces left at the origin: an identity LOCAL transform under an identity parent, touching nothing and not one of a row of siblings (several sharing it warn, one alone is look; a module whose corner is the world origin is placed).
-- resource: missing dependency files, MeshInstance3D without a mesh, surfaces without a material.
+Checks (pick with checks; the verifying-scenes skill explains each):
+- through_hole: ray grids through each facade line that pass the wall AND reach the building's far side (an insert narrower than its frame, a missing module). Props do not close an opening.
+- exposed_edge: edges of walls, bands, piers and corner blocks nothing covers within 4-7 mm, seen from walkable space, with a 2-60 cm reveal, a 4 cm seam or a 35 cm gap. Warn on bands or when depth_step agrees, else look.
+- open_fixture_end (warn): open ends of pipe, duct or gutter runs (2+ open rims of one size) nothing joins within 2.5 cm; caps, funnels, outlets are open by design.
+- depth_step (look): ray rows at each facade's band levels and every 1.25 m: recesses, missing runs, seams, proud modules, holes (a hole by a through_hole makes it an error).
+- floor_gap: down rays over tiles, seams and the strip to a wall within 1 m, by FIRST surface hit: the void (error), underlay over the floor's own drain (warn, not a hole), underlay through a hole.
+- floating / sunken: over 2 cm above or 3 cm into the first surface from above; structure and wall-mounted pieces excluded.
+- interpenetration: prop hulls cutting props, walls, structure or inserts over 3 cm, with every partner (up to 3).
+- orientation (look): long props within 1.2 m of a wall over 15 deg off parallel; never says which way to face.
+- uv_stretch: shown triangles with UVs stretched over 8:1 or collapsed.
+- duplicate: same scene, same transform.
+- z_fight: coplanar overlapping faces of two pieces (opposite-facing only if both double-sided) or of one mesh: a gap under twice the 24-bit depth step at the view distance (else 30 m). Warn over 0.05 m2 seen; ev.nudge names the axis to move (world and local). render_priority, depth or normal offsets, alpha, no depth test or writes demote it to look, with the reason.
+- lights: over the per-object omni/spot limit (Compatibility: 8 each), spot_angle_attenuation under 3; shadowed counts.
+- transform: NaN, negative or non-uniform scale, far out of bounds, pieces left at the origin (several = warn, one = look).
+- resource: missing dependencies, a MeshInstance3D without a mesh, surfaces without a material.
 
-budget_ms (default 3000) bounds the editor time: each check gets a weighted share of it, and a check past its share stops and is marked counts.<check>.partial (the share it covered), never clean. The three gap detectors (exposed_edge, open_fixture_end, depth_step) run last on the time the other checks leave (band pieces and band rows first); rerun them alone when partial.
+budget_ms (default 3000) bounds editor time: each check gets a weighted share; one past it stops, marked counts.<check>.partial (the share covered), never clean. exposed_edge, open_fixture_end and depth_step run last on the time left: rerun them alone when partial.
 
-accept:[{key, reason}] (keys from issues[].key) records look and warn items you judged fine in res://.summer/audit-accept.json (the only file the audit writes); later audits count them (counts.<check>.accepted) but hide them until their evidence changes materially (severity rises, or the measured size moves by over 25%: shown again with accept_stale). Errors cannot be accepted; show_accepted lists them.
+accept:[{key, reason}] (issues[].key) records look/warn items you judged fine in res://.summer/audit-accept.json, the only file the audit writes. Later audits count them (counts.<check>.accepted) but hide them until severity rises or the measured size moves over 25% (then accept_stale). Errors cannot be accepted; show_accepted lists them.
 
-Returns at most 5 KB of JSON: counts per check, time per check (editor ms), the scene size, and ONE page of issues {n, check, sev (error|warn|look), path, pos (world), why, ev (evidence numbers: sizes, distances, angles, the ray to reproduce), next (the tool to use next), key (for accept)}. Page with offset/limit (next_offset names the next page); filter with checks, root (a subtree) and min_severity. render:"sheet" adds ONE inline image of the page's first 6 issues framed up close from their open side (a camera never behind a wall), each tile labelled #n.
+Returns at most 5 KB of JSON: counts and editor ms per check, scene size, ONE page of issues {n, check, sev (error|warn|look), path, pos (world), why, ev (evidence numbers, the ray to reproduce), next (the next tool), key}. Page with offset/limit (next_offset); filter with checks, root (subtree), min_severity. render:"sheet" adds ONE image of the page's first 6 issues framed close from their open side, tiles labelled #n.
 
-Every check works on any scene from geometry, the engine's node and resource data and materials alone: never node or file names, never kit metadata. Each piece's role comes from its shape: see-through cards (every material alpha) are dressing; thin upright sheets are walls (facing their side with more face area); flat slabs whose tops cover their footprint are floors (raised ones with walls under them are roofs, a large one below the rest is the underlay); a piece inside a wall's rectangle that reaches through the wall where it is open is an insert; bands, piers and corner blocks touching a facade wall are structure; the rest are props up to 3.5 m.
+Every check works from geometry, node and resource data and materials alone: never node or file names, never kit metadata. Each piece's role (dressing, wall, floor, roof, underlay, insert, structure, a prop up to 3.5 m) comes from its shape.
 
-Read-only: it audits the SAVED file in a private offscreen copy (ScenePreview), so the open tab never becomes unsaved, undo is untouched and nothing is saved (accept writes only its own file). Save the scene first. Failures are structured (failure_reason), never a silent fallback.`, sceneAuditShape, async (args) => withEngine(async (client) => {
+Read-only: audits the SAVED file (save first) in a private offscreen copy (ScenePreview): the open tab never becomes unsaved, undo is untouched, nothing is saved. Failures are structured (failure_reason), never a silent fallback.`, sceneAuditShape, async (args) => withEngine(async (client) => {
         const audit = await sceneAudit(client, args);
         return audit.ok ? { audit } : { audit, failure_reason: audit.failure_reason };
     }, { onResult: (wrapped) => auditContent(wrapped.audit) }));