summer-engine 2.6.1 → 2.6.5

package/dist/lib/api-client.js

@@ -14,6 +14,9 @@ function stringFrom(value) {
 function numberFrom(value) {
     return typeof value === "number" ? value : undefined;
 }
+function boolFrom(value) {
+    return typeof value === "boolean" ? value : undefined;
+}
 function findSnapshotPayload(value) {
     const record = asRecord(value);
     if (!record)
@@ -21,7 +24,8 @@ function findSnapshotPayload(value) {
     if (typeof record.base64 === "string" ||
         typeof record.image_base64 === "string" ||
         record.op === "ViewportSnapshot" ||
-        record.op === "GameSnapshot") {
+        record.op === "GameSnapshot" ||
+        record.op === "ScenePreview") {
         return record;
     }
     if (Array.isArray(record.results)) {
@@ -63,9 +67,17 @@ function withoutImageData(payload) {
 export class EngineApiClient {
     port;
     token;
-    constructor(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) {
         this.port = port;
         this.token = token;
+        this.boundProjectIdHash = boundProjectIdHash;
     }
     static async connect() {
         const port = await getApiPort();
@@ -77,7 +89,36 @@ export class EngineApiClient {
         if (!health) {
             throw new Error(`Summer Engine is not responding on port ${port}. Make sure it's open.`);
         }
-        return new EngineApiClient(port, token);
+        // Bind to whatever project is open right now. On a genuine engine restart the
+        // token rotates and getClient() rebuilds this client, so a restart naturally
+        // 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);
+    }
+    /** The projectIdHash this session is bound to (undefined if none was reported
+     *  at connect — e.g. no project open yet). */
+    getBoundProjectIdHash() {
+        return this.boundProjectIdHash;
+    }
+    /**
+     * 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.
+     */
+    async rebind() {
+        const health = await checkEngineHealth(this.port);
+        if (health) {
+            this.boundProjectIdHash = health.projectIdHash;
+        }
+        return this.boundProjectIdHash;
+    }
+    /** 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 } : {};
     }
     async request(method, path, body) {
         const url = `http://127.0.0.1:${this.port}${path}`;
@@ -150,7 +191,11 @@ export class EngineApiClient {
         // Ops may include long-running work (ImportFromUrlBatch, GitCommit); the
         // engine keeps it "running" and we poll. 120s budget. Resolves legacy-200 or
         // async-202 (Block E).
-        return this._requestQueued("POST", "/api/ops", { ops, options }, 120_000);
+        // Attach the bound project identity so the engine rejects a write aimed at a
+        // different project (identity_mismatch, atomic — before any op applies).
+        const merged = { ...this.identityOptions(), ...(options ?? {}) };
+        const body = Object.keys(merged).length ? { ops, options: merged } : { ops };
+        return this._requestQueued("POST", "/api/ops", body, 120_000);
     }
     async getSceneState() {
         return this.request("GET", "/api/state/scene");
@@ -174,11 +219,14 @@ export class EngineApiClient {
         // Cold-load on large projects can take 25-40s. 60s budget.
         // 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);
+        // dropped, so the scene MUST be nested inside options. The bound identity
+        // rides in the same options dict so play is refused on a mismatched project.
+        const options = { ...this.identityOptions(), ...(scene ? { scene } : {}) };
+        return this._requestQueued("POST", "/api/play", Object.keys(options).length ? { options } : {}, 60_000);
     }
     async stop() {
-        return this._requestQueued("POST", "/api/stop", undefined, 15_000);
+        const options = this.identityOptions();
+        return this._requestQueued("POST", "/api/stop", Object.keys(options).length ? { options } : undefined, 15_000);
     }
     async readFile(path, maxBytes) {
         const params = new URLSearchParams({ path });
@@ -211,6 +259,18 @@ export class EngineApiClient {
         // The terminal result is the apply dict; the image rides as base64 inside it
         // (no raw-binary channel). Legacy/dormant engines answer 200 synchronously
         // with the same payload shape — _requestQueued resolves both.
+        //
+        // Game capture over local HTTP structurally 409s today with a STRUCTURED
+        // reason (`failure_reason:"unsupported_transport"`, `bridge_required:true`,
+        // tool_net_thread.cpp:495-503). Detect that specific shape and return it
+        // verbatim so the tool can give an honest message — do NOT hardcode "game
+        // always fails": once the engine answers 200/202 (P4.4), the normal path
+        // below just works.
+        if (kind === "game") {
+            const bridge = await this._detectBridgeRequired(`/api/snapshot/${kind}`);
+            if (bridge)
+                return bridge;
+        }
         let response;
         try {
             response = await this._requestQueued("GET", `/api/snapshot/${kind}`, undefined, 60_000);
@@ -218,11 +278,16 @@ export class EngineApiClient {
         catch (err) {
             return { ok: false, error: err instanceof Error ? err.message : String(err) };
         }
+        return this._parseSnapshotResponse(response, kind);
+    }
+    /** Shared: turn an ops/snapshot response envelope into an EngineSnapshot.
+     *  Used by viewport/game snapshots and by scenePreview. */
+    async _parseSnapshotResponse(response, kind) {
         const payload = findSnapshotPayload(response);
         if (!payload) {
             return {
                 ok: false,
-                error: "Snapshot response did not include a viewport/game payload.",
+                error: "Snapshot response did not include an image payload.",
             };
         }
         const base64 = stringFrom(payload.base64) ?? stringFrom(payload.image_base64);
@@ -230,16 +295,40 @@ export class EngineApiClient {
             return {
                 ok: false,
                 error: stringFrom(payload.error) ?? "Snapshot response did not include image data.",
+                failureReason: stringFrom(payload.failure_reason),
+                sceneHasCamera: boolFrom(payload.scene_has_camera),
+                sceneHadLight: boolFrom(payload.scene_had_light),
+                usedSyntheticCamera: boolFrom(payload.used_synthetic_camera),
                 metadata: withoutImageData(payload),
             };
         }
         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.
+        let projectMismatch;
+        if (this.boundProjectIdHash) {
+            try {
+                const health = await checkEngineHealth(this.port);
+                if (health?.projectIdHash && health.projectIdHash !== this.boundProjectIdHash) {
+                    projectMismatch = true;
+                }
+            }
+            catch {
+                // ignore — never fail a capture on a transient health read
+            }
+        }
         return {
             ok: payload.ok !== false,
             localPath,
             path: localPath,
+            base64,
             width: numberFrom(payload.width),
             height: numberFrom(payload.height),
             format,
@@ -248,16 +337,110 @@ export class EngineApiClient {
             op: stringFrom(payload.op),
             provenance: payload.provenance,
             bytes: buffer.byteLength,
+            sceneHasCamera: boolFrom(payload.scene_has_camera),
+            sceneHadLight: boolFrom(payload.scene_had_light),
+            usedSyntheticCamera: boolFrom(payload.used_synthetic_camera),
+            projectMismatch,
             metadata: withoutImageData(payload),
         };
     }
+    /**
+     * Probe /api/snapshot/game for the structural 409 `bridge_required` shape
+     * (tool_net_thread.cpp:495-503). Returns a structured failure only when the
+     * engine actually answers 409 with `bridge_required` / `unsupported_transport`;
+     * ANY other status (200/202/other) returns null so the caller proceeds to the
+     * normal queued path — so the moment the engine starts answering over HTTP
+     * (P4.4), game capture just works with no code change here.
+     */
+    async _detectBridgeRequired(path) {
+        let res;
+        try {
+            res = await this._fetchRaw("GET", path, undefined, 15_000);
+        }
+        catch {
+            // Transport error — let the normal path surface it uniformly.
+            return null;
+        }
+        if (res.status !== 409)
+            return null;
+        const body = (await res.json().catch(() => ({})));
+        const reason = stringFrom(body.failure_reason);
+        const bridge = body.bridge_required === true;
+        if (!bridge && reason !== "unsupported_transport") {
+            // A 409 we don't recognize — surface it as a plain error rather than
+            // silently claiming "bridge required".
+            return {
+                ok: false,
+                error: stringFrom(body.error) ?? "Engine returned 409 for game snapshot.",
+            };
+        }
+        return {
+            ok: false,
+            failureReason: reason ?? "bridge_required",
+            error: stringFrom(body.error) ?? "Game snapshots require the desktop bridge async transport.",
+        };
+    }
     async viewportSnapshot() {
         return this.snapshot("viewport");
     }
     async gameSnapshot() {
         return this.snapshot("game");
     }
+    /**
+     * Offscreen scene render via the `ScenePreview` op over /api/ops (no game
+     * boot; physics/animations are static). Mirrors the web previewScene op input
+     * (snapshot-tools.ts): { op:'ScenePreview', scene_path?, framing?, size?,
+     * node_path? } — scene_path optional, engine defaults to the open scene. The
+     * result carries image_base64 + mime (+ width/height) plus the P4.3 confession
+     * fields (scene_has_camera / scene_had_light / used_synthetic_camera).
+     */
+    async scenePreview(input) {
+        const opInput = { op: "ScenePreview" };
+        const trimmed = input?.scenePath?.trim();
+        if (trimmed && trimmed !== "." && trimmed !== "./")
+            opInput.scene_path = trimmed;
+        if (input?.framing)
+            opInput.framing = input.framing;
+        if (input?.size)
+            opInput.size = input.size;
+        if (input?.nodePath)
+            opInput.node_path = input.nodePath;
+        let response;
+        try {
+            // executeOps stamps the bound identity so a drifted project is rejected
+            // (identity_mismatch) before rendering — ScenePreview reads no game state
+            // but still targets a project's resources.
+            response = await this.executeOps([opInput]);
+        }
+        catch (err) {
+            return { ok: false, error: err instanceof Error ? err.message : String(err) };
+        }
+        return this._parseSnapshotResponse(response, "scene");
+    }
     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;
+        }
+    }
 }

package/dist/lib/game-task-plan.js

@@ -308,10 +308,14 @@ function buildMcpToolPlan(mode, target, assetPolicy, verification, goal = "") {
         assets.push("summer_search_assets", "summer_import_asset");
     }
     if (verification !== "none") {
-        verify.push("summer_get_script_errors", "summer_get_diagnostics");
+        // Rung 1-2 of the ladder: does it compile / does it look right.
+        verify.push("summer_get_script_errors", "summer_get_diagnostics", "summer_screenshot");
     }
     if (verification === "full") {
-        verify.push("summer_clear_console", "summer_play", "summer_get_debugger_errors", "summer_stop");
+        // Rung 3: run it and read runtime errors. Ordered as the composed loop —
+        // clear -> play -> read runtime errors -> look at the live frame -> stop.
+        // (There is no single "verify" tool; the agent composes these.)
+        verify.push("summer_clear_console", "summer_play", "summer_get_debugger_errors", "summer_screenshot", "summer_stop");
     }
     return { start, mutate, assets, verify };
 }