summer-engine 3.7.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.d.ts

@@ -0,0 +1,2 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerAppTools(server: McpServer): void;

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

@@ -0,0 +1,71 @@
+import { MAX_APP_EVENTS_WAIT_SECONDS, APP_DOCK_FALLBACK, appCall, appCallArgsSchema, appCreate, appCreateArgsSchema, appData, appDataArgsSchema, appDockArgsSchema, appDockOp, appEvents, appEventsArgsSchema, appGet, appGetArgsSchema, appGuide, appGuideArgsSchema, appList, appListArgsSchema, appPage, appPageArgsSchema, appPublish, appPublishArgsSchema, appReportGap, appReportGapArgsSchema, appScreenshot, appScreenshotArgsSchema, appUpdate, appUpdateArgsSchema, appsGateway, appTools, appToolsArgsSchema, } from "../../core/capabilities/apps.js";
+import { enablePluginArgsSchema, enablePluginOp, interpretEnablePluginResult } from "../../core/capabilities/enable-plugin.js";
+import { missingEngineOpResult, withEngine } from "./with-engine.js";
+/**
+ * Summer Apps over MCP: tools a game team uses inside Summer Studio, built by
+ * the agent. Shared implementation: core/capabilities/apps.ts.
+ */
+const CLOUD = "Cloud tool: runs on Summer's servers and works without the Summer Engine app open. Requires sign-in: npx -y summer-engine@latest login.";
+function result(value) {
+    return { content: [{ type: "text", text: JSON.stringify(value, null, 2) }], ...(value.ok === false ? { isError: true } : {}) };
+}
+/** The MCP handler of one cloud tool: validate with the shared schema, call the web API. */
+function cloud(name, schema, run) {
+    return async (args) => {
+        const parsed = schema.safeParse(args ?? {});
+        if (!parsed.success)
+            return result({ ok: false, code: "invalid", error: parsed.error.issues[0]?.message ?? "Invalid arguments" });
+        return result(await run(parsed.data, { request: appsGateway("mcp", name) }));
+    };
+}
+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). 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));
+    server.tool("summer_app_get", `A Summer App's manifest, its current version's files (or layout) and a summary of its shared data. Use it before changing an app.\n\n${CLOUD}`, appGetArgsSchema.shape, cloud("summer_app_get", appGetArgsSchema, appGet));
+    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, 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" });
+        const shot = await appScreenshot(parsed.data, { request: appsGateway("mcp", "summer_app_screenshot") });
+        if (shot.ok !== true || !("image" in shot))
+            return result(shot);
+        const { image, ...report } = shot;
+        return { content: [{ type: "image", data: image.base64, mimeType: image.mimeType }, { type: "text", text: JSON.stringify(report, null, 2) }] };
+    });
+    server.tool("summer_app_data", `Read or write a Summer App's shared data, its API: works with no app open, and everyone in the app sees writes live. Without ops it reads records (paged with after) plus declaredCollections, the record shape the app declares; with ops it writes them in one revision: {op: put|patch|remove, collection, recordId, data|patch, ifRevision?}. Writes show as yours (actor kind agent); as: seed writes starter data for the team (kind seed, no author).\n\n${CLOUD}`, appDataArgsSchema.shape, cloud("summer_app_data", appDataArgsSchema, appData));
+    server.tool("summer_app_tools", `The agent tools (name, description, input JSON Schema) and the data collections (record fields and types) a Summer App declares. Run a tool with summer_app_call; read or write the collections with summer_app_data.\n\n${CLOUD}`, appToolsArgsSchema.shape, cloud("summer_app_tools", appToolsArgsSchema, appTools));
+    server.tool("summer_app_call", `Run one of a Summer App's agent tools inside the person's open app (Studio tab or editor dock) with their rights; waits up to 60 s. app_not_open when the app is not open: use summer_app_data or ask the person to open it. May spend the person's credits when the tool generates.\n\n${CLOUD}`, appCallArgsSchema.shape, cloud("summer_app_call", appCallArgsSchema, appCall));
+    server.tool("summer_app_report_gap", `Tell Summer about an SDK capability a Summer App needed and did not have, so it can be built for everyone.\n\n${CLOUD}`, appReportGapArgsSchema.shape, cloud("summer_app_report_gap", appReportGapArgsSchema, appReportGap));
+    server.tool("summer_app_dock", `Dock a Summer App as a panel in the running Summer Engine editor (left, right or bottom), close its dock, or list docked apps. Docks persist per project. Engine builds without app docks return engine_lacks_op: open the app in the Summer Studio tab instead.`, appDockArgsSchema.shape, async (args) => {
+        const parsed = appDockArgsSchema.safeParse(args ?? {});
+        if (!parsed.success)
+            return result({ ok: false, code: "invalid", error: parsed.error.issues[0]?.message ?? "Invalid arguments" });
+        if (parsed.data.action !== "list" && !parsed.data.appId)
+            return result({ ok: false, code: "invalid", error: `${parsed.data.action} needs appId` });
+        const op = appDockOp(parsed.data);
+        return withEngine(async (client) => {
+            const missing = missingEngineOpResult(client, op.op, APP_DOCK_FALLBACK);
+            if (missing)
+                return missing;
+            return client.executeOps([op]);
+        });
+    });
+    server.tool("summer_enable_plugin", `Enable an editor plugin in the open project (res://addons/<name>/, for example one paired with a Summer App) and report the real result: enabled with the autoloads it registered, or why it failed (code SCRIPT_ERROR, NOT_TOOL, NOT_EDITOR_PLUGIN, CFG_MISSING, TIMEOUT, ...). Older Summer Engine builds only queue the enable; then the result says queued: true and enabled: null, and you check summer_get_debugger_errors before relying on the plugin.`, enablePluginArgsSchema.shape, async (args) => {
+        const parsed = enablePluginArgsSchema.safeParse(args ?? {});
+        if (!parsed.success)
+            return result({ ok: false, code: "invalid", error: parsed.error.issues[0]?.message ?? "Invalid arguments" });
+        return withEngine(async (client) => interpretEnablePluginResult(await client.executeOps([enablePluginOp(parsed.data)])));
+    });
+}

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",