summer-engine 1.0.0 → 1.1.0

package/dist/bin/summer.js

@@ -11,6 +11,7 @@ import { installCommand } from "../commands/install.js";
 import { createCommand } from "../commands/create.js";
 import { listCommand } from "../commands/list.js";
 import { skillsCommand } from "../commands/skills.js";
+import { orchestratorCommand } from "../commands/orchestrator.js";
 const require = createRequire(import.meta.url);
 const { version } = require("../../package.json");
 const program = new Command();
@@ -28,6 +29,7 @@ program.addCommand(createCommand);
 program.addCommand(listCommand);
 program.addCommand(skillsCommand);
 program.addCommand(mcpCommand);
+program.addCommand(orchestratorCommand);
 program.parseAsync().catch((err) => {
     console.error(err instanceof Error ? err.message : String(err));
     process.exit(1);

package/dist/commands/orchestrator.d.ts

@@ -0,0 +1,8 @@
+/**
+ * CLI command: summer agent
+ * Launches the web app locally with direct engine execution enabled.
+ * The web app handles all AI logic (prompts, tools, RAG, billing).
+ * This command just starts it with LOCAL_ENGINE_PORT set.
+ */
+import { Command } from "commander";
+export declare const orchestratorCommand: Command;

package/dist/commands/orchestrator.js

@@ -0,0 +1,143 @@
+/**
+ * CLI command: summer agent
+ * Launches the web app locally with direct engine execution enabled.
+ * The web app handles all AI logic (prompts, tools, RAG, billing).
+ * This command just starts it with LOCAL_ENGINE_PORT set.
+ */
+import { Command } from "commander";
+import { spawn } from "node:child_process";
+import { readFile, access, writeFile } from "node:fs/promises";
+import { join, resolve, dirname } from "node:path";
+import { homedir } from "node:os";
+import { getApiToken, getApiPort, checkEngineHealth } from "../lib/engine.js";
+import { getSummerDir } from "../lib/auth.js";
+async function findWebAppPath() {
+    // 1. Check env var
+    if (process.env.SUMMER_WEB_APP_PATH) {
+        return process.env.SUMMER_WEB_APP_PATH;
+    }
+    // 2. Check ~/.summer/web-app-path
+    try {
+        const stored = (await readFile(join(getSummerDir(), "web-app-path"), "utf-8")).trim();
+        if (stored) {
+            await access(join(stored, "package.json"));
+            return stored;
+        }
+    }
+    catch {
+        // Not stored yet
+    }
+    // 3. Search common sibling locations
+    const cliDir = dirname(dirname(dirname(new URL(import.meta.url).pathname)));
+    const searchPaths = [
+        resolve(cliDir, "../../publicsummerengine"), // sibling in development/
+        resolve(cliDir, "../../../publicsummerengine"), // one level up
+        resolve(homedir(), "development/publicsummerengine"),
+    ];
+    for (const candidate of searchPaths) {
+        try {
+            await access(join(candidate, "package.json"));
+            const pkg = JSON.parse(await readFile(join(candidate, "package.json"), "utf-8"));
+            if (pkg.name && pkg.name.includes("summer")) {
+                // Store for future use
+                try {
+                    await writeFile(join(getSummerDir(), "web-app-path"), candidate, "utf-8");
+                }
+                catch {
+                    // Non-critical
+                }
+                return candidate;
+            }
+        }
+        catch {
+            continue;
+        }
+    }
+    return null;
+}
+async function loadEnvFile() {
+    const envVars = {};
+    try {
+        const envPath = join(getSummerDir(), "env");
+        const content = await readFile(envPath, "utf-8");
+        for (const line of content.split("\n")) {
+            const trimmed = line.trim();
+            if (!trimmed || trimmed.startsWith("#"))
+                continue;
+            const eqIdx = trimmed.indexOf("=");
+            if (eqIdx > 0) {
+                envVars[trimmed.slice(0, eqIdx)] = trimmed.slice(eqIdx + 1);
+            }
+        }
+    }
+    catch {
+        // No env file — user will need to have env vars set
+    }
+    return envVars;
+}
+export const orchestratorCommand = new Command("agent")
+    .description("Start the web app locally with direct engine execution. " +
+    "Tools call localhost:6550 instead of the Redis bridge.")
+    .option("-p, --port <number>", "Web app port", "3000")
+    .option("--web-path <path>", "Path to publicsummerengine (auto-detected if not set)")
+    .option("--dev", "Run in dev mode (pnpm dev) instead of production")
+    .action(async (opts) => {
+    const port = parseInt(opts.port, 10);
+    // 1. Verify engine is running
+    const enginePort = await getApiPort();
+    const engineToken = await getApiToken();
+    const health = await checkEngineHealth(enginePort);
+    if (!health) {
+        console.error("Summer Engine is not running. Open Summer Engine first.");
+        process.exit(1);
+    }
+    console.log(`Engine running on port ${enginePort} | project: ${health.project_name ?? "unknown"}`);
+    // 2. Find web app
+    const webAppPath = opts.webPath ?? (await findWebAppPath());
+    if (!webAppPath) {
+        console.error("Could not find publicsummerengine. Set --web-path or SUMMER_WEB_APP_PATH.");
+        process.exit(1);
+    }
+    console.log(`Web app: ${webAppPath}`);
+    // 3. Load env vars from ~/.summer/env
+    const storedEnv = await loadEnvFile();
+    // 4. Build env for the web app
+    const childEnv = {
+        ...process.env,
+        ...storedEnv,
+        LOCAL_ENGINE_PORT: String(enginePort),
+        LOCAL_ENGINE_TOKEN: engineToken ?? "",
+        PORT: String(port),
+    };
+    // 5. Start the web app
+    const cmd = opts.dev ? "pnpm" : "pnpm";
+    const args = opts.dev ? ["dev", "--port", String(port)] : ["start", "--port", String(port)];
+    console.log(`\nStarting web app (${opts.dev ? "dev" : "production"} mode) on port ${port}...`);
+    console.log(`  LOCAL_ENGINE_PORT=${enginePort}`);
+    console.log(`  Tools will execute via localhost:${enginePort} (direct, no bridge)\n`);
+    const child = spawn(cmd, args, {
+        cwd: webAppPath,
+        env: childEnv,
+        stdio: "inherit",
+    });
+    // Write agent port for engine to discover
+    try {
+        await writeFile(join(getSummerDir(), "agent-port"), String(port), "utf-8");
+    }
+    catch {
+        // Non-critical
+    }
+    child.on("error", (err) => {
+        console.error("Failed to start web app:", err.message);
+        process.exit(1);
+    });
+    child.on("exit", (code) => {
+        process.exit(code ?? 0);
+    });
+    // Graceful shutdown
+    const shutdown = () => {
+        child.kill("SIGTERM");
+    };
+    process.on("SIGINT", shutdown);
+    process.on("SIGTERM", shutdown);
+});

package/dist/commands/run.js

@@ -8,6 +8,7 @@ const MAC_PATHS = [
     `${process.env.HOME}/Applications/Summer.app/Contents/MacOS/Summer`,
 ];
 const WIN_PATHS = [
+    `${process.env.LOCALAPPDATA}\\SummerEngine\\current\\Summer.exe`,
     `${process.env.LOCALAPPDATA}\\Programs\\Summer Engine\\Summer.exe`,
     `${process.env.PROGRAMFILES}\\Summer Engine\\Summer.exe`,
 ];

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

@@ -14,4 +14,10 @@ export declare class EngineApiClient {
     getScriptErrors(path: string): Promise<unknown>;
     play(scene?: string): Promise<unknown>;
     stop(): Promise<unknown>;
+    readFile(path: string, maxBytes?: number): Promise<unknown>;
+    getFsTree(root?: string, limit?: number): Promise<unknown>;
+    getSelection(): Promise<unknown>;
+    viewportSnapshot(): Promise<Buffer>;
+    gameSnapshot(): Promise<Buffer>;
+    getPort(): number;
 }

package/dist/lib/api-client.js

@@ -66,4 +66,43 @@ export class EngineApiClient {
     async stop() {
         return this.request("POST", "/api/stop");
     }
+    async readFile(path, maxBytes) {
+        const params = new URLSearchParams({ path });
+        if (maxBytes)
+            params.set("maxBytes", String(maxBytes));
+        return this.request("GET", `/api/state/read-file?${params}`);
+    }
+    async getFsTree(root = "res://", limit = 2000) {
+        const params = new URLSearchParams({
+            root,
+            limit: String(limit),
+        });
+        return this.request("GET", `/api/state/fs-tree?${params}`);
+    }
+    async getSelection() {
+        return this.request("GET", "/api/state/selection");
+    }
+    async viewportSnapshot() {
+        const url = `http://127.0.0.1:${this.port}/api/snapshot/viewport`;
+        const res = await fetch(url, {
+            headers: { Authorization: `Bearer ${this.token}` },
+            signal: AbortSignal.timeout(15000),
+        });
+        if (!res.ok)
+            throw new Error(`Viewport snapshot failed: ${res.status}`);
+        return Buffer.from(await res.arrayBuffer());
+    }
+    async gameSnapshot() {
+        const url = `http://127.0.0.1:${this.port}/api/snapshot/game`;
+        const res = await fetch(url, {
+            headers: { Authorization: `Bearer ${this.token}` },
+            signal: AbortSignal.timeout(15000),
+        });
+        if (!res.ok)
+            throw new Error(`Game snapshot failed: ${res.status}`);
+        return Buffer.from(await res.arrayBuffer());
+    }
+    getPort() {
+        return this.port;
+    }
 }

package/dist/mcp/server.js

@@ -36,5 +36,5 @@ export async function startMcpServer() {
     registerAssetTools(server);
     const transport = new StdioServerTransport();
     await server.connect(transport);
-    process.stderr.write(`[summer-mcp] MCP server running v${version}. 28 tools available.\n`);
+    process.stderr.write(`[summer-mcp] MCP server running v${version}.\n`);
 }

package/dist/mcp/tools/project-tools.js

@@ -1,6 +1,93 @@
 import { z } from "zod";
 import { withEngine } from "./with-engine.js";
+import { readFile } from "fs/promises";
+import { join } from "path";
+async function readMainSceneFromProject(projectPath) {
+    if (!projectPath)
+        return null;
+    try {
+        const text = await readFile(join(projectPath, "project.godot"), "utf-8");
+        const match = text.match(/run\/main_scene="([^"]+)"/);
+        return match?.[1] ?? null;
+    }
+    catch {
+        return null;
+    }
+}
 export function registerProjectTools(server) {
+    server.tool("summer_get_agent_playbook", `AI-first operating guide for Summer Engine MCP.
+
+Call this at the start of a fresh chat before touching scenes.
+It returns the safe workflow, anti-patterns, and recovery steps.`, {}, async () => ({
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify({
+                    startupChecklist: [
+                        "Decide first: file edit or engine operation.",
+                        "For normal code/content edits (.gd/.tscn/.tres/.ts), use host file-edit tools directly.",
+                        "Call summer_get_project_context first.",
+                        "If no scene is open, call summer_open_main_scene.",
+                        "Call summer_get_scene_tree before structural edits.",
+                        "Call summer_save_scene after edits.",
+                    ],
+                    safeDefaults: [
+                        "Never guess scene filenames (main.tscn/Main.tscn).",
+                        "Do not route ordinary code edits through MCP when direct file tools are available.",
+                        "Never remove multiple top-level nodes unless user explicitly requests destructive edits.",
+                        "Never write .tscn/.scn with file write tools; use scene ops.",
+                    ],
+                    preferredFlow: [
+                        "summer_get_project_context",
+                        "summer_open_main_scene (if needed)",
+                        "summer_get_scene_tree",
+                        "edit via summer_add_node / summer_set_prop / summer_set_resource_property",
+                        "summer_save_scene",
+                        "summer_get_diagnostics",
+                    ],
+                    recovery: [
+                        "If you see 'no scene open': run summer_open_main_scene.",
+                        "If open_scene fails: re-check mainScene from summer_get_project_context.",
+                        "If save fails: verify scene is open and game is not running.",
+                    ],
+                }, null, 2),
+            },
+        ],
+    }));
+    server.tool("summer_get_project_context", `Get essential project context before editing. Returns:
+- engine health/status
+- project name and path
+- current scene path (if available)
+- main scene path from project.godot
+
+Use this first in every fresh chat to avoid guessing scene filenames or editing the wrong scene.`, {}, async () => withEngine(async (client) => {
+        const [health, projectState] = await Promise.all([
+            client.health(),
+            client.getProjectState(),
+        ]);
+        const healthObj = (health ?? {});
+        const mainScene = await readMainSceneFromProject(typeof healthObj.project_path === "string" ? healthObj.project_path : undefined);
+        return {
+            health,
+            project: projectState,
+            mainScene,
+            guidance: mainScene
+                ? "Use `summer_open_scene` with `mainScene` if no scene is open."
+                : "Main scene not found in project.godot. Open a known scene path explicitly.",
+        };
+    }));
+    server.tool("summer_open_main_scene", `Open the project's configured main scene from project.godot.
+
+Safer than guessing scene names like main.tscn/Main.tscn.
+Call this when you get "no scene open".`, {}, async () => withEngine(async (client) => {
+        const health = (await client.health());
+        const projectPath = typeof health.project_path === "string" ? health.project_path : undefined;
+        const mainScene = await readMainSceneFromProject(projectPath);
+        if (!mainScene) {
+            throw new Error("Could not resolve application/run/main_scene from project.godot. Call `summer_get_project_context` and open a scene explicitly.");
+        }
+        return client.executeOps([{ op: "OpenScene", path: mainScene }]);
+    }));
     server.tool("summer_project_setting", `Set a project setting in project.godot. Common settings:
 - "application/config/name" — project name
 - "application/run/main_scene" — main scene path
@@ -29,7 +116,10 @@ Example: Bind jump to Space and W:
         ];
         return client.executeOps(ops);
     }));
-    server.tool("summer_get_scene_tree", "Get the full scene tree structure of the currently open scene. Returns all nodes with their types, paths, and children. Use this to understand the scene before making changes.", {}, async () => withEngine(async (client) => client.getSceneState()));
+    server.tool("summer_get_scene_tree", `Get the full scene tree structure of the currently open scene.
+
+Use this before structural edits (add/remove/replace).
+If you get "no edited scene", call summer_open_main_scene first.`, {}, async () => withEngine(async (client) => client.getSceneState()));
     server.tool("summer_import_from_url", `Download a file from a URL and import it into the project. Triggers Godot's full import pipeline — generates .import files, extracts textures from .glb models, creates materials.
 
 Use this for:

package/dist/mcp/tools/scene-tools.js

@@ -1,8 +1,79 @@
 import { z } from "zod";
 import { withEngine } from "./with-engine.js";
+import { readFile } from "fs/promises";
+import { join } from "path";
+async function readMainSceneFromProject(projectPath) {
+    if (!projectPath)
+        return null;
+    try {
+        const text = await readFile(join(projectPath, "project.godot"), "utf-8");
+        const match = text.match(/run\/main_scene="([^"]+)"/);
+        return match?.[1] ?? null;
+    }
+    catch {
+        return null;
+    }
+}
 export function registerSceneTools(server) {
+    server.tool("summer_create_scene", `Create a new empty scene file safely.
+
+IMPORTANT:
+- This tool uses a temporary mutation strategy: it opens a template scene, removes children, saves to a new path, then restores the previous scene.
+- To prevent accidental destructive actions, you MUST explicitly set allow_temporary_scene_mutation=true.
+- If you don't want this strategy, stop and ask the user for manual scene creation in the editor.
+
+Recommended workflow:
+1) Call summer_get_project_context
+2) Call summer_open_main_scene (optional)
+3) Call summer_create_scene with a new path`, {
+        path: z.string().describe("New scene path, e.g. 'res://scenes/empty_level.tscn'"),
+        rootName: z.string().default("Main").describe("Root node name for the new scene"),
+        allow_temporary_scene_mutation: z
+            .boolean()
+            .default(false)
+            .describe("Safety gate. Must be true to proceed."),
+    }, async ({ path, rootName, allow_temporary_scene_mutation }) => withEngine(async (client) => {
+        if (!allow_temporary_scene_mutation) {
+            throw new Error("Refusing to create scene without explicit approval. Re-run with allow_temporary_scene_mutation=true.");
+        }
+        const health = (await client.health());
+        const currentScene = typeof health.scene === "string" && health.scene.length > 0 ? health.scene : null;
+        const projectPath = typeof health.project_path === "string" ? health.project_path : undefined;
+        const mainScene = await readMainSceneFromProject(projectPath);
+        const templateScene = currentScene || mainScene;
+        if (!templateScene) {
+            throw new Error("No scene open and could not resolve main scene. Call summer_get_project_context first, then open a known scene.");
+        }
+        await client.executeOps([{ op: "OpenScene", path: templateScene }]);
+        const tree = (await client.getSceneState());
+        const children = tree.data?.children ?? tree.children ?? [];
+        const removeOps = children
+            .map((c) => c.path)
+            .filter((p) => typeof p === "string" && p.length > 0)
+            .map((p) => ({ op: "RemoveNode", path: `./${p}` }));
+        if (removeOps.length > 0) {
+            await client.executeOps(removeOps, { groupUndo: true });
+        }
+        await client.executeOps([{ op: "SetProp", path: ".", key: "name", value: rootName }]);
+        await client.executeOps([{ op: "SaveScene", path }]);
+        if (currentScene && currentScene !== path) {
+            await client.executeOps([{ op: "OpenScene", path: currentScene }]);
+        }
+        return {
+            ok: true,
+            created: path,
+            rootName,
+            templateScene,
+            restoredScene: currentScene,
+        };
+    }));
     server.tool("summer_add_node", `Add a new node to the scene tree.
 
+Preflight (fresh chat):
+1) summer_get_project_context
+2) summer_open_main_scene (if no scene open)
+3) summer_get_scene_tree
+
 Common node types:
 - 3D: Node3D, MeshInstance3D, CharacterBody3D, RigidBody3D, StaticBody3D, Camera3D, DirectionalLight3D, OmniLight3D, SpotLight3D, WorldEnvironment, CollisionShape3D, Area3D
 - 2D: Node2D, Sprite2D, CharacterBody2D, RigidBody2D, StaticBody2D, Camera2D, CollisionShape2D, Area2D, TileMapLayer
@@ -52,14 +123,19 @@ Use when you need to modify a sub-property of a resource, like:
     }, async ({ nodePath, resourceProperty, subProperty, value }) => withEngine(async (client) => client.executeOps([
         { op: "SetResourceProperty", nodePath, resourceProperty, subProperty, value },
     ])));
-    server.tool("summer_remove_node", "Remove a node from the scene tree. All children are removed too. Cannot remove the root node. Supports undo.", { path: z.string().describe("Node path to remove, e.g. './World/OldEnemy'") }, async ({ path }) => withEngine(async (client) => client.executeOps([{ op: "RemoveNode", path }])));
+    server.tool("summer_remove_node", "Remove a node from the scene tree. All children are removed too. Cannot remove the root node. Supports undo. Destructive operation: do not delete multiple top-level nodes unless the user explicitly requests destructive changes.", { path: z.string().describe("Node path to remove, e.g. './World/OldEnemy'") }, async ({ path }) => withEngine(async (client) => client.executeOps([{ op: "RemoveNode", path }])));
     server.tool("summer_save_scene", "Save the current scene to disk. Call this after making scene changes to persist them. Without saving, changes only exist in the editor's memory.", { path: z.string().optional().describe("Save-as path for creating a new scene file, e.g. 'res://levels/level2.tscn'") }, async ({ path }) => withEngine(async (client) => {
         const op = { op: "SaveScene" };
         if (path)
             op.path = path;
         return client.executeOps([op]);
     }));
-    server.tool("summer_open_scene", "Open a scene file in the editor. Use this to switch between scenes (e.g., open a level to edit it).", { path: z.string().describe("Scene path, e.g. 'res://main.tscn' or 'res://levels/level1.tscn'") }, async ({ path }) => withEngine(async (client) => client.executeOps([{ op: "OpenScene", path }])));
+    server.tool("summer_open_scene", `Open a scene file in the editor. Use this to switch between scenes.
+
+Do not guess paths. Prefer:
+1) summer_get_project_context (read mainScene)
+2) summer_open_main_scene (open known main scene)
+3) summer_open_scene only when user gave an explicit path.`, { path: z.string().describe("Scene path, e.g. 'res://main.tscn' or 'res://levels/level1.tscn'") }, async ({ path }) => withEngine(async (client) => client.executeOps([{ op: "OpenScene", path }])));
     server.tool("summer_instantiate_scene", `Add an existing scene or 3D model as a child node. Use this to:
 - Add a .tscn prefab (reusable scene) as a child
 - Add a .glb/.gltf 3D model into the scene

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

@@ -1,6 +1,28 @@
 import { getClient, resetClient } from "../server.js";
 import { getAuthToken } from "../../lib/auth.js";
 const GATEWAY_URL = process.env.SUMMER_GATEWAY_URL || "https://www.summerengine.com";
+function extractOpError(result) {
+    if (!result || typeof result !== "object")
+        return null;
+    const op = result;
+    if (op.status === "error" && op.error)
+        return op.error;
+    const firstFailed = op.results?.find((r) => r.ok === false && r.error);
+    return firstFailed?.error ?? null;
+}
+function buildActionHint(message) {
+    const normalized = message.toLowerCase();
+    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).";
+    }
+    if (normalized.includes("failed to open scene")) {
+        return "Scene path could not be opened. Call `summer_get_project_context` to get `mainScene`, then open that exact path. Avoid guessing scene filenames.";
+    }
+    if (normalized.includes("writefile cannot edit .tscn/.scn")) {
+        return "This MCP operation cannot write .tscn/.scn directly. If your host AI has normal file-edit tools, edit .gd/.tscn files there; use Summer MCP for engine/state/scene-tree operations.";
+    }
+    return null;
+}
 async function checkMcpQuota() {
     const token = await getAuthToken();
     if (!token) {
@@ -55,6 +77,12 @@ export async function withEngine(fn) {
         }
         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 };
+        }
         return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
     }
     catch (err) {

package/package.json

@@ -1,8 +1,16 @@
 {
   "name": "summer-engine",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "CLI and MCP tools for Summer Engine — the AI-native game engine",
-  "keywords": ["game-engine", "godot", "ai", "mcp", "gamedev", "3d", "summer-engine"],
+  "keywords": [
+    "game-engine",
+    "godot",
+    "ai",
+    "mcp",
+    "gamedev",
+    "3d",
+    "summer-engine"
+  ],
   "homepage": "https://summerengine.com",
   "repository": {
     "type": "git",
@@ -14,7 +22,11 @@
   "bin": {
     "summer": "./dist/bin/summer.js"
   },
-  "files": ["dist/", "skills/", "README.md"],
+  "files": [
+    "dist/",
+    "skills/",
+    "README.md"
+  ],
   "scripts": {
     "build": "tsc",
     "dev": "tsc --watch",
@@ -25,12 +37,16 @@
     "node": ">=18"
   },
   "dependencies": {
+    "@ai-sdk/anthropic": "^3.0.0",
     "@modelcontextprotocol/sdk": "^1.0.0",
+    "ai": "^6.0.0",
     "commander": "^12.0.0",
+    "diff": "^7.0.0",
     "open": "^10.0.0",
     "zod": "^3.23.0"
   },
   "devDependencies": {
+    "@types/diff": "^7.0.0",
     "@types/node": "^20.0.0",
     "typescript": "^5.5.0"
   }