summer-engine 2.6.0 → 2.6.3

package/README.md

@@ -2,21 +2,48 @@
 
 Build real 2D and 3D games through conversation. No coding required. Export to Steam, desktop, mobile, and web. Built on the Godot team's work, customized and honed so AI agents and humans can collaborate on great games.
 
-**Summer** is the MIT open-source agent layer that connects your AI coding agent to Summer Engine: CLI, MCP server, skills, hooks, and plugin manifests. First-class setup works in Claude Code, Cursor, Codex, Windsurf, Cline, Roo Code, Gemini CLI, GitHub Copilot CLI, GitHub Copilot in VS Code, and OpenCode. Factory Droid uses the plugin marketplace path.
+**Summer** is the MIT open-source agent layer that connects your AI coding agent to Summer Engine. It is the **Summer CLI**, the **Summer MCP** server, and the **Summer agent** skills, hooks, and plugin manifests, all in one package. First-class setup works in Claude Code, Cursor, Codex, Devin Desktop (formerly Windsurf), Cline, Roo Code, Gemini CLI, GitHub Copilot CLI, GitHub Copilot in VS Code, and OpenCode. Factory Droid uses the plugin marketplace path.
 
 - **Source:** [github.com/SummerEngine/summer-engine-agent](https://github.com/SummerEngine/summer-engine-agent)
-- **Docs:** [summerengine.com/docs](https://summerengine.com/docs)
-- **MCP setup:** [summerengine.com/mcp](https://summerengine.com/mcp)
+- **CLI setup:** [www.summerengine.com/cli](https://www.summerengine.com/cli)
+- **MCP setup:** [www.summerengine.com/mcp](https://www.summerengine.com/mcp)
+- **Docs:** [docs.summerengine.com](https://docs.summerengine.com)
 
 It just works. Open your agent, say *"let's make an FPS in Summer Engine,"* and it does.
 
 ---
 
+## Summer CLI, Summer MCP, and the Summer agent
+
+Three names, one npm package (`summer-engine`):
+
+- **Summer CLI** (`npx -y summer-engine@latest`): installs the engine, signs you in, scaffolds and runs projects, and writes your agent's config. See [www.summerengine.com/cli](https://www.summerengine.com/cli).
+- **Summer MCP**: the local MCP server that gives your agent 44 engine tools to build, run, and debug a real game. See [www.summerengine.com/mcp](https://www.summerengine.com/mcp).
+- **Summer agent layer**: the game-dev skills, hooks, and plugin manifests that give your AI agent judgment, not just a chat box.
+
+All MIT, all free to use. One paste sets up all three.
+
+## Summer Cloud (new in 2.6.0)
+
+`summer cloud` syncs your whole game project across machines: scenes, scripts, settings, and the big binary assets that never fit in git. Files are stored by content hash, every push becomes a restorable version, and local checkpoints are taken before anything destructive touches your disk.
+
+```bash
+summer cloud init      # bind this project to your account
+summer cloud push      # upload what changed (only missing bytes travel)
+summer cloud pull      # make this machine match the cloud, verified by hash
+summer cloud status    # what differs between here and the cloud
+summer cloud restore   # roll the project back to any version
+```
+
+The same operations are available to agents as MCP tools (`summer_cloud_push`, `summer_cloud_pull`, and friends). See [www.summerengine.com/cloud](https://www.summerengine.com/cloud).
+
+---
+
 ## Get started: one prompt
 
-Open your AI agent (Claude Code, Cursor, Codex, Copilot, Windsurf, etc.) and paste:
+Open your AI agent (Claude Code, Cursor, Codex, Copilot, Devin Desktop, etc.) and paste:
 
-> Install Summer Engine and let's make a game.
+> Install Summer Engine and let's make a game. Read github.com/SummerEngine/summer-engine-agent, check what I already have installed, install whatever is missing, log me in, and scaffold a starter project so we can start building.
 
 That's it. The agent reads this README, detects what's already on your machine, and runs only what's missing via Bash. **No `/plugin` slash commands. No manual installs. One paste.**
 
@@ -75,7 +102,7 @@ The relevant check ids are `node-version`, `cli-version`, `cli-version-current`,
 npx -y summer-engine@latest setup claude-code --yes --force
 ```
 
-Replace `claude-code` with the user's actual agent: `codex`, `cursor`, `windsurf`, `cline`, `roo-code`, `gemini`, `github-copilot`, `vscode-copilot`, or `opencode`. Use `github-copilot` for Copilot CLI and `vscode-copilot` for GitHub Copilot Chat/Agent in VS Code. Factory Droid still uses the plugin marketplace path in the install section below. This writes the current Summer skill bundle to `~/.claude/skills/<name>/SKILL.md` (or the agent's equivalent user-skill directory) AND writes the MCP server config so the agent can talk to the engine. The `--force` flag wipes any stale skill content first, so re-runs always end up with the latest copy.
+Replace `claude-code` with the user's actual agent: `codex`, `cursor`, `windsurf`, `cline`, `roo-code`, `kilo-code`, `gemini`, `github-copilot`, `vscode-copilot`, `opencode`, or `lm-studio`. Use `github-copilot` for Copilot CLI and `vscode-copilot` for GitHub Copilot Chat/Agent in VS Code. Factory Droid still uses the plugin marketplace path in the install section below. This writes the current Summer skill bundle to `~/.claude/skills/<name>/SKILL.md` (or the agent's equivalent user-skill directory) AND writes the MCP server config so the agent can talk to the engine. The `--force` flag wipes any stale skill content first, so re-runs always end up with the latest copy.
 
 **First-install detection:** if `~/.claude/skills/` didn't exist before this command, Claude Code wasn't watching it and won't auto-detect the new files this session. Tell the user **once**: "Skills installed - restart your agent so they load." On subsequent installs (directory already existed), skills auto-detect mid-session and no restart is needed. **You can detect first-install vs upgrade by checking if `~/.claude/skills/` existed before Step 1; record the result before running setup.**
 
@@ -165,7 +192,7 @@ Only skip brainstorm if the user explicitly said "skip brainstorm" or "just buil
 - **Don't loop `summer login` if it times out at 120s.** Re-run it once and tell the user to be quicker; loop forever and the user is stuck.
 - **Don't jump straight into `summer create` from a vague prompt.** Invoke `summer:brainstorm-game` first (Step 6). The build skills assume `.summer/GameSoul.md` exists.
 
-**Using a different agent?** Replace `claude-code` with any supported agent in Step 1: `codex`, `cursor`, `windsurf`, `cline`, `roo-code`, `gemini`, `github-copilot`, `vscode-copilot`, or `opencode`. Skill targets vary per agent (Cursor uses `.cursor/rules/`, Windsurf uses `.windsurfrules`, Cline + Roo use `.clinerules/`, Copilot uses `~/.copilot/skills` or `.github/skills`, OpenCode uses agent definitions, etc.). The CLI handles the difference. After install, **Cline and Roo Code users should restart VS Code** so the extension reloads its MCP config. **Gemini users** may need to run `gemini extensions enable summer-engine` after the first install. **VS Code Copilot users** should start the `summer-engine` MCP server from Agent mode if VS Code does not autostart it. **Factory Droid** still has its own plugin path below.
+**Using a different agent?** Replace `claude-code` with any supported agent in Step 1: `codex`, `cursor`, `windsurf`, `cline`, `roo-code`, `kilo-code`, `gemini`, `github-copilot`, `vscode-copilot`, `opencode`, or `lm-studio`. (`devin` is also accepted as an alias for `windsurf`.) Skill targets vary per agent (Cursor uses `.cursor/rules/`, Devin Desktop uses `.windsurfrules`, Cline + Roo use `.clinerules/`, Copilot uses `~/.copilot/skills` or `.github/skills`, OpenCode uses agent definitions, etc.). The CLI handles the difference. After install, **Cline and Roo Code users should restart VS Code** so the extension reloads its MCP config. **Gemini users** may need to run `gemini extensions enable summer-engine` after the first install. **VS Code Copilot users** should start the `summer-engine` MCP server from Agent mode if VS Code does not autostart it. **Factory Droid** still has its own plugin path below.
 
 **Power-user note:** if the user specifically wants `summer` on their `PATH` for everyday terminal use outside the AI agent, a global npm install is still possible. The agent flow doesn't need it.
 
@@ -363,7 +390,15 @@ Writes the MCP server config to VS Code's globalStorage for the Cline extension
 npx -y summer-engine@latest setup roo-code --yes
 ```
 
-Same shape as Cline (Roo Code is a Cline fork): writes globalStorage MCP config and `.clinerules/` files. **Restart VS Code** afterward.
+Same shape as Cline (Roo Code is a Cline fork): writes globalStorage MCP config and `.clinerules/` files. **Restart VS Code** afterward. Note: Roo Code shut down in May 2026 — prefer Kilo Code, its maintained successor.
+
+### Kilo Code (VS Code)
+
+```bash
+npx -y summer-engine@latest setup kilo-code --yes
+```
+
+Writes the MCP server config to VS Code's globalStorage for the Kilo Code extension (project scope writes `.kilocode/mcp.json`) and drops rules into `.kilocode/rules/`. **Restart VS Code** so Kilo reloads its MCP config.
 
 ### Gemini CLI
 
@@ -397,7 +432,19 @@ npx -y summer-engine@latest setup opencode --yes
 
 Writes the MCP server entry into `opencode.json` (`~/.config/opencode/opencode.json` for user scope, `./opencode.json` for project) using the array-shaped `command: ["npx", "-y", "summer-engine@latest", "mcp"]` format. Restart OpenCode. Full guide: [`.opencode/INSTALL.md`](./.opencode/INSTALL.md).
 
-### Windsurf and others
+### LM Studio (local models)
+
+```bash
+npx -y summer-engine@latest setup lm-studio --yes
+```
+
+Writes the MCP server entry into `~/.lmstudio/mcp.json` (app-global; there is no project scope). In LM Studio, toggle the `summer-engine` server on in the **Program** tab, and raise the loaded model's context length to **32k or higher** — MCP tool schemas overflow small contexts silently. LM Studio has no rules/skills folder; the MCP server's `summer_get_agent_playbook` tool covers in-chat guidance. Pair with a tool-calling-reliable local model (gpt-oss-20b on 12–16 GB VRAM, Qwen3-Coder-30B on 24 GB).
+
+### Ollama (local models)
+
+Ollama is the model backend, not an MCP client — pair it with OpenCode, Kilo Code, or Goose and point that agent's provider at `http://localhost:11434/v1`. Before connecting MCP, raise Ollama's context window (defaults to 4k under 24 GB VRAM): start with `OLLAMA_CONTEXT_LENGTH=65536 ollama serve`, then `ollama ps` to confirm the model still fits on the GPU.
+
+### Devin Desktop (formerly Windsurf) and others
 
 ```bash
 npx -y summer-engine@latest setup <agent> --yes --force
@@ -429,7 +476,7 @@ npx -y summer-engine@latest doctor
 | `summer mcp setup <agent>` | Write MCP config for an agent. |
 | `summer setup <agent> [--yes]` | One shot: MCP config + recommended skills + doctor. |
 
-Agents: `claude-code`, `codex`, `cursor`, `windsurf`, `cline`, `roo-code`, `gemini`, `opencode`. Scopes: `--scope user` (default), `--scope project`.
+Agents: `claude-code`, `codex`, `cursor`, `windsurf`, `cline`, `roo-code`, `kilo-code`, `gemini`, `github-copilot`, `vscode-copilot`, `opencode`, `lm-studio`. (`devin` and `devin-desktop` are accepted as aliases for `windsurf`.) Scopes: `--scope user` (default), `--scope project`.
 
 ---
 

package/dist/bin/summer.js

@@ -56,7 +56,7 @@ function printIntro(version) {
     console.log(`     ${sym.arrow()} ${c.bold("Summer Engine")} ${c.dim("v" + version)}  ${c.dim("·")}  AI-native game engine`);
     console.log("");
     console.log(`     ${c.bold("Setup wizard")}`);
-    console.log(`     Open Claude Code, Cursor, Codex, Copilot, Windsurf, or another supported agent and paste:`);
+    console.log(`     Open Claude Code, Cursor, Codex, Copilot, Devin Desktop (formerly Windsurf), or another supported agent and paste:`);
     console.log(`     ${c.brand("\"Install Summer Engine and let's make a game.\"")}`);
     console.log("");
     console.log(`     ${c.bold("Manual commands")}`);

package/dist/commands/setup.js

@@ -10,13 +10,15 @@ const AGENT_LABEL = {
     "claude-code": "Claude Code",
     codex: "Codex",
     cursor: "Cursor",
-    windsurf: "Windsurf",
+    windsurf: "Devin Desktop (Windsurf)",
     cline: "Cline",
     "roo-code": "Roo Code",
+    "kilo-code": "Kilo Code",
     gemini: "Gemini CLI",
     "github-copilot": "GitHub Copilot CLI",
     "vscode-copilot": "GitHub Copilot in VS Code",
     opencode: "OpenCode",
+    "lm-studio": "LM Studio",
 };
 export const setupCommand = new Command("setup")
     .description("Configure Summer Engine for an AI agent and run diagnostics")
@@ -76,6 +78,12 @@ function resolveScope(scopeOpt) {
     return parsed;
 }
 function setupRecommendedSkills(agent, options) {
+    if (agent === "lm-studio") {
+        return {
+            status: "skipped",
+            message: "LM Studio has no rules or skills folder. The MCP server ships summer_get_agent_playbook, so the model can pull Summer guidance in-chat.",
+        };
+    }
     const invocation = skillInstallInvocation(agent, { force: options.force });
     if (!invocation) {
         return {

package/dist/commands/skills.js

@@ -113,7 +113,8 @@ function resolveScope(agent, opts) {
     if (agent === "cursor" ||
         agent === "windsurf" ||
         agent === "cline" ||
-        agent === "roo-code") {
+        agent === "roo-code" ||
+        agent === "kilo-code") {
         return "project";
     }
     return "user";
@@ -127,11 +128,13 @@ function agentLabel(agent) {
         case "cursor":
             return "Cursor";
         case "windsurf":
-            return "Windsurf";
+            return "Devin Desktop (Windsurf)";
         case "cline":
             return "Cline";
         case "roo-code":
             return "Roo Code";
+        case "kilo-code":
+            return "Kilo Code";
         case "gemini":
             return "Gemini CLI";
         case "github-copilot":
@@ -152,7 +155,7 @@ function resolveInstallLocation(agent, scope) {
         if (agent === "windsurf") {
             return { kind: "windsurf-rule-file", path: join(overrideDir, ".windsurfrules") };
         }
-        if (agent === "cline" || agent === "roo-code") {
+        if (agent === "cline" || agent === "roo-code" || agent === "kilo-code") {
             return { kind: "cline-rule-dir", path: overrideDir };
         }
         if (agent === "gemini") {
@@ -187,6 +190,13 @@ function resolveInstallLocation(agent, scope) {
                     ? rooCodeUserRulesDir()
                     : join(process.cwd(), ".clinerules"),
             };
+        case "kilo-code":
+            return {
+                kind: "cline-rule-dir",
+                path: scope === "user"
+                    ? join(homedir(), ".kilocode", "rules")
+                    : join(process.cwd(), ".kilocode", "rules"),
+            };
         case "gemini":
             return {
                 kind: "gemini-skill-dir",
@@ -390,7 +400,7 @@ function printInstallSummary(count, agent, scope, location) {
         console.log("Restart OpenCode so it picks up the new agent definitions.");
     }
     else {
-        console.log(`Windsurf rules are in ${tildeified}`);
+        console.log(`Devin Desktop (formerly Windsurf) rules are in ${tildeified}`);
     }
 }
 export const skillsCommand = new Command("skills")
@@ -484,7 +494,7 @@ function installClaudeCommands(scope, force) {
 }
 /**
  * Drop a `.summer-version` marker into the install dir so doctor's
- * `skills-version-stale` check can detect drift later. Windsurf writes a
+ * `skills-version-stale` check can detect drift later. Devin Desktop (formerly Windsurf) writes a
  * single rules file with no surrounding dir, so we skip it there.
  */
 function writeMarkerForLocation(location) {

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

@@ -1,5 +1,5 @@
 export declare const SUMMER_MCP_SERVER_NAME = "summer-engine";
-export declare const supportedAgents: readonly ["codex", "claude-code", "cursor", "windsurf", "cline", "roo-code", "gemini", "github-copilot", "vscode-copilot", "opencode"];
+export declare const supportedAgents: readonly ["codex", "claude-code", "cursor", "windsurf", "cline", "roo-code", "kilo-code", "gemini", "github-copilot", "vscode-copilot", "opencode", "lm-studio"];
 export type SupportedAgent = (typeof supportedAgents)[number];
 export type ConfigScope = "user" | "project";
 export interface StdioMcpServerConfig {

package/dist/lib/agent-config.js

@@ -11,10 +11,12 @@ export const supportedAgents = [
     "windsurf",
     "cline",
     "roo-code",
+    "kilo-code",
     "gemini",
     "github-copilot",
     "vscode-copilot",
     "opencode",
+    "lm-studio",
 ];
 const agentAliases = {
     claude: "claude-code",
@@ -22,10 +24,16 @@ const agentAliases = {
     codex: "codex",
     cursor: "cursor",
     windsurf: "windsurf",
+    devin: "windsurf",
+    "devin-desktop": "windsurf",
+    devindesktop: "windsurf",
     cline: "cline",
     "roo-code": "roo-code",
     roo: "roo-code",
     roocode: "roo-code",
+    kilo: "kilo-code",
+    kilocode: "kilo-code",
+    "kilo-code": "kilo-code",
     gemini: "gemini",
     "gemini-cli": "gemini",
     copilot: "github-copilot",
@@ -39,6 +47,9 @@ const agentAliases = {
     "github-copilot-vscode": "vscode-copilot",
     opencode: "opencode",
     "open-code": "opencode",
+    lmstudio: "lm-studio",
+    "lm-studio": "lm-studio",
+    "lm_studio": "lm-studio",
 };
 export function parseAgent(value) {
     if (!value)
@@ -148,7 +159,7 @@ function resolveConfigTarget(agent, scope, cwd, env) {
     const warnings = [];
     if (override) {
         if (scope === "project" &&
-            (agent === "cline" || agent === "roo-code" || agent === "gemini")) {
+            (agent === "cline" || agent === "roo-code" || agent === "gemini" || agent === "lm-studio")) {
             warnings.push(`${agent} MCP config has no project scope today; treating as user scope.`);
         }
         return {
@@ -212,6 +223,25 @@ function resolveConfigTarget(agent, scope, cwd, env) {
             warnings,
         };
     }
+    if (agent === "kilo-code") {
+        return {
+            path: scope === "user"
+                ? vsCodeGlobalStoragePath(env, "kilocode.kilo-code", "mcp_settings.json")
+                : join(cwd, ".kilocode", "mcp.json"),
+            format: "json",
+            warnings,
+        };
+    }
+    if (agent === "lm-studio") {
+        if (scope === "project") {
+            warnings.push("LM Studio's MCP config is app-global (~/.lmstudio/mcp.json); treating as user scope.");
+        }
+        return {
+            path: join(homedir(), ".lmstudio", "mcp.json"),
+            format: "json",
+            warnings,
+        };
+    }
     if (agent === "gemini") {
         if (scope === "project") {
             warnings.push("Gemini extensions are user-scoped today; writing to ~/.gemini/extensions/summer-engine/ instead of project.");
@@ -250,7 +280,7 @@ function resolveConfigTarget(agent, scope, cwd, env) {
         };
     }
     if (scope === "project") {
-        warnings.push("Windsurf documents MCP configuration as user-scoped; project scope writes .windsurf/mcp_config.json for teams that load workspace config.");
+        warnings.push("Devin Desktop (formerly Windsurf) documents MCP configuration as user-scoped; project scope writes .windsurf/mcp_config.json for teams that load workspace config.");
     }
     return {
         path: scope === "user"
@@ -260,18 +290,18 @@ function resolveConfigTarget(agent, scope, cwd, env) {
         warnings,
     };
 }
-function vsCodeGlobalStoragePath(env, extensionId) {
+function vsCodeGlobalStoragePath(env, extensionId, fileName = "cline_mcp_settings.json") {
     const os = platform();
     if (os === "win32") {
         const appData = env.APPDATA ?? join(homedir(), "AppData", "Roaming");
-        return join(appData, "Code", "User", "globalStorage", extensionId, "settings", "cline_mcp_settings.json");
+        return join(appData, "Code", "User", "globalStorage", extensionId, "settings", fileName);
     }
     if (os === "darwin") {
-        return join(homedir(), "Library", "Application Support", "Code", "User", "globalStorage", extensionId, "settings", "cline_mcp_settings.json");
+        return join(homedir(), "Library", "Application Support", "Code", "User", "globalStorage", extensionId, "settings", fileName);
     }
     // Linux and other Unix
     const xdg = env.XDG_CONFIG_HOME ?? join(homedir(), ".config");
-    return join(xdg, "Code", "User", "globalStorage", extensionId, "settings", "cline_mcp_settings.json");
+    return join(xdg, "Code", "User", "globalStorage", extensionId, "settings", fileName);
 }
 function opencodeUserConfigPath(env) {
     const os = platform();
@@ -305,6 +335,10 @@ function getConfigPathOverride(agent, env) {
         return env.SUMMER_CLINE_CONFIG_FILE;
     if (agent === "roo-code")
         return env.SUMMER_ROO_CODE_CONFIG_FILE;
+    if (agent === "kilo-code")
+        return env.SUMMER_KILO_CODE_CONFIG_FILE;
+    if (agent === "lm-studio")
+        return env.SUMMER_LM_STUDIO_CONFIG_FILE;
     if (agent === "gemini")
         return env.SUMMER_GEMINI_CONFIG_FILE;
     if (agent === "github-copilot")
@@ -558,15 +592,19 @@ function createNextSteps(agent, scope, path) {
                     ? "Restart VS Code so Cline reloads its MCP config."
                     : agent === "roo-code"
                         ? "Restart VS Code so Roo Code reloads its MCP config."
-                        : agent === "gemini"
-                            ? "Run `gemini extensions enable summer-engine` (if not already enabled), then restart Gemini CLI."
-                            : agent === "github-copilot"
-                                ? "Restart Copilot CLI, or run /mcp reload and /skills reload in the active session."
-                                : agent === "vscode-copilot"
-                                    ? "Restart VS Code or run MCP: List Servers, then start summer-engine in Copilot Agent mode."
-                                    : agent === "opencode"
-                                        ? "Restart OpenCode so it reloads opencode.json."
-                                        : "Restart Windsurf and refresh MCP servers from Cascade settings.";
+                        : agent === "kilo-code"
+                            ? "Restart VS Code so Kilo Code reloads its MCP config."
+                            : agent === "lm-studio"
+                                ? "Open LM Studio, toggle on the summer-engine MCP server in the Program tab, and raise the loaded model's context length to 32k or higher."
+                                : agent === "gemini"
+                                    ? "Run `gemini extensions enable summer-engine` (if not already enabled), then restart Gemini CLI."
+                                    : agent === "github-copilot"
+                                        ? "Restart Copilot CLI, or run /mcp reload and /skills reload in the active session."
+                                        : agent === "vscode-copilot"
+                                            ? "Restart VS Code or run MCP: List Servers, then start summer-engine in Copilot Agent mode."
+                                            : agent === "opencode"
+                                                ? "Restart OpenCode so it reloads opencode.json."
+                                                : "Restart Devin Desktop (formerly Windsurf) and refresh MCP servers from the agent settings.";
     const projectTrust = scope === "project" && agent === "codex"
         ? "Codex only loads project .codex/config.toml from trusted projects."
         : null;

package/dist/lib/api-client.d.ts

@@ -2,6 +2,10 @@ export type EngineSnapshot = {
     ok: boolean;
     localPath?: string;
     path?: string;
+    /** Raw image bytes, base64-encoded. Carried so a caller (e.g. the MCP
+     *  screenshot tool) can return an MCP image content block to a vision-capable
+     *  client without re-reading localPath off disk. */
+    base64?: string;
     width?: number;
     height?: number;
     format?: string;
@@ -50,4 +54,17 @@ export declare class EngineApiClient {
     viewportSnapshot(): Promise<EngineSnapshot>;
     gameSnapshot(): Promise<EngineSnapshot>;
     getPort(): number;
+    /**
+     * Cheap drift probe for the MCP client cache. The engine mints a fresh
+     * api-token on every launch (local_api_server.cpp::_generate_api_token) and can
+     * bind a different port (tool_net_thread.cpp::start increments 6550..6565 when
+     * the old socket lingers), so a client built before an engine restart holds
+     * dead credentials. Re-read the on-disk creds and report whether they no longer
+     * match this client's snapshot.
+     *
+     * Empty / unreadable creds (engine mid-write, or just closed) are treated as
+     * "no drift" so a transient read never thrashes the cache — the live request
+     * will fail and trigger a reconnect+retry if the client really is stale.
+     */
+    credentialsChanged(): Promise<boolean>;
 }

package/dist/lib/api-client.js

@@ -172,7 +172,10 @@ export class EngineApiClient {
     }
     async play(scene) {
         // Cold-load on large projects can take 25-40s. 60s budget.
-        return this._requestQueued("POST", "/api/play", scene ? { scene } : {}, 60_000);
+        // The engine reads play params from body.options (tool_net_thread.cpp:503),
+        // and the play handler reads options["scene"] — a top-level { scene } is
+        // dropped, so the scene MUST be nested inside options.
+        return this._requestQueued("POST", "/api/play", scene ? { options: { scene } } : {}, 60_000);
     }
     async stop() {
         return this._requestQueued("POST", "/api/stop", undefined, 15_000);
@@ -237,6 +240,7 @@ export class EngineApiClient {
             ok: payload.ok !== false,
             localPath,
             path: localPath,
+            base64,
             width: numberFrom(payload.width),
             height: numberFrom(payload.height),
             format,
@@ -257,4 +261,27 @@ export class EngineApiClient {
     getPort() {
         return this.port;
     }
+    /**
+     * Cheap drift probe for the MCP client cache. The engine mints a fresh
+     * api-token on every launch (local_api_server.cpp::_generate_api_token) and can
+     * bind a different port (tool_net_thread.cpp::start increments 6550..6565 when
+     * the old socket lingers), so a client built before an engine restart holds
+     * dead credentials. Re-read the on-disk creds and report whether they no longer
+     * match this client's snapshot.
+     *
+     * Empty / unreadable creds (engine mid-write, or just closed) are treated as
+     * "no drift" so a transient read never thrashes the cache — the live request
+     * will fail and trigger a reconnect+retry if the client really is stale.
+     */
+    async credentialsChanged() {
+        try {
+            const [port, token] = await Promise.all([getApiPort(), getApiToken()]);
+            if (!token)
+                return false;
+            return port !== this.port || token !== this.token;
+        }
+        catch {
+            return false;
+        }
+    }
 }