summer-engine 3.8.0 → 4.0.0

package/dist/mcp/server.js

@@ -27,29 +27,49 @@ import { registerNavigationTools } from "./tools/navigation-tools.js";
 import { registerLibraryTools } from "./tools/library-tools.js";
 import { getCachedBootDriftNotice as getCachedNotice, setCachedBootDriftNotice, } from "./boot-notice.js";
 import { appendMcpLogEvent } from "../core/mcp-log.js";
-import { prepareHostedMount } from "./hosted-mount.js";
+import { defaultHostedMountDependencies, prepareHostedMount } from "./hosted-mount.js";
+import { applyOpsSurface, hostedFileTools, OPS_MCP_ASSETS_INSTRUCTIONS, OPS_MCP_INSTRUCTIONS, SUMMER_CALL, SUMMER_SEARCH } from "./ops-surface.js";
+import { FileSaver } from "../core/ops/save-files.js";
+import { opForToolCall } from "../core/ops/contract.js";
+import { v4HostedUrl } from "../core/ops/cloud.js";
 import { serveProviderSafeToolSchemas } from "./provider-safe-schema.js";
+import { legacyHostedDescription, resolveLegacy, takeLegacyToolset } from "./legacy-toolset.js";
+import { OUTPUT_CAPS, PROFILE_TOOL_LIMIT, PROFILES, TOOLSETS, annotationsFor, registryAuthorities, resolveToolSelection, selectionIncludes, withMaxCharactersArg, } from "./tool-surface.js";
+import { shapeToolResult, singleEditCounter } from "./tool-results.js";
+import { recordLocalToolCall, recordMcpSession } from "../core/telemetry.js";
+import { currentToolContext, registerMcpClientSource, runWithToolContext } from "../core/agent-host.js";
 import { buildBootDriftNotice, fetchLatestRegistryVersion, } from "../installer/version-check.js";
 import { TOOLKIT_VERSION as version } from "../core/version.js";
+import { ENGINE_FREE_NOTE, engineNotRunningFromConnectError } from "../core/error-codes.js";
+import { resolveSurface } from "../core/tool-profiles.js";
+import { OAuthError } from "../core/oauth.js";
 let processDiagnosticsInstalled = false;
+const FULL_SELECTION = { profile: "full", toolsets: null, ignored: [] };
 export const getCachedBootDriftNotice = getCachedNotice;
 /**
  * Server `instructions` in the MCP initialize response (SDK ServerOptions,
  * @modelcontextprotocol/sdk >= 1.x). Hosts hand this to the model once per
- * session, before any tool call — the place for the five habits an end-to-end run
- * showed an agent needs on the first
- * turn and would otherwise learn the hard way. Kept under 600 characters so
- * it costs a few hundred tokens once; the full operating guide stays in the
- * summer_agent_playbook prompt / summer_get_agent_playbook tool. The last
- * sentence names the publishing path, the owner-approval rule and where
- * review feedback is read.
+ * session, before any tool call — the place for the habits end-to-end runs
+ * showed an agent needs on the first turn and would otherwise learn the hard
+ * way, including scripting a run of scene edits instead of hundreds of single
+ * calls. Kept under 600 characters so it costs a few hundred tokens once; the
+ * full operating guide stays in the summer_agent_playbook prompt /
+ * summer_get_agent_playbook tool. The last sentence names the publishing path,
+ * the owner-approval rule and where review feedback is read.
  */
-export const SUMMER_MCP_INSTRUCTIONS = "Summer Engine MCP. Call summer_get_project_context first: it binds the open project, returns mainScene, projectMemory, any capabilitySkewWarning. " +
-    "Before building or fixing, summer_search_library then summer_read_library the hit. " +
-    "After play, read summer_get_diagnostics, not summer_get_console alone. " +
-    "An all-black screenshot means no redraw yet: recapture. " +
+export const SUMMER_MCP_INSTRUCTIONS = "Summer Engine MCP. Call summer_get_project_context first: it binds the open project. " +
+    "Before building or fixing: summer_search_library, then summer_read_library the hit. " +
+    "More than 3 scene edits: one summer_run_script (snapshot, script, diff, screenshot). " +
+    "After play: summer_get_diagnostics, not only summer_get_console. " +
+    "All-black screenshot: no redraw yet, recapture. " +
     "Report verified entries via summer_library_feedback. " +
-    "Publishing: summer_export_game, summer_publish_build, summer_store_*; agents never publish alone: summer_store_submit returns the owner's approval link; summer_store_review, feedback to fix.";
+    "Publish: summer_export_game, summer_publish_build, summer_store_*; never alone: summer_store_submit returns the owner's approval link, summer_store_review the feedback.";
+/** The same first-turn habits for a profile without engine tools (`--profile assets`). */
+export const SUMMER_MCP_ASSETS_INSTRUCTIONS = "Summer MCP, assets profile: generation and the Summer asset library, no engine tools. " +
+    "Read skill/summer-assets, then the asset's skill (sound-effect, prop-model, ...): stop at the file, skip its engine steps. " +
+    "Generation costs credits: confirm first. A job returns a jobId: summer_check_job. " +
+    "Hand over files with summer_get_asset_download_url. " +
+    "Report verified entries via summer_library_feedback.";
 /**
  * Fire-and-forget probe of the npm registry on MCP boot. Caches the result for
  * the session. We never await this in startup so a slow / offline registry
@@ -103,26 +123,20 @@ export async function getClient() {
         const reason = error instanceof Error
             ? error.message
             : "Summer Engine is not running.";
+        // Nothing reachable: a coded error withEngine renders as JSON
+        // (engine_not_running). Anything else (several editors open, …) already
+        // says how to pick one.
+        const notRunning = engineNotRunningFromConnectError(reason);
+        if (notRunning)
+            throw notRunning;
         throw new Error(reason + "\n" +
-            "Open the intended project in Summer Engine, or run: npx -y summer-engine@latest run\n" +
-            "Note: only tools that touch the local project need the engine. Cloud tools " +
-            "(summer_generate_*, summer_search_assets, summer_list_my_assets, summer_get_asset, " +
-            "summer_check_job) work right now without it — they only need 'npx -y summer-engine@latest login'.");
+            "Open the intended project in Summer Engine, or run: npx -y summer-engine@latest run <project-path>\n" +
+            "Note: " + ENGINE_FREE_NOTE);
     }
 }
 export function resetClient() {
     cachedClient = null;
 }
-/**
- * Passive result-size observability. Monkey-patches server.tool() so every
- * registered handler's serialized text payload is measured and logged to
- * stderr in the existing `[summer-mcp]` JSON shape. The result itself is
- * never modified — external coding agents (Claude Code, Cursor, Codex)
- * manage their own context budgets, and silently truncating their tool
- * results is the wrong shape (see #102 revert). If a specific tool turns
- * out to produce pathological payloads in practice, the right fix is
- * adding range/depth/filter parameters to that tool — not a blanket cap.
- */
 function errorDetails(error) {
     if (error instanceof Error) {
         return {
@@ -170,74 +184,115 @@ function installMcpProcessDiagnostics() {
         appendMcpLogEvent("mcp:exit", { pid: process.pid, code });
     });
 }
-function installResultSizeLogger(server) {
-    const original = server.tool.bind(server);
+/** Index of the zod raw shape among server.tool()'s middle arguments, or -1. */
+function rawShapeIndex(args) {
+    for (let index = 1; index < args.length - 1; index++) {
+        const candidate = args[index];
+        if (!candidate || typeof candidate !== "object" || "_def" in candidate)
+            continue;
+        const values = Object.values(candidate);
+        if (values.length > 0 && values.every((value) => !!value && typeof value === "object" && "_def" in value))
+            return index;
+    }
+    return -1;
+}
+function installToolCallWrapper(server, surfaceMeta) {
+    const target = server;
+    const original = target.tool.bind(server);
+    const singleEdits = singleEditCounter();
+    const hostApp = () => server.server.getClientVersion()?.name;
     let registeredToolCount = 0;
-    server.tool = function patchedTool(...args) {
-        if (args.length < 2)
-            return original(...args);
-        const name = args[0];
+    target.tool = function patchedTool(...registration) {
+        if (registration.length < 2)
+            return original(...registration);
+        const name = registration[0];
         if (typeof name !== "string")
-            return original(...args);
-        const lastIdx = args.length - 1;
-        const handler = args[lastIdx];
+            return original(...registration);
+        const lastIdx = registration.length - 1;
+        const handler = registration[lastIdx];
         if (typeof handler !== "function")
-            return original(...args);
+            return original(...registration);
         registeredToolCount += 1;
+        const args = [...registration];
+        const cap = OUTPUT_CAPS.get(name);
+        const shapeAt = cap === undefined ? -1 : rawShapeIndex(args);
+        if (shapeAt > 0)
+            args[shapeAt] = withMaxCharactersArg(name, args[shapeAt]);
         // Schema-less tools receive only the SDK's `extra` — never record that as
         // the tool's arguments (see registrationHasInputSchema).
         const hasInputSchema = registrationHasInputSchema(args);
-        const wrapped = async (...handlerArgs) => {
+        args[lastIdx] = async (...handlerArgs) => {
+            let maxCharacters = cap;
+            if (shapeAt > 0 && handlerArgs[0] && typeof handlerArgs[0] === "object") {
+                const { maxCharacters: requested, ...rest } = handlerArgs[0];
+                if (typeof requested === "number")
+                    maxCharacters = requested;
+                handlerArgs = [rest, ...handlerArgs.slice(1)];
+            }
             const startedAt = Date.now();
+            // A tool another tool runs (summer_call, a v4 operation over its 3.x
+            // tool) is part of that call: only the outer call sends a usage line.
+            const nested = currentToolContext() !== undefined;
+            const recordUsage = (ok, durationMs) => {
+                if (!nested)
+                    recordLocalToolCall({ tool: name, op: opForToolCall(name, handlerArgs[0]), ...surfaceMeta, ok, durationMs, mcpClient: hostApp() });
+            };
             let result;
             try {
-                result = await handler(...handlerArgs);
+                // Every Summer request the tool makes names it (core/agent-host.ts).
+                result = await runWithToolContext(name, "mcp", () => handler(...handlerArgs));
             }
             catch (error) {
                 // A handler THROW never produced a result to classify; record it as
                 // ok:false / exception so the stream does not silently skip failures,
                 // then let the SDK turn it into the protocol error it always did.
+                const durationMs = Date.now() - startedAt;
                 recordToolCall({
                     tool: name,
                     args: trajectoryArgsFor(hasInputSchema, handlerArgs),
                     exception: error instanceof Error ? error.message : String(error),
-                    durationMs: Date.now() - startedAt,
+                    durationMs,
                 });
+                recordUsage(false, durationMs);
                 throw error;
             }
             const durationMs = Date.now() - startedAt;
+            const record = result && typeof result === "object" ? result : null;
+            const isError = record?.isError === true;
+            // withEngine stamps failure classifiers + retried + bound hash on a
+            // non-enumerable symbol so we can log them here without every tool
+            // threading its own name through withEngine.
+            const meta = record ? record[WITH_ENGINE_META] : undefined;
             try {
+                const hint = singleEdits(name, isError);
+                result = shapeToolResult(result, { maxCharacters, hint });
+            }
+            catch {
+                // Shaping must never break the tool call; the raw result goes out.
+            }
+            try {
+                recordMcpSession();
+                recordUsage(!isError, durationMs);
                 // Opt-in local trajectory capture: one JSONL line per tool call when
                 // SUMMER_TRAJECTORY_DIR is set. recordToolCall never throws and is a
                 // no-op when the env var is unset.
-                {
-                    const record = result;
-                    const callMeta = record && typeof record === "object"
-                        ? record[WITH_ENGINE_META]
-                        : undefined;
-                    recordToolCall({
-                        tool: name,
-                        args: trajectoryArgsFor(hasInputSchema, handlerArgs),
-                        isError: record?.isError === true,
-                        terminalState: callMeta?.terminalState,
-                        errorClass: callMeta?.errorClass,
-                        failureReason: callMeta?.failureReason,
-                        durationMs,
-                        // Read only under SUMMER_TRAJECTORY_EVAL=1 (bounded summary); the
-                        // default redacted stream ignores it.
-                        result,
-                    });
-                }
+                recordToolCall({
+                    tool: name,
+                    args: trajectoryArgsFor(hasInputSchema, handlerArgs),
+                    isError,
+                    terminalState: meta?.terminalState,
+                    errorClass: meta?.errorClass,
+                    failureReason: meta?.failureReason,
+                    durationMs,
+                    // Read only under SUMMER_TRAJECTORY_EVAL=1 (bounded summary); the
+                    // default redacted stream ignores it.
+                    result,
+                });
                 if (result &&
                     typeof result === "object" &&
                     "content" in result &&
                     Array.isArray(result.content)) {
                     const debug = process.env.SUMMER_MCP_DEBUG === "1";
-                    const isError = result.isError === true;
-                    // withEngine stamps failure classifiers + retried + bound hash on a
-                    // non-enumerable symbol so we can log them here without every tool
-                    // threading its own name through withEngine.
-                    const meta = result[WITH_ENGINE_META];
                     // Structured per-call line. Verbose behind SUMMER_MCP_DEBUG=1; when the
                     // flag is off, log ONLY failures — the success path stays quiet.
                     if (debug || isError) {
@@ -258,17 +313,11 @@ function installResultSizeLogger(server) {
                         process.stderr.write(`[summer-mcp] ${callLine}\n`);
                     }
                     if (debug) {
-                        let chars = 0;
-                        for (const entry of result
-                            .content) {
-                            if (entry && entry.type === "text" && typeof entry.text === "string") {
-                                chars += entry.text.length;
-                            }
-                        }
-                        const bytes = Buffer.byteLength(result.content
+                        const texts = result.content
                             .filter((e) => e && e.type === "text" && typeof e.text === "string")
-                            .map((e) => e.text)
-                            .join(""), "utf8");
+                            .map((e) => e.text);
+                        const chars = texts.reduce((sum, text) => sum + text.length, 0);
+                        const bytes = Buffer.byteLength(texts.join(""), "utf8");
                         const line = JSON.stringify({
                             event: "mcp:result_size",
                             tool_name: name,
@@ -289,31 +338,44 @@ function installResultSizeLogger(server) {
             }
             return result;
         };
-        const newArgs = [...args];
-        newArgs[lastIdx] = wrapped;
-        return original(...newArgs);
+        return original(...args);
     };
     return () => registeredToolCount;
 }
 /**
- * Build the MCP server with every Summer tool registered, without connecting
- * a transport. startMcpServer() uses this; tests use it to count the live
- * tool surface against registry/generated/counts.json.
+ * Build the MCP server with every Summer tool of the selected profile
+ * registered, without connecting a transport. startMcpServer() uses this;
+ * tests use it to count the live tool surface against
+ * registry/generated/counts.json. Without a selection: the full profile.
  */
-export function createMcpServer() {
+export { resolveSurface };
+const NO_CLOUD = {
+    call: async () => {
+        throw new OAuthError("store_login_required", "The hosted Summer server is not connected.", 'Recovery: run "summer login".');
+    },
+};
+export function createMcpServer(selection = FULL_SELECTION, options = {}) {
+    const surface = options.surface ?? "v3";
+    // A profile without engine tools (assets) gets the no-engine instructions,
+    // playbook and task plan, so nothing points the agent at a tool it lacks.
+    const engine = !selection.toolsets || selection.toolsets.has("engine");
     const server = new McpServer({
         name: "summer-engine",
         version,
-    }, { instructions: SUMMER_MCP_INSTRUCTIONS });
-    // Passive observability: log result-size to stderr but do not modify
-    // results. See installResultSizeLogger above.
-    const getRegisteredToolCount = installResultSizeLogger(server);
+    }, {
+        instructions: surface === "v4"
+            ? engine ? OPS_MCP_INSTRUCTIONS : OPS_MCP_ASSETS_INSTRUCTIONS
+            : engine ? SUMMER_MCP_INSTRUCTIONS : SUMMER_MCP_ASSETS_INSTRUCTIONS,
+    });
+    const getWrappedToolCount = installToolCallWrapper(server, { surfaceVersion: surface, profile: selection.profile });
+    // Requests to Summer's servers name the agent app from the initialize handshake.
+    registerMcpClientSource(() => server.server.getClientVersion());
     registerSceneTools(server);
     registerDebugTools(server);
     registerVisualTools(server);
     registerSeeingTools(server);
     registerAuditTools(server);
-    registerProjectTools(server);
+    registerProjectTools(server, { engine });
     registerFileTools(server);
     registerAssetTools(server);
     registerGenerateTools(server);
@@ -332,10 +394,37 @@ export function createMcpServer() {
     registerAppTools(server);
     // The playbook is also an MCP prompt so prompt-surfacing hosts get it
     // natively (same content as the summer_get_agent_playbook tool).
-    registerPlaybookPrompt(server);
+    registerPlaybookPrompt(server, { engine });
     // Strict providers (Kimi, OpenAI strict) reject tuple and $ref schemas.
     serveProviderSafeToolSchemas(server);
-    return { server, getRegisteredToolCount };
+    // Effect hints from each tool's registry authority, then the profile:
+    // tools outside it are removed before any client lists them.
+    const registered = server._registeredTools;
+    const authorities = registryAuthorities();
+    let removed = 0;
+    for (const [name, tool] of Object.entries(registered)) {
+        if (!selectionIncludes(selection, name, true)) {
+            tool.remove();
+            removed += 1;
+            continue;
+        }
+        const authority = authorities.get(name);
+        if (authority)
+            tool.update({ annotations: annotationsFor(name, authority) });
+    }
+    // Without engine tools nothing imports a file into a project, so files save into it by default.
+    const files = new FileSaver({ saveByDefault: !engine });
+    if (surface === "v4")
+        applyOpsSurface(server, { engine, cloud: options.cloud ?? NO_CLOUD, legacy: options.legacy === true, files });
+    return { server, getRegisteredToolCount: () => getWrappedToolCount() - removed, files };
+}
+/** What the hosted tools a profile mounts are, for summer_store_tools. */
+function hostedToolsLabel(toolsets) {
+    if (toolsets.has("ship"))
+        return "Summer store and publishing tools";
+    if (toolsets.has("tools"))
+        return "Tool Factory tools (summer_tool_*) and asset editing tools";
+    return undefined;
 }
 export async function startMcpServer(options = {}) {
     configureMcpEngineSelection({
@@ -355,7 +444,22 @@ export async function startMcpServer(options = {}) {
             cwd: options.cwd ?? process.cwd(),
         },
     });
-    const { server, getRegisteredToolCount } = createMcpServer();
+    const surface = resolveSurface(options.surface);
+    // `legacy` is not a toolset of its own: it lists the 3.x names on the v4 surface.
+    const toolsetList = takeLegacyToolset(options.toolsets ?? process.env.SUMMER_TOOLSETS);
+    const legacy = surface === "v4" ? resolveLegacy(toolsetList.requested) : { on: false, reason: "off" };
+    const selection = resolveToolSelection({ profile: options.profile, toolsets: toolsetList.toolsets });
+    if (selection.ignored.length > 0) {
+        writeMcpStderr("mcp:unknown_toolsets", {
+            ignored: selection.ignored,
+            profiles: Object.keys(PROFILES),
+            toolsets: TOOLSETS,
+        });
+    }
+    // v4 runs cloud operations through the hosted mount below, once it exists.
+    let hostedCall = null;
+    const cloud = { call: (name, args) => (hostedCall ? hostedCall(name, args) : NO_CLOUD.call(name, args)) };
+    const { server, getRegisteredToolCount, files } = createMcpServer(selection, { surface, cloud, legacy: legacy.on });
     // Fire-and-forget — never block tool registration on the npm registry.
     void probeBootDrift().catch((error) => {
         setCachedBootDriftNotice(null);
@@ -364,13 +468,54 @@ export async function startMcpServer(options = {}) {
     // Hosted Summer Engine MCP tools (store, publishing, board, Grow): ready
     // before connect, mounted after it. The first tools/list waits a few
     // seconds for the mount (not under summer doctor, which times the list).
-    const hosted = prepareHostedMount(server, undefined, process.env.SUMMER_MCP_DOCTOR === "1" ? { firstListWaitMs: 0 } : {});
+    // A profile mounts only its hosted toolsets, and never more tools in total
+    // than PROFILE_TOOL_LIMIT.
+    // v4 mounts the hosted v4 surface (its direct tools for this profile;
+    // summer_search and summer_call stay local and forward to it).
+    // The legacy toolset (below) mounts after this mount, and again after a retry of it.
+    let legacyHosted = null;
+    const hosted = prepareHostedMount(server, surface === "v4" ? { ...defaultHostedMountDependencies, url: v4HostedUrl(selection.profile) } : undefined, {
+        ...(process.env.SUMMER_MCP_DOCTOR === "1" ? { firstListWaitMs: 0 } : {}),
+        onMounted: () => void legacyHosted?.mount(),
+        ...(surface === "v4"
+            ? { includeTool: (name) => name !== SUMMER_SEARCH && name !== SUMMER_CALL, maxTools: PROFILE_TOOL_LIMIT, local: hostedFileTools(files) }
+            : selection.toolsets === null
+                ? {}
+                : {
+                    includeTool: (name) => selectionIncludes(selection, name, false),
+                    maxTools: PROFILE_TOOL_LIMIT,
+                    hostedToolsLabel: hostedToolsLabel(selection.toolsets),
+                }),
+    });
+    hostedCall = hosted.call;
+    // The legacy toolset also lists the hosted 3.x names this profile listed in
+    // 3.x, from the hosted 3.x surface, each running its 3.x tool, under the
+    // same limit as in 3.x. Its sign-in waits for the v4 mount's (a token
+    // refresh is not shared), so it starts at boot and the first tools/list
+    // still waits for it.
+    legacyHosted = legacy.on
+        ? prepareHostedMount(server, {
+            ...defaultHostedMountDependencies,
+            token: async () => {
+                await hosted.mount();
+                return defaultHostedMountDependencies.token();
+            },
+        }, {
+            ...(process.env.SUMMER_MCP_DOCTOR === "1" ? { firstListWaitMs: 0 } : {}),
+            ...(selection.toolsets === null ? {} : { includeTool: (name) => selectionIncludes(selection, name, false), maxTools: PROFILE_TOOL_LIMIT }),
+            describe: legacyHostedDescription,
+        })
+        : null;
     const transport = new StdioServerTransport();
     await server.connect(transport);
     void hosted.mount();
+    void legacyHosted?.mount();
     appendMcpLogEvent("mcp:ready", {
         version,
         pid: process.pid,
+        profile: selection.profile,
+        surface,
+        ...(surface === "v4" ? { legacy: legacy.reason } : {}),
         toolCount: getRegisteredToolCount(),
     });
     process.stderr.write(`[summer-mcp] MCP server running v${version}.\n`);

package/dist/mcp/tool-results.d.ts

@@ -0,0 +1,26 @@
+type Content = {
+    type?: string;
+    text?: unknown;
+};
+/** Pretty-printed JSON text as compact JSON; anything else unchanged. */
+export declare function compactJsonText(text: string): string;
+/** Cut text blocks to maxCharacters in total, with one note saying how to get the rest. */
+export declare function capText(content: Content[], maxCharacters: number): Content[];
+/**
+ * The text an agent gets: compact JSON, cut at maxCharacters when the tool
+ * is capped, plus an optional hint line. Images and error flags are kept.
+ */
+export declare function shapeToolResult(result: unknown, options: {
+    maxCharacters?: number;
+    hint?: string | null;
+}): unknown;
+/** The first single edit in a row that gets the hint, and how often it repeats after that. */
+export declare const SINGLE_EDIT_HINT_AT = 4;
+/**
+ * Counts successful single scene edits since the last batched edit
+ * (summer_run_script, summer_batch, summer_run_editor_script). Reads in
+ * between do not break the run. Returns the hint on the 4th edit in a row,
+ * then every 6th.
+ */
+export declare function singleEditCounter(): (tool: string, isError: boolean) => string | null;
+export {};

package/dist/mcp/tool-results.js

@@ -0,0 +1,81 @@
+import { BATCH_EDIT_TOOLS, SINGLE_EDIT_TOOLS } from "./tool-surface.js";
+/** Pretty-printed JSON text as compact JSON; anything else unchanged. */
+export function compactJsonText(text) {
+    const first = text[0];
+    if ((first !== "{" && first !== "[") || !text.includes("\n"))
+        return text;
+    try {
+        return JSON.stringify(JSON.parse(text));
+    }
+    catch {
+        return text;
+    }
+}
+/** The library read's last line (the feedback footer) survives a cut. */
+const KEEP_LAST_LINE = /\n(— entry_id: [^\n]*)\s*$/;
+/** Cut text blocks to maxCharacters in total, with one note saying how to get the rest. */
+export function capText(content, maxCharacters) {
+    const total = content.reduce((sum, part) => sum + (part.type === "text" && typeof part.text === "string" ? part.text.length : 0), 0);
+    if (total <= maxCharacters)
+        return content;
+    const note = `\n\n[Truncated: ${maxCharacters} of ${total} characters shown. Call again with maxCharacters: ${total} for all of it, or narrow the request.]`;
+    let budget = maxCharacters;
+    let cut = false;
+    const out = [];
+    for (const part of content) {
+        if (part.type !== "text" || typeof part.text !== "string") {
+            out.push(part);
+            continue;
+        }
+        if (cut)
+            continue;
+        if (part.text.length <= budget) {
+            budget -= part.text.length;
+            out.push(part);
+            continue;
+        }
+        const footer = part.text.match(KEEP_LAST_LINE)?.[1];
+        out.push({ ...part, text: part.text.slice(0, budget) + note + (footer ? `\n\n${footer}` : "") });
+        cut = true;
+    }
+    return out;
+}
+/**
+ * The text an agent gets: compact JSON, cut at maxCharacters when the tool
+ * is capped, plus an optional hint line. Images and error flags are kept.
+ */
+export function shapeToolResult(result, options) {
+    if (!result || typeof result !== "object" || !Array.isArray(result.content))
+        return result;
+    const original = result;
+    let content = original.content.map((part) => part && part.type === "text" && typeof part.text === "string" ? { ...part, text: compactJsonText(part.text) } : part);
+    if (options.maxCharacters !== undefined)
+        content = capText(content, options.maxCharacters);
+    if (options.hint)
+        content = [...content, { type: "text", text: options.hint }];
+    return { ...original, content };
+}
+/** The first single edit in a row that gets the hint, and how often it repeats after that. */
+export const SINGLE_EDIT_HINT_AT = 4;
+const SINGLE_EDIT_HINT_EVERY = 6;
+/**
+ * Counts successful single scene edits since the last batched edit
+ * (summer_run_script, summer_batch, summer_run_editor_script). Reads in
+ * between do not break the run. Returns the hint on the 4th edit in a row,
+ * then every 6th.
+ */
+export function singleEditCounter() {
+    let run = 0;
+    return (tool, isError) => {
+        if (BATCH_EDIT_TOOLS.has(tool)) {
+            run = 0;
+            return null;
+        }
+        if (isError || !SINGLE_EDIT_TOOLS.has(tool))
+            return null;
+        run += 1;
+        if (run < SINGLE_EDIT_HINT_AT || (run - SINGLE_EDIT_HINT_AT) % SINGLE_EDIT_HINT_EVERY !== 0)
+            return null;
+        return `Tip: ${run} single scene edits in a row. More than 3 edits: write one summer_run_script instead (snapshot, script, diff, screenshot).`;
+    };
+}

package/dist/mcp/tool-surface.d.ts

@@ -0,0 +1,65 @@
+import type { ToolAnnotations } from "@modelcontextprotocol/sdk/types.js";
+import { type ZodTypeAny } from "zod";
+import { type Profile, type Toolset } 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, type Toolset, type Profile } from "../core/tool-profiles.js";
+/** The toolset a tool belongs to: local tools by the table above, hosted ones by name. */
+export declare function toolsetOf(name: string, local: boolean): Toolset;
+export interface ToolSelection {
+    /** "custom" = toolsets given without a profile. */
+    profile: Profile | "custom";
+    /** null = every toolset (the full profile). */
+    toolsets: ReadonlySet<Toolset> | null;
+    /** Unknown names given in flags or env, for one warning line. */
+    ignored: string[];
+}
+/**
+ * `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 declare function resolveToolSelection(options?: {
+    profile?: string;
+    toolsets?: string;
+}, env?: NodeJS.ProcessEnv): ToolSelection;
+/** True when the selection keeps this tool. */
+export declare function selectionIncludes(selection: ToolSelection, name: string, local: boolean): boolean;
+/** Every name the refinement sets mention (a test checks each is a real tool). */
+export declare const ANNOTATION_REFINEMENTS: ReadonlySet<string>;
+export type Authority = Partial<Record<"filesystem" | "editor_mutation" | "network" | "credentials" | "publish", boolean>>;
+/** MCP annotations for one local tool from its registry authority. */
+export declare function annotationsFor(name: string, authority: Authority): ToolAnnotations;
+/** Registry authority per MCP tool name (registry/generated/index.json). */
+export declare function registryAuthorities(): Map<string, Authority>;
+/** Default text cap for tools whose results can be large. */
+export declare const DEFAULT_MAX_CHARACTERS = 4000;
+/**
+ * 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 declare const OUTPUT_CAPS: ReadonlyMap<string, number>;
+/**
+ * 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 declare function withMaxCharactersArg<T extends Record<string, ZodTypeAny>>(name: string, shape: T): T;
+/** One-change scene tools; a run of them is one summer_run_script. */
+export declare const SINGLE_EDIT_TOOLS: ReadonlySet<string>;
+/** Calls that already batch edits; they end a run of single edits. */
+export declare const BATCH_EDIT_TOOLS: ReadonlySet<string>;