summer-engine 2.6.1 → 2.6.5

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

@@ -1,5 +1,14 @@
 import { getClient, resetClient } from "../server.js";
 import { recordMcpSession } from "../../lib/telemetry.js";
+export const WITH_ENGINE_META = Symbol("summerWithEngineMeta");
+function attachMeta(result, meta) {
+    Object.defineProperty(result, WITH_ENGINE_META, {
+        value: meta,
+        enumerable: false,
+        configurable: true,
+    });
+    return result;
+}
 // 0.5.34 Block E contract (publicsummerengine src/lib/tools/contract.ts §0.1).
 // The async lifecycle (async-op-lifecycle.ts pollOpToTerminal) merges
 // terminalState/errorClass onto the apply dict it returns. ONLY these two are
@@ -17,6 +26,23 @@ const TERMINAL_STATE_MESSAGES = {
     denied: "Operation denied (terminalState: denied). Nothing was applied.",
     canceled: "Operation canceled (terminalState: canceled). Nothing was applied.",
 };
+/** Pull the failure classifiers off an engine envelope for logging (best-effort,
+ *  shape-tolerant). Does not decide success/failure — that stays in
+ *  extractOpError. */
+function readClassifiers(result) {
+    if (!result || typeof result !== "object")
+        return {};
+    const op = result;
+    return {
+        terminalState: typeof op.terminalState === "string" ? op.terminalState : undefined,
+        errorClass: typeof op.errorClass === "string" ? op.errorClass : undefined,
+        failureReason: typeof op.failureReason === "string"
+            ? op.failureReason
+            : typeof op.failure_reason === "string"
+                ? op.failure_reason
+                : undefined,
+    };
+}
 /**
  * Decide whether an engine result envelope represents a FAILURE, and if so
  * return a model-visible message. Returns null only for genuine success.
@@ -56,8 +82,35 @@ export function extractOpError(result) {
     }
     return null;
 }
+/**
+ * An auth failure is the ONE class of thrown error that is provably pre-apply:
+ * the engine rejects on the Bearer-token check (tool_net_thread.cpp::_validate_auth)
+ * BEFORE the op is queued or applied, so reconnecting with the fresh api-token and
+ * retrying cannot double-apply a mutation. This is exactly the stale-token case
+ * after the engine rotates its api-token on relaunch.
+ *
+ * Deliberately NARROW. A generic connection error (ECONNREFUSED / "fetch failed")
+ * thrown from inside the tool closure is NOT retriable here, because it may be a
+ * disconnect mid-operation where a mutation already partially applied — and the
+ * MCP sends no idempotency key the engine can dedup on, so a blind retry would
+ * re-apply it. The restart-between-calls case is handled proactively by
+ * getClient()'s credential-drift check; the connect/preflight-failure case is
+ * retried separately in withEngine (nothing is submitted there).
+ *
+ * Exported for unit tests.
+ */
+export function isAuthError(err) {
+    const m = (err instanceof Error ? err.message : String(err)).toLowerCase();
+    return m.includes("401") || m.includes("403") || m.includes("unauthorized");
+}
 function buildActionHint(message) {
     const normalized = message.toLowerCase();
+    if (normalized.includes("identity_mismatch") ||
+        normalized.includes("projectidhash mismatch") ||
+        normalized.includes("projectid mismatch") ||
+        normalized.includes("wrong project/instance")) {
+        return "Summer Engine is now on a DIFFERENT project than this session is bound to — nothing was applied (your edit did NOT land in the wrong project). If you meant to work on the now-open project, call `summer_get_project_context` to rebind to it, then retry. If not, switch the engine back to the original project first.";
+    }
     if (normalized.includes("no scene open") || normalized.includes("no edited scene")) {
         return "No scene is currently open. Call `summer_get_project_context` first, then `summer_open_main_scene` (or `summer_open_scene` with a known .tscn path).";
     }
@@ -69,24 +122,73 @@ 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. The
+    // proactive credential-drift check in getClient() reconnects when a restart
+    // happened BETWEEN calls; this loop only covers the race where the restart
+    // lands DURING a call. We retry ONLY where nothing could have been applied:
+    //   - a connect/preflight failure (getClient threw — request never submitted)
+    //   - a stale-token 401/403 (engine rejects at auth, before queue/apply)
+    // A generic connection error thrown from inside fn() is NOT retried: it may be
+    // a disconnect mid-operation where a mutation already partially applied, and
+    // the MCP sends no idempotency key the engine can dedup on. A soft failure
+    // terminal state (e.g. identity_mismatch from a project switch) is surfaced,
+    // never silently retried — a retry cannot fix a project switch.
+    const MAX_ATTEMPTS = 2;
+    let lastError;
+    let retried = false;
+    let boundProjectIdHash;
+    for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) {
+        if (attempt > 1)
+            retried = true;
+        let client;
+        try {
+            client = await getClient();
+        }
+        catch (err) {
+            // Pre-submission: the request never went out, so reconnect and retry.
+            resetClient();
+            lastError = err;
+            if (attempt < MAX_ATTEMPTS)
+                continue;
+            break;
+        }
+        boundProjectIdHash =
+            typeof client.getBoundProjectIdHash === "function"
+                ? client.getBoundProjectIdHash()
+                : undefined;
+        try {
+            const result = await fn(client);
+            const opError = extractOpError(result);
+            if (opError) {
+                const hint = buildActionHint(opError);
+                const message = hint ? `${opError}\n\nHint: ${hint}` : opError;
+                return attachMeta({ content: [{ type: "text", text: message }], isError: true }, { ...readClassifiers(result), retried, boundProjectIdHash });
+            }
+            const meta = { ...readClassifiers(result), retried, boundProjectIdHash };
+            if (opts?.onResult) {
+                const short = opts.onResult(result);
+                if (short)
+                    return attachMeta(short, meta);
+            }
+            if (opts?.toContent) {
+                return attachMeta({ content: opts.toContent(result) }, meta);
+            }
+            return attachMeta({ content: [{ type: "text", text: JSON.stringify(result, null, 2) }] }, meta);
+        }
+        catch (err) {
+            // Drop the cached client (it may point at a dead/rotated engine). Retry
+            // once only for a provably pre-apply auth failure; anything else surfaces.
+            resetClient();
+            lastError = err;
+            if (attempt < MAX_ATTEMPTS && isAuthError(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 attachMeta({ content: [{ type: "text", text: msg }], isError: true }, { errorClass: "transport", retried, boundProjectIdHash });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "summer-engine",
-  "version": "2.6.1",
+  "version": "2.6.5",
   "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",