summer-engine 3.8.0 → 4.0.0

package/dist/cli/commands/ops.d.ts

@@ -0,0 +1,47 @@
+import { Command } from "commander";
+import { type HostedCall } from "../../core/ops/cloud.js";
+import { type Answer } from "../../core/ops/contract.js";
+import { FileSaver } from "../../core/ops/save-files.js";
+import { dispatchTool } from "../../core/capabilities/tool-dispatch.js";
+/**
+ * The CLI view of the operation catalog (on by default; SUMMER_SURFACE=v3 leaves it out):
+ *
+ *   summer <area> <action> [--<field> <value> ...] [--input '<json>'] [--dry-run] [--idempotency-key <k>] [--wait] [--json]
+ *   summer whoami
+ *   summer ops search <words...> | summer ops describe <op>
+ *
+ * Engine and local operations run in this process (the same functions
+ * `summer tool` runs); cloud operations run on the hosted Summer server
+ * through its summer_call, with the person's sign-in.
+ */
+/** Areas with operations today; CLI command words stay out of this list. */
+export declare const CLI_AREAS: readonly ["team", "profile", "docs", "assets", "makers", "jobs", "projects", "plans", "games", "store", "jams", "pricing", "analytics", "experiments", "marketing", "players", "economy", "inbox", "apps", "studio", "chats", "stories", "plugins", "engine", "account"];
+type JsonSchema = {
+    type?: string | string[];
+    properties?: Record<string, JsonSchema>;
+    items?: JsonSchema;
+};
+export interface ParsedCall {
+    input: Record<string, unknown>;
+    json: boolean;
+    dryRun: boolean;
+    wait: boolean;
+    idempotencyKey?: string;
+}
+/** `--max-items 3 --tag a --tag b --no-loop` -> `{ maxItems: 3, tag: ["a", "b"], loop: false }`, typed by the schema. */
+export declare function parseCallFlags(argv: readonly string[], schema: JsonSchema | null): ParsedCall;
+export interface OpsCliDeps {
+    hosted: HostedCall;
+    dispatch: typeof dispatchTool;
+    print: (text: string) => void;
+    printError: (text: string) => void;
+    /** Saves generated files (`--out`, else the project's asset folder). Default: a new FileSaver per run. */
+    files?: FileSaver;
+}
+export declare const defaultOpsCliDeps: OpsCliDeps;
+/** The answer for a person; `out` is the --out to keep in the printed wait command. */
+export declare function formatAnswer(answer: Answer, out?: string): string;
+/** Run one operation from the command line and print its answer; returns the exit code. */
+export declare function runOpFromCli(op: string, argv: readonly string[], deps?: OpsCliDeps): Promise<number>;
+export declare function opsCliCommands(): Command[];
+export {};

package/dist/cli/commands/ops.js

@@ -0,0 +1,301 @@
+import { Command } from "commander";
+import { localEntries, localInputSchema, localWireForm, missingInput } from "../../core/ops/catalog.js";
+import { answerOfHosted, callHostedV4, hostedCallFailure, searchEverywhere } from "../../core/ops/cloud.js";
+import { errorAnswer, isLocalOp, localToolsFor, opFromCli, OP_NAME } from "../../core/ops/contract.js";
+import { ENGINE_SPLIT_OPS, engineOpDef, splitToolArgs } from "../../core/ops/engine.js";
+import { engineFailure, engineNotRunning } from "../../core/ops/engine-answer.js";
+import { loadLibraryIndex } from "../../core/library-search.js";
+import { FileSaver, withOutField } from "../../core/ops/save-files.js";
+import { dispatchTool, EngineUnavailableError, ToolResultError } from "../../core/capabilities/tool-dispatch.js";
+/**
+ * The CLI view of the operation catalog (on by default; SUMMER_SURFACE=v3 leaves it out):
+ *
+ *   summer <area> <action> [--<field> <value> ...] [--input '<json>'] [--dry-run] [--idempotency-key <k>] [--wait] [--json]
+ *   summer whoami
+ *   summer ops search <words...> | summer ops describe <op>
+ *
+ * Engine and local operations run in this process (the same functions
+ * `summer tool` runs); cloud operations run on the hosted Summer server
+ * through its summer_call, with the person's sign-in.
+ */
+/** Areas with operations today; CLI command words stay out of this list. */
+export const CLI_AREAS = [
+    "team", "profile", "docs", "assets", "makers", "jobs", "projects", "plans", "games", "store", "jams", "pricing",
+    "analytics", "experiments", "marketing", "players", "economy", "inbox", "apps", "studio", "chats", "stories",
+    "plugins", "engine", "account",
+];
+const RESERVED_FLAGS = new Set(["json", "dry-run", "wait", "idempotency-key", "input"]);
+const camel = (flag) => flag.replace(/-([a-z0-9])/g, (_match, letter) => letter.toUpperCase());
+/** A flag's field: camelCase (`--scene-path` is scenePath), or snake_case when the schema names it so (`--look-at` is look_at). */
+function fieldName(flag, schema) {
+    const snake = flag.replace(/-/g, "_");
+    return snake !== flag && schema?.properties?.[snake] && !schema.properties[camel(flag)] ? snake : camel(flag);
+}
+function coerce(value, schema) {
+    const type = Array.isArray(schema?.type) ? schema?.type[0] : schema?.type;
+    if (value === true)
+        return true;
+    if (type === "number" || type === "integer")
+        return Number(value);
+    if (type === "boolean")
+        return value === "true";
+    if (type === "string")
+        return value;
+    if (type === "object" || type === "array") {
+        try {
+            return JSON.parse(value);
+        }
+        catch {
+            return type === "array" ? value.split(",") : value;
+        }
+    }
+    return /^(-?\d+(\.\d+)?|true|false)$/.test(value) ? JSON.parse(value) : value;
+}
+/** `--max-items 3 --tag a --tag b --no-loop` -> `{ maxItems: 3, tag: ["a", "b"], loop: false }`, typed by the schema. */
+export function parseCallFlags(argv, schema) {
+    const out = { input: {}, json: false, dryRun: false, wait: false };
+    const fields = {};
+    for (let index = 0; index < argv.length; index++) {
+        const token = argv[index];
+        if (!token.startsWith("--"))
+            throw new Error(`Unexpected argument "${token}". Pass fields as --name value.`);
+        const [rawName, inline] = token.slice(2).split(/=(.*)/s, 2);
+        if (rawName === "json")
+            out.json = true;
+        else if (rawName === "dry-run")
+            out.dryRun = true;
+        else if (rawName === "wait")
+            out.wait = true;
+        else if (rawName === "idempotency-key" || rawName === "input") {
+            const value = inline ?? argv[++index];
+            if (value === undefined)
+                throw new Error(`--${rawName} needs a value.`);
+            if (rawName === "input") {
+                const parsed = JSON.parse(value);
+                if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+                    throw new Error("--input must be a JSON object.");
+                Object.assign(out.input, parsed);
+            }
+            else
+                out.idempotencyKey = value;
+        }
+        else if (rawName.startsWith("no-") && !RESERVED_FLAGS.has(rawName)) {
+            fields[fieldName(rawName.slice(3), schema)] = false;
+        }
+        else {
+            const name = fieldName(rawName, schema);
+            const next = argv[index + 1];
+            const value = inline ?? (next !== undefined && !next.startsWith("--") ? (index++, next) : true);
+            const property = schema?.properties?.[name];
+            const typed = property?.type === "array" ? coerce(value, property.items) : coerce(value, property);
+            if (property?.type === "array")
+                fields[name] = [...(fields[name] ?? []), ...(Array.isArray(typed) ? typed : [typed])];
+            else
+                fields[name] = name in fields ? [...[fields[name]].flat(), typed] : typed;
+        }
+    }
+    out.input = { ...out.input, ...fields };
+    return out;
+}
+export const defaultOpsCliDeps = {
+    hosted: (name, args) => callHostedV4(name, args),
+    dispatch: dispatchTool,
+    print: (text) => process.stdout.write(`${text}\n`),
+    printError: (text) => process.stderr.write(`${text}\n`),
+};
+/** The docs.read id of a local tool's guide (tool/<slug>). */
+function guideOf(toolName) {
+    const entry = loadLibraryIndex().find((candidate) => candidate.kind === "tool" && candidate.mcp_tool_name === toolName);
+    return entry?.id;
+}
+async function runLocal(op, call, deps) {
+    // A split operation runs its 3.x tool with the action fixed (core/ops/engine.ts).
+    const split = ENGINE_SPLIT_OPS[op];
+    const entry = localEntries().find((candidate) => candidate.name === op);
+    const tool = split?.tool ?? entry?.mcpTool ?? localToolsFor(op)[0];
+    if (!tool)
+        return errorAnswer("not_found", `No operation is named "${op}".`, { next: { op: "ops.search", input: { query: op } } });
+    const args = split ? splitToolArgs(split, call.input) : call.input;
+    const def = engineOpDef(op);
+    const guide = guideOf(tool);
+    const describe = guide && def ? { op: "docs.read", input: { id: guide } } : { op: "ops.describe", input: { name: op } };
+    const missing = missingInput(localInputSchema(op), call.input);
+    if (missing)
+        return errorAnswer("invalid_input", missing, { next: describe });
+    if (call.dryRun) {
+        return { ok: true, status: "dry_run", preview: { summary: `${entry?.title ?? op}: the input is valid. Nothing was done.`, changes: [], approval: entry?.approval ?? "none", estimate: null, valid: true } };
+    }
+    try {
+        return { ok: true, status: "done", result: await deps.dispatch(tool, args) };
+    }
+    catch (error) {
+        if (error instanceof EngineUnavailableError)
+            return engineNotRunning();
+        if (error instanceof ToolResultError) {
+            return def ? engineFailure(JSON.stringify(error.result), op, { effect: def.effect, guide }) : errorAnswer("invalid_input", error.message, { details: { tool: error.result } });
+        }
+        return errorAnswer("invalid_input", error instanceof Error ? error.message : String(error), { next: describe });
+    }
+}
+async function runCloud(op, call, deps) {
+    try {
+        return answerOfHosted(await deps.hosted("summer_call", { op, input: call.input, ...(call.dryRun ? { dryRun: true } : {}), ...(call.idempotencyKey ? { idempotencyKey: call.idempotencyKey } : {}) }));
+    }
+    catch (error) {
+        return hostedCallFailure(error, { op, dryRun: call.dryRun, idempotencyKey: call.idempotencyKey });
+    }
+}
+/** The input schema used to type flags: the local descriptor, or the hosted ops.describe. */
+async function schemaFor(op, deps) {
+    if (isLocalOp(op))
+        return localInputSchema(op);
+    const answer = await runCloud("ops.describe", { input: { name: op }, json: true, dryRun: false, wait: false }, deps);
+    const input = answer.ok && answer.status === "done" ? answer.result.operation?.input : undefined;
+    return input ? withOutField(op, input) : null;
+}
+/** Failed waits the job itself does not cause: the call to Summer did not get through. */
+const WAIT_DID_NOT_GET_THROUGH = new Set(["unavailable", "outcome_unknown", "not_signed_in", "forbidden", "rate_limited"]);
+/** Follow a running job or an approval until it ends (jobs.wait, at most 50 s per call). */
+async function waitFor(answer, deps) {
+    let current = answer;
+    if (current.ok && current.status === "needs_approval")
+        deps.printError(`Waiting for approval: ${current.approval.url}`);
+    for (let round = 0; round < 120 && current.ok && (current.status === "running" || current.status === "needs_approval"); round++) {
+        const job = current.job.id;
+        const waited = await runCloud("jobs.wait", { input: { jobId: job, timeoutSeconds: 50 }, json: true, dryRun: false, wait: false }, deps);
+        // The job runs on whatever the wait answered: a failed wait names it, so the job is waited on, not started again.
+        // One that did not get through says to wait again; any other keeps its own next step (sign in, slow down).
+        if (!waited.ok && WAIT_DID_NOT_GET_THROUGH.has(waited.error.code)) {
+            const { code, message, retry, next, details } = waited.error;
+            return errorAnswer(code, `${message} Job ${job} is still on Summer's server.`, {
+                retry,
+                next: code === "unavailable" ? { op: "jobs.wait", input: { jobId: job } } : next,
+                details: { ...details, job },
+            });
+        }
+        if (!waited.ok || waited.status !== "done")
+            return waited;
+        const result = waited.result;
+        if (!result.finished)
+            continue;
+        // An approved generation runs on as its own job: follow that job.
+        const chained = result.job.result;
+        if (result.job.state === "done" && chained?.status === "running" && chained.job?.id) {
+            current = { ok: true, status: "running", job: chained.job };
+            continue;
+        }
+        if (result.job.state === "done")
+            return { ok: true, status: "done", result: result.job.result ?? {} };
+        return errorAnswer(result.job.state === "failed" ? "invalid_input" : "conflict", result.job.error?.message ?? `The job ended: ${result.job.state}.`, { details: { job } });
+    }
+    return current;
+}
+/** A value as one shell word: single quotes, so the shell expands nothing in it. */
+const shellWord = (value) => (/^[\w./:@+=-]+$/.test(value) ? value : `'${value.replace(/'/g, `'\\''`)}'`);
+/** The answer for a person; `out` is the --out to keep in the printed wait command. */
+export function formatAnswer(answer, out) {
+    const waitFlags = (id) => `summer jobs wait --job-id ${id}${out ? ` --out ${shellWord(out)}` : ""}`;
+    if (!answer.ok) {
+        const next = answer.error.next;
+        const step = !next ? "" : "op" in next ? `\nNext: ${next.op}` : "url" in next ? `\nNext: ${next.label}: ${next.url}` : `\nNext: ${next.say}`;
+        return `Error (${answer.error.code}): ${answer.error.message}${step}`;
+    }
+    switch (answer.status) {
+        case "done":
+            return JSON.stringify(answer.result, null, 2);
+        case "running":
+            return `Started: job ${answer.job.id}. Wait for it: ${waitFlags(answer.job.id)}`;
+        case "needs_approval":
+            return `Needs approval (${answer.approval.who}): ${answer.approval.summary}\n${answer.approval.url}\nNothing changes until they approve. Follow it: ${waitFlags(answer.job.id)}`;
+        case "dry_run":
+            return `Dry run: ${String(answer.preview.summary ?? "")}\n${JSON.stringify(answer.preview, null, 2)}`;
+    }
+}
+/** Run one operation from the command line and print its answer; returns the exit code. */
+export async function runOpFromCli(op, argv, deps = defaultOpsCliDeps) {
+    if (!OP_NAME.test(op)) {
+        deps.printError(formatAnswer(errorAnswer("invalid_input", `"${op}" is not an operation name (area action).`, { next: { op: "ops.search" } })));
+        return 1;
+    }
+    let call;
+    try {
+        const hasFields = argv.some((token) => token.startsWith("--") && !RESERVED_FLAGS.has(token.slice(2).split("=")[0]));
+        call = parseCallFlags(argv, hasFields ? await schemaFor(op, deps) : null);
+    }
+    catch (error) {
+        deps.printError(formatAnswer(errorAnswer("invalid_input", error instanceof Error ? error.message : String(error))));
+        return 1;
+    }
+    let answer;
+    let out;
+    if (isLocalOp(op)) {
+        answer = await runLocal(op, call, deps);
+        if (call.wait)
+            answer = await waitFor(answer, deps);
+    }
+    else {
+        // --out stays here: the files save on this machine once the answer (or the waited job) names them.
+        const files = deps.files ?? new FileSaver({ saveByDefault: true });
+        const taken = files.take(op, call.input);
+        out = taken.out;
+        answer = await runCloud(op, { ...call, input: taken.input }, deps);
+        if (call.wait)
+            answer = await waitFor(answer, deps);
+        answer = await files.finish(op, answer, out);
+    }
+    (answer.ok ? deps.print : deps.printError)(call.json ? JSON.stringify(answer) : formatAnswer(answer, out));
+    if (!call.json && answer.ok)
+        for (const warning of answer.warnings ?? [])
+            deps.printError(`Warning: ${warning}`);
+    return answer.ok ? 0 : 1;
+}
+function areaCommand(area) {
+    return new Command(area)
+        .description(`Summer ${area} operations: summer ${area} <action> --field value. Find them: summer ops search ${area}`)
+        .argument("<action>", "The operation's action, e.g. list or set-base")
+        .allowUnknownOption(true)
+        .allowExcessArguments(true)
+        .helpOption(false)
+        .action(async (action, _options, command) => {
+        process.exitCode = await runOpFromCli(opFromCli(area, action), command.args.slice(1));
+    });
+}
+export function opsCliCommands() {
+    const whoami = new Command("whoami")
+        .description("Who is signed in, and their credits")
+        .allowUnknownOption(true)
+        .allowExcessArguments(true)
+        .action(async (_options, command) => {
+        process.exitCode = await runOpFromCli("whoami", command.args);
+    });
+    const ops = new Command("ops").description("Find and describe Summer operations");
+    ops
+        .command("search <words...>")
+        .description("Find operations by describing the job in plain words")
+        .option("--area <area>", "Only this area")
+        .option("--limit <n>", "Most results", "8")
+        .option("--json", "Print the answer as JSON")
+        .action(async (wordsArg, options) => {
+        const { items, warning } = await searchEverywhere(wordsArg.join(" "), { area: options.area, limit: Number(options.limit) || 8 }, defaultOpsCliDeps.hosted);
+        if (options.json) {
+            defaultOpsCliDeps.print(JSON.stringify({ ok: true, status: "done", result: { items }, ...(warning ? { warnings: [warning] } : {}) }));
+            return;
+        }
+        for (const item of items)
+            defaultOpsCliDeps.print(`${item.name.padEnd(32)} ${item.effect.padEnd(13)} ${item.title}`);
+        if (warning)
+            defaultOpsCliDeps.printError(warning);
+    });
+    ops
+        .command("describe <op>")
+        .description("Show one operation with its exact input")
+        .action(async (op) => {
+        const local = localWireForm(op);
+        if (local) {
+            defaultOpsCliDeps.print(JSON.stringify(local, null, 2));
+            return;
+        }
+        process.exitCode = await runOpFromCli("ops.describe", ["--name", op]);
+    });
+    return [whoami, ops, ...CLI_AREAS.map(areaCommand)];
+}

package/dist/cli/commands/setup.d.ts

@@ -1,2 +1,4 @@
 import { Command } from "commander";
 export declare const setupCommand: Command;
+/** One line instead of a row per three skills: the first few names and how many more. `--json` keeps the full list. */
+export declare function skillNamesSample(names: readonly string[], max?: number): string;

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 {};