summer-engine 2.6.5 → 2.6.6

package/CHANGELOG.md

@@ -2,6 +2,17 @@
 
 All notable changes to summer-engine will be documented here. Following [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and [Semantic Versioning](https://semver.org/).
 
+## [2.6.6] — 2026-07-15 — "Project-bound engine requests"
+
+### Fixed
+- Every local engine request now carries the engine instance ID, stable project ID, project ID hash, and identity protocol version captured when the CLI connects. This lets compatible engine builds reject stale requests after a project or engine switch instead of acting on the wrong target.
+- An explicit project rebind now refreshes the complete engine and project identity, while keeping the existing project-hash mutation guard and screenshot drift checks.
+- Summer Cloud's engine bridge now binds its save, rescan, and scene reload requests to the project it verified on disk.
+
+### Changed
+- Summer Cloud is documented as an optional Research Preview instead of part of the core local CLI and MCP workflow.
+- Release metadata and the manual npm runbook now pin the public registry and require a clean, reviewed public source checkout.
+
 ## [2.6.5] — 2026-07-04 — "Cloud tools don't need the engine"
 
 ### Fixed

package/README.md

@@ -23,22 +23,6 @@ Three names, one npm package (`summer-engine`):
 
 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, Devin Desktop, etc.) and paste:
@@ -556,6 +540,24 @@ Skills evolve fast. Two ways to help:
 
 ---
 
+## Research Preview: Summer Cloud
+
+Summer Cloud is an experimental R&D preview. It is optional, it may change or break, and it is **not** the core Summer CLI or MCP workflow. You do not need it to install or run Summer Engine, work with local projects, or use the local MCP server. The stable workflow is the local engine, CLI, MCP bridge, and agent skills described above.
+
+The preview explores content-addressed project sync across machines, including large assets that do not fit comfortably in git:
+
+```bash
+summer cloud init
+summer cloud status
+summer cloud push
+summer cloud pull
+summer cloud restore
+```
+
+Matching `summer_cloud_*` MCP tools are also experimental. Keep an independent backup and do not use this preview as the only recovery path for an important project. See [www.summerengine.com/cloud](https://www.summerengine.com/cloud).
+
+---
+
 ## License
 
 MIT for everything in this repo. Summer Engine itself is proprietary. See [What's open and what's not](#whats-open-and-whats-not).

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

@@ -33,11 +33,16 @@ export type EngineSnapshot = {
      *  (item 4, client-side drift check). */
     projectMismatch?: boolean;
 };
+type EngineTargetIdentity = {
+    instanceId?: string;
+    projectId?: string;
+    projectIdHash?: string;
+};
 export declare class EngineApiClient {
     private port;
     private token;
-    private boundProjectIdHash?;
-    constructor(port: number, token: string, boundProjectIdHash?: string);
+    private targetIdentity;
+    constructor(port: number, token: string, targetIdentity?: EngineTargetIdentity | string);
     static connect(): Promise<EngineApiClient>;
     /** The projectIdHash this session is bound to (undefined if none was reported
      *  at connect — e.g. no project open yet). */
@@ -46,13 +51,14 @@ export declare class EngineApiClient {
      * Re-read health and rebind to the currently-open project. Called by
      * summer_get_project_context so the agent can INTENTIONALLY follow a project
      * switch (the deliberate escape hatch after an identity_mismatch). Returns the
-     * new bound hash. Reads carry no identity, so this always reaches the engine
-     * even when a mutation would be rejected.
+     * new bound hash. The direct health probe is intentionally unscoped, so it can
+     * reach the current engine even when bound requests would be rejected.
      */
     rebind(): Promise<string | undefined>;
     /** Identity to attach to a MUTATING command's options so the engine can reject
      *  a wrong-project write. Empty when unbound (engine then skips the check). */
     private identityOptions;
+    private targetUrl;
     private request;
     /** Raw fetch with auth + timeout — returns the Response so callers can inspect
      *  the status (202 queued vs 200 legacy). */
@@ -125,3 +131,4 @@ export declare class EngineApiClient {
      */
     credentialsChanged(): Promise<boolean>;
 }
+export {};

package/dist/lib/api-client.js

@@ -67,17 +67,19 @@ function withoutImageData(payload) {
 export class EngineApiClient {
     port;
     token;
-    // The project this session is BOUND to — the projectIdHash reported by the
-    // engine when this client first connected. Sent on every mutating op so the
-    // engine's identity guard (local_api_server.cpp ~271-302) atomically rejects a
-    // write aimed at a DIFFERENT project (e.g. after the user switched projects
-    // in-place). Health is the only identity signal the MCP has — /api/state/project
-    // carries no path and /api/health exposes only projectIdHash, not the raw id.
-    boundProjectIdHash;
-    constructor(port, token, boundProjectIdHash) {
+    // The engine and project this session is bound to. Every request carries the
+    // identity captured from health so the engine can reject requests after an
+    // in-place project switch or an unexpected instance change. The string form
+    // preserves the pre-2.6.6 constructor contract for existing callers that only
+    // supplied a projectIdHash.
+    targetIdentity;
+    constructor(port, token, targetIdentity = {}) {
         this.port = port;
         this.token = token;
-        this.boundProjectIdHash = boundProjectIdHash;
+        this.targetIdentity =
+            typeof targetIdentity === "string"
+                ? { projectIdHash: targetIdentity }
+                : { ...targetIdentity };
     }
     static async connect() {
         const port = await getApiPort();
@@ -94,34 +96,57 @@ export class EngineApiClient {
         // rebinds to the current project. An in-place project switch keeps the same
         // token, so the cached client retains its original binding and the engine
         // rejects mismatched mutations until the agent explicitly rebinds.
-        return new EngineApiClient(port, token, health.projectIdHash);
+        return new EngineApiClient(port, token, {
+            instanceId: health.instanceId,
+            projectId: health.projectId,
+            projectIdHash: health.projectIdHash,
+        });
     }
     /** The projectIdHash this session is bound to (undefined if none was reported
      *  at connect — e.g. no project open yet). */
     getBoundProjectIdHash() {
-        return this.boundProjectIdHash;
+        return this.targetIdentity.projectIdHash;
     }
     /**
      * Re-read health and rebind to the currently-open project. Called by
      * summer_get_project_context so the agent can INTENTIONALLY follow a project
      * switch (the deliberate escape hatch after an identity_mismatch). Returns the
-     * new bound hash. Reads carry no identity, so this always reaches the engine
-     * even when a mutation would be rejected.
+     * new bound hash. The direct health probe is intentionally unscoped, so it can
+     * reach the current engine even when bound requests would be rejected.
      */
     async rebind() {
         const health = await checkEngineHealth(this.port);
         if (health) {
-            this.boundProjectIdHash = health.projectIdHash;
+            this.targetIdentity = {
+                instanceId: health.instanceId,
+                projectId: health.projectId,
+                projectIdHash: health.projectIdHash,
+            };
         }
-        return this.boundProjectIdHash;
+        return this.targetIdentity.projectIdHash;
     }
     /** Identity to attach to a MUTATING command's options so the engine can reject
      *  a wrong-project write. Empty when unbound (engine then skips the check). */
     identityOptions() {
-        return this.boundProjectIdHash ? { projectIdHash: this.boundProjectIdHash } : {};
+        const projectIdHash = this.targetIdentity.projectIdHash;
+        return projectIdHash ? { projectIdHash } : {};
+    }
+    targetUrl(path) {
+        const url = new URL(path, `http://127.0.0.1:${this.port}`);
+        const { instanceId, projectId, projectIdHash } = this.targetIdentity;
+        if (instanceId)
+            url.searchParams.set("instanceId", instanceId);
+        if (projectId)
+            url.searchParams.set("projectId", projectId);
+        if (projectIdHash)
+            url.searchParams.set("projectIdHash", projectIdHash);
+        if (instanceId && projectId && projectIdHash) {
+            url.searchParams.set("projectIdentityVersion", "1");
+        }
+        return url.toString();
     }
     async request(method, path, body) {
-        const url = `http://127.0.0.1:${this.port}${path}`;
+        const url = this.targetUrl(path);
         const headers = {
             Authorization: `Bearer ${this.token}`,
             "Content-Type": "application/json",
@@ -141,7 +166,7 @@ export class EngineApiClient {
     /** Raw fetch with auth + timeout — returns the Response so callers can inspect
      *  the status (202 queued vs 200 legacy). */
     async _fetchRaw(method, path, body, timeoutMs) {
-        return fetch(`http://127.0.0.1:${this.port}${path}`, {
+        return fetch(this.targetUrl(path), {
             method,
             headers: {
                 Authorization: `Bearer ${this.token}`,
@@ -305,18 +330,17 @@ export class EngineApiClient {
         const { format, mime, ext } = snapshotFormat(payload);
         const buffer = Buffer.from(base64, "base64");
         const localPath = await this.writeSnapshotFile(kind, buffer, ext);
-        // Client-side identity drift check (item 4). The engine's identity guard only
-        // acts on options.projectIdHash inside a queued command; a GET snapshot from
-        // `fetch` carries no reliable body, so we cannot count on the engine to reject
-        // a drifted read. Re-read health and compare to the bound hash — if the engine
-        // has switched projects since we bound, this frame may be from the WRONG
-        // project. Best-effort: a failed health read never blocks the (already
-        // captured) image.
+        // Client-side identity drift check (item 4). Current engines validate the
+        // identity query on snapshot reads, but older builds may ignore it. Re-read
+        // health and compare to the bound hash so a frame from a switched project is
+        // still marked as suspect. Best-effort: a failed health read never blocks the
+        // already captured image.
         let projectMismatch;
-        if (this.boundProjectIdHash) {
+        const boundProjectIdHash = this.targetIdentity.projectIdHash;
+        if (boundProjectIdHash) {
             try {
                 const health = await checkEngineHealth(this.port);
-                if (health?.projectIdHash && health.projectIdHash !== this.boundProjectIdHash) {
+                if (health?.projectIdHash && health.projectIdHash !== boundProjectIdHash) {
                     projectMismatch = true;
                 }
             }

package/dist/lib/cloud/engine-bridge.js

@@ -50,7 +50,15 @@ async function connectForProject(projectRoot) {
         // rescan; the executor rejects mismatches too, but skip the round trip.
         if (health.projectIdHash && health.projectIdHash !== projectIdHash)
             return null;
-        return { client: new EngineApiClient(port, token), projectIdHash, scene: health.scene };
+        return {
+            client: new EngineApiClient(port, token, {
+                instanceId: health.instanceId,
+                projectId: health.projectId,
+                projectIdHash,
+            }),
+            projectIdHash,
+            scene: health.scene,
+        };
     }
     catch {
         return null;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "summer-engine",
-  "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.",
+  "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",