summer-engine 3.8.0 → 4.0.0

package/dist/installer/version-check.js

@@ -18,6 +18,8 @@ import { join, sep } from "node:path";
 import { PACKAGE_ROOT } from "../core/package-root.js";
 import { configureAgentMcp, parseAgent, SUMMER_MCP_SERVER_NAME, topLevelKey, } from "./agent-config.js";
 const NPM_REGISTRY_LATEST_URL = "https://registry.npmjs.org/summer-engine/latest";
+const NPM_REGISTRY_DIST_TAGS_URL = "https://registry.npmjs.org/-/package/summer-engine/dist-tags";
+const NPM_REGISTRY_PACKAGE_URL = "https://registry.npmjs.org/summer-engine";
 const REGISTRY_FETCH_TIMEOUT_MS = 3000;
 export function parseSemver(version) {
     if (!version)
@@ -69,8 +71,8 @@ export function classifyDrift(installed, target) {
     }
     return { severity: "warning", reason: "minor-drift" };
 }
-export async function fetchLatestRegistryVersion(options = {}) {
-    const url = options.url ?? NPM_REGISTRY_LATEST_URL;
+async function fetchRegistryJson(defaultUrl, options) {
+    const url = options.url ?? defaultUrl;
     const timeoutMs = options.timeoutMs ?? REGISTRY_FETCH_TIMEOUT_MS;
     const fetchImpl = options.fetchImpl ?? globalThis.fetch;
     if (!fetchImpl) {
@@ -88,15 +90,7 @@ export async function fetchLatestRegistryVersion(options = {}) {
                 message: `registry responded ${response.status}`,
             };
         }
-        const body = (await response.json());
-        if (typeof body.version !== "string") {
-            return {
-                ok: false,
-                reason: "registry-unreachable",
-                message: "registry payload missing version",
-            };
-        }
-        return { ok: true, version: body.version };
+        return { ok: true, body: await response.json() };
     }
     catch (error) {
         return {
@@ -106,6 +100,43 @@ export async function fetchLatestRegistryVersion(options = {}) {
         };
     }
 }
+export async function fetchLatestRegistryVersion(options = {}) {
+    const result = await fetchRegistryJson(NPM_REGISTRY_LATEST_URL, options);
+    if (!result.ok)
+        return result;
+    const body = result.body;
+    if (typeof body?.version !== "string") {
+        return {
+            ok: false,
+            reason: "registry-unreachable",
+            message: "registry payload missing version",
+        };
+    }
+    return { ok: true, version: body.version };
+}
+export async function fetchRegistryDistTags(options = {}) {
+    const result = await fetchRegistryJson(NPM_REGISTRY_DIST_TAGS_URL, options);
+    if (!result.ok)
+        return result;
+    const body = result.body;
+    const tags = {};
+    for (const [tag, value] of Object.entries(body ?? {})) {
+        if (typeof value === "string")
+            tags[tag] = value;
+    }
+    if (!tags.latest) {
+        return { ok: false, reason: "registry-unreachable", message: "registry payload missing latest" };
+    }
+    return { ok: true, tags };
+}
+/** Whether npm has this exact version: true, false (registry says 404), or
+ *  null when the registry could not be asked. */
+export async function isRegistryVersionPublished(version, options = {}) {
+    const result = await fetchRegistryJson(`${NPM_REGISTRY_PACKAGE_URL}/${encodeURIComponent(version)}`, options);
+    if (result.ok)
+        return true;
+    return result.message === "registry responded 404" ? false : null;
+}
 const RECOMMENDED_REFRESH_COMMAND = "npx clear-npx-cache && npx -y summer-engine@latest setup <agent> --yes --force";
 export function buildCliVersionCheck(input) {
     if (!input.registry.ok) {
@@ -212,28 +243,51 @@ export function defaultSkillMarkerCandidates() {
     }
     return candidates;
 }
-/** The npm dist-tag a refresh command should name. A CLI that is AHEAD of
- *  npm `latest` was installed from `next` (a soaking release); telling that
- *  user to run `summer-engine@latest` would silently downgrade the MCP server
- *  while leaving the newer skills in place (release review P1-3). */
-export function refreshChannel(installedVersion, latestVersion) {
+/** The npm spec a refresh command or a new MCP entry should name, so the agent
+ *  never runs an older release than this CLI (release review P1-3). `latest`
+ *  unless this CLI is AHEAD of npm latest; then `next` only when the next
+ *  dist-tag is this exact version, else this exact version. A CLI that is ahead
+ *  is not always on `next`: `next` stayed on 3.1.0 while latest moved to 3.8.0,
+ *  and pinning it dropped every option newer than 3.1.0 (SUMMER_PROFILE). */
+export function refreshChannel(installedVersion, latestVersion, nextVersion) {
     const installed = parseSemver(installedVersion);
     const latest = latestVersion ? parseSemver(latestVersion) : null;
     if (!installed || !latest)
         return "latest";
-    return classifyDrift(installed, latest).reason === "ahead" ? "next" : "latest";
+    if (classifyDrift(installed, latest).reason !== "ahead")
+        return "latest";
+    return nextVersion?.trim() === installedVersion.trim() ? "next" : installedVersion.trim();
 }
 /** Default `summer setup` channel when neither --channel nor SUMMER_CHANNEL is
- *  given: `next` while this CLI is ahead of npm latest, else `latest`. Network
- *  failure means `latest` (never blocks setup). */
-export async function resolveDefaultChannel(installedVersion) {
-    const registry = await fetchLatestRegistryVersion();
+ *  given: `latest`, unless this CLI is ahead of npm latest. Then `next` when
+ *  next is this exact version, this exact version when npm has it, and
+ *  otherwise (a checkout that was never published) `latest` with a note that
+ *  points at --local-dev. Network failure means `latest` (never blocks setup). */
+export async function resolveDefaultChannel(installedVersion, deps = {}) {
+    const registry = await (deps.fetchDistTags ?? fetchRegistryDistTags)();
     if (!registry.ok)
         return { channel: "latest" };
-    const channel = refreshChannel(installedVersion, registry.version);
-    return channel === "next"
-        ? { channel, note: `This CLI (${installedVersion}) is ahead of npm latest (${registry.version}); the MCP entry is pinned to summer-engine@next so the agent keeps running this release. Pass --channel latest to override.` }
-        : { channel };
+    const latest = registry.tags.latest;
+    const channel = refreshChannel(installedVersion, latest, registry.tags.next);
+    if (channel === "latest")
+        return { channel };
+    if (channel === "next") {
+        return {
+            channel,
+            note: `This CLI (${installedVersion}) is the npm next release, ahead of latest (${latest}); the MCP entry runs summer-engine@next. Pass --channel latest to override.`,
+        };
+    }
+    const published = await (deps.isPublished ?? isRegistryVersionPublished)(installedVersion);
+    if (published) {
+        return {
+            channel,
+            note: `This CLI (${installedVersion}) is ahead of npm latest (${latest}); the MCP entry is pinned to summer-engine@${installedVersion} so the agent runs this release. Pass --channel latest to override.`,
+        };
+    }
+    return {
+        channel: "latest",
+        note: `This CLI (${installedVersion}) is not on npm, so the MCP entry runs summer-engine@latest (${latest}), which can lack options this CLI has. To run this build, pass --local-dev.`,
+    };
 }
 export async function buildSkillsVersionCheck(input) {
     const cliParsed = parseSemver(input.installedCliVersion);
@@ -306,7 +360,7 @@ export async function buildSkillsVersionCheck(input) {
             ...baseDetails,
             drift: worst.drift.reason,
             ...(install ? { install } : {}),
-            recommendedAction: skillsRefreshCommand(worst.agent, install, refreshChannel(input.installedCliVersion, input.latestRegistryVersion)),
+            recommendedAction: skillsRefreshCommand(worst.agent, install, refreshChannel(input.installedCliVersion, input.latestRegistryVersion, input.nextRegistryVersion)),
         },
     };
 }
@@ -330,8 +384,7 @@ export function skillsRefreshCommand(agent, install, channel = "latest") {
     if (install?.localDev && install.cliPath) {
         return `node ${install.cliPath} setup ${agent} --local-dev --yes --force`;
     }
-    const tag = channel === "next" ? "next" : "latest";
-    return `npx clear-npx-cache && npx -y summer-engine@${tag} setup ${agent} --yes --force${channel === "next" ? " --channel next" : ""}`;
+    return `npx clear-npx-cache && npx -y summer-engine@${channel} setup ${agent} --yes --force${channel === "latest" ? "" : ` --channel ${channel}`}`;
 }
 /** The shape `summer setup --local-dev` writes: `node <…>/dist/bin/summer.js mcp`
  *  (createSummerMcpServerConfig(true)). */

package/dist/mcp/command.js

@@ -1,14 +1,21 @@
 import { Command, Option } from "commander";
 import { configureAgentMcp, parseAgent, parseScope, supportedAgents, } from "../installer/agent-config.js";
 import { startMcpServer } from "./server.js";
+import { TOOLSETS } from "./tool-surface.js";
 export const mcpCommand = new Command("mcp")
     .description("Start the MCP server for AI tool integration (Cursor, Claude Code, etc.)")
     .option("--project <path>", "Bind local engine tools to the editor running this project")
     .option("--instance <id>", "Bind local engine tools to one exact Summer editor instance")
+    .option("--profile <profile>", "Tool profile: full (every tool, the default), engine (engine, generation and the store; under 128 tools), assets (generation and the asset library, no engine). Env: SUMMER_PROFILE")
+    .option("--toolsets <list>", `Comma-separated toolsets to add (alone: core plus these): ${TOOLSETS.join(", ")}, or all. Env: SUMMER_TOOLSETS`)
+    .option("--surface <surface>", "Tool surface: v4 (the default: engine tools, summer_search and summer_call for the operation catalog) or v3 (the 3.x tools). Env: SUMMER_SURFACE")
     .action(async (opts) => {
     await startMcpServer({
         projectPath: opts.project,
         instanceId: opts.instance,
+        profile: opts.profile,
+        toolsets: opts.toolsets,
+        surface: opts.surface,
     });
 });
 // Deprecated alias. `summer setup <agent>` (src/cli/commands/setup.ts) is the

package/dist/mcp/hosted-mount.d.ts

@@ -1,4 +1,5 @@
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { type Tool } from "@modelcontextprotocol/sdk/types.js";
 import { type HostedClient, type HostedConnectDependencies } from "../core/hosted-mcp.js";
 export type { HostedClient };
 /**
@@ -30,6 +31,8 @@ export interface HostedMountState {
     resources: string[];
     /** Hosted names the local MCP already defines (kept local). */
     collisions: string[];
+    /** Hosted tools left out because the server's tool limit was reached. */
+    overLimit: string[];
     error?: {
         code: string;
         message: string;
@@ -42,9 +45,31 @@ export interface HostedMountState {
  * reports each mounted tool's own JSON Schema rather than the passthrough one.
  * Returns mount(), which callers run after connect without awaiting it.
  */
-export declare function prepareHostedMount(server: McpServer, deps?: HostedMountDependencies, options?: {
+/** Fields and handling this package adds around a hosted tool (the v4 surface saves generated files here). */
+export interface HostedLocalHook {
+    /** The input schema a client lists for the tool. */
+    inputSchema(tool: Tool): Tool["inputSchema"];
+    /** Runs the call; `forward` sends arguments on to the hosted tool, `tool` is its listing (annotations included). */
+    call(name: string, args: Record<string, unknown>, forward: (args: Record<string, unknown>) => Promise<Record<string, unknown>>, tool: Tool): Promise<Record<string, unknown>>;
+}
+export interface HostedMountOptions {
     firstListWaitMs?: number;
-}): {
+    /** The profile's filter: false leaves a hosted tool out. Default: every tool. */
+    includeTool?: (name: string) => boolean;
+    /** Mount no tool once the server has this many. Default: no limit. */
+    maxTools?: number;
+    /** The description a mounted tool gets here. Default: the hosted one. */
+    describe?: (tool: Tool) => string;
+    /** Runs after each successful mount (another mount can follow it). */
+    onMounted?: () => void;
+    /** What summer_store_tools calls the hosted tools this profile mounts.
+     *  Default: the full profile's store, publishing, board and Grow tools. */
+    hostedToolsLabel?: string;
+    /** Local fields and handling around each mounted tool. Default: none. */
+    local?: HostedLocalHook;
+}
+export declare function prepareHostedMount(server: McpServer, deps?: HostedMountDependencies, options?: HostedMountOptions): {
     mount: () => Promise<HostedMountState>;
     state: HostedMountState;
+    call: (name: string, args: Record<string, unknown>) => Promise<Record<string, unknown>>;
 };

package/dist/mcp/hosted-mount.js

@@ -1,6 +1,6 @@
 import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
 import { z } from "zod";
-import { connectHostedMcp } from "../core/hosted-mcp.js";
+import { connectHostedMcp, hostedConnectFailure, HostedUnreachableError, withV3Surface } from "../core/hosted-mcp.js";
 import { getStoreAccessToken, OAuthError, resolveMcpResourceUrl } from "../core/oauth.js";
 import { appendMcpLogEvent } from "../core/mcp-log.js";
 import { providerSafeSchema } from "./provider-safe-schema.js";
@@ -26,7 +26,7 @@ export const STORE_TOOLS_STATUS = "summer_store_tools";
 export const FIRST_LIST_WAIT_MS = 5_000;
 const passthroughArgs = z.object({}).passthrough();
 export const defaultHostedMountDependencies = {
-    url: () => resolveMcpResourceUrl(),
+    url: () => withV3Surface(resolveMcpResourceUrl()),
     token: () => getStoreAccessToken(),
     connect: connectHostedMcp,
 };
@@ -45,16 +45,10 @@ async function listAll(page, key) {
 function errorText(error) {
     return { content: [{ type: "text", text: JSON.stringify({ ok: false, ...error }) }], isError: true };
 }
-/**
- * Get the server ready for hosted tools before the transport connects (the
- * SDK fixes capabilities at connect): resource handlers exist, and tools/list
- * reports each mounted tool's own JSON Schema rather than the passthrough one.
- * Returns mount(), which callers run after connect without awaiting it.
- */
 export function prepareHostedMount(server, deps = defaultHostedMountDependencies, options = {}) {
     const firstListWaitMs = options.firstListWaitMs ?? FIRST_LIST_WAIT_MS;
     let listed = false;
-    const state = { status: "idle", tools: [], prompts: [], resources: [], collisions: [] };
+    const state = { status: "idle", tools: [], prompts: [], resources: [], collisions: [], overLimit: [] };
     const schemas = new Map();
     const registries = server;
     // Declare the resources capability now: registering one and removing it
@@ -74,7 +68,7 @@ export function prepareHostedMount(server, deps = defaultHostedMountDependencies
                 ...result,
                 tools: result.tools.map((tool) => {
                     const hosted = schemas.get(tool.name);
-                    return hosted ? { ...tool, inputSchema: providerSafeSchema(hosted.inputSchema), ...(hosted.annotations ? { annotations: hosted.annotations } : {}), ...(hosted.title ? { title: hosted.title } : {}) } : tool;
+                    return hosted ? { ...tool, inputSchema: providerSafeSchema(options.local ? options.local.inputSchema(hosted) : hosted.inputSchema), ...(hosted.annotations ? { annotations: hosted.annotations } : {}), ...(hosted.title ? { title: hosted.title } : {}) } : tool;
                 }),
             };
         });
@@ -93,6 +87,8 @@ export function prepareHostedMount(server, deps = defaultHostedMountDependencies
     }
     let statusTool = null;
     let running = null;
+    let connected = null;
+    const listedToolCount = () => Object.values(registries._registeredTools).filter((tool) => tool.enabled !== false).length;
     /** Wait for a mount in progress, at most ms; returns at once when none runs. */
     async function waitForMount(ms) {
         if (!running || ms <= 0)
@@ -105,8 +101,12 @@ export function prepareHostedMount(server, deps = defaultHostedMountDependencies
         if (statusTool || STORE_TOOLS_STATUS in registries._registeredTools)
             return;
         statusTool = server.registerTool(STORE_TOOLS_STATUS, {
-            description: "The Summer store, publishing, board and Grow tools come from the hosted Summer Engine MCP and are not loaded. Call this to see why and how to fix it (usually: run \"summer login --store\" in a terminal); it loads them when the sign-in works.",
+            title: "Load the hosted Summer tools",
+            description: `The ${options.hostedToolsLabel ?? "Summer store, publishing, board and Grow tools"} come from the hosted Summer Engine MCP and are not loaded. Call this to see why and how to fix it (usually: run "summer login --store" in a terminal); it loads them when the sign-in works.`,
             inputSchema: passthroughArgs,
+            // Registered after the server's annotation pass, so it carries its own:
+            // it asks Summer's servers which tools this sign-in may use and changes nothing.
+            annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
         }, async () => {
             const after = await mount();
             if (after.status === "mounted") {
@@ -124,14 +124,12 @@ export function prepareHostedMount(server, deps = defaultHostedMountDependencies
         }
         catch (error) {
             state.status = "unavailable";
-            state.error =
-                error instanceof OAuthError
-                    ? { code: error.code, message: error.message.replace(` ${error.recovery}`, ""), recovery: error.recovery }
-                    : {
-                        code: "store_tools_unreachable",
-                        message: `The hosted Summer Engine MCP did not answer: ${error instanceof Error ? error.message : String(error)}.`,
-                        recovery: 'Recovery: check the network; if it says unauthorized, run "summer login --store --force". Then call summer_store_tools.',
-                    };
+            const failure = hostedConnectFailure(error, 'Recovery: check the network; if it says unauthorized, run "summer login --store --force". Then call summer_store_tools.');
+            state.error = {
+                code: failure instanceof OAuthError ? failure.code : "store_tools_unreachable",
+                message: failure.message.replace(` ${failure.recovery}`, ""),
+                recovery: failure.recovery,
+            };
             appendMcpLogEvent("mcp:hosted_mount_failed", { code: state.error.code });
             showStatusTool();
             return state;
@@ -149,10 +147,19 @@ export function prepareHostedMount(server, deps = defaultHostedMountDependencies
             }
             if (schemas.has(tool.name))
                 continue;
+            if (options.includeTool && !options.includeTool(tool.name))
+                continue;
+            // The limit is on what a client lists: tools a surface keeps unlisted (v4) do not count.
+            if (options.maxTools !== undefined && listedToolCount() >= options.maxTools) {
+                if (!state.overLimit.includes(tool.name))
+                    state.overLimit.push(tool.name);
+                continue;
+            }
             schemas.set(tool.name, tool);
-            server.registerTool(tool.name, { description: tool.description ?? "", inputSchema: passthroughArgs, ...(tool.annotations ? { annotations: tool.annotations } : {}) }, async (args) => {
+            server.registerTool(tool.name, { description: options.describe ? options.describe(tool) : (tool.description ?? ""), inputSchema: passthroughArgs, ...(tool.annotations ? { annotations: tool.annotations } : {}) }, async (args) => {
                 try {
-                    return (await client.callTool({ name: tool.name, arguments: args }));
+                    const forward = (sent) => client.callTool({ name: tool.name, arguments: sent });
+                    return (options.local ? await options.local.call(tool.name, args, forward, tool) : await forward(args));
                 }
                 catch (error) {
                     return errorText({
@@ -185,9 +192,17 @@ export function prepareHostedMount(server, deps = defaultHostedMountDependencies
         }
         statusTool?.remove();
         statusTool = null;
+        connected = client;
         state.status = "mounted";
         delete state.error;
-        appendMcpLogEvent("mcp:hosted_mounted", { tools: state.tools.length, prompts: state.prompts.length, resources: state.resources.length, collisions: state.collisions.length });
+        options.onMounted?.();
+        appendMcpLogEvent("mcp:hosted_mounted", {
+            tools: state.tools.length,
+            prompts: state.prompts.length,
+            resources: state.resources.length,
+            collisions: state.collisions.length,
+            ...(state.overLimit.length ? { overLimit: state.overLimit } : {}),
+        });
         return state;
     }
     /** Mount once; a failed mount runs again on the next call. */
@@ -209,5 +224,20 @@ export function prepareHostedMount(server, deps = defaultHostedMountDependencies
         }
         return running;
     }
-    return { mount, state };
+    /**
+     * Call a hosted tool whether or not it is listed here (the v4 surface's
+     * summer_search and summer_call stay local and forward through this).
+     */
+    async function call(name, args) {
+        const after = await mount();
+        if (!connected) {
+            const error = after.error ?? { code: "store_tools_unavailable", message: "The hosted Summer server is not connected.", recovery: 'Recovery: run "summer login".' };
+            // Nothing was sent. A sign-in failure keeps its OAuth code; anything else is the server not answering.
+            if (error.code === "store_tools_unreachable" || error.code === "store_tools_unavailable")
+                throw new HostedUnreachableError(error.message, error.recovery);
+            throw new OAuthError(error.code, error.message, error.recovery);
+        }
+        return connected.callTool({ name, arguments: args });
+    }
+    return { mount, state, call };
 }

package/dist/mcp/legacy-toolset.d.ts

@@ -0,0 +1,27 @@
+import type { Tool } from "@modelcontextprotocol/sdk/types.js";
+import { type SkillMarkerCandidate } from "../installer/version-check.js";
+/**
+ * The legacy toolset of the v4 surface (SPEC §8.1, §12.3): every 3.x tool
+ * name listed again, each running as it did in 3.x, each description
+ * starting "3.x name; use <op>." It keeps skills written for 3.x working.
+ *
+ * On when the toolsets name `legacy` (`--toolsets legacy`,
+ * SUMMER_TOOLSETS=legacy), or SUMMER_LEGACY_TOOLS=on, or, unless
+ * SUMMER_LEGACY_TOOLS=off, while the Summer skills installed on this
+ * computer are older than 4.0 (their .summer-version marker).
+ */
+export declare const LEGACY_TOOLSET = "legacy";
+/** `--toolsets` without `legacy`, and whether it was there. */
+export declare function takeLegacyToolset(list: string | undefined): {
+    toolsets: string | undefined;
+    requested: boolean;
+};
+/** True when any installed Summer skills carry a marker older than 4.0. */
+export declare function installedSkillsBefore4(candidates?: SkillMarkerCandidate[]): boolean;
+export type LegacyReason = "toolsets" | "env" | "skills" | "off";
+export declare function resolveLegacy(requested: boolean, env?: NodeJS.ProcessEnv, skillsBefore4?: () => boolean): {
+    on: boolean;
+    reason: LegacyReason;
+};
+/** A hosted 3.x tool's description in the legacy toolset: its operation, then its first sentence. */
+export declare function legacyHostedDescription(tool: Pick<Tool, "name" | "description">): string;

package/dist/mcp/legacy-toolset.js

@@ -0,0 +1,43 @@
+import { resolveOpName } from "../core/ops/contract.js";
+import { defaultSkillMarkerCandidates, readSkillMarker } from "../installer/version-check.js";
+/**
+ * The legacy toolset of the v4 surface (SPEC §8.1, §12.3): every 3.x tool
+ * name listed again, each running as it did in 3.x, each description
+ * starting "3.x name; use <op>." It keeps skills written for 3.x working.
+ *
+ * On when the toolsets name `legacy` (`--toolsets legacy`,
+ * SUMMER_TOOLSETS=legacy), or SUMMER_LEGACY_TOOLS=on, or, unless
+ * SUMMER_LEGACY_TOOLS=off, while the Summer skills installed on this
+ * computer are older than 4.0 (their .summer-version marker).
+ */
+export const LEGACY_TOOLSET = "legacy";
+/** `--toolsets` without `legacy`, and whether it was there. */
+export function takeLegacyToolset(list) {
+    if (list === undefined)
+        return { toolsets: undefined, requested: false };
+    const parts = list.split(",").map((part) => part.trim());
+    const rest = parts.filter((part) => part.toLowerCase() !== LEGACY_TOOLSET);
+    return { toolsets: rest.filter(Boolean).join(","), requested: rest.length !== parts.length };
+}
+/** True when any installed Summer skills carry a marker older than 4.0. */
+export function installedSkillsBefore4(candidates = defaultSkillMarkerCandidates()) {
+    return candidates.some((candidate) => {
+        const major = Number.parseInt(readSkillMarker(candidate.dir)?.version.split(".")[0] ?? "", 10);
+        return Number.isFinite(major) && major < 4;
+    });
+}
+export function resolveLegacy(requested, env = process.env, skillsBefore4 = installedSkillsBefore4) {
+    if (requested)
+        return { on: true, reason: "toolsets" };
+    const forced = (env.SUMMER_LEGACY_TOOLS ?? "").trim().toLowerCase();
+    if (forced === "on")
+        return { on: true, reason: "env" };
+    if (forced === "off")
+        return { on: false, reason: "off" };
+    return skillsBefore4() ? { on: true, reason: "skills" } : { on: false, reason: "off" };
+}
+/** A hosted 3.x tool's description in the legacy toolset: its operation, then its first sentence. */
+export function legacyHostedDescription(tool) {
+    const first = (tool.description ?? "").split(/(?<=\.)\s/)[0]?.slice(0, 200) ?? "";
+    return `3.x name; use ${resolveOpName(tool.name)}. ${first}`.trim();
+}

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

@@ -0,0 +1,59 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { type ToolAnnotations } from "@modelcontextprotocol/sdk/types.js";
+import { type FileSaver } from "../core/ops/save-files.js";
+import type { HostedLocalHook } from "./hosted-mount.js";
+/**
+ * The v4 surface of the local MCP (`summer mcp --surface v4`, SUMMER_SURFACE=v4):
+ * one catalog of Summer operations instead of one tool per feature.
+ *
+ * - Listed: the engine operations under their 3.x names (the core build loop
+ *   keeps its tools) plus the operations split out of mixed 3.x tools,
+ *   docs.search and docs.read, the hosted server's direct tools (mounted from
+ *   its v4 surface), summer_search and summer_call.
+ * - An engine tool here is its operation: a short summary (the how-to is its
+ *   guide, docs.read tool/<slug>), annotations from its effect, and the one
+ *   answer shape, with engine_not_running and the other codes instead of
+ *   plain text.
+ * - Every other local 3.x tool stays registered but unlisted: summer_call
+ *   runs it by its operation name or its old name, through the same handler.
+ *   The legacy toolset lists them again under their 3.x names.
+ * - Cloud operations run on the hosted server: summer_call forwards them to
+ *   the hosted summer_call with the person's sign-in; summer_search merges
+ *   the hosted hits with the local ones.
+ */
+export declare const SUMMER_SEARCH = "summer_search";
+export declare const SUMMER_CALL = "summer_call";
+export declare const OPS_MCP_INSTRUCTIONS: string;
+/** The assets profile's version: no engine tools, so it names none. */
+export declare const OPS_MCP_ASSETS_INSTRUCTIONS: string;
+/** Runs a tool on the hosted server's v4 surface (hosted-mount.ts). */
+export interface CloudCaller {
+    call(name: string, args: Record<string, unknown>): Promise<Record<string, unknown>>;
+}
+export interface OpsSurfaceOptions {
+    /** Keep the engine operations listed (profiles with engine tools). */
+    engine: boolean;
+    cloud: CloudCaller;
+    /** The legacy toolset: list every local 3.x name too, each running as it did in 3.x. */
+    legacy?: boolean;
+    /** Saves generated files on this machine (`out`, localPath); shared with the mounted hosted tools. */
+    files: FileSaver;
+}
+/** Its v4 description, within the 300-character summary rule; the full text stays on the 3.x surface. */
+export declare const ENGINE_REFERENCE_SUMMARY = "Look up an engine class offline before writing script code: inherits, properties, methods, signals and constants, or one member. Lists only members declared on that class (walk inherits). No engine needed. Next: summer_run_script.";
+/** The read footer in this surface's words: feedback goes through summer_call (docs.feedback is not listed). */
+export declare const V4_FOOTER_SUFFIX = "If this entry is wrong, stale, or you deviate from it, report via summer_call {\"op\":\"docs.feedback\"}.";
+/** MCP annotations from an operation's effect (SPEC §4.1); engine operations never need a retry key. */
+export declare function annotationsForEffect(effect: "read" | "write", openWorld: boolean, title: string): ToolAnnotations;
+/** A parameter description cut to its whole sentences within PARAM_LIMIT characters; the guide has it whole. */
+export declare function shortParamDescription(text: string): string;
+export declare function v4Text(text: string): string;
+export declare function applyOpsSurface(server: McpServer, options: OpsSurfaceOptions): void;
+/**
+ * The hosted direct tools on the v4 surface. Those that take `out`
+ * (summer_assets_generate_image, summer_assets_get, summer_jobs_wait, ...)
+ * show it in their listed input, and a call keeps it here and saves the files
+ * the answer names. A call that throws answers in the one shape too
+ * (hostedCallFailure), never with a plain "retry".
+ */
+export declare function hostedFileTools(files: FileSaver): HostedLocalHook;