summer-engine 3.8.0 → 4.2.0

package/dist/core/ops/search.js

@@ -0,0 +1,187 @@
+import { stem } from "../registry-search.js";
+/**
+ * Plain-words ranking over operations. cloud.ts ranks the local rows, the
+ * shipped cloud catalog and the server's live rows together here, so a query
+ * ranks the same signed in or out.
+ *
+ * - A query word scores by the best place it meets a row: the action (the
+ *   name after the dot) 7, the area or the title 4, a short tag 3, a 3.x name
+ *   2, the summary or a long use-when line 1. An exact word counts whole, a
+ *   stemmed one 0.9, a prefix half, a plain-English synonym (SYNONYMS) 0.7.
+ * - Rare words weigh more (idf over the rows searched) and everyday verbs
+ *   half: in "publish my game" publish decides, in "add multiplayer"
+ *   multiplayer does.
+ * - A row that meets every word in its name, title or short tags keeps its
+ *   score; one that meets none of them there keeps half. One whose whole
+ *   action the query names gains a quarter: "publish" is store.publish
+ *   before store.cancel_publish.
+ * - A title or tag the query says nearly word for word, articles aside
+ *   ("how is my game doing" for "how did my game do"), adds 2 per word.
+ */
+const STOP = new Set([
+    "a", "an", "the", "my", "of", "for", "to", "in", "on", "and", "or", "with", "is", "it", "me", "i", "please", "how", "do", "what",
+    "did", "does", "doing", "done", "am", "are", "was", "were", "be", "have", "has", "had", "can", "could", "would", "should", "will",
+    "want", "need", "this", "that", "these", "those", "some", "any", "many", "much", "why", "where", "when", "which", "there", "you",
+    "your", "we", "our", "us", "at", "by", "from", "as", "so", "just", "s",
+]);
+/** Verbs that say what to do but rarely which operation: the object does. */
+const EVERYDAY_VERBS = new Set(["add", "make", "create", "set", "get", "change", "update", "edit", "run", "start", "put", "take", "show", "read", "list", "use", "give", "check", "find", "see", "turn", "open"]);
+/** Left out of phrase matching: "put my game on sale" says "Put a game on sale". */
+const ARTICLES = new Set(["a", "an", "the", "my", "your", "our", "their", "its", "this", "that"]);
+/** Irregular forms, so "how did my game do" meets "how is my game doing". */
+const IRREGULAR = { did: "do", does: "do", doing: "do", done: "do", is: "be", are: "be", was: "be", were: "be", am: "be", has: "have", had: "have" };
+/** Plain English to the catalog's words (stemmed keys). */
+const SYNONYMS = {
+    make: ["generate", "create"],
+    create: ["generate", "make"],
+    picture: ["image"],
+    drawing: ["image"],
+    photo: ["image"],
+    model: ["3d"],
+    mesh: ["3d"],
+    sound: ["audio"],
+    music: ["audio"],
+    song: ["audio"],
+    clip: ["video"],
+    movie: ["video"],
+    film: ["video"],
+    animate: ["motion"],
+    animation: ["motion"],
+    run: ["play", "start"],
+    cost: ["price"],
+    teammate: ["member"],
+    character: ["model"],
+    game: ["store"],
+    error: ["diagnostic"],
+    bug: ["error", "diagnostic"],
+};
+const norm = (word) => IRREGULAR[word] ?? stem(word);
+const tokens = (text) => text
+    .toLowerCase()
+    .replace(/\ba\/b\b/g, "ab")
+    .split(/[^a-z0-9]+/)
+    .filter(Boolean)
+    .map((raw) => ({ raw, normed: norm(raw) }));
+export function words(text) {
+    return tokens(text)
+        .filter(({ raw }) => raw.length > 1 && !STOP.has(raw))
+        .map(({ raw }) => raw);
+}
+const indexCache = new WeakMap();
+function indexed(entry) {
+    const cached = indexCache.get(entry);
+    if (cached)
+        return cached;
+    const [area, action] = entry.name.includes(".") ? entry.name.split(".") : ["", entry.name];
+    const kept = (text) => tokens(text).filter(({ raw }) => raw.length > 1 && !STOP.has(raw));
+    const tags = entry.tags ?? [];
+    // A tag of a few words is a keyword; a long one (a use-when line) reads like the summary.
+    const short = (tag) => tokens(tag).length <= 3;
+    const fields = [
+        { weight: 7, words: kept(action.replace(/_/g, " ")) },
+        { weight: 4, words: kept(area) },
+        { weight: 4, words: kept(entry.title) },
+        { weight: 3, words: [...tags.filter(short), ...(entry.topics ?? [])].flatMap(kept) },
+        { weight: 2, words: (entry.legacy ?? []).flatMap((name) => kept(name.replace(/^summer_/, "").replace(/[#_]/g, " "))) },
+        { weight: 1, words: [entry.summary, ...tags.filter((tag) => !short(tag))].flatMap(kept) },
+    ];
+    const phrases = [entry.title, ...tags].map((text) => tokens(text).filter(({ raw }) => !ARTICLES.has(raw))).filter((phrase) => phrase.length >= 2);
+    const result = { fields, phrases, action: kept(action.replace(/_/g, " ")), area: kept(area) };
+    indexCache.set(entry, result);
+    return result;
+}
+/** How well one query word meets one row word: exact 1, same stem 0.9, a prefix 0.5 ("anim" in animation; not "play" in players). */
+function meets(term, word) {
+    if (word.raw === term.raw)
+        return 1;
+    if (word.normed === term.normed)
+        return 0.9;
+    const [a, b] = [term.normed, word.normed];
+    return (a.length >= 4 && b.startsWith(a)) || (b.length >= 5 && a.startsWith(b)) ? 0.5 : 0;
+}
+const alternatesOf = (term) => (SYNONYMS[term.normed] ?? []).map((synonym) => ({ raw: synonym, normed: norm(synonym) }));
+/** A query word's best weight in a row, and whether it met a strong field (weight 3 or more). */
+function best(term, entry, synonyms = true) {
+    const alternates = synonyms ? alternatesOf(term) : [];
+    let score = 0;
+    let strong = false;
+    for (const field of indexed(entry).fields) {
+        for (const word of field.words) {
+            const quality = Math.max(meets(term, word), ...alternates.map((alternate) => 0.7 * meets(alternate, word)));
+            if (quality === 0)
+                continue;
+            score = Math.max(score, field.weight * quality);
+            if (field.weight >= 3)
+                strong = true;
+        }
+    }
+    return { score, strong };
+}
+/** The best title or tag the query says nearly word for word: 2 per word met. */
+function phraseBonus(entry, all) {
+    const query = all.filter(({ raw }) => !ARTICLES.has(raw));
+    let bonus = 0;
+    for (const phrase of indexed(entry).phrases) {
+        const met = phrase.map((word) => Math.max(0, ...query.map((term) => (term.raw === word.raw ? 1 : term.normed === word.normed ? 0.9 : alternatesOf(term).some((alternate) => alternate.normed === word.normed) ? 0.7 : 0))));
+        const count = met.filter((quality) => quality > 0).length;
+        const meaningful = phrase.some((word, index) => met[index] > 0 && !STOP.has(word.raw));
+        if (meaningful && count >= 2 && count / phrase.length >= 0.75)
+            bonus = Math.max(bonus, 2 * met.reduce((sum, quality) => sum + quality, 0));
+    }
+    return bonus;
+}
+/**
+ * The query names the row's whole action, and its area too when the action
+ * is only an everyday verb: "list my games" names games.list, "run my game"
+ * does not name engine.is_running.
+ */
+function namesAction(entry, terms) {
+    const { action, area } = indexed(entry);
+    const met = (word) => terms.some((term) => meets(term, word) >= 0.9);
+    return action.length > 0 && action.every(met) && (action.some((word) => !EVERYDAY_VERBS.has(word.normed)) || area.some(met));
+}
+function scoreAll(entries, query) {
+    const exact = query.trim().toLowerCase();
+    const all = tokens(query);
+    const terms = all.filter(({ raw }) => raw.length > 1 && !STOP.has(raw));
+    if (!terms.length)
+        return entries.map(() => 0);
+    // Rarer words weigh more: idf over the rows searched; everyday verbs count half.
+    const weightOf = terms.map((term) => {
+        const df = entries.filter((entry) => best(term, entry, false).score > 0).length;
+        return Math.log(1 + entries.length / (1 + df)) * (EVERYDAY_VERBS.has(term.normed) ? 0.5 : 1);
+    });
+    return entries.map((entry) => {
+        if (exact === entry.name || entry.legacy?.some((name) => name.split("#")[0] === exact))
+            return 1000;
+        let total = 0;
+        let strong = 0;
+        let missed = false;
+        terms.forEach((term, index) => {
+            const hit = best(term, entry);
+            total += weightOf[index] * hit.score;
+            if (hit.strong)
+                strong += 1;
+            if (hit.score === 0)
+                missed = true;
+        });
+        if (total === 0)
+            return 0;
+        return total * (0.5 + (0.5 * strong) / terms.length) * (!missed && namesAction(entry, terms) ? 1.25 : 1) + phraseBonus(entry, all);
+    });
+}
+const STATUS_RANK = { stable: 0, preview: 1, deprecated: 2 };
+export function searchEntries(entries, query, filters) {
+    const hasTerms = words(query).length > 0;
+    const kept = entries
+        .filter((entry) => entry.status !== "deprecated")
+        .filter((entry) => !filters.area || entry.name === filters.area || entry.name.startsWith(`${filters.area}.`))
+        .filter((entry) => !filters.effect || entry.effect === filters.effect);
+    const scores = scoreAll(kept, query);
+    return kept
+        .map((entry, index) => ({ entry, score: scores[index] }))
+        .filter(({ score }) => score > 0 || !hasTerms)
+        .sort((a, b) => b.score - a.score || STATUS_RANK[a.entry.status] - STATUS_RANK[b.entry.status] || Number(b.entry.available) - Number(a.entry.available) || a.entry.name.localeCompare(b.entry.name))
+        .slice(0, filters.limit)
+        .map(({ entry }) => entry);
+}

package/dist/core/skills-registry.d.ts

@@ -25,6 +25,10 @@ export interface SkillRegistryEntry {
     path: string;
     /** facets.domains from resource.yaml; the first is the primary domain. Empty on old registries. */
     domains: string[];
+    /** Bulk installs and the plugin manifests take it. false = library only
+     *  (library-author tools, research digests): readable with
+     *  summer_read_library and installable by name. Absent reads as true. */
+    bundled?: boolean;
 }
 /**
  * Load the generated skill registry (cached after first read).
@@ -34,18 +38,29 @@ export interface SkillRegistryEntry {
 export declare function getSkillRegistry(): readonly SkillRegistryEntry[];
 /** Shape-tolerant parse of skills-registry.json. Exported for unit tests. */
 export declare function parseSkillRegistry(json: unknown): SkillRegistryEntry[];
+/**
+ * The assets-only install (`summer setup --assets-only`, `skills install
+ * --assets`): skills that make sounds, music, voices, images, models,
+ * animation and video on Summer's servers, plus `summer-assets`, the session
+ * skill for that profile. Each says what to do without Summer Engine. The
+ * engine session skill `using-summer` and skills that wire assets into a
+ * running engine stay out.
+ */
+export declare function isAssetSkill(skill: Pick<SkillRegistryEntry, "name" | "domains">): boolean;
 /**
  * The one bulk-install rule (`skills install --all/--recommended` and
  * `summer setup` both use it): `stable` and `preview` skills install —
  * preview is a label ("not yet exercised in-engine by the Summer team"),
  * carried in each skill's own guidance, not a reason to hide contributed work;
- * `deprecated` never installs in bulk. `stableOnly` opts out of preview.
+ * `deprecated` never installs in bulk, and neither does a library-only skill
+ * (`bundled: false`). `stableOnly` opts out of preview.
  * The counts let the caller say how many preview skills it installed (or, with
  * stableOnly, left out) instead of printing a bare total.
  */
 export declare function selectSkillsForBulkInstall(skills: readonly SkillRegistryEntry[], options: {
     recommended?: boolean;
     stableOnly?: boolean;
+    assetsOnly?: boolean;
 }): {
     selected: SkillRegistryEntry[];
     previewIncluded: number;

package/dist/core/skills-registry.js

@@ -78,19 +78,52 @@ export function parseSkillRegistry(json) {
         status: s.status === "preview" || s.status === "deprecated" ? s.status : "stable",
         path: s.path,
         domains: Array.isArray(s.domains) ? s.domains.filter((d) => typeof d === "string") : [],
+        bundled: s.bundled !== false,
     }));
 }
+/** Skills that handle assets but need more than the assets profile: they wire
+ *  assets into a scene, or (store-art) make art for a Summer Games listing. */
+const NOT_ASSETS_ONLY_SKILLS = new Set([
+    "instantiate-asset-pack",
+    "use-widget-asset",
+    "skintokens-auto-rigging",
+    "fabricating-assets",
+    "lumera-single-image-scene-reconstruction",
+    "store-art",
+]);
+/**
+ * The assets-only install (`summer setup --assets-only`, `skills install
+ * --assets`): skills that make sounds, music, voices, images, models,
+ * animation and video on Summer's servers, plus `summer-assets`, the session
+ * skill for that profile. Each says what to do without Summer Engine. The
+ * engine session skill `using-summer` and skills that wire assets into a
+ * running engine stay out.
+ */
+export function isAssetSkill(skill) {
+    if (skill.name === "generate-motion")
+        return true;
+    if (NOT_ASSETS_ONLY_SKILLS.has(skill.name))
+        return false;
+    const domains = skill.domains ?? [];
+    return domains.includes("assets") || domains.includes("generate");
+}
 /**
  * The one bulk-install rule (`skills install --all/--recommended` and
  * `summer setup` both use it): `stable` and `preview` skills install —
  * preview is a label ("not yet exercised in-engine by the Summer team"),
  * carried in each skill's own guidance, not a reason to hide contributed work;
- * `deprecated` never installs in bulk. `stableOnly` opts out of preview.
+ * `deprecated` never installs in bulk, and neither does a library-only skill
+ * (`bundled: false`). `stableOnly` opts out of preview.
  * The counts let the caller say how many preview skills it installed (or, with
  * stableOnly, left out) instead of printing a bare total.
  */
 export function selectSkillsForBulkInstall(skills, options) {
-    const candidates = options.recommended ? skills.filter((skill) => skill.recommended) : [...skills];
+    const bundled = skills.filter((skill) => skill.bundled !== false);
+    const candidates = options.assetsOnly
+        ? bundled.filter(isAssetSkill)
+        : options.recommended
+            ? bundled.filter((skill) => skill.recommended)
+            : bundled;
     const stableOnly = options.stableOnly === true;
     const selected = candidates.filter((skill) => skill.status === "stable" || (!stableOnly && skill.status === "preview"));
     const preview = candidates.filter((skill) => skill.status === "preview").length;

package/dist/core/telemetry.d.ts

@@ -1,3 +1,20 @@
+/**
+ * Usage beacons for the local MCP server. Fire-and-forget, never blocks, never throws.
+ *
+ * - One session ping per MCP server lifetime (mcp_session_start), on the
+ *   first tool call, with the host app's name from the MCP handshake.
+ * - One line per local tool call (mcp_tool_call): the tool name, the
+ *   Summer operation it ran, success, duration, the host app's name from the
+ *   MCP handshake, and the tool surface and profile. Nothing else: no
+ *   arguments, no results, no project or file names.
+ *
+ * Both go to /api/mcp/log-local-call, only when signed in (the account token
+ * attributes them), and never when SUMMER_NO_TELEMETRY=1 or DO_NOT_TRACK=1.
+ * The endpoint always returns allowed:true and never gates; the response is
+ * ignored.
+ */
+import { isTelemetryDisabled } from "./agent-host.js";
+export { isTelemetryDisabled };
 /**
  * Ping the telemetry endpoint once per MCP server lifetime.
  *
@@ -7,6 +24,21 @@
  * - Skips entirely if no auth token is on disk (anonymous users still work).
  */
 export declare function recordMcpSession(): void;
+export interface LocalToolCall {
+    tool: string;
+    ok: boolean;
+    durationMs: number;
+    /** The host app's name from the MCP handshake (clientInfo.name). */
+    mcpClient?: string;
+    /** The Summer operation the call ran (core/ops/contract.ts opForToolCall). */
+    op?: string | null;
+    /** The tool surface: v3 (3.x names) or v4 (the operation catalog). */
+    surfaceVersion?: "v3" | "v4";
+    /** The MCP profile: full, engine, assets or custom. */
+    profile?: string;
+}
+/** Report one local tool call: tool name, success, duration, host app name. */
+export declare function recordLocalToolCall(call: LocalToolCall): void;
 /**
  * Reset the once-per-session guard. Test-only.
  */

package/dist/core/telemetry.js

@@ -1,15 +1,25 @@
 /**
- * Pure-telemetry beacon for MCP usage. Fire-and-forget, never blocks, never throws.
- * One ping per MCP server lifetime — counts daily-active users, not per-tool calls.
+ * Usage beacons for the local MCP server. Fire-and-forget, never blocks, never throws.
  *
- * The endpoint /api/mcp/log-local-call always returns allowed:true and never gates.
- * No quota. The user account is the only thing being attributed; the response is
- * ignored entirely on the CLI side.
+ * - One session ping per MCP server lifetime (mcp_session_start), on the
+ *   first tool call, with the host app's name from the MCP handshake.
+ * - One line per local tool call (mcp_tool_call): the tool name, the
+ *   Summer operation it ran, success, duration, the host app's name from the
+ *   MCP handshake, and the tool surface and profile. Nothing else: no
+ *   arguments, no results, no project or file names.
+ *
+ * Both go to /api/mcp/log-local-call, only when signed in (the account token
+ * attributes them), and never when SUMMER_NO_TELEMETRY=1 or DO_NOT_TRACK=1.
+ * The endpoint always returns allowed:true and never gates; the response is
+ * ignored.
  */
+import { currentMcpClient, isTelemetryDisabled, summerRequestHeaders } from "./agent-host.js";
 import { getAuthToken } from "./auth.js";
 import { resolveGatewayUrl } from "./config.js";
+export { isTelemetryDisabled };
 const TELEMETRY_PATH = "/api/mcp/log-local-call";
 const TIMEOUT_MS = 5000;
+const TOOL_NAME = /^summer_[a-z0-9_]{1,64}$/;
 let pinged = false;
 /**
  * Ping the telemetry endpoint once per MCP server lifetime.
@@ -20,9 +30,29 @@ let pinged = false;
  * - Skips entirely if no auth token is on disk (anonymous users still work).
  */
 export function recordMcpSession() {
-    if (pinged)
+    if (pinged || isTelemetryDisabled())
         return;
     pinged = true;
+    const mcpClient = currentMcpClient()?.name;
+    send({ client: "summer-cli", event: "mcp_session_start", ...(mcpClient ? { mcpClient: mcpClient.slice(0, 64) } : {}) });
+}
+/** Report one local tool call: tool name, success, duration, host app name. */
+export function recordLocalToolCall(call) {
+    if (isTelemetryDisabled() || !TOOL_NAME.test(call.tool))
+        return;
+    send({
+        client: "summer-cli",
+        event: "mcp_tool_call",
+        ...(call.mcpClient ? { mcpClient: call.mcpClient.slice(0, 64) } : {}),
+        tool: call.tool,
+        ...(call.op ? { op: call.op } : {}),
+        ...(call.surfaceVersion ? { surfaceVersion: call.surfaceVersion } : {}),
+        ...(call.profile ? { profile: call.profile } : {}),
+        ok: call.ok,
+        durationMs: Math.max(0, Math.round(call.durationMs)),
+    });
+}
+function send(body) {
     // Wrap the entire async pipeline in a void-discarded promise so the caller
     // never accidentally awaits us.
     void (async () => {
@@ -40,13 +70,11 @@ export function recordMcpSession() {
                     method: "POST",
                     signal: ctrl.signal,
                     headers: {
+                        ...summerRequestHeaders(),
                         Authorization: `Bearer ${token}`,
                         "Content-Type": "application/json",
                     },
-                    body: JSON.stringify({
-                        client: "summer-cli",
-                        event: "mcp_session_start",
-                    }),
+                    body: JSON.stringify(body),
                 });
             }
             finally {

package/dist/core/tool-profiles.d.ts

@@ -0,0 +1,25 @@
+/**
+ * MCP tool profiles (`summer mcp --profile`, SUMMER_PROFILE) and the toolsets
+ * they pick. Shared by the MCP server (src/mcp/tool-surface.ts) and setup,
+ * which writes a profile into an agent's MCP entry. `full` is today's
+ * surface exactly and the default, so existing configs keep it.
+ */
+export declare const TOOLSETS: readonly ["core", "assets", "tools", "engine", "ui", "ship", "uploads", "apps", "board", "grow", "studio", "cloud", "other"];
+export type Toolset = (typeof TOOLSETS)[number];
+export declare const PROFILES: {
+    /** Every tool, local and hosted (today's surface). */
+    readonly full: readonly ["core", "assets", "tools", "engine", "ui", "ship", "uploads", "apps", "board", "grow", "studio", "cloud", "other"];
+    /** Summer Engine creators: engine, generation and the store. Fits clients with a 128-tool limit. */
+    readonly engine: readonly ["core", "assets", "engine", "ship"];
+    /** Any engine or none: generation, the asset library, account and library search. No engine tools. */
+    readonly assets: readonly ["core", "assets", "tools"];
+};
+export type Profile = keyof typeof PROFILES;
+/** Non-full profiles never register more tools than this (VS Code Copilot's per-request limit). */
+export declare const PROFILE_TOOL_LIMIT = 128;
+/** A profile name, or null when the value names none. */
+export declare function parseProfile(value: string | undefined): Profile | null;
+/** v4: the operation catalog (summer_search, summer_call, `summer <area> <action>`); v3: the 3.x tools. */
+export type SurfaceVersion = "v3" | "v4";
+/** `--surface` / SUMMER_SURFACE: v4 is the default since 4.0; v3 keeps the 3.x tools. */
+export declare function resolveSurface(value: string | undefined, env?: NodeJS.ProcessEnv): SurfaceVersion;

package/dist/core/tool-profiles.js

@@ -0,0 +1,41 @@
+/**
+ * MCP tool profiles (`summer mcp --profile`, SUMMER_PROFILE) and the toolsets
+ * they pick. Shared by the MCP server (src/mcp/tool-surface.ts) and setup,
+ * which writes a profile into an agent's MCP entry. `full` is today's
+ * surface exactly and the default, so existing configs keep it.
+ */
+export const TOOLSETS = [
+    "core",
+    "assets",
+    "tools",
+    "engine",
+    "ui",
+    "ship",
+    "uploads",
+    "apps",
+    "board",
+    "grow",
+    "studio",
+    "cloud",
+    "other",
+];
+export const PROFILES = {
+    /** Every tool, local and hosted (today's surface). */
+    full: TOOLSETS,
+    /** Summer Engine creators: engine, generation and the store. Fits clients with a 128-tool limit. */
+    engine: ["core", "assets", "engine", "ship"],
+    /** Any engine or none: generation, the asset library, account and library search. No engine tools. */
+    assets: ["core", "assets", "tools"],
+};
+/** Non-full profiles never register more tools than this (VS Code Copilot's per-request limit). */
+export const PROFILE_TOOL_LIMIT = 128;
+/** A profile name, or null when the value names none. */
+export function parseProfile(value) {
+    const name = (value ?? "").trim().toLowerCase();
+    return Object.hasOwn(PROFILES, name) ? name : null;
+}
+/** `--surface` / SUMMER_SURFACE: v4 is the default since 4.0; v3 keeps the 3.x tools. */
+export function resolveSurface(value, env = process.env) {
+    const asked = (value ?? env.SUMMER_SURFACE ?? "").trim().toLowerCase();
+    return asked === "v3" || asked === "3" ? "v3" : "v4";
+}

package/dist/installer/agent-config.d.ts

@@ -1,3 +1,4 @@
+import type { Profile } from "../core/tool-profiles.js";
 import { type ConfigScope, type McpFormat, type SupportedAgent } from "./agent-table.js";
 export { supportedAgents, type ConfigScope, type SupportedAgent } from "./agent-table.js";
 export declare const SUMMER_MCP_SERVER_NAME = "summer-engine";
@@ -12,9 +13,11 @@ export interface AgentConfigOptions {
     dryRun?: boolean;
     print?: boolean;
     localDev?: boolean;
-    /** npm dist-tag the generated MCP entry runs (`npx -y summer-engine@<channel> mcp`).
+    /** npm dist-tag or exact version the generated MCP entry runs (`npx -y summer-engine@<channel> mcp`).
      *  Default "latest"; "next" while a release soaks on the next tag. Ignored with localDev. */
     channel?: string;
+    /** MCP tool profile written as SUMMER_PROFILE; default the agent's own (full for most). */
+    profile?: Profile;
     cwd?: string;
     env?: NodeJS.ProcessEnv;
 }
@@ -31,8 +34,11 @@ export interface AgentConfigResult {
     dryRun: boolean;
     print: boolean;
     localDev: boolean;
-    /** The dist-tag the written entry runs ("latest" unless --channel / SUMMER_CHANNEL). */
+    /** The dist-tag or exact version the written entry runs ("latest" unless --channel /
+     *  SUMMER_CHANNEL, or a CLI ahead of npm latest: see resolveDefaultChannel). */
     channel: string;
+    /** The MCP tool profile the entry runs (full = every tool, no SUMMER_PROFILE written). */
+    profile: Profile;
     warnings: string[];
     nextSteps: string[];
 }
@@ -72,9 +78,16 @@ export interface RemoteMcpResult {
 export declare function configureSummerGamesMcp(options: Pick<AgentConfigOptions, "agent" | "scope" | "dryRun" | "cwd" | "env">): Promise<RemoteMcpResult | null>;
 export declare const DEFAULT_CHANNEL = "latest";
 /** npm dist-tags are lowercase words like `latest`, `next`, `beta`, `v3-preview`;
- *  anything that could be read as a version or a path is refused (a bare
- *  version belongs in a version bump, not a channel). */
+ *  an exact version (`3.9.1`, `3.9.1-rc.1`) pins the entry to that release, which
+ *  setup does for a CLI that is ahead of npm latest. Anything else, partial
+ *  versions and paths included, is refused. */
 export declare function normalizeChannel(channel: string | undefined): string;
+/**
+ * The profile rides in the entry's env, not its args: an older summer-engine
+ * that an agent still runs ignores the variable and serves every tool, where
+ * an unknown --profile flag would stop it from starting.
+ */
+export declare function withProfile(server: StdioMcpServerConfig, profile: Profile): StdioMcpServerConfig;
 export declare function createSummerMcpServerConfig(localDev: boolean, platform?: NodeJS.Platform, channel?: string): StdioMcpServerConfig;
 export declare function renderConfigSnippet(agent: SupportedAgent, server: StdioMcpServerConfig): string;
 /** The key under which the file lists MCP servers (see McpFormat in agent-table.ts). */

package/dist/installer/agent-config.js

@@ -27,9 +27,12 @@ export function resolveAgentSelection(agentArg, agentOpt) {
     if (agentArg && agentOpt && parseAgent(agentArg) !== parseAgent(agentOpt)) {
         throw new Error("Specify the agent either positionally or with --agent, not both.");
     }
-    const parsed = parseAgent(agentOpt ?? agentArg);
+    const name = agentOpt ?? agentArg;
+    const parsed = parseAgent(name);
     if (!parsed) {
-        throw new Error(`Specify an agent: ${supportedAgents.join(", ")}`);
+        throw new Error(name
+            ? `Unknown agent "${name}". Supported: ${supportedAgents.join(", ")}`
+            : `Specify an agent: ${supportedAgents.join(", ")}`);
     }
     return parsed;
 }
@@ -45,9 +48,15 @@ export async function configureAgentMcp(options) {
     const env = options.env ?? process.env;
     const cwd = resolve(options.cwd ?? process.cwd());
     const channel = normalizeChannel(options.channel);
-    const server = createSummerMcpServerConfig(Boolean(options.localDev), process.platform, channel);
     const spec = agentSpec(options.agent);
+    const profile = options.profile ?? spec.mcpProfile ?? "full";
+    const server = withProfile(createSummerMcpServerConfig(Boolean(options.localDev), process.platform, channel), profile);
     const target = resolveConfigTarget(spec, options.scope, cwd, env);
+    // An entry an earlier setup wrote where the agent no longer reads (Devin Desktop moved from ~/.codeium/windsurf).
+    const moved = spec.mcp.movedFrom ? spec.mcp.movedFrom(defaultPathContext(env, cwd)) : null;
+    if (moved && moved !== target.path && (await readTextFileIfExists(moved)).includes(`"${SUMMER_MCP_SERVER_NAME}"`)) {
+        target.warnings.push(`${moved} still lists ${SUMMER_MCP_SERVER_NAME} from an earlier setup. ${spec.label} now reads ${target.path}, so setup writes it there; the old entry stays for older builds.`);
+    }
     const snippet = renderConfigSnippet(options.agent, server);
     const dryRun = Boolean(options.dryRun);
     const print = Boolean(options.print);
@@ -69,6 +78,7 @@ export async function configureAgentMcp(options) {
         print,
         localDev: Boolean(options.localDev),
         channel,
+        profile,
         warnings: target.warnings,
         nextSteps: [`Updated ${target.path}.`, spec.restart],
     };
@@ -264,17 +274,28 @@ async function upsertConfig(format, path, server, write) {
 }
 export const DEFAULT_CHANNEL = "latest";
 /** npm dist-tags are lowercase words like `latest`, `next`, `beta`, `v3-preview`;
- *  anything that could be read as a version or a path is refused (a bare
- *  version belongs in a version bump, not a channel). */
+ *  an exact version (`3.9.1`, `3.9.1-rc.1`) pins the entry to that release, which
+ *  setup does for a CLI that is ahead of npm latest. Anything else, partial
+ *  versions and paths included, is refused. */
 export function normalizeChannel(channel) {
     const value = (channel ?? "").trim();
     if (value === "")
         return DEFAULT_CHANNEL;
+    if (/^\d+\.\d+\.\d+(?:-[0-9a-z][0-9a-z.-]*)?$/.test(value))
+        return value;
     if (!/^[a-z][a-z0-9-]*$/.test(value) || /^v?\d/.test(value)) {
-        throw new Error(`Invalid channel "${channel}": use an npm dist-tag such as latest or next (lowercase letters, digits, hyphens).`);
+        throw new Error(`Invalid channel "${channel}": use an npm dist-tag such as latest or next (lowercase letters, digits, hyphens), or an exact version such as 4.0.0.`);
     }
     return value;
 }
+/**
+ * The profile rides in the entry's env, not its args: an older summer-engine
+ * that an agent still runs ignores the variable and serves every tool, where
+ * an unknown --profile flag would stop it from starting.
+ */
+export function withProfile(server, profile) {
+    return profile === "full" ? server : { ...server, env: { ...server.env, SUMMER_PROFILE: profile } };
+}
 export function createSummerMcpServerConfig(localDev, platform = process.platform, channel = DEFAULT_CHANNEL) {
     const spec = `summer-engine@${normalizeChannel(channel)}`;
     if (localDev) {

package/dist/installer/agent-table.d.ts

@@ -1,3 +1,4 @@
+import type { Profile } from "../core/tool-profiles.js";
 /** Ids `summer setup <agent>` accepts. Legacy ids stay so old commands and
  *  configs keep resolving, but they are hidden from help and warn on use. */
 export declare const AGENT_IDS: readonly ["claude-code", "claude-desktop", "codex", "cursor", "windsurf", "antigravity", "gemini", "cline", "cline-cli", "roo-code", "kilo-code", "github-copilot", "vscode-copilot", "visual-studio", "copilot-jetbrains", "opencode", "zed", "kiro", "goose", "hermes", "trae", "qwen-code", "kimi-code", "crush", "amp", "factory", "junie", "warp", "rovo-dev", "qoder", "grok-build", "mistral-vibe", "lm-studio"];
@@ -70,6 +71,8 @@ export interface AgentSpec {
     /** Env var that overrides the MCP config path (tests, unusual installs). */
     envOverride: string;
     format: McpFormat;
+    /** MCP tool profile setup writes without --profile (default full: every tool). */
+    mcpProfile?: Profile;
     /**
      * The Summer Games player MCP (a remote server that signs in with OAuth on
      * its own) in this agent's file, under the same key as summer-engine.
@@ -90,6 +93,8 @@ export interface AgentSpec {
         project: ((ctx: PathContext) => string) | null;
         /** Extra warning printed when project scope is requested (also when it is honoured). */
         projectNote?: string;
+        /** The user file the agent read before it moved: setup names an earlier summer-engine entry left there. */
+        movedFrom?: (ctx: PathContext) => string;
     };
     /** What to do after the config is written. */
     restart: string;
@@ -109,6 +114,13 @@ export declare const supportedAgents: readonly SupportedAgent[];
 export declare const skillCapableAgents: readonly SupportedAgent[];
 /** Every spelling → canonical id. Aliases must be unique across the table. */
 export declare function agentAliasMap(): Record<string, SupportedAgent>;
+/**
+ * Why `summer setup <agent> --cli` cannot set this agent up, or null. --cli
+ * installs the skills and no MCP server, so the agent needs a skills folder,
+ * and one that takes SKILL.md files: rule files (Roo Code) and the Gemini
+ * extension assume the MCP tools.
+ */
+export declare function cliSetupRefusal(spec: AgentSpec): string | null;
 export declare function agentLabel(id: SupportedAgent): string;
 export declare function defaultPathContext(env?: NodeJS.ProcessEnv, cwd?: string): PathContext;
 export interface ResolvedMcpPath {