summer-engine 3.4.1 → 3.5.0

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.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.",
@@ -252,6 +252,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 +425,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/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.
+ * 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 a remote-server
+ * entry in agent-table.ts.
+ */
+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

package/dist/installer/agent-config.js

@@ -73,6 +73,116 @@ export async function configureAgentMcp(options) {
         nextSteps: [`Updated ${target.path}.`, spec.restart],
     };
 }
+/** 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 const SUMMER_GAMES_MCP_SERVER_NAME = "summer-games";
+export const SUMMER_GAMES_MCP_URL = "https://mcp.summer.games/mcp";
+/**
+ * Adds the Summer Games MCP next to summer-engine in the same config file.
+ * 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 a remote-server
+ * entry in agent-table.ts.
+ */
+export async function configureSummerGamesMcp(options) {
+    const spec = agentSpec(options.agent);
+    if (!spec.remoteMcp)
+        return null;
+    const env = options.env ?? process.env;
+    const target = resolveConfigTarget(spec, options.scope, resolve(options.cwd ?? process.cwd()), env);
+    const write = !options.dryRun;
+    const url = SUMMER_GAMES_MCP_URL;
+    let existing;
+    let changed = false;
+    if (spec.remoteMcp.format === "toml-url") {
+        const current = await readTextFileIfExists(target.path);
+        existing = findTomlServerByUrl(current, url);
+        if (!existing) {
+            const name = SUMMER_GAMES_MCP_SERVER_NAME;
+            const next = upsertTomlTable(current, `[mcp_servers.${name}]\nurl = ${tomlString(url)}\n`, name);
+            changed = current !== next;
+            if (write && changed)
+                await writeTextFile(target.path, next);
+        }
+    }
+    else {
+        const current = await readJsonConfig(target.path);
+        existing = findJsonServerByUrl(current, url);
+        if (!existing) {
+            const next = copyJsonObject(current);
+            next.mcpServers = mergeNamedObject(next.mcpServers, SUMMER_GAMES_MCP_SERVER_NAME, { type: "http", url }, "mcpServers");
+            const nextRendered = renderJsonFile(next);
+            changed = renderJsonFile(current) !== nextRendered;
+            if (write && changed)
+                await writeTextFile(target.path, nextRendered);
+        }
+    }
+    const serverName = existing ?? SUMMER_GAMES_MCP_SERVER_NAME;
+    return {
+        serverName,
+        url,
+        path: target.path,
+        changed,
+        wrote: write && changed,
+        ...(existing && existing !== SUMMER_GAMES_MCP_SERVER_NAME ? { existingName: existing } : {}),
+        signIn: spec.remoteMcp.signIn(serverName),
+    };
+}
+function sameMcpUrl(a, b) {
+    if (typeof a !== "string")
+        return false;
+    const normalize = (value) => {
+        try {
+            const parsed = new URL(value.trim());
+            return `${parsed.protocol}//${parsed.host}${parsed.pathname.replace(/\/+$/, "")}`.toLowerCase();
+        }
+        catch {
+            return value.trim().toLowerCase();
+        }
+    };
+    return normalize(a) === normalize(b);
+}
+/** The name of a server with this URL in mcpServers. Claude Code's
+ *  ~/.claude.json also keeps per-project servers (`claude mcp add` without
+ *  --scope user) under projects.<dir>.mcpServers; those count too. */
+function findJsonServerByUrl(config, url) {
+    const maps = [config.mcpServers];
+    if (isJsonObject(config.projects)) {
+        for (const project of Object.values(config.projects)) {
+            if (isJsonObject(project))
+                maps.push(project.mcpServers);
+        }
+    }
+    for (const map of maps) {
+        if (!isJsonObject(map))
+            continue;
+        for (const [name, entry] of Object.entries(map)) {
+            if (isJsonObject(entry) && sameMcpUrl(entry.url, url))
+                return name;
+        }
+    }
+    return undefined;
+}
+/** The name of a [mcp_servers.<name>] table whose url is this URL. */
+function findTomlServerByUrl(content, url) {
+    let table;
+    for (const line of content.split(/\r?\n/)) {
+        const header = /^\s*\[([^\[\]]+)\]\s*(?:#.*)?$/.exec(line);
+        if (header) {
+            const server = /^mcp_servers\.(?:"([^"]+)"|([A-Za-z0-9_-]+))$/.exec(header[1].trim());
+            table = server ? (server[1] ?? server[2]) : undefined;
+            continue;
+        }
+        if (/^\s*\[/.test(line)) {
+            table = undefined;
+            continue;
+        }
+        const value = /^\s*url\s*=\s*(?:"([^"]*)"|'([^']*)')/.exec(line);
+        if (table && value && sameMcpUrl(value[1] ?? value[2], url))
+            return table;
+    }
+    return undefined;
+}
 async function upsertConfig(format, path, server, write) {
     switch (format) {
         case "toml":
@@ -470,10 +580,11 @@ async function readTextFileIfExists(path) {
         throw new Error(`Could not read ${path}: ${formatError(error)}`);
     }
 }
-function upsertTomlTable(content, table) {
+function upsertTomlTable(content, table, name = SUMMER_MCP_SERVER_NAME) {
     const lines = content.split(/\r?\n/);
-    const serverHeader = /^\s*\[mcp_servers\.(?:"summer-engine"|summer-engine)(?:\.|\])/;
-    const start = lines.findIndex((line) => /^\s*\[mcp_servers\.(?:"summer-engine"|summer-engine)\]\s*(?:#.*)?$/.test(line));
+    const key = name.replace(/[.*+?^${}()|[\]\\-]/g, "\\$&");
+    const serverHeader = new RegExp(`^\\s*\\[mcp_servers\\.(?:"${key}"|${key})(?:\\.|\\])`);
+    const start = lines.findIndex((line) => new RegExp(`^\\s*\\[mcp_servers\\.(?:"${key}"|${key})\\]\\s*(?:#.*)?$`).test(line));
     if (start === -1) {
         const trimmed = content.endsWith("\n") || content === "" ? content : `${content}\n`;
         return `${trimmed}${trimmed === "" ? "" : "\n"}${table}`;

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

@@ -22,6 +22,7 @@ export type ConfigScope = "user" | "project";
  *  json-gemini   the Gemini extension manifest (legacy)
  */
 export type McpFormat = "json" | "json-stdio" | "json-vscode" | "json-copilot" | "json-opencode" | "json-servers" | "json-zed" | "json-amp" | "json-crush" | "json-transport" | "toml" | "toml-array" | "yaml-goose" | "yaml-hermes" | "json-gemini";
+export type RemoteMcpFormat = "json-http" | "toml-url";
 export type SkillLocationKind = "skill-dir" | "cursor-rule-dir" | "windsurf-rule-file" | "cline-rule-dir" | "opencode-skill-dir";
 export interface PathContext {
     home: string;
@@ -70,6 +71,17 @@ export interface AgentSpec {
     /** Env var that overrides the MCP config path (tests, unusual installs). */
     envOverride: string;
     format: McpFormat;
+    /**
+     * How this agent lists a remote MCP server that signs in with OAuth on its
+     * own (the Summer Games player MCP). Absent: setup links the engine only.
+     *  json-http { mcpServers: { <name>: { type: "http", url } } }   (Claude Code)
+     *  toml-url  [mcp_servers.<name>] url                            (Codex)
+     * signIn tells the person how to sign in once, for the entry's name.
+     */
+    remoteMcp?: {
+        format: RemoteMcpFormat;
+        signIn: (name: string) => string;
+    };
     mcp: {
         /** null: user-level servers are managed in the app's UI; a user request writes the project file with a warning. */
         user: ((ctx: PathContext) => string) | null;

package/dist/installer/agent-table.js

@@ -108,6 +108,7 @@ const SPECS = [
         status: "active",
         envOverride: "SUMMER_CLAUDE_CONFIG_FILE",
         format: "json-stdio",
+        remoteMcp: { format: "json-http", signIn: (name) => `In Claude Code, run /mcp, choose ${name} and sign in.` },
         mcp: { user: home(".claude.json"), project: project(".mcp.json") },
         restart: "Restart Claude Code or run /mcp in a new session.",
         skills: skillDirs(home(".claude", "skills"), project(".claude", "skills")),
@@ -134,6 +135,10 @@ const SPECS = [
         status: "active",
         envOverride: "SUMMER_CODEX_CONFIG_FILE",
         format: "toml",
+        remoteMcp: {
+            format: "toml-url",
+            signIn: (name) => `In Codex, run /mcp login ${name} (or \`codex mcp login ${name}\` in a terminal) and sign in.`,
+        },
         mcp: {
             user: home(".codex", "config.toml"),
             project: project(".codex", "config.toml"),
@@ -149,6 +154,10 @@ const SPECS = [
         status: "active",
         envOverride: "SUMMER_CURSOR_MCP_CONFIG_FILE",
         format: "json-stdio",
+        // No remoteMcp (Summer Games) yet: Cursor's fallback OAuth flow registers
+        // cursor://anysphere.cursor-mcp/oauth/callback, which api.summer.games
+        // refuses (summer-platform#1681 allows it). Add { format: "json-url" }
+        // ({ mcpServers: { <name>: { url } } }) once that is live.
         mcp: { user: home(".cursor", "mcp.json"), project: project(".cursor", "mcp.json") },
         restart: "Restart Cursor and enable the summer-engine MCP server if prompted.",
         skills: sharedSkills({