summer-engine 4.3.0 → 4.5.0

package/dist/core/usage-fields.js

@@ -0,0 +1,150 @@
+/**
+ * The extra fields a usage line (telemetry.ts, cli-usage.ts) can carry. Each
+ * is a closed shape checked here, so nothing a person typed, no path and no
+ * project or file name can reach one:
+ *
+ * - `projectIdHash`: the engine's own project id hash (sha256 of the random
+ *   id Summer Engine keeps in `.summer/local/.project_id`), the same value
+ *   Summer already uses to route requests to a project. Not the name or path.
+ * - `templateId`, `templateTags`: the library template a project started
+ *   from (`.summer/project.json`) and that template's library domains
+ *   (`facets.domains`, e.g. `2d`, `platformer`). Only ids from the shipped
+ *   catalog; anything else is left out.
+ * - `instanceCount`: how many game clients `engine.play` started.
+ * - `engineState`: four yes/no answers when a call failed with
+ *   `engine_not_running` (is the app installed, is an editor running, is one
+ *   holding a project, is the person signed in), from local files only.
+ */
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { currentToolContext } from "./agent-host.js";
+import { hasEnvAuthToken } from "./auth.js";
+import { listEngineInstances } from "./engine.js";
+import { findEngineBinary } from "./engine-install.js";
+import { loadLibraryIndex } from "./library-search.js";
+import { getSummerDir } from "./store.js";
+import { getTemplateRegistry } from "./templates.js";
+import { readProjectManifest } from "../project-memory/project-manifest.js";
+const HASH = /^[0-9a-f]{16,128}$/;
+const SLUG = /^[a-z0-9][a-z0-9-]{0,63}$/;
+const MAX_TAGS = 8;
+/** Only the closed shapes above survive; everything else is dropped. */
+export function cleanUsageFields(fields) {
+    const out = {};
+    if (typeof fields.projectIdHash === "string" && HASH.test(fields.projectIdHash))
+        out.projectIdHash = fields.projectIdHash;
+    if (typeof fields.templateId === "string" && SLUG.test(fields.templateId))
+        out.templateId = fields.templateId;
+    if (Array.isArray(fields.templateTags)) {
+        const tags = fields.templateTags.filter((tag) => typeof tag === "string" && SLUG.test(tag)).slice(0, MAX_TAGS);
+        if (tags.length)
+            out.templateTags = tags;
+    }
+    if (typeof fields.instanceCount === "number" && Number.isInteger(fields.instanceCount) && fields.instanceCount >= 0 && fields.instanceCount <= 64) {
+        out.instanceCount = fields.instanceCount;
+    }
+    return out;
+}
+// One command per CLI process: its line reads these at exit (cli-usage.ts).
+let processNotes = {};
+let boundProjectIdHash;
+/** A tool or command noted fields for its usage line; never throws. */
+export function noteToolUsage(fields) {
+    try {
+        const clean = cleanUsageFields(fields);
+        const context = currentToolContext();
+        if (context)
+            Object.assign(context.usage, clean);
+        Object.assign(processNotes, clean);
+    }
+    catch {
+        // usage is best-effort
+    }
+}
+/** The fields noted in this process (the CLI line), with the bound project. */
+export function processUsageFields() {
+    return { ...(boundProjectIdHash ? { projectIdHash: boundProjectIdHash } : {}), ...processNotes };
+}
+/** The engine connection bound this project (api-client.ts connect and rebind). */
+export function noteBoundProject(projectIdHash) {
+    boundProjectIdHash = typeof projectIdHash === "string" && HASH.test(projectIdHash) ? projectIdHash : undefined;
+}
+export function boundProject() {
+    return boundProjectIdHash;
+}
+/** The library slug for a catalog template id or slug, else null. */
+export function catalogTemplateSlug(idOrSlug) {
+    try {
+        const entry = getTemplateRegistry().find((template) => template.id === idOrSlug || template.slug === idOrSlug);
+        return entry ? entry.slug : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** A catalog template's library domains (`facets.domains`), e.g. ["2d", "platformer"]. */
+export function templateTags(slug) {
+    try {
+        const entry = loadLibraryIndex().find((resource) => resource.id === `template/${slug}`);
+        return (entry?.facets?.domains ?? []).filter((tag) => SLUG.test(tag)).slice(0, MAX_TAGS);
+    }
+    catch {
+        return [];
+    }
+}
+const templateByHash = new Map();
+/**
+ * The catalog template the project with this hash started from: the running
+ * editor's registry entry gives its folder, `.summer/project.json` the
+ * template. Cached per hash; null when unknown or not a catalog template.
+ */
+export async function templateForProject(projectIdHash) {
+    if (templateByHash.has(projectIdHash))
+        return templateByHash.get(projectIdHash) ?? null;
+    let slug = null;
+    try {
+        const instance = (await listEngineInstances()).find((entry) => entry.projectIdHash === projectIdHash);
+        const id = instance ? readProjectManifest(instance.resourceRoot)?.template?.id : undefined;
+        slug = typeof id === "string" ? catalogTemplateSlug(id) : null;
+    }
+    catch {
+        slug = null;
+    }
+    templateByHash.set(projectIdHash, slug);
+    return slug;
+}
+/** What is true on this machine when the engine could not be reached. Local files only. */
+export async function engineState() {
+    const instances = await listEngineInstances(Date.now(), getSummerDir(), { anyHeartbeat: true }).catch(() => []);
+    return {
+        desktopInstalled: findEngineBinary() !== null,
+        engineRunning: instances.length > 0,
+        projectOpen: instances.some((instance) => !!instance.projectIdHash),
+        signedIn: hasEnvAuthToken() || existsSync(join(getSummerDir(), "auth-token")),
+    };
+}
+/**
+ * The extra fields of one usage line: what the call noted, else the bound
+ * project and its template, and the engine state for engine_not_running.
+ * Never throws.
+ */
+export async function usageLineFields(noted, error) {
+    try {
+        const fields = cleanUsageFields(noted);
+        if (fields.projectIdHash && !fields.templateId) {
+            const template = await templateForProject(fields.projectIdHash);
+            if (template)
+                fields.templateId = template;
+        }
+        return { ...fields, ...(error === "engine_not_running" ? { engineState: await engineState() } : {}) };
+    }
+    catch {
+        return {};
+    }
+}
+/** Test-only: forget notes, the bound project and the template cache. */
+export function _resetUsageFieldsForTests() {
+    processNotes = {};
+    boundProjectIdHash = undefined;
+    templateByHash.clear();
+}

package/dist/core/util/sleep.d.ts

@@ -1 +1,4 @@
 export declare function sleep(ms: number): Promise<void>;
+/** Whether `promise` settles within `ms`. The timer is cleared when it does,
+ *  so a quick answer never keeps a CLI process alive for the full wait. */
+export declare function settlesWithin(promise: Promise<unknown>, ms: number): Promise<boolean>;

package/dist/core/util/sleep.js

@@ -1,3 +1,15 @@
 export function sleep(ms) {
     return new Promise((resolveSleep) => setTimeout(resolveSleep, ms));
 }
+/** Whether `promise` settles within `ms`. The timer is cleared when it does,
+ *  so a quick answer never keeps a CLI process alive for the full wait. */
+export function settlesWithin(promise, ms) {
+    return new Promise((resolveWithin) => {
+        const timer = setTimeout(() => resolveWithin(false), ms);
+        const done = () => {
+            clearTimeout(timer);
+            resolveWithin(true);
+        };
+        promise.then(done, done);
+    });
+}

package/dist/mcp/ops-surface.js

@@ -4,7 +4,7 @@ import { localEntries, localInputSchema, localWireForm, missingInput } from "../
 import { answerOfHosted, describeFromShipped, hostedCallFailure, searchEverywhere } from "../core/ops/cloud.js";
 import { errorAnswer, isLocalOp, legacyNames, localToolsFor, mcpNameOf, resolveOpName } from "../core/ops/contract.js";
 import { ENGINE_SPLIT_OPS, engineOpDef, isSplitOp, renderOpRefs, splitToolArgs } from "../core/ops/engine.js";
-import { answerOfEngineResult, engineFailure, textsOf } from "../core/ops/engine-answer.js";
+import { answerOfEngineResult, codedLocalFailure, engineFailure, textsOf } from "../core/ops/engine-answer.js";
 import { TAKES_OUT, withOutField } from "../core/ops/save-files.js";
 import { loadLibraryIndex } from "../core/library-search.js";
 import { FOOTER_SUFFIX } from "../core/library-read.js";
@@ -32,7 +32,8 @@ export const SUMMER_CALL = "summer_call";
 export const OPS_MCP_INSTRUCTIONS = "Summer Engine MCP, operation catalog. Call summer_get_project_context first when Summer Engine is open. " +
     "Listed tools are the common jobs; for anything else, summer_search describes the job in words and returns the operation and its exact input, then summer_call runs it. " +
     "More than 3 scene edits: one summer_run_script with scenePath. Each engine tool's full guide: summer_docs_read. Long work answers with a job: jobs.wait. " +
-    "Publishing, prices and other live changes answer needs_approval with a link: give it to the person; nothing changes until they approve.";
+    "Going live: skill/release-checklist, then store.go_live with the person's yes; a game is live once Summer's automated checks pass, so never tell anyone to wait for a review. Prices and other live changes may answer needs_approval with a link: give it to the person. " +
+    "Opening the Summer editor and playing the game in a window is allowed and expected: summer_play, then summer_screenshot or summer_frame_shot to see it; close what you opened, one editor at a time.";
 /** The assets profile's version: no engine tools, so it names none. */
 export const OPS_MCP_ASSETS_INSTRUCTIONS = "Summer MCP, assets profile, operation catalog: generation and the Summer asset library, no engine tools. " +
     "Read skill/summer-assets with summer_docs_read, then the asset's skill: stop at the file, skip its engine steps. " +
@@ -43,6 +44,8 @@ const DOCS_ALIASES = [
     ["summer_docs_search", "summer_search_library"],
     ["summer_docs_read", "summer_read_library"],
 ];
+/** Local operations listed with the engine tools: they create and open the project the engine tools need, with no shell. */
+const LOCAL_PROJECT_TOOLS = ["summer_projects_create_local", "summer_projects_open_local"];
 /** Listed with the engine tools although its operation is docs.engine_api: the offline engine class reference. */
 const ENGINE_REFERENCE = "summer_api_docs";
 /** Its v4 description, within the 300-character summary rule; the full text stays on the 3.x surface. */
@@ -89,6 +92,9 @@ function answerOfLocal(result, op, effect) {
     }
     if (record.isError) {
         const body = (payload && typeof payload === "object" ? payload : {});
+        const coded = codedLocalFailure(body);
+        if (coded)
+            return coded;
         const message = typeof body.message === "string" ? body.message : typeof body.error === "string" ? body.error : first.slice(0, 500) || "The tool failed.";
         const details = { tool: payload };
         if (/not found|does not exist|no such/i.test(message))
@@ -236,6 +242,26 @@ export function applyOpsSurface(server, options) {
             }),
         });
     }
+    // projects.create_local and projects.open_local: the one answer shape, like the engine tools.
+    const localProjectTools = options.engine ? LOCAL_PROJECT_TOOLS.filter((name) => tools[name] && entries.has(names[name]?.op ?? "")) : [];
+    for (const name of localProjectTools)
+        listed.add(name);
+    for (const name of localProjectTools) {
+        const tool = tools[name];
+        const op = names[name].op;
+        const entry = entries.get(op);
+        const handler = tool.handler;
+        rawHandlers.set(name, handler);
+        tool.update({
+            title: entry.title,
+            description: renderOpRefs(entry.summary, toolOf),
+            annotations: annotationsForEffect(entry.effect === "read" ? "read" : "write", Boolean(facts.get(name)?.network), entry.title),
+            callback: (async (...args) => {
+                const raw = await handler(...args);
+                return toolResult(answerOfLocal(raw, op, "write"), raw);
+            }),
+        });
+    }
     // Operations split out of a mixed 3.x tool: their own tool, the 3.x handler with the action fixed.
     for (const [op, def] of Object.entries(ENGINE_SPLIT_OPS)) {
         const base = tools[def.tool];

package/dist/mcp/server.d.ts

@@ -13,16 +13,26 @@ export declare const getCachedBootDriftNotice: typeof getCachedNotice;
  * session, before any tool call — the place for the habits end-to-end runs
  * showed an agent needs on the first turn and would otherwise learn the hard
  * way, including scripting a run of scene edits instead of hundreds of single
- * calls. Kept under 600 characters so it costs a few hundred tokens once; the
+ * calls. Kept under 800 characters so it costs a few hundred tokens once; the
  * full operating guide stays in the summer_agent_playbook prompt /
- * summer_get_agent_playbook tool. The last sentence names the publishing path,
- * the owner-approval rule and where review feedback is read.
+ * summer_get_agent_playbook tool. The publish sentence names the publishing
+ * path, the user's confirmation and that going live has no staff wait; the last
+ * says an agent may open the editor and play the game in a window.
  */
 export declare const SUMMER_MCP_INSTRUCTIONS: string;
 /** The same first-turn habits for a profile without engine tools (`--profile assets`). */
 export declare const SUMMER_MCP_ASSETS_INSTRUCTIONS: string;
 export declare function configureMcpEngineSelection(selection?: EngineSelection): void;
-export declare function getClient(): Promise<EngineApiClient>;
+/** The session's editor selection (projects.open_local opens its project). */
+export declare function currentMcpEngineSelection(): EngineSelection | undefined;
+/** Bind the session to the project projects.open_local opened, with the client it connected. */
+export declare function bindMcpProject(projectRoot: string, client: EngineApiClient): void;
+/** The step's log lines go to the MCP log and stderr, never stdout (the protocol). */
+export declare function logEngineSelfStart(line: string): void;
+/** `launch: false`: connect only, never open the editor (summer_open lists and prints with no side effects). */
+export declare function getClient(options?: {
+    launch?: boolean;
+}): Promise<EngineApiClient>;
 export declare function resetClient(): void;
 /**
  * Build the MCP server with every Summer tool of the selected profile

package/dist/mcp/server.js

@@ -9,6 +9,7 @@ import { registerAuditTools } from "./tools/audit-tools.js";
 import { WITH_ENGINE_META } from "./tools/with-engine.js";
 import { registerPlaybookPrompt, registerProjectTools, } from "./tools/project-tools.js";
 import { registerPerceptionTools } from "./tools/perception-tools.js";
+import { registerLocalProjectTools } from "./tools/local-project-tools.js";
 import { registerSpatialTools } from "./tools/spatial-tools.js";
 import { registerPlacementTools } from "./tools/placement-tools.js";
 import { registerScriptTools } from "./tools/script-tools.js";
@@ -39,10 +40,12 @@ import { refreshInstalledSkills, refreshNotice } from "../installer/skills-refre
 import { OUTPUT_CAPS, PROFILE_TOOL_LIMIT, PROFILES, TOOLSETS, annotationsFor, registryAuthorities, resolveToolSelection, selectionIncludes, withMaxCharactersArg, } from "./tool-surface.js";
 import { shapeToolResult, singleEditCounter } from "./tool-results.js";
 import { recordLocalToolCall, recordMcpSession, toolErrorCode } from "../core/telemetry.js";
+import { boundProject } from "../core/usage-fields.js";
 import { currentToolContext, registerMcpClientSource, runWithToolContext } from "../core/agent-host.js";
 import { buildBootDriftNotice, fetchLatestRegistryVersion, } from "../installer/version-check.js";
 import { TOOLKIT_VERSION as version } from "../core/version.js";
 import { ENGINE_FREE_NOTE, engineNotRunningFromConnectError } from "../core/error-codes.js";
+import { selfStartEngine } from "../core/engine-self-start.js";
 import { resolveSurface } from "../core/tool-profiles.js";
 import { OAuthError } from "../core/oauth.js";
 let processDiagnosticsInstalled = false;
@@ -54,10 +57,11 @@ export const getCachedBootDriftNotice = getCachedNotice;
  * session, before any tool call — the place for the habits end-to-end runs
  * showed an agent needs on the first turn and would otherwise learn the hard
  * way, including scripting a run of scene edits instead of hundreds of single
- * calls. Kept under 600 characters so it costs a few hundred tokens once; the
+ * calls. Kept under 800 characters so it costs a few hundred tokens once; the
  * full operating guide stays in the summer_agent_playbook prompt /
- * summer_get_agent_playbook tool. The last sentence names the publishing path,
- * the owner-approval rule and where review feedback is read.
+ * summer_get_agent_playbook tool. The publish sentence names the publishing
+ * path, the user's confirmation and that going live has no staff wait; the last
+ * says an agent may open the editor and play the game in a window.
  */
 export const SUMMER_MCP_INSTRUCTIONS = "Summer Engine MCP. Call summer_get_project_context first: it binds the open project. " +
     "Before building or fixing: summer_search_library, then summer_read_library the hit. " +
@@ -65,7 +69,8 @@ export const SUMMER_MCP_INSTRUCTIONS = "Summer Engine MCP. Call summer_get_proje
     "After play: summer_get_diagnostics, not only summer_get_console. " +
     "All-black screenshot: no redraw yet, recapture. " +
     "Report verified entries via summer_library_feedback. " +
-    "Publish: summer_export_game, summer_publish_build, summer_store_*; never alone: summer_store_submit returns the owner's approval link, summer_store_review the feedback.";
+    "Publish: summer_export_game, summer_publish_build, skill/release-checklist, summer_go_live, each confirmed. Live once automated checks pass: never say wait for review. " +
+    "Opening the editor and playing the game in a window is allowed and expected: summer_play, then summer_screenshot or summer_frame_shot; close what you opened, one editor at a time.";
 /** The same first-turn habits for a profile without engine tools (`--profile assets`). */
 export const SUMMER_MCP_ASSETS_INSTRUCTIONS = "Summer MCP, assets profile: generation and the Summer asset library, no engine tools. " +
     "Read skill/summer-assets, then the asset's skill (sound-effect, prop-model, ...): stop at the file, skip its engine steps. " +
@@ -90,7 +95,22 @@ export function configureMcpEngineSelection(selection) {
     engineSelection = selection ? { ...selection } : undefined;
     cachedClient = null;
 }
-export async function getClient() {
+/** The session's editor selection (projects.open_local opens its project). */
+export function currentMcpEngineSelection() {
+    return engineSelection ? { ...engineSelection } : undefined;
+}
+/** Bind the session to the project projects.open_local opened, with the client it connected. */
+export function bindMcpProject(projectRoot, client) {
+    engineSelection = { cwd: projectRoot };
+    cachedClient = client;
+}
+/** The step's log lines go to the MCP log and stderr, never stdout (the protocol). */
+export function logEngineSelfStart(line) {
+    appendMcpLogEvent("mcp:engine_self_start", { line });
+    writeMcpStderr("mcp:engine_self_start", { line });
+}
+/** `launch: false`: connect only, never open the editor (summer_open lists and prints with no side effects). */
+export async function getClient(options = {}) {
     // Opt-in per-project routing (editor -> live worker -> spawned worker).
     // OFF by default: with the flag unset this block is skipped entirely and
     // src/core/headless/ is never even loaded (dynamic import). With the flag
@@ -129,8 +149,14 @@ export async function getClient() {
         // (engine_not_running). Anything else (several editors open, …) already
         // says how to pick one.
         const notRunning = engineNotRunningFromConnectError(reason);
-        if (notRunning)
+        if (notRunning && options.launch === false)
             throw notRunning;
+        if (notRunning) {
+            // Open the session's project ourselves when we can, else a coded
+            // error with the one command that gets there (core/engine-self-start.ts).
+            cachedClient = await selfStartEngine(engineSelection, notRunning, { log: logEngineSelfStart });
+            return cachedClient;
+        }
         throw new Error(reason + "\n" +
             "Open the intended project in Summer Engine, or run: npx -y summer-engine@latest run <project-path>\n" +
             "Note: " + ENGINE_FREE_NOTE);
@@ -235,14 +261,21 @@ function installToolCallWrapper(server, surfaceMeta) {
             // A tool another tool runs (summer_call, a v4 operation over its 3.x
             // tool) is part of that call: only the outer call sends a usage line.
             const nested = currentToolContext() !== undefined;
+            // What the call notes for its line (core/usage-fields.ts), shared with any tool it runs.
+            let noted = {};
             const recordUsage = (ok, durationMs, error) => {
+                const bound = boundProject();
+                const usage = { ...(bound ? { projectIdHash: bound } : {}), ...noted };
                 if (!nested)
-                    recordLocalToolCall({ tool: name, op: knownOp(opForToolCall(name, handlerArgs[0])), ...surfaceMeta, ok, durationMs, mcpClient: hostApp(), error });
+                    recordLocalToolCall({ tool: name, op: knownOp(opForToolCall(name, handlerArgs[0])), ...surfaceMeta, ok, durationMs, mcpClient: hostApp(), error, usage });
             };
             let result;
             try {
                 // Every Summer request the tool makes names it (core/agent-host.ts).
-                result = await runWithToolContext(name, "mcp", () => handler(...handlerArgs));
+                result = await runWithToolContext(name, "mcp", () => {
+                    noted = currentToolContext()?.usage ?? {};
+                    return handler(...handlerArgs);
+                });
             }
             catch (error) {
                 // A handler THROW never produced a result to classify; record it as
@@ -379,6 +412,7 @@ export function createMcpServer(selection = FULL_SELECTION, options = {}) {
     registerSeeingTools(server);
     registerAuditTools(server);
     registerProjectTools(server, { engine });
+    registerLocalProjectTools(server);
     registerFileTools(server);
     registerAssetTools(server);
     registerGenerateTools(server);

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

@@ -32,6 +32,14 @@ export declare function resolveToolSelection(options?: {
     profile?: string;
     toolsets?: string;
 }, env?: NodeJS.ProcessEnv): ToolSelection;
+/**
+ * Hosted 3.x status tools a limited profile leaves out because summer_go_live
+ * answers the same question (what players get now on each platform, and
+ * where each upload and download stands), so the local go-live tools fit
+ * under PROFILE_TOOL_LIMIT without pushing hosted store tools over it. The
+ * full profile keeps them, and store.status answers it on the v4 surface.
+ */
+export declare const SUPERSEDED_HOSTED_TOOLS: ReadonlySet<string>;
 /** True when the selection keeps this tool. */
 export declare function selectionIncludes(selection: ToolSelection, name: string, local: boolean): boolean;
 /** Every name the refinement sets mention (a test checks each is a real tool). */

package/dist/mcp/tool-surface.js

@@ -36,8 +36,11 @@ const LOCAL_TOOLSETS = {
         "summer_get_asset",
         "summer_get_asset_download_url",
     ],
-    ship: ["summer_export_game", "summer_export_templates", "summer_publish_build", "summer_capture_gameplay"],
+    ship: ["summer_export_game", "summer_export_templates", "summer_publish_build", "summer_go_live", "summer_store_set_details", "summer_capture_gameplay"],
     ui: ["summer_ui_actions", "summer_ui_activate", "summer_ui_screenshot", "summer_ui_tree"],
+    // Create and open a project on this computer with no shell (the full profile;
+    // the engine profile's clients have a shell, `summer dev`, and a tool cap).
+    projects: ["summer_projects_create_local", "summer_projects_open_local"],
 };
 const localToolset = new Map(Object.entries(LOCAL_TOOLSETS).flatMap(([set, names]) => names.map((name) => [name, set])));
 /** Hosted tool names by pattern, first match wins. Unknown names land in `other` (full only). */
@@ -99,9 +102,21 @@ export function resolveToolSelection(options = {}, env = process.env) {
         return { profile: "custom", toolsets: new Set(["core", ...extra]), ignored };
     return { profile, toolsets: new Set([...PROFILES[profile], ...extra]), ignored };
 }
+/**
+ * Hosted 3.x status tools a limited profile leaves out because summer_go_live
+ * answers the same question (what players get now on each platform, and
+ * where each upload and download stands), so the local go-live tools fit
+ * under PROFILE_TOOL_LIMIT without pushing hosted store tools over it. The
+ * full profile keeps them, and store.status answers it on the v4 surface.
+ */
+export const SUPERSEDED_HOSTED_TOOLS = new Set(["summer_store_releases", "summer_store_version_status"]);
 /** True when the selection keeps this tool. */
 export function selectionIncludes(selection, name, local) {
-    return selection.toolsets === null || selection.toolsets.has(toolsetOf(name, local));
+    if (selection.toolsets === null)
+        return true;
+    if (!local && SUPERSEDED_HOSTED_TOOLS.has(name))
+        return false;
+    return selection.toolsets.has(toolsetOf(name, local));
 }
 // ── Annotations ──────────────────────────────────────────────────────────────
 /**
@@ -139,6 +154,7 @@ const NETWORK_WRITES = new Set([
     "summer_app_report_gap",
     "summer_app_update",
     "summer_slice_asset_sheet",
+    "summer_store_set_details",
 ]);
 /** Changes that only add something new, or only touch the editor view or the running game. */
 const ADDITIVE_OR_TRANSIENT = new Set([
@@ -181,6 +197,7 @@ const ADDITIVE_OR_TRANSIENT = new Set([
 ]);
 /** Changes where a second identical call has no further effect. */
 const IDEMPOTENT_WRITES = new Set([
+    "summer_store_set_details",
     "summer_set_prop",
     "summer_set_resource_property",
     "summer_project_setting",

package/dist/mcp/tools/creator-tools.js

@@ -3,24 +3,20 @@ import { captureGameplay } from "../../core/capabilities/capture-gameplay.js";
 import { exportGame } from "../../core/capabilities/export-game.js";
 import { STORE_TARGETS } from "../../core/capabilities/export-presets.js";
 import { exportTemplates, TEMPLATE_PLATFORMS } from "../../core/capabilities/export-templates.js";
+import { goLive } from "../../core/capabilities/go-live.js";
 import { publishBuild } from "../../core/capabilities/publish-build.js";
-import { BuildToolError } from "../../core/capabilities/summer-bundle.js";
+import { AI_USES, STORE_FEATURES, setStoreDetails, SURVEY_LEVELS } from "../../core/capabilities/store-details.js";
+import { BuildToolError, buildToolFailure } from "../../core/capabilities/summer-bundle.js";
+import { syncItems } from "../../core/capabilities/sync-items.js";
+import { contentMake, contentMakeInput } from "../../core/capabilities/content-make/index.js";
 import { textJson } from "./text-json.js";
 async function creatorResult(operation) {
     try {
         return textJson(await operation());
     }
     catch (error) {
-        if (error instanceof BuildToolError) {
-            return textJson({
-                ok: false,
-                code: error.code,
-                message: error.message.replace(` ${error.recovery}`, ""),
-                recovery: error.recovery,
-                ...(error.status ? { status: error.status } : {}),
-                ...error.detail,
-            }, true);
-        }
+        if (error instanceof BuildToolError)
+            return textJson(buildToolFailure(error), true);
         return textJson({
             ok: false,
             code: "creator_request_invalid",
@@ -93,11 +89,11 @@ export function registerCreatorTools(server) {
             .optional()
             .describe("What to do after waitSeconds, in order; exactly one of press, key, action, click, drag, wait, shot per step."),
     }, async (args) => creatorResult(() => captureGameplay(args)));
-    server.tool("summer_publish_build", "Upload an export from summer_export_game to the creator's game on summer.games, through the same store upload Studio uses, straight from disk. A store bundle (format bundle): declare, upload parts, seal, wait until Summer makes the Build, name its client pack, and with publish=true approve it. A web build or native download (format download): upload it as the game's store version for its platform (web, macos-universal, windows-x64, linux-x64; read from the last export) and wait until Summer has checked it. First call with confirm=false: it checks that the game exists for this account and warns when its store page does not list the export's platforms, then returns the target (game name and id, file, digest, size, version) to show the user; set confirm only after they approve. Needs \"summer login --store\". A retry with the same file and clientVersion continues the same upload. Nothing here makes a game live: the owner approves publishing (summer_store_submit).", {
-        gameId: z.string().optional().describe("The store game id (from summer_store_list_games, or the Studio store page URL). Without it the call fails with game_required and lists your store games, or says why the store did not list them."),
+    server.tool("summer_publish_build", "Upload an export from summer_export_game to the creator's game on summer.games, through the same store upload Studio uses, straight from disk. A store bundle (format bundle): declare, upload parts, seal, wait until Summer makes the Build, name its client pack and wait for Summer's automated checks on each platform (checks: passed, or failed with the code and the fix). A web build or native download (format download): upload it as the game's store version for its platform (web, macos-universal, windows-x64, linux-x64; read from the last export) and wait until Summer has checked it. First call with confirm=false: it checks that the game exists for this account and warns when its store page does not list the export's platforms, then returns the target (game name and id, file, digest, size, version) to show the user; set confirm only after they approve. Needs \"summer login --store\". A retry with the same file and clientVersion continues the same upload. Going live is summer_go_live.", {
+        gameId: z.string().optional().describe("The store game id (from games.list, or the Studio store page URL). Without it the call fails with game_required and lists your store games, or says why the store did not list them."),
         file: z.string().optional().describe("Exported .zip. Defaults to the last summer_export_game result."),
         clientVersion: z.string().describe("Build version, vMAJOR.MINOR.PATCH (e.g. v1.0.0); a new upload needs a new version."),
-        publish: z.boolean().default(false).describe("Bundles only: also approve the Build for players. A game that has not passed review keeps it as a preview; an agent needs the owner's approval."),
+        publish: z.boolean().default(false).describe("Bundles only: also make the Build available to players once its checks pass. summer_go_live does this, the release and the store page in one step."),
         platform: z
             .enum(["web", "macos-universal", "windows-x64", "linux-x64"])
             .optional()
@@ -105,4 +101,86 @@ export function registerCreatorTools(server) {
         confirm: z.boolean().default(false).describe("Set true only after the user approves the exact upload."),
         waitSeconds: z.number().int().min(0).max(1800).optional().describe("How long to wait for Summer to make the Build (default 600). On timeout, call again to keep waiting."),
     }, async (args) => creatorResult(() => publishBuild({ ...args, face: "mcp" })));
+    server.tool("summer_go_live", "Take a store game live for players: release its uploaded bundle Build (publicationId, or the newest upload) to every platform that passed Summer's automated checks, and publish its store page, through the same store routes Studio uses; then watch until players get it. It runs without an owner approval while the person's Agent permissions allow Publish (the default). First call with confirm=false: it reads the page, the Build and its per-platform checks and what players get now, and returns live, blocked (each failure with its fix), needs_changes (Summer's decision and feedback) or confirmation_required with the plan to show the user; set confirm only after they approve going live. With confirm=true it asks the platform and polls until live, or answers waiting with waitingOn (automated_checks, activation, or summer: a hold on Summer's side that needs nothing from the creator; never tell them to wait for a review). Call again with confirm=true to keep watching: nothing is asked twice. needs_permission: Publish is off in the person's Agent permissions. Web builds and downloads go live with the page. Needs \"summer login --store\".", {
+        gameId: z.string().optional().describe("The store game id (from games.list). Without it the call fails with game_required and lists your store games."),
+        publicationId: z.string().optional().describe("The bundle Build to release: publicationId from summer_publish_build. Default: the newest uploaded export."),
+        confirm: z.boolean().default(false).describe("Set true only after the user approves taking this exact page and Build live."),
+        waitSeconds: z.number().int().min(0).max(1800).optional().describe("How long to watch before answering (default 600). On waiting, call again to keep watching."),
+    }, async (args) => creatorResult(() => goLive({ ...args, face: "mcp" })));
+    server.tool("summer_store_set_details", "Fill the store page sections store.update_listing does not edit, on the store page draft: genres (1-5 genre tag ids from store.get_listing tags), features, credits, languageSupport, systemRequirements, contentSurvey (the age questionnaire: every answer, none included) and aiDisclosure (how AI was used; an empty uses list means no AI). Each section given replaces that section, null clears it, an omitted one keeps its value. A published page gets a new draft first. Saving never publishes: take it live with summer_go_live. Needs \"summer login --store\".", {
+        gameId: z.string().optional().describe("The store game id (from games.list)."),
+        genres: z.array(z.string()).min(1).max(5).nullable().optional().describe("Genre tag ids (category genre in store.get_listing tags), in the creator's order."),
+        features: z.array(z.enum(STORE_FEATURES)).min(1).nullable().optional().describe("What the game offers, from the store's closed list."),
+        credits: z
+            .object({ developer: z.string().min(1).max(120), publisher: z.string().min(1).max(120).optional(), franchise: z.string().min(1).max(120).optional() })
+            .nullable()
+            .optional()
+            .describe("Who made and published it; omit publisher or franchise when there is none."),
+        languageSupport: z
+            .array(z.object({ code: z.string(), interface: z.boolean(), fullAudio: z.boolean(), subtitles: z.boolean() }))
+            .min(1)
+            .max(30)
+            .nullable()
+            .optional()
+            .describe("One entry per language (BCP 47 code: en, pt-br, zh-hans), each with at least one kind of support."),
+        systemRequirements: z
+            .record(z.string(), z.unknown())
+            .nullable()
+            .optional()
+            .describe("Desktop hardware: { windows | macos | linux: { minimum: { os, processor, memory, graphics, storage, network, notes }, recommended? } }."),
+        contentSurvey: z
+            .object({
+            violence: z.enum(SURVEY_LEVELS.violence),
+            bloodGore: z.enum(SURVEY_LEVELS.bloodGore),
+            sexualContent: z.enum(SURVEY_LEVELS.sexualContent),
+            nudity: z.enum(SURVEY_LEVELS.nudity),
+            language: z.enum(SURVEY_LEVELS.language),
+            substances: z.enum(SURVEY_LEVELS.substances),
+            gambling: z.enum(SURVEY_LEVELS.gambling),
+            userGeneratedContent: z.boolean(),
+            onlineInteraction: z.boolean(),
+            inGamePurchases: z.boolean(),
+            notes: z.string().max(1000).optional(),
+        })
+            .nullable()
+            .optional()
+            .describe("The mature-content questionnaire; every answer is required, none is an answer."),
+        aiDisclosure: z
+            .object({ uses: z.array(z.enum(AI_USES)), description: z.string().max(2000).optional() })
+            .nullable()
+            .optional()
+            .describe("How AI was used to make the game; uses [] means no AI. generatedGameplay needs a description of what is generated and its guardrails."),
+    }, async (args) => creatorResult(() => setStoreDetails({ ...args, face: "mcp" })));
+    server.tool("summer_sync_items", "Bring the store game's items in line with summer.items.json in the project root, matched by each item's slug (the creator key the game's code uses, e.g. emote_ponder), so the same file gives the staging game and the production game the same items. First call with confirm=false: it checks the file, reads the game's items by slug and returns the plan (create, update with the changed fields, unchanged, blocked with the reason, and the game's items the file does not name, which are never changed) for the gateway this machine is set to; show it to the user. With confirm=true it uploads the changed images and sends the plan to the game's owner: the answer carries the approval link; nothing changes until the owner approves in Studio, then each item is created or revised, priced in Sparks and submitted for Summer's review. After Summer approves an item, the owner activates it in Studio (Review activation on the item's page); players can buy it only while the game is live. A change to a live item is a new revision, reviewed and activated again. An item with the same slug that is a Passport collectible is blocked: Passport items are not synced. One approval takes at most 50 changed items: a larger plan lists batches, confirm each with slugs. A new item needs at least one image. Never activates or releases an item. Needs \"summer login --store\". Staging or production is the gateway this machine is set to; switching takes SUMMER_GATEWAY_URL and SUMMER_MCP_RESOURCE_URL, then \"summer login --store --force\" (one store sign-in per machine; a sign-in for the other environment fails with store_login_other_environment).", {
+        gameId: z.string().optional().describe("The store game id on this gateway (from games.list). Staging and production games have different ids. Without it the call fails with game_required and lists your store games."),
+        project: z.string().optional().describe("Project folder with project.godot and summer.items.json. Defaults to the MCP's bound project, then the working directory."),
+        file: z.string().optional().describe("The items file, relative to the project. Default summer.items.json."),
+        slugs: z.array(z.string()).max(500).optional().describe("Only these items (their slugs); the rest of the file is left out of the plan. Confirm a plan of more than 50 changed items one batch (from batches) at a time."),
+        confirm: z.boolean().default(false).describe("Set true only after the user approves the plan."),
+    }, async (args) => creatorResult(() => syncItems({ ...args, face: "mcp" })));
+    server.tool("summer_content_make", "Make one finished, postable piece of content for a game and put it in the team's Review (Studio > Grow > Content), on this computer: it picks the reference from Summer's library that fits today (a format the game has not posted, what changed in the repo), studies its cuts and caption look, measures the footage, maps each reference shot to a clip window with motion, cuts to the reference's timings, draws the captions in its style, mixes at -14 LUFS, checks hook, motion per shot, safe zones, length and loudness, renders the reference side by side, uploads and saves the piece (failed checks: a draft). It never writes words itself: the first call answers needs_words with the beats and the kit's learnings; call again with workDir, lines (one per beat, in the reference's pattern, true to the game, never the reference's own words) and learningIds. A reference that speaks also needs voiceFile, the lines recorded in the team's voice (needs_voice). Same workDir continues where a run stopped. claim=true takes the oldest queued make request instead (nothing_queued when none; a revision answers needs_changes with what the team asked) and reports every stage to it, so Today shows it live. Needs ffmpeg and ImageMagick (and Whisper for a voice-over). Takes a few minutes.", {
+        contentGameId: z.string().optional().describe("The game's Content id, from content.list_games. Not needed with workDir."),
+        teamId: z.string().optional().describe("From team.list, when the person has more than one team."),
+        referenceId: z.string().optional().describe("The reference to copy, from content.list_references. Without it the best fit for today is picked."),
+        footage: z.array(z.string()).max(20).optional().describe("Folders (or files) of the game's footage on this computer: clips, stills, and the game's music. Default ./content/footage."),
+        lines: z.array(z.string()).max(80).optional().describe("Our words, one per reference beat (\"\" for a beat without words), from the needs_words answer."),
+        voiceFile: z.string().optional().describe("The lines recorded in the team's voice (wav, mp3, m4a), when the reference speaks."),
+        title: z.string().max(100).optional().describe("The piece's title in Review (also the YouTube title)."),
+        caption: z.string().max(2200).optional().describe("The post caption: one dry line and a question, no hashtags."),
+        hashtags: z.array(z.string()).max(10).optional().describe("3-5 tags, the game's tag first. Default: the kit's core tags."),
+        note: z.string().max(2000).optional().describe("What to make it about (\"the new boss\", or commit lines like \"3f2a1c9 Add waiting room\"): weighs the reference pick and becomes the why."),
+        claim: z.boolean().optional().describe("Make a queued make request (the daily scheduler's, or a Change pressed on Today) and report every stage to it: the one named by requestId, else the team's oldest."),
+        requestId: z.string().optional().describe("The make request to claim, from content.make."),
+        learningIds: z.array(z.string()).max(20).optional().describe("The kit learnings (content.get_kit learnings, listed in needs_words) the words and choices applied."),
+        workDir: z.string().optional().describe("The work folder an earlier call answered: continues that piece."),
+        out: z.string().optional().describe("Where the work goes (pieces, the reference videos and footage measurements). Default ~/.summer/content."),
+        music: z.string().optional().describe("The game's own music for a reference with a song (never the reference's audio). Default: the first song in the footage folders."),
+        font: z.string().optional().describe("The game's caption font file (.ttf/.otf)."),
+        referenceFile: z.string().optional().describe("The reference video, when it cannot be fetched (yt-dlp)."),
+        repo: z.string().optional().describe("The game's repo, for what changed today. Default the working directory."),
+        stage: z.enum(["plan", "all"]).optional().describe("plan: stop after the plan, to change shots in plan.json."),
+        upload: z.boolean().optional().describe("false: render and check only, upload nothing."),
+        replan: z.boolean().optional().describe("Throw away the plan and map the shots again."),
+        status: z.enum(["draft", "in_review"]).optional().describe("Override: in_review even with failed checks, or draft."),
+    }, async (args) => creatorResult(() => contentMake({ ...contentMakeInput(args), face: "mcp" })));
 }

package/dist/mcp/tools/debug-tools.js

@@ -194,6 +194,8 @@ Use this when summer_get_diagnostics shows a non-zero \`debugger.warnings\` coun
     }));
     server.tool("summer_play", `Start the game. With no parameters it runs QUIETLY inside Summer Engine's viewport (the 'main' instance); scene runs one level or UI screen instead of the main scene.
 
+Playing the game in the editor's real window is allowed and expected: then summer_screenshot target:'game' to see it, summer_stop when done. One editor at a time.
+
 QUIET BY DEFAULT (focus:false, PlayGame agent:true): the user usually works on the same machine, so the EDITOR stays put. It does not switch to the Game tab or take keyboard focus (nor follow the game's later focus report), and skips the render-health self-check that would misread the untouched Game view as a GPU failure and flip the user's embed setting. Quiet play does NOT hide the game: it runs embedded in the Game view (visible if that tab is open) and is the running game for summer_is_running / summer_screenshot target:'game' / summer_get_diagnostics. With "Embed Game on Play" off the game gets its own OS window; engines with --summer-background (0.5.66+) open it without taking focus. The result echoes agent_quiet:true when honoured; without agent_quiet the engine predates quiet play and most likely took focus (posture_note says so). focus:true launches like the toolbar Play button (Game tab + focus): ONLY when the user is watching and asked to see the game come up.
 
 After starting, confirm boot with summer_is_running (boot time varies; never sleep a guessed delay), then summer_get_diagnostics for runtime errors.

package/dist/mcp/tools/local-project-tools.d.ts

@@ -0,0 +1,6 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+/**
+ * projects.create_local and projects.open_local: what `summer dev` does, for
+ * agents with no shell (core/capabilities/projects-local.ts).
+ */
+export declare function registerLocalProjectTools(server: McpServer): void;