summer-engine 4.3.0 → 4.5.0

package/dist/core/capabilities/publish-build.js

@@ -9,6 +9,7 @@ import { appendStoreJsonLine } from "../store.js";
 import { readJsonResponse } from "../util/http.js";
 import { readLastExport } from "./export-game.js";
 import { publishDownload } from "./publish-download.js";
+import { CHECK_FIXES, summarizeChecks } from "./store-checks.js";
 import { BuildToolError, declarationMismatch, readSummerBundle } from "./summer-bundle.js";
 /**
  * summer_publish_build: upload a summer.games export to the creator's game
@@ -51,7 +52,7 @@ const INTAKE_FAILURES = {
     template_set_unavailable: "Summer Games cannot run this Summer version yet. If you exported with the newest Summer Engine, Summer Games may still be turning that version on: retry the same upload later, there is nothing to update. With an older engine, update Summer Engine and export again.",
     client_version_conflict: "This version number already belongs to a different export. Use a new clientVersion.",
     artifact_exists: "This exact export is already uploaded for this game. Export a new version and upload that.",
-    approval_denied: "Summer Games did not approve this game, so it cannot take new builds.",
+    approval_denied: "Summer Games declined this game, so it cannot take new builds.",
     capacity_limit_reached: "Summer Games is busy right now. Try again in a few minutes.",
 };
 export const defaultDependencies = {
@@ -60,14 +61,14 @@ export const defaultDependencies = {
     now: Date.now,
     token: () => getStoreAccessToken(),
 };
-export function storeError(status, code, message, requestId) {
+export function storeError(status, code, message, requestId, detail) {
     if (status === 401) {
         // The token was sent and refused: signing in again gives the same token
         // shape and the same answer, so it is not the first thing to try.
         return new BuildToolError("store_auth_refused", `The Summer store did not accept this sign-in${message ? `: ${message.replace(/\.$/, "")}` : ""}.`, 'Recovery: run "summer doctor" (Store line) to see the store\'s answer. Signing in again does not change a refusal of a valid sign-in. Until the store accepts agent sign-in for this account, upload the .zip in Studio (Store > your game > Exports).', status, requestId ? { requestId } : undefined);
     }
     if (status === 403 && code === "owner_approval_required") {
-        return new BuildToolError("owner_approval_required", message || "Only the game's owner can do this.", "Recovery: nothing went live. Submit with summer_store_submit and give the owner the approval link it returns; a live game's new download is finished by the owner in Studio.", status);
+        return new BuildToolError("owner_approval_required", message || "Only the game's owner can do this.", "Recovery: nothing went live. The person's Agent permissions do not let this agent publish: ask them to turn on Publish (Studio > Agent permissions), or send them the approval link store.publish returns. A live game's new web build or download is finished by the owner in Studio.", status);
     }
     if (status === 403) {
         return new BuildToolError("store_forbidden", message || "This account cannot change that game.", "Recovery: check that the game belongs to the signed-in account.", status);
@@ -78,7 +79,7 @@ export function storeError(status, code, message, requestId) {
     if (status === 503 || code === "store_unavailable") {
         return new BuildToolError("store_unavailable", message || "Summer Games is not reachable right now.", "Recovery: try again in a few minutes.", status);
     }
-    return new BuildToolError(code, INTAKE_FAILURES[code] ?? message ?? `The Summer store refused the request (${status}).`, "Recovery: read the message, fix the export or version, and retry.", status);
+    return new BuildToolError(code, INTAKE_FAILURES[code] ?? message ?? `The Summer store refused the request (${status}).`, CHECK_FIXES[code] ? `Recovery: ${CHECK_FIXES[code].fix}` : "Recovery: read the message, fix the export or version, and retry.", status, { ...(requestId ? { requestId } : {}), ...detail });
 }
 export function createStore(baseUrl, token, deps) {
     return {
@@ -93,6 +94,7 @@ export function createStore(baseUrl, token, deps) {
                         authorization: `Bearer ${token}`,
                         ...(options.body === undefined ? {} : { "content-type": "application/json" }),
                         ...(options.key ? { "idempotency-key": options.key } : {}),
+                        ...options.headers,
                     },
                     body: options.body === undefined ? undefined : JSON.stringify(options.body),
                     redirect: "error",
@@ -107,7 +109,7 @@ export function createStore(baseUrl, token, deps) {
             if (!response.ok) {
                 const error = body.error && typeof body.error === "object" ? body.error : {};
                 const requestId = [error.requestId, body.requestId, response.headers.get("x-request-id")].find((value) => typeof value === "string" && value);
-                throw storeError(response.status, typeof error.code === "string" ? error.code : `http_${response.status}`, typeof error.message === "string" ? error.message : undefined, requestId);
+                throw storeError(response.status, typeof error.code === "string" ? error.code : `http_${response.status}`, typeof error.message === "string" ? error.message : undefined, requestId, Array.isArray(error.missing) ? { missing: error.missing } : undefined);
             }
             return body;
         },
@@ -312,18 +314,18 @@ async function listGames(deps) {
     }
 }
 /** gameId is required: the error carries the person's games, or why the store did not list them. */
-async function listGamesOrThrow(deps) {
+export async function listGamesOrThrow(deps) {
     const listed = await listGames(deps);
     if ("games" in listed) {
         throw new BuildToolError("game_required", listed.games.length
             ? "gameId is required: pick one of your store games below (the export is uploaded to one existing game)."
             : "gameId is required, and this account has no store game yet.", listed.games.length
             ? "Recovery: call again with gameId from the list."
-            : "Recovery: create the store game first (summer_store_create_game), then call again with its gameId.", undefined, { games: listed.games });
+            : "Recovery: create the store game first (games.create), then call again with its gameId.", undefined, { games: listed.games });
     }
     throw new BuildToolError("game_required", `gameId is required, and the store did not list your games: ${listed.error}`, "Recovery: copy the game id from Studio (the store page URL) and retry.", undefined, { listError: listed.error });
 }
-async function storeToken(deps) {
+export async function storeToken(deps) {
     try {
         return await deps.token();
     }
@@ -350,7 +352,7 @@ export async function checkStoreGame(gameId, exportTargets, deps) {
                 ? `There is no store game "${gameId}" for this account, so nothing can be uploaded to it.`
                 : `The store did not find game "${gameId}", and did not list your games either: ${listed.error}`, "games" in listed && listed.games.length
                 ? "Recovery: call again with gameId from the list."
-                : "Recovery: create the store game first (summer_store_create_game), or copy its id from Studio (the store page URL).", 404, "games" in listed ? { games: listed.games } : undefined);
+                : "Recovery: create the store game first (games.create), or copy its id from Studio (the store page URL).", 404, "games" in listed ? { games: listed.games } : undefined);
         }
         throw error;
     }
@@ -359,10 +361,57 @@ export async function checkStoreGame(gameId, exportTargets, deps) {
     const catalog = new Set(targets.map((target) => target.replace(/-(universal|x64)$/, "")));
     const unlisted = exportTargets.filter((target) => !catalog.has(target));
     const warnings = unlisted.length
-        ? [`The store page of "${game.name ?? gameId}" does not list ${unlisted.join(", ")} (it lists ${targets.join(", ") || "no platforms"}). Players on ${unlisted.join(", ")} will not see this build until the store page lists them: add them with summer_store_update_listing.`]
+        ? [`The store page of "${game.name ?? gameId}" does not list ${unlisted.join(", ")} (it lists ${targets.join(", ") || "no platforms"}). Players on ${unlisted.join(", ")} will not see this build until the store page lists them: add them with store.update_listing.`]
         : [];
     return { game: { gameId, name: typeof game.name === "string" ? game.name : null, status: typeof game.status === "string" ? game.status : null, targets }, warnings };
 }
+/**
+ * Seal the upload. While Summer's malware scan of the stored bytes runs, the
+ * store answers 409 malware_scan_pending; that is a wait, not a failure.
+ */
+async function sealWhenScanned(store, publicationPath, key, deps, deadline) {
+    for (;;) {
+        try {
+            await store.call("POST", `${publicationPath}:source-complete`, { body: {}, key });
+            return;
+        }
+        catch (error) {
+            if (!(error instanceof BuildToolError && error.code === "malware_scan_pending") || deps.now() >= deadline)
+                throw error;
+            await deps.sleep(POLL_MS);
+        }
+    }
+}
+/**
+ * Why the platform did not take a Build to players when asked: the Game's
+ * approval state as the platform reports it. Staff review is becoming a
+ * step after launch, so a pending review is reported as Summer's hold, not
+ * as something the creator waits on or fixes.
+ */
+export async function platformHold(store, gameId) {
+    let approval = {};
+    try {
+        approval = await store.call("GET", `games/${seg(gameId)}/approval`);
+    }
+    catch {
+        // The hold is still reported without the approval state.
+    }
+    const state = typeof approval.state === "string" ? approval.state : "unknown";
+    const review = approval.latestReview && typeof approval.latestReview === "object" ? approval.latestReview : null;
+    if (state === "REJECTED" || state === "REVOKED" || review?.decision === "CHANGES_REQUESTED") {
+        return {
+            by: "summer_decision",
+            approvalState: state,
+            ...(review ? { decision: review.decision, decidedBy: review.decidedBy ?? null, feedback: review.feedback || null } : {}),
+            message: "Summer decided against this game going live as it is. Apply the feedback (store.status shows it in full), then publish again.",
+        };
+    }
+    return {
+        by: "summer",
+        approvalState: state,
+        message: "Every automated check is done; the platform has not released this game's builds yet. That is on Summer's side and needs nothing from you. The Build is kept, and summer_go_live takes it live and reports the moment players get it.",
+    };
+}
 export async function publishBuild(input, overrides = {}) {
     const deps = { ...defaultDependencies, ...overrides };
     const gameId = input.gameId?.trim();
@@ -450,7 +499,7 @@ export async function publishBuild(input, overrides = {}) {
             }
             const partHashes = plan.partSizeBytes === PART_BYTES ? digest.parts : (await hashParts(file, plan.partSizeBytes)).parts;
             await uploadParts(async (numbers) => readGrants(await store.call("POST", `${publicationPath}:signParts`, { body: { parts: numbers.map((n) => ({ partNumber: n, sha256: partHashes[n - 1] })) } })), file, digest.sizeBytes, plan, deps);
-            await store.call("POST", `${publicationPath}:source-complete`, { body: {}, key: key(`seal:${publicationId}`) });
+            await sealWhenScanned(store, publicationPath, key(`seal:${publicationId}`), deps, deps.now() + (input.waitSeconds ?? DEFAULT_WAIT_SECONDS) * 1000);
             uploaded = true;
         }
         const deadline = deps.now() + (input.waitSeconds ?? DEFAULT_WAIT_SECONDS) * 1000;
@@ -470,7 +519,9 @@ export async function publishBuild(input, overrides = {}) {
                     ? "Recovery: fix what the message names, export again and retry; the same clientVersion still works, because a refused upload records no version."
                     : code === "template_set_unavailable"
                         ? `Recovery: ${INTAKE_FAILURES.template_set_unavailable.replace(/^Summer Games cannot run this Summer version yet\. /, "")} The same clientVersion works on the retry.`
-                        : "Recovery: export again, use a new clientVersion, and retry.", undefined, { publicationId });
+                        : CHECK_FIXES[code]
+                            ? `Recovery: ${CHECK_FIXES[code].fix}`
+                            : "Recovery: export again, use a new clientVersion, and retry.", undefined, { publicationId, failedCheck: { code, owner: CHECK_FIXES[code]?.owner ?? "creator" } });
             }
             if (deps.now() >= deadline) {
                 const result = {
@@ -503,9 +554,17 @@ export async function publishBuild(input, overrides = {}) {
             });
             clientPackageId = named.package?.id ?? null;
         }
+        // Summer's automated checks on the client pack, one per platform: wait for
+        // them within the same budget, so the answer says whether the build passed.
+        let checks = summarizeChecks(publication);
+        while (checks.state === "checking" && deps.now() < deadline) {
+            await deps.sleep(POLL_MS);
+            publication = await store.call("GET", publicationPath);
+            checks = summarizeChecks(publication);
+        }
         let published = false;
-        let publishNote = null;
-        if (publish) {
+        let hold = null;
+        if (publish && checks.state !== "failed") {
             try {
                 await store.call("POST", `${publicationPath}:publish`, { body: {}, key: key(`publish:${publicationId}`) });
                 published = true;
@@ -513,13 +572,14 @@ export async function publishBuild(input, overrides = {}) {
             catch (error) {
                 if (!(error instanceof BuildToolError && error.status === 409 && error.code === NOT_ACTIONABLE))
                     throw error;
-                publishNote = "The game has not passed review yet, so this Build waits as a preview.";
+                hold = await platformHold(store, gameId);
             }
         }
-        await appendStoreJsonLine("creator-audit.jsonl", { ...audit, outcome: "succeeded", publicationId, buildId, published });
+        await appendStoreJsonLine("creator-audit.jsonl", { ...audit, outcome: "succeeded", publicationId, buildId, published, checks: checks.state });
+        const failed = checks.checks.filter((check) => check.state === "failed");
         return {
             ok: true,
-            status: published ? "published" : "uploaded",
+            status: checks.state === "failed" ? "checks_failed" : published ? "published" : "uploaded",
             gameId,
             publicationId,
             buildId,
@@ -528,11 +588,17 @@ export async function publishBuild(input, overrides = {}) {
             clientVersion,
             sha256: digest.sha256,
             sizeBytes: digest.sizeBytes,
+            // passed: every platform passed Summer's automated checks; checking: call again to keep waiting.
+            checksState: checks.state,
+            checks: checks.checks,
+            ...(checks.packFailure ? { packFailure: checks.packFailure } : {}),
             published,
-            ...(publishNote ? { publishNote } : {}),
-            next: published
-                ? "The Build is approved. Summer checks the client pack per platform; Studio shows the result."
-                : "The Build exists as a preview. Summer checks the client pack per platform; publish it from Studio or call again with publish=true.",
+            ...(hold ? { hold } : {}),
+            next: checks.state === "failed"
+                ? `Summer's automated checks failed${failed.length ? ` on ${failed.map((check) => check.platform).join(", ")}` : ""}. Apply each fix, export again and upload with a new clientVersion.`
+                : checks.state === "checking"
+                    ? "Summer is still checking the client pack. Call summer_publish_build again with the same file and clientVersion to keep waiting; nothing is uploaded twice."
+                    : `Every automated check passed. Take it live with summer_go_live (gameId ${gameId}, publicationId ${publicationId}).`,
         };
     }
     catch (error) {

package/dist/core/capabilities/publish-download.js

@@ -156,7 +156,7 @@ export async function publishDownload(input, deps) {
             resumed,
             ...(version.playUrl ? { playUrl: version.playUrl } : {}),
             next: outcome === "ready"
-                ? "The file is checked. Players get it once the store page is live; submit the page with summer_store_submit (the owner approves)."
+                ? "The file is checked. Players get it once the store page is live; submit the page with store.publish (the owner approves)."
                 : "Summer is still checking the file. Call summer_publish_build again with the same file and clientVersion to keep waiting; nothing is uploaded twice.",
         };
     }

package/dist/core/capabilities/runtime-control.d.ts

@@ -138,7 +138,7 @@ export declare const runtimeSpawnArgsSchema: z.ZodObject<{
     mode: z.ZodOptional<z.ZodEnum<["queue_free", "free"]>>;
     instance: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
-    action: "spawn" | "free";
+    action: "free" | "spawn";
     mode?: "free" | "queue_free" | undefined;
     name?: string | undefined;
     instance?: string | undefined;
@@ -147,7 +147,7 @@ export declare const runtimeSpawnArgsSchema: z.ZodObject<{
     parent?: string | undefined;
     props?: Record<string, string | number | boolean> | undefined;
 }, {
-    action: "spawn" | "free";
+    action: "free" | "spawn";
     mode?: "free" | "queue_free" | undefined;
     name?: string | undefined;
     instance?: string | undefined;
@@ -552,3 +552,8 @@ export interface PlayGameClient extends CapabilityAdvertisingClient {
  * `scene` into the op and would drop agent/seed/instance.
  */
 export declare function playGame(client: PlayGameClient, args: PlayGameArgs): Promise<unknown>;
+/**
+ * How many game clients a play started, for the usage line: the Local Play
+ * echo's players + spectators, else 1. Null when the play failed.
+ */
+export declare function playClientCount(result: unknown): number | null;

package/dist/core/capabilities/runtime-control.js

@@ -30,6 +30,7 @@ import { z } from "zod";
 import { ToolInputError } from "../tool-errors.js";
 import { missingEngineOpResult } from "../capability-skew.js";
 import { extractOpError, getFailureReason, withOldEngineHint } from "./engine-receipt.js";
+import { noteToolUsage } from "../usage-fields.js";
 // ---------------------------------------------------------------------------
 // Op kinds
 // ---------------------------------------------------------------------------
@@ -538,7 +539,7 @@ export const inputEventSchema = z.object({
     pressed: z.boolean().optional().describe("type:'action'|'key' — press (default true) or release."),
     strength: z.number().optional().describe("type:'action' — press strength 0..1 (default 1). type:'axis' — signed strength; negative selects action_negative."),
     hold_ms: z.number().int().optional().describe("type:'action'|'key' — auto-release after this many ms (0 = stays pressed until a release event)."),
-    keycode: z.number().int().optional().describe("type:'key' — Godot Key enum value (e.g. 32 = Space, 4194320 = Right arrow)."),
+    keycode: z.number().int().optional().describe("type:'key' — Godot Key enum value (e.g. 32 = Space, 4194321 = Right arrow)."),
     physical_keycode: z.number().int().optional().describe("type:'key' — physical Key enum value (alternative to keycode)."),
     position: z
         .tuple([z.number(), z.number()])
@@ -1058,6 +1059,31 @@ export function withPlayPostureEcho(result, args) {
  * `scene` into the op and would drop agent/seed/instance.
  */
 export async function playGame(client, args) {
+    const result = await playGameOnce(client, args);
+    const instanceCount = playClientCount(result);
+    if (instanceCount !== null)
+        noteToolUsage({ instanceCount });
+    return result;
+}
+/**
+ * How many game clients a play started, for the usage line: the Local Play
+ * echo's players + spectators, else 1. Null when the play failed.
+ */
+export function playClientCount(result) {
+    if (!result || typeof result !== "object" || extractOpError(result))
+        return null;
+    const envelope = result;
+    if (envelope.ok === false)
+        return null;
+    const payload = envelope.results?.[0] ?? envelope;
+    const local = payload.local_play;
+    if (local && typeof local === "object" && local.applied === true) {
+        const count = (value) => (typeof value === "number" && Number.isInteger(value) && value > 0 ? value : 0);
+        return Math.max(1, count(local.players) + count(local.spectators));
+    }
+    return 1;
+}
+async function playGameOnce(client, args) {
     if (!playNeedsOp(args))
         return client.play(args.scene);
     // Validate the combination first (nothing sent); then, because an engine

package/dist/core/capabilities/seeing/args.d.ts

@@ -119,11 +119,11 @@ export declare const frameNodesArgsSchema: z.ZodObject<{
 }, "strict", z.ZodTypeAny, {
     nodes: string[];
     fill?: number | undefined;
+    from?: string | undefined;
     scenePath?: string | undefined;
     fov?: number | undefined;
     marks?: boolean | undefined;
     max_marks?: number | undefined;
-    from?: string | undefined;
     direction?: "top" | "front" | "iso" | "back" | "left" | "right" | undefined;
     bookmark_name?: string | undefined;
     max_size?: number | undefined;
@@ -131,11 +131,11 @@ export declare const frameNodesArgsSchema: z.ZodObject<{
 }, {
     nodes: string[];
     fill?: number | undefined;
+    from?: string | undefined;
     scenePath?: string | undefined;
     fov?: number | undefined;
     marks?: boolean | undefined;
     max_marks?: number | undefined;
-    from?: string | undefined;
     direction?: "top" | "front" | "iso" | "back" | "left" | "right" | undefined;
     bookmark_name?: string | undefined;
     max_size?: number | undefined;

package/dist/core/capabilities/store-checks.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Summer's automated checks on an uploaded game, read the way an agent can act
+ * on them: one entry per check with its state, the platform's code and a fix.
+ *
+ * The codes and their meaning come from the Summer platform's management API
+ * (api/management/openapi.yaml, build-publications and client packages) and
+ * its pipeline docs (docs/build-publications.md, docs/client-pack-publication.md).
+ * Two kinds of failure are kept apart, because only one is the creator's to fix:
+ * - creator: the export or its content (a fix is named);
+ * - summer: a problem on Summer's side (nothing to change; it retries or
+ *   Summer resolves it).
+ */
+export type CheckOwner = "creator" | "summer";
+export interface CheckFix {
+    owner: CheckOwner;
+    fix: string;
+}
+/** Why an upload or one of its checks failed, and what to do about it. */
+export declare const CHECK_FIXES: Record<string, CheckFix>;
+export interface PlatformCheck {
+    platform: string;
+    state: "checking" | "passed" | "failed";
+    code?: string;
+    message?: string;
+    owner?: CheckOwner;
+    fix?: string;
+}
+/** A failure line with its owner and fix (unknown codes are the creator's, with the platform's message). */
+export declare function describeFailure(code: string | null | undefined, message: string | null | undefined): {
+    code: string;
+    message?: string;
+    owner: CheckOwner;
+    fix: string;
+};
+/** Each platform the client pack is checked on, from a build publication's clientPackage. */
+export declare function platformChecks(clientPackage: Record<string, unknown> | null | undefined): PlatformCheck[];
+export interface ChecksSummary {
+    /** passed: every platform passed; failed: the pack or a platform failed; checking: not done yet. */
+    state: "checking" | "passed" | "failed";
+    checks: PlatformCheck[];
+    /** The pack itself was refused (state rejected), before any platform ran. */
+    packFailure?: ReturnType<typeof describeFailure>;
+}
+/** Where the automated checks of one build publication stand. */
+export declare function summarizeChecks(publication: Record<string, any>): ChecksSummary;

package/dist/core/capabilities/store-checks.js

@@ -0,0 +1,85 @@
+/**
+ * Summer's automated checks on an uploaded game, read the way an agent can act
+ * on them: one entry per check with its state, the platform's code and a fix.
+ *
+ * The codes and their meaning come from the Summer platform's management API
+ * (api/management/openapi.yaml, build-publications and client packages) and
+ * its pipeline docs (docs/build-publications.md, docs/client-pack-publication.md).
+ * Two kinds of failure are kept apart, because only one is the creator's to fix:
+ * - creator: the export or its content (a fix is named);
+ * - summer: a problem on Summer's side (nothing to change; it retries or
+ *   Summer resolves it).
+ */
+/** Why an upload or one of its checks failed, and what to do about it. */
+export const CHECK_FIXES = {
+    // Intake (build-publications errorCode).
+    bundle_invalid: { owner: "creator", fix: "Export again with summer_export_game (the summer.games preset) and upload the .zip exactly as Summer Engine wrote it." },
+    declaration_mismatch: { owner: "creator", fix: "Export again with summer_export_game alignDeclaration:true, or with targets equal to what summer.build.json declares." },
+    client_version_conflict: { owner: "creator", fix: "This version number already names different bytes: upload with a new clientVersion." },
+    artifact_exists: { owner: "creator", fix: "These exact bytes are already a build of this game: use that build (store.status lists it) or export a new version." },
+    engine_build_unreleased: {
+        owner: "creator",
+        fix: "The export came from a Summer Engine build Summer never released (a development or nightly build). Install the released Summer Engine, export again and upload.",
+    },
+    attempts_exhausted: { owner: "creator", fix: "Summer could not read the upload in five tries, usually because it is very large. Make the export smaller (remove unused assets), export again and upload with a new clientVersion." },
+    approval_denied: { owner: "creator", fix: "Summer declined this game. Read the decision and its feedback with store.status before uploading again." },
+    malware_detected: { owner: "creator", fix: "The malware scan found a threat in the upload. Check the project's files, plugins and add-ons, export again on a clean machine and upload with a new clientVersion." },
+    malware_scan_unsupported: { owner: "creator", fix: "The malware scanner could not read this file. Upload the .zip exactly as summer_export_game wrote it (no re-zipping, no password)." },
+    materializing_failed: { owner: "creator", fix: "Summer could not unpack the game's server. Read errorMessage, fix the server export, export again and upload with a new clientVersion." },
+    building_failed: { owner: "creator", fix: "The game's server image did not build. Read errorMessage, fix it, export again and upload with a new clientVersion." },
+    verifying_failed: {
+        owner: "creator",
+        fix: "The secrets scan found a key or password in the server. Remove it from the project (scripts, .env and config files, the export's include filters), revoke it where it was issued, export again and upload with a new clientVersion.",
+    },
+    // Client pack and per-platform checks (client packages).
+    package_not_verified: {
+        owner: "creator",
+        fix: "The client pack failed inspection: its main scene must open, and it must carry the export stamp Summer Engine writes. Read errorMessage, fix the project, export again and upload with a new clientVersion.",
+    },
+    client_platform_unavailable: {
+        owner: "creator",
+        fix: "Summer cannot run this kind of game on this platform yet (for example web for a game with a server). Export without that platform; ship web as a download (summer_export_game format download).",
+    },
+    qualification_revoked: { owner: "creator", fix: "Summer withdrew this platform's check result. Export a new version and upload it." },
+    // Summer's side: nothing for the creator to change.
+    template_set_unavailable: { owner: "summer", fix: "Summer Games is still turning this Summer version on. Nothing to change: retry the same upload later." },
+    capacity_limit_reached: { owner: "summer", fix: "Summer Games is busy. Retry the same upload in a few minutes." },
+    verification_unavailable: { owner: "summer", fix: "Summer could not run this platform's check right now and retries it. Nothing to change." },
+    verification_blocked: { owner: "summer", fix: "Summer held this platform's check for its team. Nothing to change in the game; it continues once Summer resolves it." },
+};
+/** A failure line with its owner and fix (unknown codes are the creator's, with the platform's message). */
+export function describeFailure(code, message) {
+    const known = code ? CHECK_FIXES[code] : undefined;
+    return {
+        code: code || "check_failed",
+        ...(message ? { message: message.length > 400 ? `${message.slice(0, 400)}...` : message } : {}),
+        owner: known?.owner ?? "creator",
+        fix: known?.fix ?? "Read message, fix what it names in the project, export again and upload with a new clientVersion.",
+    };
+}
+const text = (value) => (typeof value === "string" && value ? value : undefined);
+/** Each platform the client pack is checked on, from a build publication's clientPackage. */
+export function platformChecks(clientPackage) {
+    const verifications = Array.isArray(clientPackage?.verifications) ? clientPackage.verifications : [];
+    return verifications.map((check) => {
+        const platform = text(check.platform) ?? "unknown";
+        if (check.state === "ready" && text(check.qualificationId))
+            return { platform, state: "passed" };
+        if (check.state === "failed")
+            return { platform, state: "failed", ...describeFailure(text(check.errorCode), text(check.errorMessage)) };
+        return { platform, state: "checking" };
+    });
+}
+/** Where the automated checks of one build publication stand. */
+export function summarizeChecks(publication) {
+    const pack = publication.clientPackage && typeof publication.clientPackage === "object" ? publication.clientPackage : null;
+    if (pack?.state === "rejected") {
+        return { state: "failed", checks: platformChecks(pack), packFailure: describeFailure("package_not_verified", text(pack.verificationError)) };
+    }
+    const checks = platformChecks(pack);
+    // Wait for every platform: a failure on one does not stop the others from passing.
+    if (!pack || pack.state !== "uploaded" || checks.length === 0 || checks.some((check) => check.state === "checking")) {
+        return { state: "checking", checks };
+    }
+    return { state: checks.some((check) => check.state === "failed") ? "failed" : "passed", checks };
+}

package/dist/core/capabilities/store-details.d.ts

@@ -0,0 +1,37 @@
+import { type PublishBuildDependencies } from "./publish-build.js";
+/**
+ * summer_store_set_details: the store page sections the hosted
+ * store.update_listing does not edit, on the store page draft:
+ * genres, features, credits, language support, system requirements, the
+ * content questionnaire (contentSurvey) and the AI disclosure. Same route as
+ * Studio's store page editor:
+ *
+ *   GET   games/{g}/revisions          the newest revision
+ *   POST  games/{g}/revisions          a new draft from it, when it is not a draft
+ *   PATCH games/{g}/revisions/{r}      the sections, with the revision's ETag
+ *
+ * Each section given replaces that section; null clears it; an omitted one
+ * keeps its value (summer-platform api/management/openapi.yaml,
+ * PatchRevision and the store page section schemas). Saving never publishes.
+ */
+export declare const STORE_FEATURES: readonly ["single_player", "online_multiplayer", "local_multiplayer", "online_coop", "local_coop", "cross_platform", "controller_full", "controller_partial", "cloud_saves", "plays_in_browser", "level_editor", "achievements", "in_game_purchases"];
+export declare const AI_USES: readonly ["assets", "code", "generatedGameplay"];
+export declare const SURVEY_LEVELS: {
+    readonly violence: readonly ["none", "fantasy", "realistic"];
+    readonly bloodGore: readonly ["none", "mild", "intense"];
+    readonly sexualContent: readonly ["none", "suggestive", "explicit"];
+    readonly nudity: readonly ["none", "partial", "full"];
+    readonly language: readonly ["none", "mild", "strong"];
+    readonly substances: readonly ["none", "referenced", "used"];
+    readonly gambling: readonly ["none", "simulated", "realMoney"];
+};
+export declare const DETAIL_SECTIONS: readonly ["genres", "features", "credits", "languageSupport", "systemRequirements", "contentSurvey", "aiDisclosure"];
+type Section = (typeof DETAIL_SECTIONS)[number];
+export type StoreDetailsInput = {
+    gameId?: string;
+    face: "cli" | "mcp";
+} & Partial<Record<Section, unknown>>;
+export declare function setStoreDetails(input: StoreDetailsInput, overrides?: Partial<PublishBuildDependencies>): Promise<Record<string, unknown> & {
+    ok: true;
+}>;
+export {};

package/dist/core/capabilities/store-details.js

@@ -0,0 +1,94 @@
+import { createHash } from "node:crypto";
+import { resolveGatewayUrl } from "../config.js";
+import { createStore, defaultDependencies, listGamesOrThrow, storeToken } from "./publish-build.js";
+import { BuildToolError } from "./summer-bundle.js";
+/**
+ * summer_store_set_details: the store page sections the hosted
+ * store.update_listing does not edit, on the store page draft:
+ * genres, features, credits, language support, system requirements, the
+ * content questionnaire (contentSurvey) and the AI disclosure. Same route as
+ * Studio's store page editor:
+ *
+ *   GET   games/{g}/revisions          the newest revision
+ *   POST  games/{g}/revisions          a new draft from it, when it is not a draft
+ *   PATCH games/{g}/revisions/{r}      the sections, with the revision's ETag
+ *
+ * Each section given replaces that section; null clears it; an omitted one
+ * keeps its value (summer-platform api/management/openapi.yaml,
+ * PatchRevision and the store page section schemas). Saving never publishes.
+ */
+export const STORE_FEATURES = [
+    "single_player",
+    "online_multiplayer",
+    "local_multiplayer",
+    "online_coop",
+    "local_coop",
+    "cross_platform",
+    "controller_full",
+    "controller_partial",
+    "cloud_saves",
+    "plays_in_browser",
+    "level_editor",
+    "achievements",
+    "in_game_purchases",
+];
+export const AI_USES = ["assets", "code", "generatedGameplay"];
+export const SURVEY_LEVELS = {
+    violence: ["none", "fantasy", "realistic"],
+    bloodGore: ["none", "mild", "intense"],
+    sexualContent: ["none", "suggestive", "explicit"],
+    nudity: ["none", "partial", "full"],
+    language: ["none", "mild", "strong"],
+    substances: ["none", "referenced", "used"],
+    gambling: ["none", "simulated", "realMoney"],
+};
+export const DETAIL_SECTIONS = ["genres", "features", "credits", "languageSupport", "systemRequirements", "contentSurvey", "aiDisclosure"];
+const IN_REVIEW = ["SUBMITTED", "VERIFYING", "SCHEDULED"];
+const seg = encodeURIComponent;
+/** The store page refusals this tool can name before anything is sent. */
+function checkSections(input) {
+    const ai = input.aiDisclosure;
+    if (ai && Array.isArray(ai.uses) && ai.uses.includes("generatedGameplay") && !ai.description?.trim()) {
+        throw new BuildToolError("ai_disclosure_incomplete", "aiDisclosure uses generatedGameplay, which needs a description of what is generated while people play and its guardrails.", "Recovery: add aiDisclosure.description, then call again.");
+    }
+}
+async function editableDraft(store, gameId, key) {
+    const revisions = await store.call("GET", `games/${seg(gameId)}/revisions?limit=20`);
+    const newest = (revisions.items ?? []).reduce((best, item) => (!best || Number(item.sequence ?? 0) > Number(best.sequence ?? 0) ? item : best), null);
+    if (!newest)
+        throw new BuildToolError("no_store_page", "This game has no store page yet.", "Recovery: create it with games.create, then call again.");
+    if (newest.state === "DRAFT")
+        return newest;
+    if (IN_REVIEW.includes(newest.state)) {
+        throw new BuildToolError("page_publishing", "The store page is being published right now, so it cannot change until that finishes.", "Recovery: read summer_go_live (or store.status) for where it stands; once it is live, call this again to edit a new draft.");
+    }
+    return store.call("POST", `games/${seg(gameId)}/revisions`, { body: {}, key });
+}
+export async function setStoreDetails(input, overrides = {}) {
+    const deps = { ...defaultDependencies, ...overrides };
+    const gameId = input.gameId?.trim();
+    if (!gameId)
+        return listGamesOrThrow(deps);
+    const patch = Object.fromEntries(DETAIL_SECTIONS.filter((section) => input[section] !== undefined).map((section) => [section, input[section]]));
+    if (!Object.keys(patch).length) {
+        throw new BuildToolError("nothing_to_change", "No store page section was given.", `Recovery: pass at least one of ${DETAIL_SECTIONS.join(", ")}.`);
+    }
+    checkSections(input);
+    const store = createStore(await resolveGatewayUrl(), await storeToken(deps), deps);
+    const key = (step) => createHash("sha256").update(`store-details:${gameId}:${step}:${JSON.stringify(patch)}`).digest("hex");
+    const draft = await editableDraft(store, gameId, key("fork"));
+    const saved = await store.call("PATCH", `games/${seg(gameId)}/revisions/${seg(String(draft.revisionId))}`, {
+        body: patch,
+        key: key(`patch:${draft.revisionId}:${draft.etagRevision}`),
+        headers: { "x-summer-revision": `"game-revision:${draft.revisionId}:${draft.etagRevision}"` },
+    });
+    return {
+        ok: true,
+        status: "saved",
+        gameId,
+        revisionId: saved.revisionId ?? draft.revisionId,
+        state: saved.state ?? draft.state,
+        saved: Object.fromEntries(Object.keys(patch).map((section) => [section, saved[section] ?? patch[section]])),
+        next: "Saved on the store page draft; nothing is published. Read it with store.get_listing; take it live with summer_go_live.",
+    };
+}