summer-engine 2.8.2 → 3.0.0

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

@@ -1,15 +1,20 @@
 import { z } from "zod";
-import { ASSET_POLICIES, GAME_TASK_MODES, GAME_TASK_TARGETS, VERIFICATION_LEVELS, buildGameTaskPlan, } from "../../lib/game-task-plan.js";
-import { getCachedBootDriftNotice } from "../../lib/mcp-boot-notice.js";
-import { getProjectMemorySummary } from "../../lib/project-memory.js";
+import { ASSET_POLICIES, GAME_TASK_MODES, GAME_TASK_TARGETS, VERIFICATION_LEVELS, buildGameTaskPlan, } from "../../core/capabilities/game-task-plan.js";
+import { buildAgentPlaybook as buildCoreAgentPlaybook } from "../../core/capabilities/agent-playbook.js";
+import { buildProjectContext, projectContextInputShape, resolveMainScene, } from "../../core/capabilities/project-context.js";
+import { getCachedBootDriftNotice } from "../boot-notice.js";
+import { appendMcpLogEvent } from "../../core/mcp-log.js";
 import { withEngine } from "./with-engine.js";
-function asRecord(value) {
-    return value && typeof value === "object" && !Array.isArray(value)
-        ? value
-        : null;
-}
-function stringFrom(value) {
-    return typeof value === "string" && value.length > 0 ? value : null;
+import { asRecord, stringFrom } from "../../core/util/json.js";
+// One skew log line per MCP process — the warning itself stays in every
+// summer_get_project_context payload.
+let capabilitySkewLogged = false;
+function logCapabilitySkewOnce(warning) {
+    if (capabilitySkewLogged)
+        return;
+    capabilitySkewLogged = true;
+    appendMcpLogEvent("mcp:capability_skew", { warning });
+    process.stderr.write(`[summer-mcp] ${JSON.stringify({ event: "mcp:capability_skew", warning })}\n`);
 }
 function pickString(record, keys) {
     if (!record)
@@ -21,128 +26,47 @@ function pickString(record, keys) {
     }
     return null;
 }
-function getProjectData(projectState) {
-    return asRecord(asRecord(projectState)?.data);
-}
-function getProjectSetting(projectState, keys) {
-    const data = getProjectData(projectState);
-    const entries = data?.entries;
-    if (!Array.isArray(entries))
-        return null;
-    for (const entry of entries) {
-        const item = asRecord(entry);
-        const key = stringFrom(item?.key);
-        if (key && keys.includes(key)) {
-            return stringFrom(item?.value);
-        }
-    }
-    return null;
-}
-function getProjectPath(projectState, health) {
-    const root = asRecord(projectState);
-    const data = getProjectData(projectState);
-    const healthRoot = asRecord(health);
-    return (pickString(data, [
-        "projectPath",
-        "project_path",
-        "projectRoot",
-        "project_root",
-        "rootPath",
-        "root_path",
-    ]) ??
-        pickString(root, ["projectPath", "project_path", "projectRoot", "project_root"]) ??
-        pickString(healthRoot, ["project_path", "projectPath", "projectRoot", "project_root"]) ??
-        null);
-}
-function getProjectName(projectState, health) {
-    const root = asRecord(projectState);
-    const data = getProjectData(projectState);
-    const healthRoot = asRecord(health);
-    return (pickString(data, ["projectName", "project_name", "name"]) ??
-        pickString(root, ["projectName", "project_name", "name"]) ??
-        pickString(healthRoot, ["project_name", "projectName", "name"]) ??
-        getProjectSetting(projectState, ["application/config/name", "config/name"]));
-}
-function getMainScene(projectState) {
-    const root = asRecord(projectState);
-    const data = getProjectData(projectState);
-    return (pickString(data, ["mainScene", "main_scene", "mainScenePath", "main_scene_path"]) ??
-        pickString(root, ["mainScene", "main_scene", "mainScenePath", "main_scene_path"]) ??
-        getProjectSetting(projectState, [
-            "application/run/main_scene",
-            "run/main_scene",
-        ]));
-}
-function getCurrentScene(projectState, sceneState, health) {
-    const sceneRoot = asRecord(sceneState);
-    const sceneData = asRecord(sceneRoot?.data);
-    const sceneProvenance = asRecord(sceneRoot?.provenance);
-    const projectRoot = asRecord(projectState);
-    const projectData = getProjectData(projectState);
-    const projectProvenance = asRecord(projectRoot?.provenance);
-    const healthRoot = asRecord(health);
-    return (pickString(sceneProvenance, ["scenePath", "scene_path"]) ??
-        pickString(sceneData, ["scenePath", "scene_path", "currentScene", "current_scene"]) ??
-        pickString(projectData, ["currentScene", "current_scene", "scenePath", "scene_path"]) ??
-        pickString(projectProvenance, ["scenePath", "scene_path"]) ??
-        pickString(healthRoot, ["scene", "scenePath", "scene_path"]) ??
-        null);
-}
 function getScenePathFromSceneState(sceneState) {
     const root = asRecord(sceneState);
     return (pickString(asRecord(root?.provenance), ["scenePath", "scene_path"]) ??
         pickString(asRecord(root?.data), ["scenePath", "scene_path"]) ??
         null);
 }
-/** Default prefix set kept in summer_get_project_context when no settingsPrefix
- *  is given. The full settings dump measured 188KB (~47k tokens) on a real
- *  project; these prefixes cover what agents actually key on (main scene,
- *  window size, input actions, physics, renderer). */
-const CONTEXT_SETTINGS_PREFIXES = [
-    "application/",
-    "display/",
-    "input/",
-    "physics/",
-    "rendering/",
-];
 /**
- * Bound the project-state payload. The engine ignores ?prefix= on
- * /api/state/project (snapshot-served with empty args — see
- * ApiClient.getProjectState), so ALL filtering here is client-side:
- * - settingsPrefix given: keep only entries under that prefix.
- * - no prefix: keep only the curated CONTEXT_SETTINGS_PREFIXES.
- * Trimming is always declared in the payload (settingsTruncated /
- * totalSettings / hint); everything outside data.entries is preserved.
+ * The agent playbook lives in core (src/core/capabilities/agent-playbook.ts)
+ * so this tool, the MCP prompt below, and `summer tool get-agent-playbook`
+ * share ONE implementation. The MCP surface contributes the boot drift notice
+ * it owns. Exported for tests.
  */
-function trimProjectSettings(projectState, settingsPrefix) {
-    const root = asRecord(projectState);
-    const data = asRecord(root?.data);
-    const entries = data?.entries;
-    if (!root || !data || !Array.isArray(entries))
-        return projectState;
-    const keyOf = (entry) => stringFrom(asRecord(entry)?.key);
-    const kept = settingsPrefix
-        ? entries.filter((entry) => keyOf(entry)?.startsWith(settingsPrefix) ?? false)
-        : entries.filter((entry) => {
-            const key = keyOf(entry);
-            return key !== null && CONTEXT_SETTINGS_PREFIXES.some((p) => key.startsWith(p));
-        });
-    return {
-        ...root,
-        data: {
-            ...data,
-            entries: kept,
-            settingsTruncated: kept.length < entries.length,
-            totalSettings: entries.length,
-            returnedSettings: kept.length,
-            ...(settingsPrefix
-                ? { settingsPrefix }
-                : {
-                    settingsPrefixesIncluded: [...CONTEXT_SETTINGS_PREFIXES],
-                    settingsHint: "Settings were trimmed to the curated prefixes above to bound payload size. Pass settingsPrefix (e.g. 'audio/' or 'layer_names/') to read another settings group.",
-                }),
-        },
-    };
+export function buildAgentPlaybook() {
+    return buildCoreAgentPlaybook({
+        summerUpdateNotice: getCachedBootDriftNotice()?.text ?? null,
+    });
+}
+export function renderAgentPlaybook() {
+    return JSON.stringify(buildAgentPlaybook(), null, 2);
+}
+/**
+ * Register the playbook as an MCP PROMPT as well, so hosts that surface
+ * prompts (prompt pickers, slash commands) get the operating guide natively
+ * without knowing to call the tool. Same content, second doorway.
+ */
+export function registerPlaybookPrompt(server) {
+    server.registerPrompt("summer_agent_playbook", {
+        title: "Summer Engine agent playbook",
+        description: "AI-first operating guide for the Summer Engine MCP tools: observe-first loop, screenshot before/after every mutation, content routing (reuse -> import -> generate -> script last), physical invariants, cost rules, verification ritual, honesty rules, and recovery steps.",
+    }, async () => ({
+        messages: [
+            {
+                role: "user",
+                content: {
+                    type: "text",
+                    text: "Operate Summer Engine by this playbook for the rest of the session:\n\n" +
+                        renderAgentPlaybook(),
+                },
+            },
+        ],
+    }));
 }
 export function registerProjectTools(server) {
     server.tool("summer_start_game_task", `Start here for any substantial AI game-building task.
@@ -185,117 +109,13 @@ mutating the project.`, {
     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, the verification ladder, honesty rules,
-anti-patterns, and recovery steps.`, {}, async () => ({
+It returns the observe-first loop, content routing (reuse -> import ->
+generate -> script), physical invariants, cost rules, the verification
+ladder, honesty rules, anti-patterns, and recovery steps.`, {}, async () => ({
         content: [
             {
                 type: "text",
-                text: JSON.stringify({
-                    summerUpdateNotice: getCachedBootDriftNotice()?.text ?? null,
-                    startupChecklist: [
-                        "Understand the request and outline a brief plan before reaching for tools.",
-                        "Use summer_read_file, summer_write_file, and summer_replace_text for project text files so reads and guarded writes stay bound to the open engine project.",
-                        "Use Summer MCP for project mutations and live-engine work: scenes, resources, play/stop, diagnostics, screenshots/verification, bake, runtime inspection, and asset import.",
-                        "Call summer_get_project_context first so you do not guess scene paths or the project language. It also BINDS this session to the currently-open project (see projectBinding below).",
-                        "Use projectMemory from summer_get_project_context to decide which .summer Markdown files to read before creative/audio/dialogue/level/character work.",
-                        "After writing code, VERIFY through the engine (see verificationLadder) instead of waiting for the user to navigate to it.",
-                    ],
-                    safeDefaults: [
-                        "Never guess scene filenames (main.tscn/Main.tscn) -- get them from summer_get_project_context.",
-                        "Use summer_replace_text for existing project text and summer_write_file with create_only:true for new files; overwrites require the sha256 from summer_read_file.",
-                        "For live scene hierarchy and inspector changes, prefer scene tools. Guarded text writes support .tscn/.tres, and the engine schedules editor reloads after they land.",
-                        "Write GDScript by default; use C# only if the project already uses it.",
-                        "Never remove multiple top-level nodes unless the user explicitly requests destructive edits.",
-                        "Never change priority: locked .summer memory, voice IDs, canon, or provider bindings without explicit user confirmation.",
-                    ],
-                    buildFlow: [
-                        "1. Understand what the user wants (one pass, no tool spelunking first).",
-                        "2. Outline the plan fast and briefly; proceed once it is clearly right.",
-                        "3. Execute through identity-bound MCP mutations -- guarded text tools for files, scene tools for live hierarchy/inspector work (GDScript by default, C# only if the project already uses it).",
-                        "4. Verify through the engine using the verificationLadder below, fix, and repeat until it launches clean.",
-                    ],
-                    // The MCP-native verification ladder. Climb only as high as the
-                    // change demands: a script edit needs rung 1; a gameplay change
-                    // needs rungs 3-4. Each rung is a REAL engine call, not a claim.
-                    verificationLadder: {
-                        "1_compiles": [
-                            "After writing/editing a .gd file, call summer_get_script_errors <path> — compiles without running the game.",
-                            "For a project-wide sweep of editor + runtime issues, call summer_get_diagnostics (it tells you whether to then read summer_get_console / summer_get_debugger_errors).",
-                        ],
-                        "2_looks_right": [
-                            "To SEE the result, call summer_screenshot. Pick the target deliberately:",
-                            "  target:'viewport' (default) = the editor's CURRENT open tab, exactly as it looks now. Edit-time check. No game boot.",
-                            "  target:'scene' = an OFFSCREEN render of a scene FILE (pass scenePath). No game boot; physics/particles/animations are STATIC at t=0. Best for 'is the composition/scale right' without disturbing the open tab. It also confesses if the scene has no Camera3D (renders grey/black when played) or no light (lit materials look black) — READ those warnings.",
-                            "  target:'game' = a frame from the RUNNING game (real runtime state). summer_play FIRST. Over a plain local HTTP connection this returns an honest failure (needs the Summer desktop bridge); when it fails, fall back to viewport/scene or ask the user.",
-                        ],
-                        "3_runs": [
-                            "Compose the run-and-check yourself — there is no single 'verify' tool:",
-                            "summer_play [scene]   -> boot the game (or a specific scene)",
-                            "summer_get_debugger_errors  -> runtime errors (null refs, missing nodes, physics)",
-                            "summer_screenshot target:'game'  -> optional visual of the live frame",
-                            "summer_stop  -> stop when runtime verification is finished; editor scene mutations are not categorically blocked by a running game, but an existing game instance may need a restart to observe them",
-                        ],
-                        "4_interactive": [
-                            "To prove input-driven behavior (does jump/move/shoot actually work), prefer RunVerification — a scripted, repeatable probe. SimulateInput is also reachable as a single op against the RUNNING game (see rawOpsViaBatch); do NOT hand this rung to the user while either route works.",
-                            "RunVerification: spawn a hidden, disposable game instance that runs a GDScript probe (press inputs, read state, save frames) and dies — never touches the user's editor. Returns results.json + frames. Send it as a raw op through summer_batch (see rawOpsViaBatch).",
-                            "Unlike the editor's own --headless mode, the verify instance renders REAL PIXELS, so save_frame('name') writes a real image and Performance.TIME_FPS reports a real number. save_frame REQUIRES a name argument — save_frame() with no args is a script error (probe fails).",
-                            "Mount probe scenes DEFERRED: get_tree().root.add_child.call_deferred(instance); await get_tree().process_frame; await settle(). A direct add_child during _ready can hit the parent-busy guard and 'succeed' while capturing a black frame.",
-                            "press()/key() are COROUTINES — 'await press(\"move_right\", 500)' or the hold never elapses and the input does nothing.",
-                            "Assert on physics-frame-derived state (positions after N 'await get_tree().physics_frame'), which is reproducible. press(hold_ms) waits on wall clock, so distance-travelled jitters run to run — assert 'moved more than X', never an exact value.",
-                        ],
-                    },
-                    // HONESTY — mirror the in-product agent's vision rules. A capture is
-                    // a fact, not a formality; a failed capture is itself a result.
-                    honestyRules: [
-                        "NEVER describe an image you did not actually receive. If summer_screenshot returned isError or a text-only fallback (no image block), say the capture failed and why — do not invent what the frame 'probably' shows.",
-                        "A failed or blocked capture is a RESULT, not a dead end: report it, then climb down the ladder (scene->viewport) or ask the user for a screenshot.",
-                        "Describe only what is actually in the returned frame. Do not pad with expected content.",
-                        "target:'scene' is STATIC (t=0) and may use a synthetic camera — do not claim animation/particles/gameplay motion from it, and heed its no-camera / no-light / synthetic-camera warnings.",
-                        "Pass structured engine failures (failure_reason, terminalState, errorClass) through to the user verbatim — never soften 'unsupported' or 'bridge_required' into a vague 'it didn't work'.",
-                    ],
-                    // The session is pinned to the project open when you first called
-                    // summer_get_project_context. This keeps a mutation from landing in
-                    // the WRONG project after an in-place project switch.
-                    projectBinding: [
-                        "summer_get_project_context binds this session to the currently-open project and is the deliberate (re)bind point.",
-                        "If the engine later switches projects in place, mutating ops are REJECTED with identity_mismatch (nothing is applied — your edit did NOT land in the wrong project).",
-                        "summer_screenshot adds a projectMismatch WARNING when the engine's live project no longer matches this binding — the frame may be from the wrong project; do not trust it until you rebind.",
-                        "To intentionally follow the switch, call summer_get_project_context again to rebind, then retry.",
-                    ],
-                    liveEngineFlow: [
-                        "Use this flow when you genuinely need live engine state (navmesh/light bake, scene mutation, runtime inspect):",
-                        "summer_get_project_context",
-                        "Choose the exact res:// scenePath. OpenScene is a user-visible tab action, not a mutation prerequisite.",
-                        "summer_get_scene_tree with scenePath when that exact scene is already loaded; omit it only for the visible tab.",
-                        "summer_add_node / summer_set_prop / summer_set_resource_property with scenePath",
-                        "Mutation tools append one final SaveScene; use summer_save_scene only for a standalone save/save-as.",
-                        "summer_get_diagnostics",
-                    ],
-                    // summer_batch forwards each {op, ...} verbatim to the engine, so
-                    // engine ops that have no dedicated tool are still reachable.
-                    rawOpsViaBatch: [
-                        "summer_batch runs an array of raw engine ops in one undo group; each op is passed through untouched, so newer engine ops with no dedicated tool are still callable.",
-                        "RunVerification (hidden probe instance): summer_batch ops:[{op:'RunVerification', probe_source:'<gdscript>', max_seconds:20}]. probe_source extends SummerProbeBase and uses report(name, value)/save_frame(name)/press(action)/key(keycode)/finish(); returns {ok, results, frames, out_dir} or {ok:false, failure_reason: spawn_failed|timeout|bad_args|no_project|probe_not_node}. save_frame REQUIRES a name argument.",
-                        "SimulateInput (drive the RUNNING game — summer_play first): summer_batch ops:[{op:'SimulateInput', type:'action', action:'jump', pressed:true}], sent ALONE as the only op. failure_reason 'not_running' = start the game first; 'unsupported' = the running game build predates the handler — use RunVerification instead.",
-                        "SINGLE-OP CONTRACT: the engine rejects any multi-op batch containing SaveScene, InstantiateScene, ReplaceNode, SimulateInput, ViewportSnapshot, GameSnapshot, Run*/Import* or Git* ops (failure_reason 'unsupported_transport', nothing executes). summer_batch splits these into sequential requests for you; when composing raw batches keep them as their own call anyway.",
-                        "WriteFile and ReplaceText are rejected here by design — use summer_write_file / summer_replace_text so project identity, content guards and same-file ordering are enforced.",
-                        "You do not need an engine op to run a shell command: your own host already has a shell. The engine binary that runs project scripts is at OS.get_executable_path() (on macOS, /Applications/Summer.app/Contents/MacOS/Summer); see the summer-cli headless-scripting skill.",
-                        "These are runtime ops, not scene mutations — the batch undo group is a harmless no-op for them.",
-                    ],
-                    recovery: [
-                        "If a scene mutation reports missing_scene_path: pass the exact res:// scenePath and retry.",
-                        "If a scene target cannot load: repair the named missing/invalid dependency, then retry the same scenePath.",
-                        "If open_scene fails: re-check mainScene from summer_get_project_context.",
-                        "If save fails: use the returned scenePath/error to repair the exact cause. A running game alone is not a generic scene-mutation blocker.",
-                        "If a mutation is rejected with identity_mismatch: the engine switched projects — call summer_get_project_context to rebind (only if you meant to follow it), then retry.",
-                        "If a guarded file mutation is rejected with content mismatch: call summer_read_file again, review the new content, and retry with its new sha256 only if the edit is still valid.",
-                        "If a run op returns 'unsupported' / an unknown-op error: this engine build predates it — fall back to summer_play + summer_get_debugger_errors.",
-                        "If any op returns 'unsupported_transport': it was batched with other ops. Resend it as the ONLY op in the request (nothing from the rejected batch was applied).",
-                    ],
-                    debugging: [
-                        "Set SUMMER_MCP_DEBUG=1 in the MCP server's environment to log a structured stderr line per tool call (tool, ok, durationMs, terminalState, errorClass, failureReason, retried, boundProjectIdHash). With the flag OFF, only failures are logged. Use it to see exactly which op failed and why.",
-                    ],
-                }, null, 2),
+                text: renderAgentPlaybook(),
             },
         ],
     }));
@@ -304,63 +124,34 @@ anti-patterns, and recovery steps.`, {}, async () => ({
 - project name and project path when exposed by project state
 - current scene path (if available)
 - main scene path from project settings
-- lightweight .summer project memory summary when project path is available
+- projectMemory: the .summer summary — GameSoul/build-plan/memory files and
+  \`pin\` (.summer/project.json: which template at which commit started this
+  project, toolkit version, created_at)
+- capabilitySkewWarning (only when the engine build and this CLI have drifted
+  apart — non-fatal; explains upcoming 'unknown op' failures)
 
 Use this first in every fresh chat to avoid guessing scene filenames or editing the wrong scene.
 
-Project settings in project.data.entries are trimmed to a curated prefix set
-(application/, display/, input/, physics/, rendering/) to bound payload size —
-the untrimmed dump can exceed 45k tokens. The payload declares the trim
-(settingsTruncated, totalSettings, settingsPrefixesIncluded). Pass
-settingsPrefix to read a specific settings group (e.g. 'audio/') instead.`, {
-        settingsPrefix: z
-            .string()
-            .optional()
-            .describe("Only return project settings whose key starts with this prefix, e.g. 'audio/' or 'application/config/'. Omit for the curated default set."),
-    }, async ({ settingsPrefix }) => withEngine(async (client) => {
-        const [health, fullProjectState, sceneState] = await Promise.all([
-            client.health(),
-            client.getProjectState(settingsPrefix),
-            client.getSceneState().catch((err) => ({
-                ok: false,
-                error: err instanceof Error ? err.message : String(err),
-            })),
-        ]);
-        // Derived fields read the UNtrimmed state so a narrow settingsPrefix
-        // cannot hide mainScene/projectPath from the context summary.
-        const projectState = trimProjectSettings(fullProjectState, settingsPrefix);
-        const projectPath = getProjectPath(fullProjectState, health);
-        const projectName = getProjectName(fullProjectState, health);
-        const mainScene = getMainScene(fullProjectState);
-        const currentScene = getCurrentScene(fullProjectState, sceneState, health);
-        // This tool is the deliberate (re)bind point: capture the currently-open
-        // project as the one this session's mutations are pinned to. After an
-        // engine project switch the agent calls this to intentionally follow the
-        // new project; subsequent edits then target it instead of being rejected.
-        const boundProjectIdHash = await client.rebind();
-        return {
-            health,
-            project: projectState,
-            scene: sceneState,
-            projectName,
-            projectPath,
-            currentScene,
-            mainScene,
-            boundProjectIdHash,
-            projectMemory: getProjectMemorySummary(projectPath),
-            summerUpdateNotice: getCachedBootDriftNotice()?.text ?? null,
-            guidance: mainScene
-                ? "Use `summer_open_scene` with `mainScene` if no scene is open."
-                : "Main scene not found in project state. Open a known scene path explicitly.",
-            fileEditingGuidance: "Use summer_read_file plus summer_replace_text or guarded summer_write_file for project files, including .gd/.cs/.tscn/.tres/.json/docs. New files require create_only:true; overwrites require the sha256 receipt from summer_read_file. Prefer scene tools for live hierarchy/inspector changes.",
-        };
-    }));
+Project settings in project.data.entries are trimmed to the curated default
+groups (application/, display/window/, the project's input/ actions, default
+gravity, rendering/renderer/, the 2D default texture filter) to bound payload
+size — the untrimmed dump is ~1000 entries. The payload declares the trim
+(settingsTruncated, totalSettings, settingsPrefixesIncluded,
+settingsPrefixesExcluded). Pass settingsPrefixes (e.g. ["audio/",
+"layer_names/"]) or settingsPrefix to read other groups instead.`, projectContextInputShape, async (args) => withEngine(async (client) => 
+    // ONE builder for both faces (core/capabilities/project-context.ts);
+    // the MCP surface contributes the boot drift notice it owns and logs
+    // a capability skew once per process.
+    buildProjectContext(client, args, {
+        summerUpdateNotice: getCachedBootDriftNotice()?.text ?? null,
+        onCapabilitySkew: logCapabilitySkewOnce,
+    })));
     server.tool("summer_open_main_scene", `Open the project's configured main scene from project settings.
 
 Safer than guessing scene names like main.tscn/Main.tscn.
 Call this when you get "no scene open".`, {}, async () => withEngine(async (client) => {
         const projectState = await client.getProjectState();
-        const mainScene = getMainScene(projectState);
+        const mainScene = resolveMainScene(projectState);
         if (!mainScene) {
             throw new Error("Could not resolve application/run/main_scene from project state. Call `summer_get_project_context` and open a scene explicitly.");
         }

package/dist/mcp/tools/runtime-tools.d.ts

@@ -0,0 +1,2 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerRuntimeTools(server: McpServer): void;

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

@@ -0,0 +1,92 @@
+import { withEngine, missingEngineOpResult, withOldEngineHint } from "./with-engine.js";
+import { RUNTIME_FALLBACKS, buildGameControlOp, buildGameInputOp, buildGameProbeOp, buildRuntimeAnimateOp, buildRuntimeCallOp, buildRuntimeSetOp, buildRuntimeSpawnOp, findProbePayload, gameControlArgsSchema, gameInputArgsSchema, gameProbeArgsSchema, probeFrameStamp, runtimeAnimateArgsSchema, runtimeCallArgsSchema, runtimeSetArgsSchema, runtimeSpawnArgsSchema, stripProbeImage, withRuntimeFailureHints, } from "../../core/capabilities/runtime-control.js";
+/**
+ * Runtime control & playtest tools (runtime control): see and touch the RUNNING
+ * game. Seven tools over sixteen engine op kinds; the argument contracts, op
+ * builders, budgets and failure hints live in core/capabilities/runtime-control.ts
+ * and are shared with the CLI face (`summer tool …`).
+ *
+ * Every op here is async single-only on the engine (a debugger round-trip
+ * needs the reply channel) and is sent as the ONLY op in its request with a
+ * budget that outlives the engine's own watchdog. Two layers cover an older
+ * engine: the capability pre-flight (nothing is sent when /api/health PROVES
+ * the op is missing) and the post-hoc rewrite of the per-op "unknown op"
+ * answer into the same engine_lacks_op result.
+ */
+const LOOP = "THE LOOP: summer_play (add instance + mode:'offscreen' for a disposable instance; deterministic:true + seed for a reproducible run; fixed_fps for exact timing) -> wait for boot (summer_is_running, or summer_game_control action:'instances' showing attached:true) -> summer_game_probe BEFORE (frame-stamped state + pixels) -> act (summer_runtime_set / summer_runtime_call / summer_game_input) -> summer_game_control action:'step' for exact frames, or let it run -> summer_game_probe AFTER -> assert on the two probes. Never claim something moved, spawned or fired without a probe that shows it.";
+const RUNNING_GAME_GATES = "Needs a RUNNING game: failure_reason game_not_running (summer_play first), request_failed (debug session still attaching — wait, retry), unknown_instance (summer_game_control action:'instances'), game_breaked (the game sits at a breakpoint — continue it first), timeout (game wedged, minimized or breaked — summer_get_debugger_errors, or summer_stop + summer_play), unsupported (the running game predates the summer capture; restart it after updating). All runtime paths are ABSOLUTE ('/root/Main/Player') and come from summer_game_probe tree / summer_get_runtime_tree.";
+/** Send one runtime op with pre-flight, budget, and hints on both failure classes. */
+async function runRuntimeOp(client, built, extraHints = {}) {
+    const fallback = RUNTIME_FALLBACKS[built.kind] ?? "use a RunVerification probe";
+    const missing = missingEngineOpResult(client, built.kind, fallback);
+    if (missing)
+        return missing;
+    const result = await client.executeOps([built.op], undefined, built.timeoutMs);
+    return withRuntimeFailureHints(withOldEngineHint(result, built.kind, fallback), extraHints);
+}
+export function registerRuntimeTools(server) {
+    server.tool("summer_runtime_set", `Set ONE property on a node in the RUNNING game — the live object, never the scene file (nothing is saved; the change dies with the run). Use it to put the game into the state you want to test without playing there by hand: teleport the player ('/root/Main/Player' position 'Vector3(0, 2, 0)'), set health to 1, flip a flag, toggle visibility.
+
+Returns {path, property, value_before, value_after, applied, transport, frame}. READ applied: false means the read-back did not match (failure_reason not_applied) — a script rewrites the value every frame, or the literal type was wrong. Math values in and out are Godot literal strings ('Vector3(1, 2, 3)'); 'script' and 'owner' are refused. For a persistent change edit the EDITED scene (summer_set_prop) and restart.
+
+${LOOP}
+
+${RUNNING_GAME_GATES} On an engine build that predates SetRuntimeProp the result is a structured engine_lacks_op failure naming the fallback.`, runtimeSetArgsSchema.shape, async (args) => withEngine(async (client) => runRuntimeOp(client, buildRuntimeSetOp(args))));
+    server.tool("summer_runtime_call", `Call ONE method on a node in the RUNNING game and get its return value: 'take_damage' [25], 'get_velocity', 'has_method', 'start_wave' [3]. The direct way to trigger gameplay code and read its answer without wiring input or waiting for a timer.
+
+Returns {path, method, return, return_type, return_truncated, frame}; return is a Godot literal string for math values. Arguments are JSON scalars/arrays/objects or Godot literal strings ('Vector3(0, 1, 0)'); Object/RID arguments are refused (bad_args). failure_reason call_error carries call_error_detail (the method raised); method_not_found means check summer_api_docs / the node's script.
+
+Calling a method is an ACTION, not evidence: probe after it (summer_game_probe) to see what it did. ${RUNNING_GAME_GATES} engine_lacks_op on an older build names the fallback; a game whose build predates the summer capture answers unsupported (no legacy fallback carries a return value).`, runtimeCallArgsSchema.shape, async (args) => withEngine(async (client) => runRuntimeOp(client, buildRuntimeCallOp(args))));
+    server.tool("summer_runtime_spawn", `Spawn a PackedScene into the RUNNING game (action:'spawn' — SpawnRuntimeScene) or free a live node (action:'free' — FreeRuntimeNode). Stage a test in seconds: drop three goblins under '/root/Main/Enemies' with props {position: 'Vector3(4, 0, -2)', health: 10}, or remove the boss to test the empty-arena path. Nothing touches the scene file.
+
+spawn returns {node: {path, class}, renamed_to?, prop_warnings[], frame} — use node.path (absolute) for follow-up set/call/probe; unknown props land in prop_warnings, they never fail the spawn. free returns {path, queued, freed}: mode 'queue_free' (default) frees at the end of the frame, so a probe on the SAME frame may still list the node — step one frame (summer_game_control action:'step') before asserting it is gone; 'free' is immediate. The scene root cannot be freed (refused_root).
+
+${LOOP}
+
+${RUNNING_GAME_GATES} engine_lacks_op on an older build names the fallback (summer_instantiate_scene / summer_remove_node in the EDITED scene, then restart).`, runtimeSpawnArgsSchema.shape, async (args) => withEngine(async (client) => runRuntimeOp(client, buildRuntimeSpawnOp(args))));
+    server.tool("summer_runtime_animate", `Drive and read animation in the RUNNING game. target:'player' = an AnimationPlayer (cmd state|play|pause|stop|seek|speed — RuntimeAnimation); target:'tree' = an AnimationTree state machine (cmd state|travel|start|stop|set_param|get_param — RuntimeAnimationTree); target:'bones' = a Skeleton3D's live bone poses (GetRuntimeBones, read-only). Default cmd is 'state' (read-only), so the same tool answers "which clip is playing", "which state is the machine in" and "where is the hand bone" before and after an action.
+
+player returns state {current_animation, assigned_animation, position, length, speed_scale, playing, animations[]}. tree returns state {active, current_node, travel_path, playing, position, length, fading_from, parameters{}}. bones returns {skeleton: {path, bone_count, motion_scale}, bones[{idx, name, parent, global_pose{origin, rotation, scale} | pose | rest}], truncated} — at most 256 bones per call; filter with bones[] to page larger rigs. unknown_animation / unknown_state / unknown_bone list the valid names in the error.
+
+Animation is motion: one 'state' read proves a clip is assigned, not that it moves. Prove motion with summer_game_control action:'step' between two reads (position advances, bone poses change) or two summer_game_probe frames. ${RUNNING_GAME_GATES} target:'bones' and cmd:'state' still answer while the game is breaked; the mutating cmds do not. engine_lacks_op on an older build names the fallback.`, runtimeAnimateArgsSchema.shape, async (args) => withEngine(async (client) => runRuntimeOp(client, buildRuntimeAnimateOp(args))));
+    server.tool("summer_game_control", `Control the clock of the RUNNING game and list instances. action:'pause' suspends it (GamePause — Engine time frozen, physics inactive; SceneTree.paused untouched), 'resume' lifts the suspension, 'step' advances EXACTLY frames (1..600) of kind 'physics' (default) or 'process' and leaves the game suspended (GameStep), 'speed' sets the user time scale (GameSpeed, 0.25 = quarter speed), 'instances' lists every live game instance (ListGameInstances: name, mode, pid, attached, breaked, scene, seed, fixed_fps, deterministic, summer_capture).
+
+Frame stepping is how you make exact assertions: pause -> summer_game_probe -> act -> step 1 -> probe; the step result reports before/after frame counters, exact, overshoot, and draws the last stepped frame before replying so the following probe shows it. A minimized game window draws no frames and cannot step (timeout). step and pause answer game_breaked while the game sits at a breakpoint. GameSpeed rides a no-reply channel: acknowledged:false means the engine could not read the new time_scale back (older game build) — verify with summer_game_probe time_scale.
+
+'instances' is also the boot check after summer_play {instance, mode:'offscreen'}: address an instance only once attached:true (before that the ops answer request_failed). ${LOOP}
+
+${RUNNING_GAME_GATES} On an engine build that predates these ops the result is a structured engine_lacks_op failure; the fallback for exact frames is a RunVerification probe awaiting physics_frame N times.`, gameControlArgsSchema.shape, async (args) => withEngine(async (client) => runRuntimeOp(client, buildGameControlOp(args))));
+    server.tool("summer_game_input", `Drive the RUNNING game's input like a player would. action:'script' schedules up to 1000 timed synthetic events (SimulateInputScript): [{at_frame: 0, type:'action', action:'move_right', hold_ms: 500}, {at_frame: 30, type:'action', action:'jump', hold_ms: 50}]; types action | key (keycode / physical_keycode) | mouse_click (position [x,y], button) | axis (action_negative/action_positive, signed strength) | raw ({class, props} — a recorded InputEvent). clock 'frame' (at_frame, exact) or 'ms' (at_ms — exact only when the instance runs with fixed_fps, else approximate; the result reports clock_mapping). action:'record_start' / 'record_stop' capture the game's REAL input into res://.summer/replays/<id>.json (InputRecordStart/Stop — cap 20,000 events / ~1 MiB, truncated:true when hit); action:'replay' plays a recording (or inline events) back (InputReplay), with seed asserting reproducibility on a deterministic offscreen instance.
+
+script returns {scheduled, applied, rejected[{index, failure_reason, error}], first_frame, last_frame, completed, clock_mapping}; per-event rejections (unknown_action: not in the project InputMap — summer_input_map_bind, or use type:'key') are non-fatal unless all_rejected. ONE script in flight per instance: a second call answers busy — wait for the first. wait:true (default) blocks until the last event fires but the engine caps it at 20 s; a longer script uses wait:false and observes with summer_game_probe. replay returns the same shape plus {recording, deterministic}; seed on an instance not started with summer_play {mode:'offscreen', deterministic:true} answers nondeterministic_instance.
+
+Scripts vs recordings: a script is the readable, editable repro you write from the spec; a recording is the exact repro of what a human (or a script) actually did — replay it on a deterministic instance for an A/B under identical inputs. Input is an ACTION: prove what it caused with summer_game_probe before/after (or summer_game_control action:'step' for the exact frame). ${LOOP}
+
+${RUNNING_GAME_GATES} engine_lacks_op on an older build names the fallback (single SimulateInput ops via summer_batch, or a RunVerification probe's press()/key()).`, gameInputArgsSchema.shape, async (args) => withEngine(async (client) => runRuntimeOp(client, buildGameInputOp(args))));
+    server.tool("summer_game_probe", `State AND pixels of ONE frame of the RUNNING game, atomically (GameProbe): the live scene tree (tree {path, depth, limit}), up to 64 property reads (props ['/root/Main/Player:position', '/root/Main/HUD/Health:value']) and a screenshot of the game viewport, all stamped with the SAME frame counters. This is the evidence tool of the playtest loop — the only read where "what the tree says" and "what the screen shows" cannot come from different moments.
+
+You SEE the screenshot as an image block; the text block carries the frame stamp ({frame: {process_frames, physics_frames, frames_drawn}, image_frame, suspended, paused, time_scale}), values {key: Godot literal string}, missing[] (keys that did not resolve — a typo or a node that is gone), tree/total_nodes/truncated. Two probes around an action are a claim's proof: cite both frame numbers. screenshot:false is the cheap state-only read (works when the window draws nothing). max_dim (default 1280) bounds the image. Unlike summer_screenshot target:'game', the capture happens game-side, so it works for offscreen and floating instances.
+
+${LOOP}
+
+${RUNNING_GAME_GATES} A probe still answers while the game is breaked. On an engine build that predates GameProbe the result is a structured engine_lacks_op failure; fall back to summer_get_runtime_tree + summer_screenshot target:'game' (two calls, two frames).`, gameProbeArgsSchema.shape, async (args) => withEngine(async (client) => runRuntimeOp(client, buildGameProbeOp(args)), {
+        toContent: (result) => {
+            const payload = findProbePayload(result);
+            const text = JSON.stringify(stripProbeImage(result), null, 2);
+            const image = payload && typeof payload.image_base64 === "string" ? payload.image_base64 : null;
+            if (!payload || !image) {
+                return [{ type: "text", text }];
+            }
+            const dims = typeof payload.width === "number" && typeof payload.height === "number"
+                ? `${payload.width}x${payload.height}`
+                : "unknown size";
+            const caption = `Game probe — ${probeFrameStamp(payload)} (${dims}). The image above and the state below describe this ONE frame; ` +
+                "review the image and describe what you actually see before claiming anything about it.\n\n" +
+                text;
+            return [
+                { type: "image", data: image, mimeType: typeof payload.mime === "string" ? payload.mime : "image/jpeg" },
+                { type: "text", text: caption },
+            ];
+        },
+    }));
+}

package/dist/mcp/tools/scene-tools.d.ts

@@ -1,2 +1,5 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { executeSceneMutation } from "../../core/capabilities/engine-ops.js";
+import { FALLBACK_SINGLE_ONLY_OPS, resolveSingleOnlyOps } from "../../core/capability-skew.js";
+export { FALLBACK_SINGLE_ONLY_OPS, resolveSingleOnlyOps, executeSceneMutation };
 export declare function registerSceneTools(server: McpServer): void;