summer-engine 2.6.0 → 2.6.3

package/dist/lib/skills-registry.js

@@ -6,6 +6,7 @@ export const AGENT_CLIENTS = [
     "windsurf",
     "cline",
     "roo-code",
+    "kilo-code",
     "gemini",
     "github-copilot",
     "vscode-copilot",

package/dist/mcp/server.js

@@ -4,6 +4,7 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { EngineApiClient } from "../lib/api-client.js";
 import { registerSceneTools } from "./tools/scene-tools.js";
 import { registerDebugTools } from "./tools/debug-tools.js";
+import { registerVisualTools } from "./tools/visual-tools.js";
 import { registerProjectTools } from "./tools/project-tools.js";
 import { registerAssetTools } from "./tools/asset-tools.js";
 import { registerGenerateTools } from "./tools/generate-tools.js";
@@ -30,7 +31,17 @@ async function probeBootDrift() {
 let cachedClient = null;
 export async function getClient() {
     if (cachedClient) {
-        return cachedClient;
+        // The engine rotates its api-token (and can change ports) on every launch, so
+        // a cached client can outlive the engine instance it was built for. If the
+        // on-disk creds drifted, a silent engine restart happened — drop the stale
+        // client and reconnect transparently, instead of surfacing the resulting 401
+        // as a "disconnected from the project" error.
+        if (await cachedClient.credentialsChanged()) {
+            cachedClient = null;
+        }
+        else {
+            return cachedClient;
+        }
     }
     try {
         cachedClient = await EngineApiClient.connect();
@@ -113,6 +124,7 @@ export async function startMcpServer() {
     installResultSizeLogger(server);
     registerSceneTools(server);
     registerDebugTools(server);
+    registerVisualTools(server);
     registerProjectTools(server);
     registerAssetTools(server);
     registerGenerateTools(server);

package/dist/mcp/tools/visual-tools.d.ts

@@ -0,0 +1,9 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+/**
+ * Visual capture tools. Unlike the in-product chat agent (a text-only "brain"
+ * that needs a separate vision model to describe frames for it), an MCP client
+ * like Claude Code can SEE images directly. So we hand the raw engine frame back
+ * as an MCP image content block — no vision-model prepass, no paraphrase. The
+ * model reviews the actual pixels.
+ */
+export declare function registerVisualTools(server: McpServer): void;

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

@@ -0,0 +1,51 @@
+import { z } from "zod";
+import { withEngine } from "./with-engine.js";
+/**
+ * Visual capture tools. Unlike the in-product chat agent (a text-only "brain"
+ * that needs a separate vision model to describe frames for it), an MCP client
+ * like Claude Code can SEE images directly. So we hand the raw engine frame back
+ * as an MCP image content block — no vision-model prepass, no paraphrase. The
+ * model reviews the actual pixels.
+ */
+export function registerVisualTools(server) {
+    server.tool("summer_screenshot", `Capture a frame from Summer Engine and return it as an image you can look at directly.
+
+Use this to visually verify your work: scene layout, asset placement, scale, framing, lighting, materials, missing/untextured assets, or runtime gameplay state. You see the actual pixels — no description layer in between.
+
+target:
+  "viewport" (default) — the editor's current 3D/2D scene view. Works without running the game. Use for edit-time checks of how the scene looks.
+  "game" — a frame from the running game. The game must be started first (summer_play). Use to verify runtime behavior.
+
+Static frame only — one moment, not motion. On macOS the game often runs in a floating window that cannot be captured; if a game capture fails, prefer "viewport", or ask the user to share a screenshot.`, {
+        target: z
+            .enum(["viewport", "game"])
+            .optional()
+            .default("viewport")
+            .describe('"viewport" = editor scene view (default), "game" = running game frame'),
+    }, async ({ target }) => withEngine(async (client) => target === "game" ? client.gameSnapshot() : client.viewportSnapshot(), {
+        toContent: (snap) => {
+            // withEngine only calls toContent on success (ok:true, error cleared
+            // by extractOpError). Missing image bytes on a "success" is still
+            // possible defensively, so fall back to text rather than emit a
+            // broken image block.
+            if (!snap.base64) {
+                return [
+                    {
+                        type: "text",
+                        text: snap.error ||
+                            "Snapshot succeeded but returned no image data. Try again, or use summer_get_scene_tree to inspect structurally.",
+                    },
+                ];
+            }
+            const dims = snap.width && snap.height ? `${snap.width}x${snap.height}` : "unknown size";
+            const label = target === "game" ? "Running game frame" : "Editor viewport";
+            return [
+                { type: "image", data: snap.base64, mimeType: snap.mime || "image/jpeg" },
+                {
+                    type: "text",
+                    text: `${label} (${dims}). Saved to ${snap.localPath ?? "n/a"}. Review the image above and describe what you actually see.`,
+                },
+            ];
+        },
+    }));
+}

package/dist/mcp/tools/with-engine.d.ts

@@ -1,11 +1,23 @@
 import { getClient } from "../server.js";
+type ToolResultContent = {
+    type: "text";
+    text: string;
+} | {
+    type: "image";
+    data: string;
+    mimeType: string;
+};
 type ToolResult = {
-    content: {
-        type: "text";
-        text: string;
-    }[];
+    content: ToolResultContent[];
     isError?: boolean;
 };
+/** Options for {@link withEngine}. `toContent` maps a successful engine result
+ *  to MCP content blocks — used by the screenshot tool to hand the raw frame
+ *  back as an image block instead of JSON-stringified text. Only runs on genuine
+ *  success (after extractOpError clears); failures still surface as text. */
+export interface WithEngineOptions<T> {
+    toContent?: (result: T) => ToolResultContent[];
+}
 /**
  * Decide whether an engine result envelope represents a FAILURE, and if so
  * return a model-visible message. Returns null only for genuine success.
@@ -20,5 +32,15 @@ type ToolResult = {
  * Exported for unit tests.
  */
 export declare function extractOpError(result: unknown): string | null;
-export declare function withEngine<T>(fn: (client: Awaited<ReturnType<typeof getClient>>) => Promise<T>): Promise<ToolResult>;
+/**
+ * A thrown transport error is safe to retry only when the engine provably never
+ * applied the op: a stale-token rejection (401/403, after the engine rotated its
+ * api-token on relaunch) or an unreachable/closed port (connection refused/reset,
+ * after the engine moved ports or is mid-restart). A timeout or any 5xx may have
+ * mutated, so those surface instead of risking a double-apply on retry.
+ *
+ * Exported for unit tests.
+ */
+export declare function isReconnectableThrow(err: unknown): boolean;
+export declare function withEngine<T>(fn: (client: Awaited<ReturnType<typeof getClient>>) => Promise<T>, opts?: WithEngineOptions<T>): Promise<ToolResult>;
 export {};

package/dist/mcp/tools/with-engine.js

@@ -56,6 +56,43 @@ export function extractOpError(result) {
     }
     return null;
 }
+// Terminal states where the engine GUARANTEES the op never landed, so dropping
+// the cached client and retrying once is safe (no double-mutation). Everything
+// else — timed_out (may still be running), content_mismatch / denied / canceled
+// (intentional) — must surface, never silently retry.
+const RECONNECTABLE_TERMINAL_STATES = new Set([
+    "not_connected",
+    "identity_mismatch",
+]);
+function terminalStateOf(result) {
+    if (!result || typeof result !== "object")
+        return null;
+    const ts = result.terminalState;
+    return typeof ts === "string" && ts.length > 0 ? ts : null;
+}
+/**
+ * A thrown transport error is safe to retry only when the engine provably never
+ * applied the op: a stale-token rejection (401/403, after the engine rotated its
+ * api-token on relaunch) or an unreachable/closed port (connection refused/reset,
+ * after the engine moved ports or is mid-restart). A timeout or any 5xx may have
+ * mutated, so those surface instead of risking a double-apply on retry.
+ *
+ * Exported for unit tests.
+ */
+export function isReconnectableThrow(err) {
+    const m = (err instanceof Error ? err.message : String(err)).toLowerCase();
+    if (m.includes("timed out") || m.includes("timeout") || m.includes("aborted")) {
+        return false;
+    }
+    return (m.includes("401") ||
+        m.includes("403") ||
+        m.includes("unauthorized") ||
+        m.includes("econnrefused") ||
+        m.includes("econnreset") ||
+        m.includes("fetch failed") ||
+        m.includes("not running") ||
+        m.includes("not responding"));
+}
 function buildActionHint(message) {
     const normalized = message.toLowerCase();
     if (normalized.includes("no scene open") || normalized.includes("no edited scene")) {
@@ -69,24 +106,52 @@ function buildActionHint(message) {
     }
     return null;
 }
-export async function withEngine(fn) {
+export async function withEngine(fn, opts) {
     // Best-effort, fire-and-forget: count this MCP session as DAU for attribution.
     // No await, no throw, no quota gating.
     recordMcpSession();
-    try {
-        const client = await getClient();
-        const result = await fn(client);
-        const opError = extractOpError(result);
-        if (opError) {
-            const hint = buildActionHint(opError);
-            const message = hint ? `${opError}\n\nHint: ${hint}` : opError;
-            return { content: [{ type: "text", text: message }], isError: true };
+    // The engine rotates its api-token and can move ports on every launch, so a
+    // restart that lands DURING a tool call shows up as a stale-token 401, an
+    // ECONNREFUSED on the old port, or a soft not_connected / identity_mismatch
+    // terminal state. Drop the cached client and retry ONCE so a transient drop
+    // heals itself (getClient reconnects with the fresh creds) instead of
+    // surfacing as a "disconnected" error. Only provably-not-applied failures are
+    // retried — see RECONNECTABLE_TERMINAL_STATES / isReconnectableThrow.
+    const MAX_ATTEMPTS = 2;
+    let lastError;
+    for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) {
+        try {
+            const client = await getClient();
+            const result = await fn(client);
+            const opError = extractOpError(result);
+            if (opError) {
+                const ts = terminalStateOf(result);
+                if (ts && RECONNECTABLE_TERMINAL_STATES.has(ts) && attempt < MAX_ATTEMPTS) {
+                    resetClient();
+                    lastError = new Error(opError);
+                    continue;
+                }
+                const hint = buildActionHint(opError);
+                const message = hint ? `${opError}\n\nHint: ${hint}` : opError;
+                return { content: [{ type: "text", text: message }], isError: true };
+            }
+            if (opts?.toContent) {
+                return { content: opts.toContent(result) };
+            }
+            return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+        }
+        catch (err) {
+            // A thrown error means the cached client may be pointed at a dead/rotated
+            // engine — always drop it (prior behavior). Retry once only for
+            // connection-class throws that provably did not mutate.
+            resetClient();
+            lastError = err;
+            if (attempt < MAX_ATTEMPTS && isReconnectableThrow(err)) {
+                continue;
+            }
+            break;
         }
-        return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
-    }
-    catch (err) {
-        resetClient();
-        const msg = err instanceof Error ? err.message : String(err);
-        return { content: [{ type: "text", text: msg }], isError: true };
     }
+    const msg = lastError instanceof Error ? lastError.message : String(lastError);
+    return { content: [{ type: "text", text: msg }], isError: true };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "summer-engine",
-  "version": "2.6.0",
+  "version": "2.6.3",
   "description": "Summer CLI and MCP server for Summer Engine, the AI game engine. Install the engine, connect Claude Code, Cursor, Codex, Gemini, and other agents, and build real games. Skills, hooks, and plugins included.",
   "keywords": [
     "summer-engine",