summer-engine 3.4.1 → 3.5.1

package/dist/core/capabilities/image-generation.d.ts

@@ -1,8 +1,10 @@
 import { z } from "zod";
+/** Image generation can take over a minute on the larger models; wait this long for the server. */
+export declare const IMAGE_GENERATION_TIMEOUT_MS = 180000;
 /** Shared MCP/CLI image request contract; optional flags preserve omission. */
 export declare const imageGenerationArgsSchema: z.ZodObject<{
     prompt: z.ZodString;
-    model: z.ZodDefault<z.ZodString>;
+    model: z.ZodOptional<z.ZodString>;
     style: z.ZodDefault<z.ZodString>;
     referenceImageUrl: z.ZodOptional<z.ZodString>;
     removeBackground: z.ZodOptional<z.ZodBoolean>;
@@ -10,13 +12,15 @@ export declare const imageGenerationArgsSchema: z.ZodObject<{
     width: z.ZodOptional<z.ZodNumber>;
     height: z.ZodOptional<z.ZodNumber>;
     options: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
+    out: z.ZodOptional<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
     prompt: string;
-    model: string;
     style: string;
     width?: number | undefined;
     height?: number | undefined;
     options?: Record<string, any> | undefined;
+    out?: string | undefined;
+    model?: string | undefined;
     referenceImageUrl?: string | undefined;
     removeBackground?: boolean | undefined;
     aspectRatio?: "1:1" | "16:9" | "9:16" | "4:3" | "3:4" | "3:2" | "2:3" | "5:4" | "4:5" | "21:9" | undefined;
@@ -25,9 +29,15 @@ export declare const imageGenerationArgsSchema: z.ZodObject<{
     width?: number | undefined;
     height?: number | undefined;
     options?: Record<string, any> | undefined;
+    out?: string | undefined;
     model?: string | undefined;
     style?: string | undefined;
     referenceImageUrl?: string | undefined;
     removeBackground?: boolean | undefined;
     aspectRatio?: "1:1" | "16:9" | "9:16" | "4:3" | "3:4" | "3:2" | "2:3" | "5:4" | "4:5" | "21:9" | undefined;
 }>;
+/**
+ * Save a generated image where the caller asked (a folder or a file path), or
+ * under TMPDIR/summer-gen. Returns the path, or null when the download failed.
+ */
+export declare function saveGeneratedImage(url: string, out?: string, prefix?: string): Promise<string | null>;

package/dist/core/capabilities/image-generation.js

@@ -1,11 +1,17 @@
+import { mkdir, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { dirname, extname, join, resolve } from "node:path";
 import { z } from "zod";
+/** Image generation can take over a minute on the larger models; wait this long for the server. */
+export const IMAGE_GENERATION_TIMEOUT_MS = 180_000;
+const IMAGE_EXTENSIONS = new Set([".png", ".jpg", ".jpeg", ".webp"]);
 /** Shared MCP/CLI image request contract; optional flags preserve omission. */
 export const imageGenerationArgsSchema = z.object({
     prompt: z.string().describe("Description of the image to generate"),
     model: z
         .string()
-        .default("nano-banana-2")
-        .describe("Model name or full provider ID"),
+        .optional()
+        .describe("Model name or full provider ID. Omit it and the server picks one that reaches the requested size (nano-banana-2 when no size is asked)."),
     style: z
         .string()
         .default("realistic")
@@ -37,4 +43,27 @@ export const imageGenerationArgsSchema = z.object({
         .record(z.any())
         .optional()
         .describe("Extra model params (seed, negative_prompt, ...). The result lists any it did not use in ignoredOptions."),
+    out: z
+        .string()
+        .optional()
+        .describe("Where to save the image on this machine: a folder, or a file path ending in .png, .jpg or .webp. Default: <TMPDIR>/summer-gen/."),
 });
+/**
+ * Save a generated image where the caller asked (a folder or a file path), or
+ * under TMPDIR/summer-gen. Returns the path, or null when the download failed.
+ */
+export async function saveGeneratedImage(url, out, prefix = "img") {
+    try {
+        const target = out?.trim() ? resolve(out.trim()) : join(tmpdir(), "summer-gen");
+        const file = IMAGE_EXTENSIONS.has(extname(target).toLowerCase()) ? target : join(target, `${prefix}-${Date.now()}.png`);
+        await mkdir(dirname(file), { recursive: true });
+        const res = await fetch(url, { signal: AbortSignal.timeout(60_000) });
+        if (!res.ok)
+            return null;
+        await writeFile(file, Buffer.from(await res.arrayBuffer()));
+        return file;
+    }
+    catch {
+        return null;
+    }
+}

package/dist/core/capabilities/publish-build.d.ts

@@ -51,6 +51,10 @@ export declare function readGrants(body: Record<string, any>): Grant[];
  * Upload the given parts: signed in batches, PUT from disk, re-signed when
  * refused or about to expire. `sign` asks the store for URLs (build
  * publications bind each to its part SHA-256; store versions to its length).
+ * Each sign asks for every part not yet uploaded, including the parts other
+ * workers hold, so one sign usually covers them all. A part fails to sign only
+ * when the store was asked for it and did not sign it; the first fatal error
+ * stops the other workers and aborts their uploads.
  */
 export declare function uploadParts(sign: (partNumbers: number[]) => Promise<Grant[]>, file: string, sizeBytes: number, plan: {
     partSizeBytes: number;

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

@@ -8,7 +8,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 { BuildToolError, readSummerBundle } from "./summer-bundle.js";
+import { BuildToolError, declarationMismatch, readSummerBundle } from "./summer-bundle.js";
 /**
  * summer_publish_build: upload a summer.games export to the creator's game
  * through the same creator store routes Studio's export upload uses
@@ -47,7 +47,7 @@ const INTAKE_FAILURES = {
     game_identity_mismatch: "This export belongs to another game. Upload it to its original game, or make a portable export for this game.",
     bundle_invalid: "Summer could not read this export. Export the game again and upload the new file.",
     declaration_mismatch: "The export's game or settings do not match this upload. Use the original game or export a new version with the intended settings.",
-    template_set_unavailable: "Summer Games cannot run this Summer version yet. Update Summer Engine, export again and upload the new file.",
+    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.",
@@ -185,19 +185,28 @@ async function readPart(path, partNumber, partSize, sizeBytes) {
  * Upload the given parts: signed in batches, PUT from disk, re-signed when
  * refused or about to expire. `sign` asks the store for URLs (build
  * publications bind each to its part SHA-256; store versions to its length).
+ * Each sign asks for every part not yet uploaded, including the parts other
+ * workers hold, so one sign usually covers them all. A part fails to sign only
+ * when the store was asked for it and did not sign it; the first fatal error
+ * stops the other workers and aborts their uploads.
  */
 export async function uploadParts(sign, file, sizeBytes, plan, deps, parts = Array.from({ length: plan.partCount }, (_, index) => index + 1)) {
     const queue = [...parts];
+    const unfinished = new Set(parts);
     const grants = new Map();
+    const stop = new AbortController();
+    let failure;
     let signing = null;
     const fresh = (grant) => grant !== undefined && grant.expiresAt - deps.now() > 60_000;
     const grantFor = async (partNumber) => {
-        for (let attempt = 0; attempt < 3; attempt++) {
-            if (fresh(grants.get(partNumber)))
-                return grants.get(partNumber);
+        for (;;) {
+            const grant = grants.get(partNumber);
+            if (fresh(grant))
+                return grant;
             if (!signing) {
-                const batch = [...new Set([partNumber, ...queue.filter((n) => !fresh(grants.get(n)))])].slice(0, MAX_SIGNED_PARTS);
-                signing = sign(batch)
+                const others = [...unfinished].filter((n) => n !== partNumber && !fresh(grants.get(n)));
+                const batch = [partNumber, ...others].slice(0, MAX_SIGNED_PARTS);
+                const done = sign(batch)
                     .then((signed) => {
                     for (const grant of signed)
                         grants.set(grant.partNumber, grant);
@@ -205,43 +214,67 @@ export async function uploadParts(sign, file, sizeBytes, plan, deps, parts = Arr
                     .finally(() => {
                     signing = null;
                 });
+                signing = { batch, done };
+            }
+            const { batch, done } = signing;
+            await done;
+            // The store was asked for this part and did not sign it (or signed it already expiring).
+            if (batch.includes(partNumber) && !fresh(grants.get(partNumber))) {
+                throw new BuildToolError("store_sign_failed", `The store did not sign part ${partNumber}.`, "Recovery: retry; a retry continues the same upload.");
             }
-            await signing;
         }
-        throw new BuildToolError("store_sign_failed", `The store did not sign part ${partNumber}.`, "Recovery: retry; a retry continues the same upload.");
     };
-    const worker = async () => {
-        for (let partNumber = queue.shift(); partNumber !== undefined; partNumber = queue.shift()) {
-            const body = await readPart(file, partNumber, plan.partSizeBytes, sizeBytes);
-            for (let attempt = 0;; attempt++) {
+    const upload = async (partNumber) => {
+        const body = await readPart(file, partNumber, plan.partSizeBytes, sizeBytes);
+        for (let attempt = 0;; attempt++) {
+            let status = null;
+            let error = null;
+            try {
                 const grant = await grantFor(partNumber);
-                let status = null;
-                try {
-                    const response = await deps.fetch(grant.url, {
-                        method: "PUT",
-                        headers: grant.headers,
-                        body,
-                        redirect: "error",
-                        signal: AbortSignal.timeout(600_000),
-                    });
-                    if (response.ok)
-                        break;
-                    status = response.status;
-                }
-                catch {
-                    status = null;
-                }
-                // An expired or refused signature gets a new URL on the next try.
-                if (status === 400 || status === 403)
-                    grants.delete(partNumber);
-                if (attempt >= PART_RETRIES) {
-                    throw new BuildToolError("store_part_upload_failed", `Part ${partNumber} of ${plan.partCount} did not upload${status ? ` (${status})` : ""}.`, "Recovery: retry with the same file and clientVersion; the upload continues where it stopped.");
-                }
-                await deps.sleep(500 * 2 ** attempt);
+                const response = await deps.fetch(grant.url, {
+                    method: "PUT",
+                    headers: grant.headers,
+                    body,
+                    redirect: "error",
+                    signal: AbortSignal.any([stop.signal, AbortSignal.timeout(600_000)]),
+                });
+                if (response.ok)
+                    return;
+                status = response.status;
+            }
+            catch (caught) {
+                error = caught;
+            }
+            if (stop.signal.aborted)
+                return;
+            // An expired or refused signature gets a new URL on the next try.
+            if (status === 400 || status === 403)
+                grants.delete(partNumber);
+            if (attempt >= PART_RETRIES) {
+                if (error instanceof BuildToolError)
+                    throw error;
+                throw new BuildToolError("store_part_upload_failed", `Part ${partNumber} of ${plan.partCount} did not upload${status ? ` (${status})` : ""}.`, "Recovery: retry with the same file and clientVersion; the upload continues where it stopped.");
+            }
+            await deps.sleep(500 * 2 ** attempt);
+            if (stop.signal.aborted)
+                return;
+        }
+    };
+    const worker = async () => {
+        for (let partNumber = queue.shift(); partNumber !== undefined && !stop.signal.aborted; partNumber = queue.shift()) {
+            try {
+                await upload(partNumber);
+                unfinished.delete(partNumber);
+            }
+            catch (error) {
+                failure ??= error;
+                stop.abort();
             }
         }
     };
     await Promise.all(Array.from({ length: Math.min(CONCURRENCY, queue.length) }, worker));
+    if (stop.signal.aborted)
+        throw failure;
 }
 export function normalizeClientVersion(value) {
     const raw = value?.trim() ?? "";
@@ -252,6 +285,10 @@ export function normalizeClientVersion(value) {
     return version;
 }
 function targetPlatforms(bundle) {
+    const mismatch = declarationMismatch(bundle);
+    if (mismatch) {
+        throw new BuildToolError("declaration_mismatch", `The store would refuse this upload (declaration_mismatch): ${mismatch}. Nothing was uploaded and no version was used.`, "Recovery: export again with summer_export_game alignDeclaration:true (it sets summer.build.json targetPlatforms to the targets you export), or with targets equal to what summer.build.json declares; then upload the new export.");
+    }
     if (bundle.hosted)
         return bundle.targetPlatforms;
     const other = bundle.targetPlatforms.filter((platform) => !STANDALONE_TARGETS.includes(platform));
@@ -421,7 +458,17 @@ export async function publishBuild(input, overrides = {}) {
                 break;
             if (publication.state === "failed" || publication.state === "cancelled") {
                 const code = typeof publication.errorCode === "string" ? publication.errorCode : "publication_failed";
-                throw new BuildToolError(code, (code === "declaration_mismatch" && publication.errorMessage) || INTAKE_FAILURES[code] || publication.errorMessage || "Summer could not make a build from this upload.", "Recovery: export again, use a new clientVersion, and retry.", undefined, { publicationId });
+                throw new BuildToolError(code, ((code === "declaration_mismatch" || code === "template_set_unavailable") && publication.errorMessage) ||
+                    INTAKE_FAILURES[code] ||
+                    publication.errorMessage ||
+                    "Summer could not make a build from this upload.", 
+                // The store checks the declaration and the bundle before it records a
+                // client pack, so those refusals leave the version free.
+                code === "declaration_mismatch" || code === "bundle_invalid"
+                    ? "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 });
             }
             if (deps.now() >= deadline) {
                 const result = {

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

@@ -186,8 +186,8 @@ export declare const runtimeAnimateArgsSchema: z.ZodObject<{
     value?: string | number | boolean | undefined;
     instance?: string | undefined;
     name?: string | undefined;
-    cmd?: "state" | "pause" | "play" | "stop" | "seek" | "speed" | "travel" | "start" | "set_param" | "get_param" | undefined;
     space?: "local" | "global" | "both" | undefined;
+    cmd?: "state" | "pause" | "play" | "stop" | "seek" | "speed" | "travel" | "start" | "set_param" | "get_param" | undefined;
     blend?: number | undefined;
     position?: number | undefined;
     speed?: number | undefined;
@@ -205,8 +205,8 @@ export declare const runtimeAnimateArgsSchema: z.ZodObject<{
     value?: string | number | boolean | undefined;
     instance?: string | undefined;
     name?: string | undefined;
-    cmd?: "state" | "pause" | "play" | "stop" | "seek" | "speed" | "travel" | "start" | "set_param" | "get_param" | undefined;
     space?: "local" | "global" | "both" | undefined;
+    cmd?: "state" | "pause" | "play" | "stop" | "seek" | "speed" | "travel" | "start" | "set_param" | "get_param" | undefined;
     blend?: number | undefined;
     position?: number | undefined;
     speed?: number | undefined;

package/dist/core/capabilities/summer-bundle.d.ts

@@ -6,6 +6,15 @@
  */
 export declare const BUNDLE_SCHEMA = "summer.bundle.v1";
 export declare const BUNDLE_MANIFEST = "summer-bundle.json";
+/** The same platforms, in any order. */
+export declare function samePlatforms(a: readonly string[], b: readonly string[]): boolean;
+/**
+ * Why the store will refuse this hosted bundle's Build declaration, or null.
+ * The store requires summer.build.json's targetPlatforms to equal the
+ * platforms the client pack was exported for (declaration_mismatch), and the
+ * refusal spends the clientVersion, so this is checked before any upload.
+ */
+export declare function declarationMismatch(bundle: Pick<SummerBundle, "hostedBuild" | "targetPlatforms">): string | null;
 /** A failure with a stable code, a plain message and the next step. */
 export declare class BuildToolError extends Error {
     readonly code: string;

package/dist/core/capabilities/summer-bundle.js

@@ -12,6 +12,25 @@ export const BUNDLE_MANIFEST = "summer-bundle.json";
 const BUNDLE_CLIENT = "client.pck";
 const BUNDLE_SERVER = "server.pck";
 const BUNDLE_BUILD = "config/summer.build.json";
+/** The same platforms, in any order. */
+export function samePlatforms(a, b) {
+    return a.length === b.length && [...a].sort().join(",") === [...b].sort().join(",");
+}
+/**
+ * Why the store will refuse this hosted bundle's Build declaration, or null.
+ * The store requires summer.build.json's targetPlatforms to equal the
+ * platforms the client pack was exported for (declaration_mismatch), and the
+ * refusal spends the clientVersion, so this is checked before any upload.
+ */
+export function declarationMismatch(bundle) {
+    const declared = bundle.hostedBuild?.targetPlatforms;
+    if (!Array.isArray(declared))
+        return null;
+    const platforms = declared.map(String);
+    return samePlatforms(platforms, bundle.targetPlatforms)
+        ? null
+        : `the bundle targets ${[...bundle.targetPlatforms].sort().join(", ")} but its summer.build.json declares ${[...platforms].sort().join(", ")}`;
+}
 const SHA256 = /^sha256:[0-9a-f]{64}$/;
 const AS_EXPORTED = "Recovery: export the game again with the summer.games preset and use the .zip exactly as Summer Engine wrote it.";
 /** A failure with a stable code, a plain message and the next step. */

package/dist/core/capabilities/tool-dispatch.js

@@ -28,7 +28,7 @@ import { executeSceneMutation, occurrenceCount, readTextPayload, safeProjectPath
 import { extractOpError, withOldEngineHint } from "./engine-receipt.js";
 import { lookupApiDocs } from "./api-docs.js";
 import { BOARD_ENDPOINT, boardArgsSchema, boardQuery } from "./board.js";
-import { imageGenerationArgsSchema } from "./image-generation.js";
+import { IMAGE_GENERATION_TIMEOUT_MS, imageGenerationArgsSchema, saveGeneratedImage } from "./image-generation.js";
 import { buildMotionRequestBody, motionGenerationArgsSchema } from "./motion-generation.js";
 import { ImportHdriError, importHdriArgsSchema, importPolyHavenHdri } from "./hdri-import.js";
 import { FABRICATE_FALLBACK, buildFabricateMeshOp, fabricateArgsSchema } from "./fabricate-mesh.js";
@@ -618,6 +618,7 @@ export const TOOL_DISPATCH = [
         targets: Array.isArray(args.targets) ? args.targets.map(String) : undefined,
         format: optStr(args, "format"),
         debug: args.debug === true,
+        alignDeclaration: args.alignDeclaration === true,
         ...(typeof args.timeoutSeconds === "number" ? { timeoutMs: args.timeoutSeconds * 1000 } : {}),
     })),
     entry("summer_export_templates", "List or install Summer export templates from the CDN (web, macos, windows)", false, (args) => {
@@ -639,6 +640,8 @@ export const TOOL_DISPATCH = [
         waitSeconds: optNumberOrUndefined(args, "waitSeconds"),
         intervalSeconds: optNumberOrUndefined(args, "intervalSeconds"),
         out: optStr(args, "out"),
+        args: args.args,
+        steps: args.steps,
     })),
     entry("summer_publish_build", "Upload a summer.games export to your store game (confirm-gated)", false, (args) => publishBuild({
         gameId: optStr(args, "gameId"),
@@ -896,7 +899,15 @@ export const TOOL_DISPATCH = [
         const parsed = parseToolArgs(boardArgsSchema, args, "get-board");
         return gatewayGet(BOARD_ENDPOINT, boardQuery({ ...parsed, pictures: parsed.pictures ?? false }), 45_000);
     }),
-    entry("summer_generate_image", "Generate or edit an image via Summer Studio", false, (args) => gatewayPost("/api/mcp/generate/image", parseToolArgs(imageGenerationArgsSchema, args, "generate-image"))),
+    entry("summer_generate_image", "Generate or edit an image via Summer Studio", false, async (args) => {
+        const { out, ...body } = parseToolArgs(imageGenerationArgsSchema, args, "generate-image");
+        const result = await gatewayPost("/api/mcp/generate/image", body, IMAGE_GENERATION_TIMEOUT_MS);
+        if (!out)
+            return result;
+        const asset = (result.asset ?? {});
+        const url = typeof asset.fileUrl === "string" ? asset.fileUrl : typeof asset.thumbnailUrl === "string" ? asset.thumbnailUrl : null;
+        return { ...result, localPath: url ? await saveGeneratedImage(url, out) : null };
+    }),
     entry("summer_slice_asset_sheet", "Detect and crop every asset from a generated sheet image", false, (args) => gatewayPost("/api/mcp/generate/slice-asset-sheet", { assetId: str(args, "assetId") }, 300_000)),
     entry("summer_generate_audio", "Generate speech, sound effects, music, or dialogue", false, (args) => {
         const body = { capability: str(args, "capability") };

package/dist/core/library-read.d.ts

@@ -10,6 +10,8 @@ export declare const FOOTER_SUFFIX = "If this entry is wrong, stale, or you devi
 export declare const LINKED_FILE_EXTENSIONS: ReadonlySet<string>;
 /** A linked file larger than this is refused rather than dumped. */
 export declare const LINKED_FILE_MAX_BYTES: number;
+/** How long a hosted skill read waits for the hosted Summer Engine MCP. */
+export declare const HOSTED_READ_TIMEOUT_MS = 8000;
 export declare const readLibraryInputShape: {
     id: z.ZodString;
     part: z.ZodOptional<z.ZodEnum<["skill", "resource", "all"]>>;
@@ -29,6 +31,8 @@ export interface LibraryReadDeps extends LibrarySearchDeps {
     /** Root holding library/ (default: the installed package). */
     packageRoot?: string;
     templates?: readonly TemplateEntry[];
+    /** Reads a hosted skill's text by resource URI; throws when it cannot. */
+    readHostedResource?: (uri: string) => Promise<string>;
 }
 export interface LibraryReadOk {
     ok: true;
@@ -57,6 +61,9 @@ export interface LibraryReadOk {
         target: string;
         id: string | null;
     }>;
+    /** Hosted skills: the resource the body comes from, and why it did not load. */
+    hosted_resource?: string;
+    hosted_error?: string;
     /** Tool records: how to reach it. */
     mcp_tool_name?: string;
     cli_command?: string;

package/dist/core/library-read.js

@@ -31,11 +31,18 @@
  * ships it; and `reference/<slug>` that is no entry falls back to the one
  * `references/<slug>.md` an entry ships. A body render ends with its links and
  * the id that loads each. A linked file's footer names its entry.
+ *
+ * Hosted skills: a skill whose resource.yaml names a `hosted_resource`
+ * (summer://skills/<slug>) keeps its current text on the hosted Summer Engine
+ * MCP, the text the Studio agent reads. The body is read from there with the
+ * store sign-in; without it the local SKILL.md renders with the reason and how
+ * to load the full text. The entry also resolves by that resource URI.
  */
 import { existsSync, readdirSync, readFileSync, realpathSync, statSync } from "node:fs";
 import { join, posix, sep } from "node:path";
 import { z } from "zod";
 import { LIBRARY_KIND_DIRS, loadLibraryIndex, searchLibrary, } from "./library-search.js";
+import { withHostedMcp } from "./hosted-mcp.js";
 import { PACKAGE_ROOT } from "./package-root.js";
 import { getTemplateRegistry } from "./templates.js";
 export const READ_PARTS = ["skill", "resource", "all"];
@@ -60,6 +67,8 @@ export const LINKED_FILE_EXTENSIONS = new Set([
 ]);
 /** A linked file larger than this is refused rather than dumped. */
 export const LINKED_FILE_MAX_BYTES = 256 * 1024;
+/** How long a hosted skill read waits for the hosted Summer Engine MCP. */
+export const HOSTED_READ_TIMEOUT_MS = 8_000;
 export const readLibraryInputShape = {
     id: z
         .string()
@@ -81,13 +90,13 @@ export function entryIdWithHash(id, contentHash) {
     return hash ? `${id}@${hash}` : id;
 }
 // ── Resolution ─────────────────────────────────────────────────────────────
-/** Exact id, an id with an @hash suffix (as the footer prints it), or a bare
- *  slug that names exactly one entry. */
+/** Exact id, an id with an @hash suffix (as the footer prints it), a hosted
+ *  skill's resource URI, or a bare slug that names exactly one entry. */
 function resolveEntry(requested, entries) {
     const bare = requested.trim().replace(/@[a-f0-9]+$/i, "");
     if (!bare)
         return null;
-    const exact = entries.find((entry) => entry.id === bare);
+    const exact = entries.find((entry) => entry.id === bare || entry.hosted_resource === bare);
     if (exact)
         return exact;
     if (!bare.includes("/")) {
@@ -324,7 +333,7 @@ function relatedMap(entry) {
     }
     return out;
 }
-function header(entry, slug, related) {
+function header(entry, slug, related, hostedLoaded) {
     const lines = [];
     lines.push(`${entry.id} — ${entry.kind} v${entry.version ?? "?"} (${entry.status ?? "stable"})`);
     if (entry.summary)
@@ -338,7 +347,10 @@ function header(entry, slug, related) {
     const relatedIds = Object.values(related).flat();
     if (relatedIds.length > 0)
         lines.push(`related: ${relatedIds.join(", ")}`);
-    if (entry.kind === "skill") {
+    if (hostedLoaded) {
+        lines.push(`The body is the current text from the hosted Summer Engine MCP (also the \`${slug}\` MCP prompt and the resource ${entry.hosted_resource}). Follow it, do not paraphrase it.`);
+    }
+    else if (entry.kind === "skill") {
         lines.push(`Invoke: the \`${slug}\` skill in your host (Claude Code: /${slug}); installed under its bare slug by \`summer setup\`. The body follows — follow it, do not paraphrase it.`);
     }
     return lines.join("\n");
@@ -451,7 +463,21 @@ export async function readLibraryEntry(requestedId, part = "all", deps = {}) {
     let bodyTitle;
     let body;
     let links = [];
-    if (kind === "tool") {
+    let hostedText = null;
+    let hostedError;
+    if (kind === "skill" && entry.hosted_resource && part !== "resource") {
+        try {
+            hostedText = (await (deps.readHostedResource ?? readHostedSkill)(entry.hosted_resource)).replace(/\s+$/, "");
+        }
+        catch (error) {
+            hostedError = error instanceof Error ? error.message : String(error);
+        }
+    }
+    if (hostedText !== null) {
+        bodyTitle = `${entry.hosted_resource} (hosted Summer Engine MCP)`;
+        body = hostedText;
+    }
+    else if (kind === "tool") {
         bodyTitle = "how to call";
         body = toolBody(entry, slug);
     }
@@ -474,11 +500,14 @@ export async function readLibraryEntry(requestedId, part = "all", deps = {}) {
             body = `(no body file shipped for this ${kind}; the descriptor below is all there is)`;
         }
     }
-    const sections = [header(entry, slug, related)];
+    const sections = [header(entry, slug, related, hostedText !== null)];
     if (part === "skill" || part === "all") {
         sections.push(`--- ${bodyTitle} ---\n${body}`);
         if (links.length > 0)
             sections.push(linksSection(links));
+        if (hostedError !== undefined) {
+            sections.push(`--- hosted text not loaded ---\nThe full current text of this skill is the resource ${entry.hosted_resource} on the hosted Summer Engine MCP, and it could not be read: ${hostedError}\nThe body above is only the local summary: load the full text before you act (here after the fix, or as the \`${slug}\` MCP prompt or resource in a host connected to the hosted Summer Engine MCP).`);
+        }
     }
     if (part === "resource" || part === "all")
         sections.push(`--- ${relPath}/resource.yaml ---\n${resourceYaml}`);
@@ -486,6 +515,10 @@ export async function readLibraryEntry(requestedId, part = "all", deps = {}) {
     const result = { ...base, text: sections.join("\n\n") };
     if (bodyFile)
         result.body_file = bodyFile;
+    if (entry.hosted_resource)
+        result.hosted_resource = entry.hosted_resource;
+    if (hostedError !== undefined)
+        result.hosted_error = hostedError;
     if (links.length > 0 && part !== "resource")
         result.links = links;
     if (kind === "tool") {
@@ -499,6 +532,25 @@ export async function readLibraryEntry(requestedId, part = "all", deps = {}) {
     }
     return result;
 }
+/** A hosted skill's text, read from the hosted Summer Engine MCP with the store sign-in. */
+async function readHostedSkill(uri) {
+    let timer;
+    const timeout = new Promise((_, reject) => {
+        timer = setTimeout(() => reject(new Error(`the hosted Summer Engine MCP did not answer within ${HOSTED_READ_TIMEOUT_MS / 1000} s.`)), HOSTED_READ_TIMEOUT_MS);
+        timer.unref?.();
+    });
+    try {
+        const result = await Promise.race([withHostedMcp((client) => client.readResource({ uri })), timeout]);
+        const contents = Array.isArray(result.contents) ? result.contents : [];
+        const text = contents.map((content) => (typeof content.text === "string" ? content.text : "")).join("\n").trim();
+        if (!text)
+            throw new Error("the hosted Summer Engine MCP returned no text for it.");
+        return text;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
 function safeTemplates() {
     try {
         return getTemplateRegistry();

package/dist/core/library-search.d.ts

@@ -49,6 +49,8 @@ export interface LibraryIndexEntry {
     cli_command?: string;
     authority?: Record<string, boolean>;
     recommended?: boolean;
+    /** The hosted Summer Engine MCP resource holding the skill's current text. */
+    hosted_resource?: string;
 }
 export type MatchedBy = "lexical" | "semantic";
 export interface LibrarySearchHit {

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

@@ -45,6 +45,31 @@ export declare function resolveAgentSelection(agentArg: string | undefined, agen
 /** `--scope` with a user-facing error; absent means "user". */
 export declare function resolveConfigScope(scopeOpt: string | undefined): ConfigScope;
 export declare function configureAgentMcp(options: AgentConfigOptions): Promise<AgentConfigResult>;
+/** The Summer Games player MCP: friends, parties, messages and the player's
+ *  inbox, as the signed-in player. A remote server; the agent signs in to it
+ *  with OAuth in the browser, so setup writes no credential. */
+export declare const SUMMER_GAMES_MCP_SERVER_NAME = "summer-games";
+export declare const SUMMER_GAMES_MCP_URL = "https://mcp.summer.games/mcp";
+export interface RemoteMcpResult {
+    /** The entry's name: summer-games, or the name the person already gave it. */
+    serverName: string;
+    url: string;
+    path: string;
+    changed: boolean;
+    wrote: boolean;
+    /** Set when the server was already listed under another name (e.g. a
+     *  hand-added "summer"); setup then leaves the file alone. */
+    existingName?: string;
+    /** What the person does once to sign in (the agent opens summer.games). */
+    signIn: string;
+}
+/**
+ * Adds the Summer Games MCP next to summer-engine in the same config file, in
+ * the agent's own entry shape (remoteMcp in agent-table.ts). An entry that
+ * already points at the same URL, under any name, counts as added and is left
+ * as it is. Returns null for agents without remoteMcp.
+ */
+export declare function configureSummerGamesMcp(options: Pick<AgentConfigOptions, "agent" | "scope" | "dryRun" | "cwd" | "env">): Promise<RemoteMcpResult | null>;
 export declare const DEFAULT_CHANNEL = "latest";
 /** npm dist-tags are lowercase words like `latest`, `next`, `beta`, `v3-preview`;
  *  anything that could be read as a version or a path is refused (a bare
@@ -60,4 +85,4 @@ export declare function mcpEntry(format: McpFormat, server: StdioMcpServerConfig
 export declare function resolvePackageRoot(): string;
 /** Directory name Gemini expects the extension under; the manifest `name` must match it. */
 export declare const GEMINI_EXTENSION_DIR_NAME = "summer-engine";
-export declare function upsertTomlArrayBlock(content: string, block: string): string;
+export declare function upsertTomlArrayBlock(content: string, block: string, name?: string): string;