summer-engine 2.6.3 → 2.6.5

package/.claude-plugin/plugin.json

@@ -2,7 +2,7 @@
   "$schema": "https://json.schemastore.org/claude-code-plugin-manifest.json",
   "name": "summer",
   "version": "2.5.1",
-  "description": "Agent tooling for Summer Engine: game-dev skills, lifecycle hooks, and a 44-tool MCP bridge to the local desktop app.",
+  "description": "Agent tooling for Summer Engine: game-dev skills, lifecycle hooks, and a 52-tool MCP bridge to the local desktop app.",
   "author": {
     "name": "Summer Engine",
     "email": "founders@summerengine.com",

package/.codex-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "summer",
   "version": "2.5.1",
-  "description": "Agent tooling for Summer Engine: game-dev skills, lifecycle hooks, and a 44-tool MCP bridge. Build games by talking.",
+  "description": "Agent tooling for Summer Engine: game-dev skills, lifecycle hooks, and a 52-tool MCP bridge. Build games by talking.",
   "author": {
     "name": "Summer Engine",
     "email": "founders@summerengine.com",
@@ -92,7 +92,7 @@
   "interface": {
     "displayName": "Summer",
     "shortDescription": "Superpowers for AI game dev. Build games by talking.",
-    "longDescription": "Summer turns Codex into a game-dev studio for Summer Engine, the AI-native game engine. It adds game-dev skills, a using-summer workflow skill, lifecycle hooks, and a 44-tool MCP bridge for scene editing, asset import, play mode, diagnostics, and generation. File, git, shell, and grep stay with the host agent. Summer Engine is compatible with Godot 4.5. Write code in GDScript and drive the engine through MCP. Session-start orients the session. Pre-commit doctor (opt-in) blocks bad commits.",
+    "longDescription": "Summer turns Codex into a game-dev studio for Summer Engine, the AI-native game engine. It adds game-dev skills, a using-summer workflow skill, lifecycle hooks, and a 52-tool MCP bridge for scene editing, asset import, play mode, diagnostics, and generation. File, git, shell, and grep stay with the host agent. Summer Engine is compatible with Godot 4.5. Write code in GDScript and drive the engine through MCP. Session-start orients the session. Pre-commit doctor (opt-in) blocks bad commits.",
     "developerName": "Summer Engine",
     "category": "Coding",
     "capabilities": ["Interactive", "Read", "Write"],

package/.cursor-plugin/plugin.json

@@ -3,7 +3,7 @@
   "name": "summer",
   "displayName": "Summer",
   "version": "2.5.1",
-  "description": "Agent tooling for Summer Engine: game-dev skills, lifecycle hooks, and a 44-tool MCP bridge to the local desktop app.",
+  "description": "Agent tooling for Summer Engine: game-dev skills, lifecycle hooks, and a 52-tool MCP bridge to the local desktop app.",
   "author": { "name": "Summer Engine", "email": "founders@summerengine.com" },
   "publisher": "summer-engine",
   "homepage": "https://summerengine.com",

package/.factory-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "summer",
-  "description": "Agent tooling for Summer Engine: game-dev skills, lifecycle hooks, and a 44-tool MCP bridge to the local desktop app.",
+  "description": "Agent tooling for Summer Engine: game-dev skills, lifecycle hooks, and a 52-tool MCP bridge to the local desktop app.",
   "version": "2.5.1",
   "author": {
     "name": "Summer Engine",

package/AGENTS.md

@@ -22,11 +22,12 @@ This file is for any AI agent that loads context from `AGENTS.md` (Codex CLI, Fa
 
 ## MCP tool palette (engine on `localhost:6550`)
 
-44 tools total. Categories:
+52 tools total. Categories:
 
 - Scene: `summer_get_scene_tree`, `summer_open_scene`, `summer_create_scene`, `summer_add_node`, `summer_set_prop`, `summer_set_resource_property`, `summer_remove_node`, `summer_save_scene`, `summer_instantiate_scene`, `summer_replace_node`, `summer_select_node`, `summer_inspect_node`, `summer_inspect_resource`, `summer_connect_signal`, `summer_batch`.
 - Diagnostics: `summer_get_script_errors`, `summer_get_diagnostics`, `summer_get_console`, `summer_clear_console`, `summer_get_debugger_errors`, `summer_get_debugger_warnings`.
 - Runtime: `summer_play`, `summer_stop`, `summer_is_running`.
+- Visual: `summer_screenshot` (capture the editor viewport or running game as an image to verify it).
 - Project: `summer_get_project_context`, `summer_open_main_scene`, `summer_project_setting`, `summer_input_map_bind`, `summer_get_agent_playbook`.
 - Assets: `summer_search_assets`, `summer_list_my_assets`, `summer_get_asset`, `summer_get_asset_download_url`, `summer_import_asset`, `summer_import_asset_by_id`, `summer_import_from_url`, `summer_import_from_url_batch`.
 - Generation: `summer_generate_image`, `summer_generate_3d`, `summer_generate_audio`, `summer_generate_video`, `summer_generate_motion`, `summer_check_job`.

package/CHANGELOG.md

@@ -2,6 +2,26 @@
 
 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.5] — 2026-07-04 — "Cloud tools don't need the engine"
+
+### Fixed
+- Tool descriptions now say explicitly which tools run in Summer's cloud and work WITHOUT the engine open (`summer_generate_*`, `summer_search_assets`, `summer_list_my_assets`, `summer_get_asset`, `summer_get_asset_download_url`, `summer_check_job`) and which need the engine (imports, scene ops). Agents were misreading a missing `npx summer-engine login` as "MCP requires the engine".
+- The "Summer Engine is not running" error now tells the agent that cloud tools still work without the engine.
+
+## [2.6.4] — 2026-07-03 — "See-Work + project binding" (unpublished, ships with 2.6.5)
+
+### Added
+- MCP session binds to its project; the engine rejects wrong-project writes (`identity_mismatch`) instead of applying them to whatever project is open.
+- Structured per-tool-call stderr logging; agent playbook rewritten around the MCP verification ladder; honest game-capture failure states and identity-stamped reads.
+
+## [2.6.3] — 2026-06-30 — "Agent vision"
+
+### Added
+- `summer_screenshot` MCP tool: capture the editor viewport or the running game as an image the agent sees directly (`target: "viewport" | "game"`, viewport by default). Lets the agent visually verify scene layout, asset placement, scale, framing, and runtime state — the client reads the actual frame, with no description step in between. Total MCP tool surface is now 52.
+
+### Fixed
+- MCP/CLI session now reconnects automatically after a transient engine restart (the engine rotates its api-token and can move its port on relaunch), instead of surfacing as a "disconnected" error.
+
 ## [2.6.0] — 2026-06-10 — "Summer Cloud"
 
 ### Added

package/GEMINI.md

@@ -20,12 +20,13 @@ The single most important skill to know is `summer:using-summer` — it explains
 
 ## MCP tools (when the engine is running on `localhost:6550`)
 
-The `summer-engine` MCP server exposes 44 focused tools. The most important:
+The `summer-engine` MCP server exposes 52 focused tools. The most important:
 
 - **Scene mutation**: `summer_add_node`, `summer_set_prop`, `summer_set_resource_property`, `summer_remove_node`, `summer_save_scene`, `summer_replace_node`, `summer_batch`.
 - **Scene inspection**: `summer_get_scene_tree`, `summer_inspect_node`, `summer_inspect_resource`.
 - **Diagnostics**: `summer_get_script_errors` (cheapest), `summer_get_diagnostics`, `summer_get_console`, `summer_get_debugger_errors`, `summer_get_debugger_warnings`.
 - **Run game**: `summer_play`, `summer_stop`, `summer_is_running`.
+- **Visual**: `summer_screenshot` (capture the viewport or running game as an image you can see).
 - **Project**: `summer_get_project_context`, `summer_open_main_scene`, `summer_project_setting`, `summer_input_map_bind`.
 - **Assets**: `summer_search_assets`, `summer_import_asset`, `summer_import_from_url`, `summer_generate_image`, `summer_generate_3d`, `summer_generate_audio`, `summer_generate_video`, `summer_check_job`.
 

package/README.md

@@ -18,7 +18,7 @@ It just works. Open your agent, say *"let's make an FPS in Summer Engine,"* and
 Three names, one npm package (`summer-engine`):
 
 - **Summer CLI** (`npx -y summer-engine@latest`): installs the engine, signs you in, scaffolds and runs projects, and writes your agent's config. See [www.summerengine.com/cli](https://www.summerengine.com/cli).
-- **Summer MCP**: the local MCP server that gives your agent 44 engine tools to build, run, and debug a real game. See [www.summerengine.com/mcp](https://www.summerengine.com/mcp).
+- **Summer MCP**: the local MCP server that gives your agent 52 engine tools to build, run, and debug a real game. See [www.summerengine.com/mcp](https://www.summerengine.com/mcp).
 - **Summer agent layer**: the game-dev skills, hooks, and plugin manifests that give your AI agent judgment, not just a chat box.
 
 All MIT, all free to use. One paste sets up all three.
@@ -269,13 +269,15 @@ Two pieces, plus the glue.
 
 Skills don't list steps. They encode the **order of operations**: diagnose before editing, scope before building, ask before guessing. [Agent Skills](https://agentskills.io) format, so any conformant tool picks them up.
 
-**MCP bridge.** The `summer-engine` MCP server gives the agent 44 tools that talk to your local engine on `localhost:6550`:
+**MCP bridge.** The `summer-engine` MCP server gives the agent 52 tools that talk to your local engine on `localhost:6550`:
 
 | | |
 |---|---|
 | Scene | `summer_add_node`, `summer_set_prop`, `summer_instantiate_scene`, `summer_replace_node`, `summer_get_scene_tree`, `summer_inspect_node`, `summer_batch` |
 | Diagnostics | `summer_get_script_errors`, `summer_get_diagnostics`, `summer_get_console`, `summer_get_debugger_errors`, `summer_get_debugger_warnings` |
 | Runtime | `summer_play`, `summer_stop`, `summer_is_running` |
+| Visual | `summer_screenshot` (see the editor viewport, an offscreen scene render, or the running game) |
+| Interactive | `SimulateInput` / `RunVerification` raw ops via `summer_batch` — drive the running game or run a hidden GDScript probe (engine-build dependent) |
 | Project | `summer_get_project_context`, `summer_open_main_scene`, `summer_project_setting`, `summer_input_map_bind` |
 | Assets | `summer_search_assets`, `summer_import_asset`, `summer_import_from_url`, `summer_generate_image`, `summer_generate_3d`, `summer_generate_audio`, `summer_generate_video` |
 
@@ -285,6 +287,36 @@ File ops, git, shell, and grep already belong to your agent. We don't shadow the
 
 For the full architecture, see [docs/OVERVIEW.md](docs/OVERVIEW.md).
 
+### Using Summer via MCP: the verification loop
+
+There is no single "verify" tool. You **compose** the checks, climbing only as high as the change demands. Call `summer_get_agent_playbook` for the full ladder; the short version:
+
+**1. Does it compile?** After writing a `.gd`, call `summer_get_script_errors res://scripts/player.gd` — no game boot. For a project-wide sweep, `summer_get_diagnostics` (it tells you whether to then read `summer_get_console` / `summer_get_debugger_errors`).
+
+**2. Does it look right?** `summer_screenshot` returns the actual pixels — you see them, no description layer. Pick the target on purpose:
+- `viewport` (default) — the editor's current tab, as it looks now.
+- `scene` — an offscreen render of a scene *file* (`scenePath`). No boot; **static at t=0**. Confesses if the scene has no `Camera3D` (renders grey/black when played) or no light — read those warnings.
+- `game` — a frame from the **running** game (`summer_play` first). Over plain local HTTP this returns an honest failure until the desktop bridge is present; when it fails, drop to `viewport`/`scene` or ask the user.
+
+**3. Does it run?** Compose the loop:
+
+```
+summer_clear_console            # clean slate
+summer_play                     # boot the game (or a specific scene)
+summer_get_debugger_errors      # runtime errors: null refs, missing nodes, physics
+summer_screenshot target:game   # optional: look at the live frame
+summer_stop                     # ALWAYS stop — scene edits are refused while running
+```
+
+**4. Does the interaction work?** To prove input-driven behavior (jump/move/shoot), send a raw op through `summer_batch` (engine-build dependent — a `failure_reason:"unsupported"` comes back verbatim on older builds):
+- `SimulateInput` — inject into the **running** game: `summer_batch ops:[{op:"SimulateInput", type:"action", action:"jump", pressed:true}]`, then re-check screenshot/debugger.
+- `RunVerification` — spawn a hidden, disposable game instance that runs a GDScript probe (press inputs, read state, save frames) and dies, never touching the editor: `summer_batch ops:[{op:"RunVerification", probe_source:"…", max_seconds:20}]` → `{ok, results, frames, out_dir}`.
+- If neither is available on this build, **ask the user to try it** and report what they see — don't fake it.
+
+**Honesty.** Never describe an image you didn't receive; a failed capture is a *result* — report it and climb down (`scene`→`viewport`) or ask the user. Pass structured failures (`failure_reason`, `terminalState`, `identity_mismatch`) through verbatim. `summer_get_project_context` binds the session to the open project; a `projectMismatch` warning on a screenshot means the engine switched projects and the frame may be from the wrong one — rebind before trusting it.
+
+**Debugging the MCP itself.** Set `SUMMER_MCP_DEBUG=1` in the server's environment to log a structured stderr line per tool call (`tool`, `ok`, `durationMs`, `terminalState`, `errorClass`, `failureReason`, `retried`). With the flag off, only failures are logged.
+
 ---
 
 ## The basic workflow

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

@@ -16,12 +16,43 @@ export type EngineSnapshot = {
     bytes?: number;
     error?: string;
     metadata?: Record<string, unknown>;
+    /** Structured failure classifier the engine returns on a game snapshot over
+     *  local HTTP (409 `bridge_required`) — surfaced verbatim so the tool can give
+     *  an honest, actionable message instead of a truncated generic 409 string.
+     *  When P4.4 lands (game snapshots answer 200/202 over HTTP) this simply
+     *  never fires and the tool works. */
+    failureReason?: string;
+    /** Scene-preview confession fields (P4.3). Populated only for target:"scene".
+     *  A scene with no Camera3D renders grey/black when played; the engine reports
+     *  whether it had to synthesize a camera/light so the model can warn honestly. */
+    sceneHasCamera?: boolean;
+    sceneHadLight?: boolean;
+    usedSyntheticCamera?: boolean;
+    /** Set true when the bound projectIdHash no longer matches the engine's live
+     *  health hash at capture time — the frame may be from the WRONG project
+     *  (item 4, client-side drift check). */
+    projectMismatch?: boolean;
 };
 export declare class EngineApiClient {
     private port;
     private token;
-    constructor(port: number, token: string);
+    private boundProjectIdHash?;
+    constructor(port: number, token: string, boundProjectIdHash?: 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). */
+    getBoundProjectIdHash(): string | undefined;
+    /**
+     * 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.
+     */
+    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 request;
     /** Raw fetch with auth + timeout — returns the Response so callers can inspect
      *  the status (202 queued vs 200 legacy). */
@@ -51,8 +82,34 @@ export declare class EngineApiClient {
     getSelection(): Promise<unknown>;
     private writeSnapshotFile;
     private snapshot;
+    /** Shared: turn an ops/snapshot response envelope into an EngineSnapshot.
+     *  Used by viewport/game snapshots and by scenePreview. */
+    private _parseSnapshotResponse;
+    /**
+     * 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.
+     */
+    private _detectBridgeRequired;
     viewportSnapshot(): Promise<EngineSnapshot>;
     gameSnapshot(): Promise<EngineSnapshot>;
+    /**
+     * 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).
+     */
+    scenePreview(input?: {
+        scenePath?: string;
+        framing?: "auto" | "top" | "front" | "iso";
+        size?: [number, number];
+        nodePath?: string;
+    }): Promise<EngineSnapshot>;
     getPort(): number;
     /**
      * Cheap drift probe for the MCP client cache. The engine mints a fresh

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,12 +295,35 @@ 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,
@@ -249,15 +337,86 @@ 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;
     }

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 };
 }

package/dist/mcp/server.js

@@ -5,6 +5,7 @@ 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 { WITH_ENGINE_META } from "./tools/with-engine.js";
 import { registerProjectTools } from "./tools/project-tools.js";
 import { registerAssetTools } from "./tools/asset-tools.js";
 import { registerGenerateTools } from "./tools/generate-tools.js";
@@ -49,7 +50,10 @@ export async function getClient() {
     }
     catch {
         cachedClient = null;
-        throw new Error("Summer Engine is not running. Open it first, or run: npx summer-engine run");
+        throw new Error("Summer Engine is not running. Open it first, or run: npx summer-engine run\n" +
+            "Note: only tools that touch the local project need the engine. Cloud tools " +
+            "(summer_generate_*, summer_search_assets, summer_list_my_assets, summer_get_asset, " +
+            "summer_check_job) work right now without it — they only need 'npx summer-engine login'.");
     }
 }
 export function resetClient() {
@@ -78,30 +82,59 @@ function installResultSizeLogger(server) {
         if (typeof handler !== "function")
             return original(...args);
         const wrapped = async (...handlerArgs) => {
+            const startedAt = Date.now();
             const result = await handler(...handlerArgs);
+            const durationMs = Date.now() - startedAt;
             try {
                 if (result &&
                     typeof result === "object" &&
                     "content" in result &&
                     Array.isArray(result.content)) {
-                    let chars = 0;
-                    for (const entry of result
-                        .content) {
-                        if (entry && entry.type === "text" && typeof entry.text === "string") {
-                            chars += entry.text.length;
+                    const debug = process.env.SUMMER_MCP_DEBUG === "1";
+                    const isError = result.isError === true;
+                    // withEngine stamps failure classifiers + retried + bound hash on a
+                    // non-enumerable symbol so we can log them here without every tool
+                    // threading its own name through withEngine.
+                    const meta = result[WITH_ENGINE_META];
+                    // Structured per-call line. Verbose behind SUMMER_MCP_DEBUG=1; when the
+                    // flag is off, log ONLY failures — the success path stays quiet.
+                    if (debug || isError) {
+                        const callLine = JSON.stringify({
+                            event: "mcp:tool_call",
+                            tool: name,
+                            ok: !isError,
+                            isError,
+                            durationMs,
+                            ...(meta?.terminalState ? { terminalState: meta.terminalState } : {}),
+                            ...(meta?.errorClass ? { errorClass: meta.errorClass } : {}),
+                            ...(meta?.failureReason ? { failureReason: meta.failureReason } : {}),
+                            ...(meta?.retried ? { retried: true } : {}),
+                            ...(meta?.boundProjectIdHash
+                                ? { boundProjectIdHash: meta.boundProjectIdHash }
+                                : {}),
+                        });
+                        process.stderr.write(`[summer-mcp] ${callLine}\n`);
+                    }
+                    if (debug) {
+                        let chars = 0;
+                        for (const entry of result
+                            .content) {
+                            if (entry && entry.type === "text" && typeof entry.text === "string") {
+                                chars += entry.text.length;
+                            }
                         }
+                        const bytes = Buffer.byteLength(result.content
+                            .filter((e) => e && e.type === "text" && typeof e.text === "string")
+                            .map((e) => e.text)
+                            .join(""), "utf8");
+                        const line = JSON.stringify({
+                            event: "mcp:result_size",
+                            tool_name: name,
+                            chars,
+                            bytes,
+                        });
+                        process.stderr.write(`[summer-mcp] ${line}\n`);
                     }
-                    const bytes = Buffer.byteLength(result.content
-                        .filter((e) => e && e.type === "text" && typeof e.text === "string")
-                        .map((e) => e.text)
-                        .join(""), "utf8");
-                    const line = JSON.stringify({
-                        event: "mcp:result_size",
-                        tool_name: name,
-                        chars,
-                        bytes,
-                    });
-                    process.stderr.write(`[summer-mcp] ${line}\n`);
                 }
             }
             catch {