summer-engine 2.6.3 → 2.6.6

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,45 +82,35 @@ 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.
+ * 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 isReconnectableThrow(err) {
+export function isAuthError(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"));
+    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).";
     }
@@ -110,48 +126,69 @@ 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();
-    // 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.
+    // 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 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 };
+                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 { content: opts.toContent(result) };
+                return attachMeta({ content: opts.toContent(result) }, meta);
             }
-            return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
+            return attachMeta({ content: [{ type: "text", text: JSON.stringify(result, null, 2) }] }, meta);
         }
         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.
+            // 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 && isReconnectableThrow(err)) {
+            if (attempt < MAX_ATTEMPTS && isAuthError(err))
                 continue;
-            }
             break;
         }
     }
     const msg = lastError instanceof Error ? lastError.message : String(lastError);
-    return { content: [{ type: "text", text: msg }], isError: true };
+    return attachMeta({ content: [{ type: "text", text: msg }], isError: true }, { errorClass: "transport", retried, boundProjectIdHash });
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "summer-engine",
-  "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.",
+  "version": "2.6.6",
+  "description": "Local Summer CLI and MCP server for Summer Engine. Install and run the engine, connect Claude Code, Cursor, Codex, Gemini, and other agents, and build real games with bundled skills, hooks, and plugins.",
   "keywords": [
     "summer-engine",
     "summer-cli",
@@ -27,6 +27,10 @@
     "type": "git",
     "url": "git+https://github.com/SummerEngine/summer-engine-agent.git"
   },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  },
   "license": "MIT",
   "author": "Summer Engine <founders@summerengine.com>",
   "type": "module",