summer-engine 2.8.1 → 3.0.0

package/dist/core/capabilities/scene-kind.d.ts

@@ -0,0 +1,19 @@
+export type SceneKind = "3d" | "2d" | "none" | "unknown";
+export interface SceneKindResult {
+    kind: SceneKind;
+    /** Why the kind is unknown (tree unreadable) — omitted otherwise. */
+    reason?: string;
+    /** Distinct node classes seen in the tree walk. */
+    classesSeen?: number;
+    /** The tree read declared itself truncated (depth/limit hit). */
+    truncated?: boolean;
+}
+export declare function isNode3DClass(className: string): boolean;
+export declare function isCanvasItemClass(className: string): boolean;
+/**
+ * Classify a scene-tree read (`/api/state/scene`, summer_get_scene_tree) into
+ * 3d / 2d / none, or unknown when the payload carries no tree.
+ */
+export declare function classifySceneKindFromTree(sceneState: unknown): SceneKindResult;
+/** Test seam: forget cached ancestry (after resetApiDocsForTests). */
+export declare function resetSceneKindCacheForTests(): void;

package/dist/core/capabilities/scene-kind.js

@@ -0,0 +1,137 @@
+/**
+ * Is a scene 2D or 3D? Decided from a scene-tree read, the way the engine's
+ * ScenePreview decides it (preview_ops.cpp `_scene_has_3d` / `_scene_has_2d`):
+ * any Node3D anywhere in the tree makes the scene 3D; otherwise any CanvasItem
+ * makes it 2D; a tree of plain Nodes is neither.
+ *
+ * Needed because the ScenePreview receipt reports `scene_has_camera` for BOTH
+ * kinds (Camera3D in 3D scenes, Camera2D in 2D scenes) but never says which
+ * kind it rendered, and the toolkit used to turn every `scene_has_camera:false`
+ * into "no Camera3D — will render grey/black when played" (E2E 2026-09-03
+ * F-05: false on a 2D room that played fine).
+ *
+ * Class ancestry comes from the bundled offline class reference
+ * (assets/api-docs.json.gz, `inherits` chain) when it is installed; without it
+ * a suffix heuristic plus the short list of Node3D subclasses that lack the
+ * "3D" suffix is used. Either way an unknown class (plugin/custom) counts as
+ * neither kind, so the failure direction is "no warning", never a false one.
+ */
+import { isApiDocsBundleInstalled, lookupApiDocs } from "./api-docs.js";
+/** Node3D subclasses in Godot 4.7 whose names do not end in "3D" (from the
+ *  bundled class reference). Fallback for installs without api-docs. */
+const NODE3D_WITHOUT_SUFFIX = new Set([
+    "Decal",
+    "FogVolume",
+    "GridMap",
+    "LightmapGI",
+    "LightmapProbe",
+    "OpenXRCompositionLayer",
+    "OpenXRCompositionLayerCylinder",
+    "OpenXRCompositionLayerEquirect",
+    "OpenXRCompositionLayerQuad",
+    "OpenXRHand",
+    "OpenXRRenderModel",
+    "OpenXRRenderModelManager",
+    "OpenXRVisibilityMask",
+    "ReflectionProbe",
+    "RootMotionView",
+    "VoxelGI",
+]);
+const ancestryCache = new Map();
+/** Ancestor chain of a native class from the offline class reference, or null
+ *  when the bundle is missing or does not know the class. */
+function ancestry(className) {
+    if (!isApiDocsBundleInstalled())
+        return null;
+    const cached = ancestryCache.get(className);
+    if (cached)
+        return cached;
+    const chain = [];
+    let current = className;
+    let guard = 0;
+    while (current && guard++ < 32) {
+        const entry = lookupApiDocs(current);
+        if (entry.ok === false || typeof entry !== "object")
+            return null;
+        chain.push(typeof entry.class === "string" ? entry.class : current);
+        current = typeof entry.inherits === "string" ? entry.inherits : null;
+    }
+    ancestryCache.set(className, chain);
+    return chain;
+}
+export function isNode3DClass(className) {
+    const chain = ancestry(className);
+    if (chain)
+        return chain.includes("Node3D");
+    return /3D$/.test(className) || NODE3D_WITHOUT_SUFFIX.has(className);
+}
+export function isCanvasItemClass(className) {
+    const chain = ancestry(className);
+    if (chain)
+        return chain.includes("CanvasItem");
+    return /2D$/.test(className) || isCanvasLikeName(className);
+}
+/** Common Control/CanvasItem classes without a 2D suffix — heuristic only. */
+function isCanvasLikeName(className) {
+    return /^(Control|Container|Label|RichTextLabel|Button|TextureButton|CheckBox|CheckButton|OptionButton|MenuButton|LinkButton|Panel|PanelContainer|MarginContainer|VBoxContainer|HBoxContainer|GridContainer|CenterContainer|ScrollContainer|TabContainer|TextureRect|ColorRect|NinePatchRect|ProgressBar|TextureProgressBar|HSlider|VSlider|SpinBox|LineEdit|TextEdit|CodeEdit|ItemList|Tree|Popup|PopupMenu|PopupPanel|Window|SubViewportContainer|GraphEdit|GraphNode|VideoStreamPlayer|Range|BaseButton|Separator|HSeparator|VSeparator|SplitContainer|HSplitContainer|VSplitContainer|FlowContainer|HFlowContainer|VFlowContainer|AspectRatioContainer|ReferenceRect|MenuBar|TabBar|ScrollBar|HScrollBar|VScrollBar|ColorPicker|ColorPickerButton|FileDialog|AcceptDialog|ConfirmationDialog)$/.test(className);
+}
+function collectClasses(node, out, budget) {
+    if (!node || typeof node !== "object" || budget.left <= 0)
+        return;
+    budget.left -= 1;
+    const record = node;
+    if (typeof record.class === "string" && record.class)
+        out.add(record.class);
+    if (Array.isArray(record.children)) {
+        for (const child of record.children)
+            collectClasses(child, out, budget);
+    }
+}
+/** Find the tree root inside a scene-state envelope ({data:{name,class,children}}
+ *  or the node itself). */
+function findTreeRoot(sceneState) {
+    if (!sceneState || typeof sceneState !== "object")
+        return null;
+    const record = sceneState;
+    if (typeof record.class === "string" && ("children" in record || "name" in record))
+        return record;
+    for (const key of ["data", "tree", "scene", "root"]) {
+        const inner = record[key];
+        if (inner && typeof inner === "object") {
+            const found = findTreeRoot(inner);
+            if (found)
+                return found;
+        }
+    }
+    return null;
+}
+/**
+ * Classify a scene-tree read (`/api/state/scene`, summer_get_scene_tree) into
+ * 3d / 2d / none, or unknown when the payload carries no tree.
+ */
+export function classifySceneKindFromTree(sceneState) {
+    const root = findTreeRoot(sceneState);
+    if (!root) {
+        const record = sceneState && typeof sceneState === "object" ? sceneState : null;
+        const error = record && typeof record.error === "string" ? record.error : "scene tree read returned no tree";
+        return { kind: "unknown", reason: error };
+    }
+    const classes = new Set();
+    collectClasses(root, classes, { left: 5000 });
+    const envelope = sceneState;
+    const truncated = envelope.truncated === true || envelope.data?.truncated === true;
+    let has3d = false;
+    let has2d = false;
+    for (const cls of classes) {
+        if (isNode3DClass(cls))
+            has3d = true;
+        else if (isCanvasItemClass(cls))
+            has2d = true;
+    }
+    const kind = has3d ? "3d" : has2d ? "2d" : "none";
+    return { kind, classesSeen: classes.size, ...(truncated ? { truncated: true } : {}) };
+}
+/** Test seam: forget cached ancestry (after resetApiDocsForTests). */
+export function resetSceneKindCacheForTests() {
+    ancestryCache.clear();
+}

package/dist/core/capabilities/scene-script.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Scene-scripting op builders (tool/run-script, tool/run-editor-script).
+ * Shared by the MCP tools and the CLI dispatcher so both surfaces send the
+ * same op with the same clamps and the same client poll budget.
+ *
+ * Server-side clamps: RunSceneScript blocks between frames of the LIVE editor,
+ * so its ceiling is deliberately low; RunEditorScript boots a whole headless
+ * child editor, so its floor covers the boot cost (editor_script_ops.cpp:
+ * 15..600 default 120).
+ */
+export declare const SCENE_SCRIPT_MIN_SECONDS = 5;
+export declare const SCENE_SCRIPT_MAX_SECONDS = 120;
+export declare const SCENE_SCRIPT_DEFAULT_SECONDS = 20;
+export declare const EDITOR_SCRIPT_MIN_SECONDS = 15;
+export declare const EDITOR_SCRIPT_MAX_SECONDS = 600;
+export declare const EDITOR_SCRIPT_DEFAULT_SECONDS = 120;
+/** What each tool tells the model to do when the engine lacks its op. */
+export declare const RUN_SCRIPT_FALLBACK = "use summer_run_editor_script (a headless child editor against the ON-DISK project) for the same work";
+export declare const RUN_EDITOR_SCRIPT_FALLBACK = "run the script from a shell with the engine binary --headless --script (see the headless-scripting skill)";
+export interface RunSceneScriptArgs {
+    source: string;
+    max_seconds?: number;
+    checkpoint?: boolean;
+    undo?: "action" | "none";
+}
+export interface RunEditorScriptArgs {
+    source: string;
+    max_seconds?: number;
+    checkpoint?: boolean;
+}
+export interface BuiltScriptOp {
+    op: Record<string, unknown>;
+    /** Client poll budget — MUST outlive the engine's own max_seconds, or a
+     *  long-but-successful run is reported as timed_out client-side. */
+    timeoutMs: number;
+}
+export declare function buildRunSceneScriptOp(args: RunSceneScriptArgs): BuiltScriptOp;
+export declare function buildRunEditorScriptOp(args: RunEditorScriptArgs): BuiltScriptOp;

package/dist/core/capabilities/scene-script.js

@@ -0,0 +1,45 @@
+/**
+ * Scene-scripting op builders (tool/run-script, tool/run-editor-script).
+ * Shared by the MCP tools and the CLI dispatcher so both surfaces send the
+ * same op with the same clamps and the same client poll budget.
+ *
+ * Server-side clamps: RunSceneScript blocks between frames of the LIVE editor,
+ * so its ceiling is deliberately low; RunEditorScript boots a whole headless
+ * child editor, so its floor covers the boot cost (editor_script_ops.cpp:
+ * 15..600 default 120).
+ */
+export const SCENE_SCRIPT_MIN_SECONDS = 5;
+export const SCENE_SCRIPT_MAX_SECONDS = 120;
+export const SCENE_SCRIPT_DEFAULT_SECONDS = 20;
+export const EDITOR_SCRIPT_MIN_SECONDS = 15;
+export const EDITOR_SCRIPT_MAX_SECONDS = 600;
+export const EDITOR_SCRIPT_DEFAULT_SECONDS = 120;
+/** What each tool tells the model to do when the engine lacks its op. */
+export const RUN_SCRIPT_FALLBACK = "use summer_run_editor_script (a headless child editor against the ON-DISK project) for the same work";
+export const RUN_EDITOR_SCRIPT_FALLBACK = "run the script from a shell with the engine binary --headless --script (see the headless-scripting skill)";
+function clamp(value, min, max) {
+    return Math.min(max, Math.max(min, Math.round(value)));
+}
+export function buildRunSceneScriptOp(args) {
+    const budgetSeconds = clamp(args.max_seconds ?? SCENE_SCRIPT_DEFAULT_SECONDS, SCENE_SCRIPT_MIN_SECONDS, SCENE_SCRIPT_MAX_SECONDS);
+    const op = {
+        op: "RunSceneScript",
+        script_source: args.source,
+        max_seconds: budgetSeconds,
+        checkpoint: args.checkpoint ?? true,
+    };
+    if (args.undo)
+        op.undo = args.undo;
+    return { op, timeoutMs: budgetSeconds * 1000 + 30_000 };
+}
+export function buildRunEditorScriptOp(args) {
+    const budgetSeconds = clamp(args.max_seconds ?? EDITOR_SCRIPT_DEFAULT_SECONDS, EDITOR_SCRIPT_MIN_SECONDS, EDITOR_SCRIPT_MAX_SECONDS);
+    const op = {
+        op: "RunEditorScript",
+        script_source: args.source,
+        max_seconds: budgetSeconds,
+    };
+    if (args.checkpoint !== undefined)
+        op.checkpoint = args.checkpoint;
+    return { op, timeoutMs: budgetSeconds * 1000 + 60_000 };
+}

package/dist/core/capabilities/tool-dispatch.d.ts

@@ -0,0 +1,42 @@
+import { EngineApiClient } from "../api-client.js";
+export type DispatchArgs = Record<string, unknown>;
+export interface ToolDispatchContext {
+    /** Lazily connect to the local engine. Throws EngineUnavailableError with a
+     *  clean, actionable message when the engine is not running. */
+    engine(): Promise<EngineApiClient>;
+}
+export interface ToolDispatchEntry {
+    /** Canonical MCP tool name, e.g. "summer_add_node". */
+    name: string;
+    /** Library slug (tool/<slug>), e.g. "add-node". */
+    slug: string;
+    /** One-line summary for --list. */
+    summary: string;
+    /** True when the tool needs the local Summer Engine running. */
+    engineRequired: boolean;
+    handler(args: DispatchArgs, ctx: ToolDispatchContext): Promise<unknown>;
+}
+/** Dispatch-level failure with a user-facing message (no stack needed). */
+export declare class ToolDispatchError extends Error {
+}
+/** The local engine is not reachable — a clean state, not a crash. */
+export declare class EngineUnavailableError extends ToolDispatchError {
+}
+/** A tool failed with a structured receipt that `summer tool` prints whole
+ *  (JSON on stdout, exit 1) instead of flattening to `message`: every engine
+ *  envelope extractOpError reads as a failure (the same gate the MCP face
+ *  applies in withEngine before setting isError), the engine_lacks_op result
+ *  from the capability pre-flight (nothing sent) and from the post-hoc
+ *  unknown-op rewrite (requireSupportedOp), and the not-found/ambiguous
+ *  results of the library and navigation tools. */
+export declare class ToolResultError extends ToolDispatchError {
+    readonly result: Record<string, unknown>;
+    constructor(result: Record<string, unknown>, message: string);
+}
+export declare function createDefaultDispatchContext(): ToolDispatchContext;
+export declare const TOOL_DISPATCH: readonly ToolDispatchEntry[];
+export declare function listToolDispatches(): readonly ToolDispatchEntry[];
+/** Resolve by library slug ("add-node"), MCP name ("summer_add_node"), or the
+ *  underscore-less mixed forms users type ("add_node", "summer-add-node"). */
+export declare function resolveToolDispatch(nameOrSlug: string): ToolDispatchEntry | null;
+export declare function dispatchTool(nameOrSlug: string, args: DispatchArgs, ctx?: ToolDispatchContext): Promise<unknown>;