summer-engine 3.7.0 → 4.0.0

package/dist/cli/commands/setup.js

@@ -6,6 +6,12 @@ import { brandLine, c, sym, tildeify } from "../../core/format.js";
 import { TOOLKIT_VERSION as cliVersion } from "../../core/version.js";
 import { resolveDefaultChannel } from "../../installer/version-check.js";
 import { agentLabel } from "../../installer/agent-table.js";
+import { PROFILES, parseProfile } from "../../core/tool-profiles.js";
+const PROFILE_NOTES = {
+    full: "Every Summer tool.",
+    engine: "Engine, generation and store tools. Every tool: summer setup <agent> --profile full",
+    assets: "Generation and asset tools, no engine tools. Every tool: summer setup <agent> --profile full",
+};
 export const setupCommand = new Command("setup")
     .description("Configure Summer Engine for an AI agent and run diagnostics. For agents that can sign in to it, it also adds Summer Games (summer-games).")
     .argument("[agent]", `Agent to configure: ${supportedAgents.join(", ")}`)
@@ -14,9 +20,11 @@ export const setupCommand = new Command("setup")
     .option("--dry-run", "Show planned changes without writing files")
     .option("--print", "Print the MCP config snippet instead of writing files")
     .option("--local-dev", "Point the agent at this checkout's built CLI (node <repo>/dist/bin/summer.js mcp) instead of npx summer-engine@latest — for testing unpublished builds. SUMMER_DEV=1 does the same.")
-    .option("--channel <dist-tag>", "npm dist-tag the agent's MCP entry runs: npx -y summer-engine@<dist-tag> mcp (default latest; use next while a release soaks on the next tag). SUMMER_CHANNEL does the same.")
+    .option("--channel <dist-tag>", "npm dist-tag or exact version the agent's MCP entry runs: npx -y summer-engine@<dist-tag> mcp (default latest; a CLI newer than npm latest pins next when next is this version, else this version). SUMMER_CHANNEL does the same.")
     .option("--yes", "Apply practical setup steps without prompting")
     .option("--no-games", "Do not add the Summer Games MCP (summer-games: friends, parties and messages as you, signed in through summer.games)")
+    .option("--profile <profile>", "MCP tool profile: full (every tool, the default), engine (engine, generation and the store; under 128 tools; the default for VS Code Copilot), assets (generation and the asset library, no engine tools)")
+    .option("--assets-only", "Set up for making assets without Summer Engine: the assets profile, only the asset skills, and no Summer Games")
     .option("--json", "Print setup result as JSON")
     .option("--force", "Overwrite existing skill content (passes --force through to skills install)")
     .option("--recommended", "Install only the recommended skill subset instead of the whole library")
@@ -26,6 +34,7 @@ export const setupCommand = new Command("setup")
     .action(async (agentArg, opts) => {
     const agent = resolveAgentSelection(agentArg, opts.agent);
     const scope = resolveConfigScope(opts.scope);
+    const profile = resolveSetupProfile(opts);
     const defaultChannel = await resolveDefaultChannel(cliVersion);
     const config = await configureAgentMcp({
         agent,
@@ -34,8 +43,9 @@ export const setupCommand = new Command("setup")
         print: opts.print,
         localDev: Boolean(opts.localDev) || process.env.SUMMER_DEV === "1",
         channel: opts.channel ?? process.env.SUMMER_CHANNEL ?? defaultChannel.channel,
+        profile,
     });
-    const games = opts.games === false || opts.print
+    const games = opts.games === false || opts.assetsOnly || opts.print
         ? null
         : await configureSummerGamesMcp({ agent, scope, dryRun: opts.dryRun });
     if (!opts.channel && !process.env.SUMMER_CHANNEL && defaultChannel.note && !opts.print) {
@@ -48,6 +58,7 @@ export const setupCommand = new Command("setup")
         scope,
         recommended: Boolean(opts.recommended),
         stableOnly: Boolean(opts.stableOnly),
+        assetsOnly: Boolean(opts.assetsOnly),
     });
     const doctor = await runDoctor({ quiet: true });
     if (opts.json) {
@@ -66,6 +77,19 @@ export const setupCommand = new Command("setup")
         process.exit(1);
     }
 });
+/** --assets-only means the assets profile; --profile must name a profile and agree with it. */
+function resolveSetupProfile(opts) {
+    const profile = opts.profile === undefined ? undefined : parseProfile(opts.profile);
+    if (profile === null) {
+        throw new Error(`Unknown --profile "${opts.profile}". Use one of: ${Object.keys(PROFILES).join(", ")}.`);
+    }
+    if (opts.assetsOnly) {
+        if (profile && profile !== "assets")
+            throw new Error("--assets-only uses the assets profile; leave out --profile.");
+        return "assets";
+    }
+    return profile;
+}
 function printSetupResult(config, games, skills, doctor) {
     if (config.print) {
         console.log(config.snippet.trimEnd());
@@ -90,6 +114,9 @@ function printSetupResult(config, games, skills, doctor) {
     else if (config.channel !== "latest") {
         console.log(`  ${c.dim(`(channel ${config.channel})`)}  MCP server command: ${c.dim(`${config.server.command} ${config.server.args.join(" ")}`)}`);
     }
+    if (config.profile !== "full") {
+        console.log(`  ${c.dim(`(profile ${config.profile})`)}  ${c.dim(PROFILE_NOTES[config.profile])}`);
+    }
     if (games) {
         const name = c.bold("Summer Games");
         const url = c.dim(games.url);
@@ -114,15 +141,7 @@ function printSetupResult(config, games, skills, doctor) {
                 ? c.dim(` (${skills.installed.added} new, ${skills.installed.updated} updated${note ? `; ${note}` : ""})`)
                 : "";
             console.log(`  ${sym.ok()}  Installed ${c.bold(String(installed.length) + " skills")}${tally}  ${where ? c.dim(tildeify(where)) : ""}`);
-            const grouped = installed.reduce((rows, name, i) => {
-                const row = Math.floor(i / 3);
-                rows[row] = rows[row] ?? [];
-                rows[row].push(name);
-                return rows;
-            }, []);
-            for (const row of grouped) {
-                console.log(`     ${c.dim(row.join(" · "))}`);
-            }
+            console.log(`     ${c.dim(skillNamesSample(installed))}`);
         }
         else {
             console.log(`  ${sym.ok()}  ${skills.message}`);
@@ -147,9 +166,15 @@ function printSetupResult(config, games, skills, doctor) {
     printDoctorResult(doctor);
     if (doctor.ok && skills.status !== "failed" && !config.dryRun) {
         console.log("");
-        console.log(`${c.dim("Try it:")} open ${label} and ask: ${c.bold("\"add a DirectionalLight3D and Camera3D to my scene\"")}`);
+        const ask = config.profile === "assets" ? "make a sword clash sound effect" : "add a DirectionalLight3D and Camera3D to my scene";
+        console.log(`${c.dim("Try it:")} open ${label} and ask: ${c.bold(`"${ask}"`)}`);
     }
 }
+/** One line instead of a row per three skills: the first few names and how many more. `--json` keeps the full list. */
+export function skillNamesSample(names, max = 8) {
+    const shown = names.slice(0, max).join(" · ");
+    return names.length > max ? `${shown} · and ${names.length - max} more` : shown;
+}
 function parseInstalledSkills(stdout) {
     if (!stdout)
         return [];

package/dist/cli/commands/skills.js

@@ -62,25 +62,26 @@ function previewIncludedLine(count) {
     return `  ${count} preview skill${count === 1 ? "" : "s"} included — labelled in ${count === 1 ? "its" : "each skill's"} guidance; add --stable-only to skip.`;
 }
 function selectSkills(name, opts) {
-    if (opts.all && opts.recommended) {
-        die("Use only one bulk option: --all or --recommended.");
+    if ([opts.all, opts.recommended, opts.assets].filter(Boolean).length > 1) {
+        die("Use only one bulk option: --all, --recommended or --assets.");
     }
-    if (name && (opts.all || opts.recommended)) {
+    if (name && (opts.all || opts.recommended || opts.assets)) {
         die("Specify either a skill name or a bulk option, not both.");
     }
     const skills = getBuiltinSkills();
-    if (opts.all || opts.recommended) {
+    if (opts.all || opts.recommended || opts.assets) {
         // Bulk installs take stable and preview skills (preview is a label, not a
         // gate); --stable-only skips preview. An explicit name below installs
         // regardless of status.
         const { selected, previewIncluded, previewSkipped } = selectSkillsForBulkInstall(skills, {
             recommended: Boolean(opts.recommended),
             stableOnly: Boolean(opts.stableOnly),
+            assetsOnly: Boolean(opts.assets),
         });
         return { skills: selected, previewIncluded, previewSkipped };
     }
     if (!name) {
-        console.error("Specify a skill name, --recommended, or --all.");
+        console.error("Specify a skill name, --recommended, --assets, or --all.");
         printAvailableSkillNames();
         process.exit(1);
     }
@@ -276,7 +277,8 @@ skillsCommand
     .description("Install Summer skills for a target agent")
     .option("--all", "Install all available skills")
     .option("--recommended", "Install only the recommended skill subset (summer setup installs all by default)")
-    .option("--stable-only", "With --all / --recommended, skip preview skills (installed by default; labelled preview in their guidance)")
+    .option("--assets", "Install only the asset skills (sound, music, voice, images, 3D, animation, video) for agents that make assets without the engine")
+    .option("--stable-only", "With --all / --recommended / --assets, skip preview skills (installed by default; labelled preview in their guidance)")
     .option("--agent <agent>", `Target agent: ${AGENT_CLIENTS.join("|")}`)
     .option("--scope <scope>", "Install scope: user or project")
     // Legacy aliases: still accepted for old scripts, hidden from --help.
@@ -342,7 +344,9 @@ skillsCommand
         console.log(previewSkippedLine(previewSkipped));
     // Claude Code: also install slash commands (`commands/*.md`)
     // into `~/.claude/commands/`. Other agents don't have an equivalent today.
-    if (agent === "claude-code") {
+    // The commands start and route game work in the engine, so the asset
+    // skills (--assets, setup --assets-only) leave them out.
+    if (agent === "claude-code" && !opts.assets) {
         const commandResults = installClaudeCommands(scope, Boolean(opts.force));
         for (const r of commandResults) {
             console.log(`  ${r.action} command ${r.name} -> ${r.path}`);

package/dist/cli/index.js

@@ -16,9 +16,11 @@ import { debugCommand } from "./commands/debug.js";
 import { configCommand } from "./commands/config.js";
 import { eventsCommand } from "./commands/events.js";
 import { toolCommand } from "./commands/tool.js";
+import { opsCliCommands } from "./commands/ops.js";
 import { getBanner } from "./banner.js";
 import { runRootAction } from "./root-action.js";
 import { c, sym } from "../core/format.js";
+import { resolveSurface } from "../core/tool-profiles.js";
 import { TOOLKIT_VERSION as version } from "../core/version.js";
 /**
  * Build and run the summer CLI. The `mcp` command is injected by the bin
@@ -51,6 +53,11 @@ export function runCli(mcpCommand) {
     program.addCommand(configCommand);
     program.addCommand(eventsCommand);
     program.addCommand(toolCommand);
+    // The 4.0 operation catalog (`summer <area> <action>`); SUMMER_SURFACE=v3 leaves it out.
+    if (resolveSurface(undefined) === "v4") {
+        for (const command of opsCliCommands())
+            program.addCommand(command);
+    }
     program.parseAsync().catch((err) => {
         console.error(err instanceof Error ? err.message : String(err));
         process.exit(1);

package/dist/core/agent-host.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Which agent app runs Summer (Claude Code, Codex, Cursor, ...) and which tool
+ * made a request, sent as headers on every request to Summer's servers
+ * (summerengine.com and the hosted Summer Engine MCP), so usage can be
+ * counted per agent app and per tool.
+ *
+ * The server reads X-Summer-Agent-Host / X-Summer-Agent-Host-Source
+ * (publicsummerengine src/lib/mcp/agent-host.ts) into the attribution of the
+ * usage rows a request causes, and X-Summer-MCP-Tool on generation errors.
+ * X-Summer-Agent-Host-Name / -Version carry the MCP handshake's clientInfo
+ * as the app sent it.
+ *
+ * Host resolution: SUMMER_AGENT_HOST (explicit override), then the MCP
+ * initialize handshake's clientInfo.name, then the environment an agent sets
+ * for the commands it runs (the CLI surface), else "unknown".
+ *
+ * SUMMER_NO_TELEMETRY=1 / DO_NOT_TRACK=1 drop the host and tool headers; the
+ * product headers (X-Summer-Client, -Version, -Surface) stay, like a
+ * user agent.
+ */
+export declare const AGENT_HOST_HEADER = "X-Summer-Agent-Host";
+export declare const AGENT_HOST_SOURCE_HEADER = "X-Summer-Agent-Host-Source";
+export declare const AGENT_HOST_NAME_HEADER = "X-Summer-Agent-Host-Name";
+export declare const AGENT_HOST_VERSION_HEADER = "X-Summer-Agent-Host-Version";
+export declare const MCP_TOOL_HEADER = "X-Summer-MCP-Tool";
+export declare const AGENT_HOST_OVERRIDE_ENV = "SUMMER_AGENT_HOST";
+export type AgentHostSource = "override" | "mcp-client" | "env" | "none";
+export type ClientSurface = "mcp" | "cli";
+export interface AgentHost {
+    id: string;
+    source: AgentHostSource;
+}
+export interface McpClientInfo {
+    name?: string;
+    version?: string;
+}
+type Env = Record<string, string | undefined>;
+/** The opt-out switches, the same two the library feedback mailbox honors. */
+export declare function isTelemetryDisabled(env?: Env): boolean;
+/** Lowercase `[a-z0-9-]`, at most 40 characters: the server's host id shape. */
+export declare function sanitizeHostId(raw: string): string;
+/** A known host id, or "other.<name>" for a client Summer does not know yet. */
+export declare function hostFromClientName(name: string | undefined | null): string | null;
+/** AI_AGENT ("<name>_<version>_<mode>") first, then the per-host variables. */
+export declare function hostFromEnv(env: Env): string | null;
+export declare function registerMcpClientSource(source: (() => McpClientInfo | undefined) | null): void;
+export declare function currentMcpClient(): McpClientInfo | undefined;
+export declare function resolveAgentHost(env?: Env, client?: McpClientInfo | undefined): AgentHost;
+interface ToolContext {
+    tool: string;
+    surface: ClientSurface;
+}
+/** Run one tool call so every Summer request it makes names the tool and surface. */
+export declare function runWithToolContext<T>(tool: string, surface: ClientSurface, fn: () => T): T;
+/** The tool call running now, if any (a tool that runs inside another one sees the outer call). */
+export declare function currentToolContext(): ToolContext | undefined;
+/**
+ * Headers for a request to Summer's servers. `tool` names the tool when no
+ * tool call is running (the endpoint's own tool); a running call's tool wins.
+ */
+export declare function summerRequestHeaders(options?: {
+    tool?: string;
+    surface?: ClientSurface;
+}, env?: Env): Record<string, string>;
+export {};

package/dist/core/agent-host.js

@@ -0,0 +1,193 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { TOOLKIT_VERSION } from "./version.js";
+/**
+ * Which agent app runs Summer (Claude Code, Codex, Cursor, ...) and which tool
+ * made a request, sent as headers on every request to Summer's servers
+ * (summerengine.com and the hosted Summer Engine MCP), so usage can be
+ * counted per agent app and per tool.
+ *
+ * The server reads X-Summer-Agent-Host / X-Summer-Agent-Host-Source
+ * (publicsummerengine src/lib/mcp/agent-host.ts) into the attribution of the
+ * usage rows a request causes, and X-Summer-MCP-Tool on generation errors.
+ * X-Summer-Agent-Host-Name / -Version carry the MCP handshake's clientInfo
+ * as the app sent it.
+ *
+ * Host resolution: SUMMER_AGENT_HOST (explicit override), then the MCP
+ * initialize handshake's clientInfo.name, then the environment an agent sets
+ * for the commands it runs (the CLI surface), else "unknown".
+ *
+ * SUMMER_NO_TELEMETRY=1 / DO_NOT_TRACK=1 drop the host and tool headers; the
+ * product headers (X-Summer-Client, -Version, -Surface) stay, like a
+ * user agent.
+ */
+export const AGENT_HOST_HEADER = "X-Summer-Agent-Host";
+export const AGENT_HOST_SOURCE_HEADER = "X-Summer-Agent-Host-Source";
+export const AGENT_HOST_NAME_HEADER = "X-Summer-Agent-Host-Name";
+export const AGENT_HOST_VERSION_HEADER = "X-Summer-Agent-Host-Version";
+export const MCP_TOOL_HEADER = "X-Summer-MCP-Tool";
+export const AGENT_HOST_OVERRIDE_ENV = "SUMMER_AGENT_HOST";
+/** The opt-out switches, the same two the library feedback mailbox honors. */
+export function isTelemetryDisabled(env = process.env) {
+    return env.SUMMER_NO_TELEMETRY === "1" || env.DO_NOT_TRACK === "1";
+}
+const set = (env, key) => {
+    const value = env[key];
+    return value !== undefined && value !== "" && value !== "0" && value.toLowerCase() !== "false";
+};
+/**
+ * Variables hosts set for the commands they run, most specific first (the
+ * convention @vercel/detect-agent reads). CURSOR_TRACE_ID is last: Cursor sets
+ * it in every integrated terminal, so Claude Code or Codex inside Cursor wins.
+ */
+const ENV_SIGNALS = [
+    { id: "claude-code", test: (e) => set(e, "CLAUDECODE") || set(e, "CLAUDE_CODE") || set(e, "CLAUDE_CODE_ENTRYPOINT") },
+    { id: "codex", test: (e) => set(e, "CODEX_SANDBOX") || set(e, "CODEX_CI") || set(e, "CODEX_THREAD_ID") },
+    { id: "gemini-cli", test: (e) => set(e, "GEMINI_CLI") },
+    { id: "antigravity", test: (e) => set(e, "ANTIGRAVITY_AGENT") },
+    { id: "augment", test: (e) => set(e, "AUGMENT_AGENT") },
+    { id: "opencode", test: (e) => set(e, "OPENCODE_CLIENT") },
+    { id: "github-copilot", test: (e) => set(e, "COPILOT_MODEL") || set(e, "COPILOT_ALLOW_ALL") || set(e, "COPILOT_GITHUB_TOKEN") },
+    { id: "cursor", test: (e) => set(e, "CURSOR_AGENT") || e.CURSOR_EXTENSION_HOST_ROLE === "agent-exec" },
+    { id: "replit", test: (e) => set(e, "REPL_ID") },
+    { id: "cursor", test: (e) => set(e, "CURSOR_TRACE_ID") },
+];
+/**
+ * clientInfo.name patterns (lowercased), most specific first. Names are what
+ * each app sends in `initialize`, matched loosely so a renamed build lands.
+ */
+const MCP_CLIENT_PATTERNS = [
+    { id: "claude-code", pattern: /claude[-_ ]?code/ },
+    { id: "claude-desktop", pattern: /^claude(-ai)?$|claude[-_ ]desktop/ },
+    { id: "codex", pattern: /codex/ },
+    { id: "cursor", pattern: /cursor/ },
+    { id: "windsurf", pattern: /windsurf|codeium|cascade|devin/ },
+    { id: "gemini-cli", pattern: /gemini/ },
+    { id: "antigravity", pattern: /antigravity/ },
+    { id: "openclaw", pattern: /openclaw|clawdbot|moltbot/ },
+    { id: "hermes", pattern: /hermes/ },
+    { id: "grok", pattern: /grok/ },
+    { id: "chatgpt", pattern: /chatgpt|openai/ },
+    { id: "roo-code", pattern: /roo[-_ ]?(code|cline)/ },
+    { id: "kilo-code", pattern: /kilo/ },
+    { id: "cline", pattern: /cline/ },
+    { id: "github-copilot", pattern: /copilot/ },
+    { id: "vscode", pattern: /visual studio code|vscode/ },
+    { id: "visual-studio", pattern: /visual studio/ },
+    { id: "zed", pattern: /\bzed\b/ },
+    { id: "opencode", pattern: /opencode/ },
+    { id: "goose", pattern: /goose/ },
+    { id: "amp", pattern: /\bamp\b/ },
+    { id: "kiro", pattern: /kiro/ },
+    { id: "trae", pattern: /trae/ },
+    { id: "qwen-code", pattern: /qwen/ },
+    { id: "kimi-code", pattern: /kimi/ },
+    { id: "crush", pattern: /crush/ },
+    { id: "factory", pattern: /factory|droid/ },
+    { id: "junie", pattern: /junie|jetbrains/ },
+    { id: "warp", pattern: /warp/ },
+    { id: "rovo-dev", pattern: /rovo/ },
+    { id: "qoder", pattern: /qoder/ },
+    { id: "mistral-vibe", pattern: /mistral|vibe/ },
+    { id: "lm-studio", pattern: /lm[-_ ]?studio/ },
+    { id: "continue", pattern: /continue/ },
+    { id: "augment", pattern: /augment/ },
+    { id: "replit", pattern: /replit/ },
+];
+/** Lowercase `[a-z0-9-]`, at most 40 characters: the server's host id shape. */
+export function sanitizeHostId(raw) {
+    return raw
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9-]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 40);
+}
+function matchClientPattern(name) {
+    const lower = name.toLowerCase();
+    return MCP_CLIENT_PATTERNS.find(({ pattern }) => pattern.test(lower))?.id ?? null;
+}
+/** A known host id, or "other.<name>" for a client Summer does not know yet. */
+export function hostFromClientName(name) {
+    if (!name)
+        return null;
+    const known = matchClientPattern(name);
+    if (known)
+        return known;
+    const fallback = sanitizeHostId(name);
+    return fallback ? `other.${fallback}` : null;
+}
+/** AI_AGENT ("<name>_<version>_<mode>") first, then the per-host variables. */
+export function hostFromEnv(env) {
+    if (env.AI_AGENT) {
+        const declared = hostFromClientName(env.AI_AGENT.split("_")[0]);
+        if (declared)
+            return declared;
+    }
+    return ENV_SIGNALS.find(({ test }) => test(env))?.id ?? null;
+}
+// The MCP server registers a getter; it is read at request time, after the
+// initialize handshake has given the client's name and version.
+let mcpClientSource = null;
+export function registerMcpClientSource(source) {
+    mcpClientSource = source;
+}
+export function currentMcpClient() {
+    try {
+        return mcpClientSource?.() ?? undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+export function resolveAgentHost(env = process.env, client = currentMcpClient()) {
+    const override = env[AGENT_HOST_OVERRIDE_ENV] ? sanitizeHostId(env[AGENT_HOST_OVERRIDE_ENV]) : "";
+    if (override)
+        return { id: override, source: "override" };
+    const fromClient = hostFromClientName(client?.name);
+    if (fromClient)
+        return { id: fromClient, source: "mcp-client" };
+    const fromEnv = hostFromEnv(env);
+    if (fromEnv)
+        return { id: fromEnv, source: "env" };
+    return { id: "unknown", source: "none" };
+}
+const toolContext = new AsyncLocalStorage();
+/** Run one tool call so every Summer request it makes names the tool and surface. */
+export function runWithToolContext(tool, surface, fn) {
+    return toolContext.run({ tool, surface }, fn);
+}
+/** The tool call running now, if any (a tool that runs inside another one sees the outer call). */
+export function currentToolContext() {
+    return toolContext.getStore();
+}
+/** Printable ASCII only, so a header value never breaks a request. */
+const headerValue = (value, max) => value.replace(/[^\x20-\x7e]/g, "").trim().slice(0, max);
+/**
+ * Headers for a request to Summer's servers. `tool` names the tool when no
+ * tool call is running (the endpoint's own tool); a running call's tool wins.
+ */
+export function summerRequestHeaders(options = {}, env = process.env) {
+    const context = toolContext.getStore();
+    const surface = context?.surface ?? options.surface ?? (mcpClientSource ? "mcp" : "cli");
+    const headers = {
+        "X-Summer-Client": "summer-cli",
+        "X-Summer-Client-Version": TOOLKIT_VERSION,
+        "X-Summer-Client-Surface": surface,
+    };
+    if (isTelemetryDisabled(env))
+        return headers;
+    const client = surface === "mcp" ? currentMcpClient() : undefined;
+    const host = resolveAgentHost(env, client);
+    headers[AGENT_HOST_HEADER] = host.id;
+    headers[AGENT_HOST_SOURCE_HEADER] = host.source;
+    const name = client?.name ? headerValue(client.name, 64) : "";
+    const version = client?.version ? headerValue(client.version, 32) : "";
+    if (name)
+        headers[AGENT_HOST_NAME_HEADER] = name;
+    if (version)
+        headers[AGENT_HOST_VERSION_HEADER] = version;
+    const tool = context?.tool ?? options.tool;
+    if (tool)
+        headers[MCP_TOOL_HEADER] = tool;
+    return headers;
+}

package/dist/core/capabilities/agent-playbook.d.ts

@@ -15,6 +15,9 @@
 export interface AgentPlaybookOptions {
     /** The MCP layer's cached "Summer update available" notice, if any. */
     summerUpdateNotice?: string | null;
+    /** False for a session without engine tools (the assets profile): the
+     *  playbook then covers finding, generating and handing over files. */
+    engine?: boolean;
 }
 export declare function buildAgentPlaybook(options?: AgentPlaybookOptions): Record<string, unknown>;
 export declare function renderAgentPlaybook(options?: AgentPlaybookOptions): string;

package/dist/core/capabilities/agent-playbook.js

@@ -1,4 +1,6 @@
 export function buildAgentPlaybook(options = {}) {
+    if (options.engine === false)
+        return buildAssetsPlaybook(options);
     return {
         summerUpdateNotice: options.summerUpdateNotice ?? null,
         // ------------------------------------------------------------------
@@ -204,7 +206,7 @@ export function buildAgentPlaybook(options = {}) {
             "summer_get_project_context",
             "Choose the exact res:// scenePath. OpenScene is a user-visible tab action, not a mutation prerequisite.",
             "summer_world_snapshot (keep the snapshot_id) — or summer_get_scene_tree with scenePath for the hierarchy view.",
-            "summer_add_node / summer_set_prop / summer_set_resource_property with scenePath — or one summer_run_script for anything computed.",
+            "3 or more scene edits: one summer_run_script with scenePath (snapshot, script, diff, screenshot). A single tweak: summer_set_prop / summer_set_resource_property with scenePath.",
             "Mutation tools append one final SaveScene; use summer_save_scene only for a standalone save/save-as.",
             "summer_snapshot_diff from_id:<the id> + summer_screenshot — then summer_get_diagnostics.",
         ],
@@ -226,7 +228,7 @@ export function buildAgentPlaybook(options = {}) {
         ],
         // Scene scripting: when one GDScript beats a chain of CRUD ops.
         scripting: [
-            "Single property tweak -> summer_set_prop. Composition or ANY computed placement (3+ related ops, scatter/grids/rings, procedural meshes, bulk edits) -> summer_run_script: one GDScript `func run(ctx):` executed in the LIVE editor against the OPEN scene, with ctx.get_scene_root() / ctx.report(key, value) / print capture.",
+            "Single property tweak -> summer_set_prop. Composition or ANY computed placement (3+ related ops, scatter/grids/rings, procedural meshes, bulk edits) -> summer_run_script: one GDScript `func run(ctx):` executed in the LIVE editor against its scenePath (opened first when needed), with ctx.get_scene_root() / ctx.report(key, value) / print capture.",
             "OWNERSHIP in scripts: call ctx.set_owner_recursive(node) AFTER add_child on every created subtree (manual form: node.owner = root on the node AND each descendant), or the nodes silently vanish on save. The ctx creation helpers (ctx.add_node, ctx.add_mesh, ctx.instance_scene, ...) set the owner for you — prefer them.",
             "Cold batch/project-wide jobs (re-save every scene, resource sweeps, long bakes) -> summer_run_editor_script: a fresh HEADLESS child editor against the ON-DISK project. Unsaved live edits are invisible to it; it has no renderer, so it can never screenshot.",
             "Property/method/signal lookup -> summer_api_docs (offline class reference, stamped with the engine technical base it was generated from). Verify names before scripting instead of guessing; entries list declared members only, so walk `inherits` for inherited ones.",
@@ -259,6 +261,56 @@ export function buildAgentPlaybook(options = {}) {
         ],
     };
 }
+/**
+ * The playbook for the assets profile: the same habits (search the library
+ * first, reuse before generating, confirm spend, never describe an image you
+ * did not receive) without any engine tool, ending at a file the person can
+ * use in any engine or web app.
+ */
+function buildAssetsPlaybook(options) {
+    return {
+        summerUpdateNotice: options.summerUpdateNotice ?? null,
+        profile: "assets",
+        scope: [
+            "This session has generation, the Summer asset library, account and library search, and no Summer Engine tools: no project context, scenes, play, screenshots or imports. You deliver files, not scenes.",
+            "Load the summer-assets skill (summer_read_library skill/summer-assets) for the whole loop.",
+            "If the person wants a game built in Summer Engine, say that needs the full setup: npx -y summer-engine@latest setup <agent> --yes, then open the project in Summer Engine.",
+        ],
+        step0_askFirst: [
+            "Ask once, in one message, what the asset is for: the engine or app, the file format, the size or scale, the style, how many.",
+            "Then summer_search_library for the asset's skill and summer_read_library it before you generate.",
+            "Asset skills are written for Summer Engine too. Follow each one until the asset exists, then read its 'Without Summer Engine' section: skip every step that imports into a project (summer_import_asset_by_id, summer_import_from_url) or adds nodes to a scene (summer_add_node, summer_set_prop). Those tools are not in this session.",
+        ],
+        contentRouting: {
+            priorityOrder: ["1_reuseMyAssets", "2_assetLibrary", "3_generation"],
+            "1_reuseMyAssets": "summer_list_my_assets: the person's own uploads and earlier generations. Never generate an asset they already have.",
+            "2_assetLibrary": "summer_search_assets (source: library | my_assets | all), then summer_get_asset for the hit.",
+            "3_generation": "summer_generate_image / summer_generate_3d / summer_generate_audio / summer_generate_sfx_choices / summer_generate_video / summer_generate_motion, then summer_check_job until the state is terminal (never continue on a pending job), then summer_get_asset with the asset id the job returned (never search by name right after a generation). The summer_tool_* generators load after summer login; when they are missing, summer_store_tools says why.",
+        },
+        handOff: [
+            "summer_generate_image saves the file itself when you pass out (a folder or a file path in the person's project).",
+            "For every other asset, summer_get_asset_download_url (role primary, or thumbnail for a preview) returns a link: download it with your own shell into the folder the person named, and keep a clear file name.",
+            "Formats: GLB for 3D models, PNG, JPG or WebP for images, MP3 or WAV for audio, MP4 for video. Generated models are not at real-world size: give the person the target size.",
+            "Tell the person the path, the format and anything their engine must set (looping, texture filtering, scale).",
+        ],
+        costRules: [
+            "Generation uses the person's Summer credits: say what you will make and how many versions, and wait for a yes. Search and download are free.",
+            "Never run a paid generation again for the same item: download the asset you already have.",
+        ],
+        honestyRules: [
+            "Never describe an image you did not receive. Look at the preview (the localPath of a generated image, or the thumbnail) before you say it looks right; for audio, the person listens.",
+            "A failed or pending job is a result: report its state and error as returned, do not claim the asset exists.",
+        ],
+        doneMeans: [
+            "The job finished without an error.",
+            "You saw the preview, or the person heard the sound.",
+            "The file is where the person asked, and you told them the path and format.",
+        ],
+        libraryFeedback: [
+            "At a natural checkpoint, call summer_library_feedback once with every skill you loaded: 'worked' only after the asset was checked as above, 'worked_with_fixes' with the deviation, 'wrong'/'outdated'/'incomplete' when the entry misled you.",
+        ],
+    };
+}
 export function renderAgentPlaybook(options = {}) {
     return JSON.stringify(buildAgentPlaybook(options), null, 2);
 }