summer-engine 3.1.0 → 3.2.0

package/dist/core/capabilities/project-context.d.ts

@@ -15,6 +15,14 @@
  * is client-side and every trim is declared (settingsTruncated, totalSettings,
  * settingsPrefixesIncluded, settingsPrefixesExcluded) — nothing is hidden,
  * only deferred behind settingsPrefixes.
+ *
+ * Compact default (the full capability lists plus a 200-node scene tree make
+ * a first call too large for a host to hand to the agent): the payload carries the
+ * project, the scene path with a one-line scene summary, a scalar health
+ * summary with capability COUNTS, projectMemory and every warning. The scene
+ * tree, the capability lists and the project settings come back only with
+ * include:['scene_tree' | 'capabilities' | 'settings']; `omitted` says how to
+ * ask for each one that was left out.
  */
 import { z } from "zod";
 import { type ProjectMemorySummary } from "../../project-memory/project-memory.js";
@@ -37,17 +45,24 @@ export declare const DEFAULT_PROJECT_CONTEXT_SETTINGS_PREFIXES: readonly string[
  */
 export declare const DEFAULT_PROJECT_CONTEXT_SETTINGS_EXCLUDED: readonly string[];
 export declare const MAX_SETTINGS_PREFIXES = 32;
+/** Heavy blocks the default (compact) payload leaves out; `include` opts in. */
+export declare const PROJECT_CONTEXT_INCLUDES: readonly ["scene_tree", "capabilities", "settings"];
+export type ProjectContextInclude = (typeof PROJECT_CONTEXT_INCLUDES)[number];
 export declare const projectContextInputShape: {
+    include: z.ZodOptional<z.ZodArray<z.ZodEnum<["scene_tree", "capabilities", "settings"]>, "many">>;
     settingsPrefix: z.ZodOptional<z.ZodString>;
     settingsPrefixes: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
 };
 export declare const projectContextInputSchema: z.ZodObject<{
+    include: z.ZodOptional<z.ZodArray<z.ZodEnum<["scene_tree", "capabilities", "settings"]>, "many">>;
     settingsPrefix: z.ZodOptional<z.ZodString>;
     settingsPrefixes: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
 }, "strict", z.ZodTypeAny, {
+    include?: ("capabilities" | "scene_tree" | "settings")[] | undefined;
     settingsPrefix?: string | undefined;
     settingsPrefixes?: string[] | undefined;
 }, {
+    include?: ("capabilities" | "scene_tree" | "settings")[] | undefined;
     settingsPrefix?: string | undefined;
     settingsPrefixes?: string[] | undefined;
 }>;
@@ -69,10 +84,18 @@ export interface ProjectContextExtras {
     onCapabilitySkew?: (warning: string) => void;
 }
 export interface ProjectContextPayload extends JsonRecord {
+    /** Compact by default (scalar fields + a capabilities summary); the full
+     *  /api/health payload with include:['capabilities']. */
     health: unknown;
     capabilitySkewWarning?: string;
-    project: unknown;
-    scene: unknown;
+    /** Project settings: only with include:['settings'] or a settings prefix. */
+    project?: unknown;
+    /** The open scene's tree: only with include:['scene_tree']. */
+    scene?: unknown;
+    /** Always: path, root node and node count of the open scene. */
+    sceneSummary: JsonRecord;
+    included: ProjectContextInclude[];
+    omitted: Partial<Record<ProjectContextInclude, string>>;
     projectName: string | null;
     projectPath: string | null;
     currentScene: string | null;
@@ -111,4 +134,12 @@ export declare function resolveProjectPath(projectState: unknown, health: unknow
 export declare function resolveProjectName(projectState: unknown, health: unknown): string | null;
 export declare function resolveMainScene(projectState: unknown): string | null;
 export declare function resolveCurrentScene(projectState: unknown, sceneState: unknown, health: unknown): string | null;
+/** Which heavy blocks the payload carries: `include`, plus 'settings' when a
+ *  settings prefix was named (asking for a group is asking for settings). */
+export declare function resolveIncludes(args: ProjectContextArgs): Set<ProjectContextInclude>;
+/** /api/health without its capability lists: every scalar field, plus counts
+ *  of what the engine advertises. */
+export declare function compactHealth(health: unknown): unknown;
+/** Path, root node and size of the open scene, from the scene-state read. */
+export declare function summarizeScene(sceneState: unknown, currentScene: string | null): JsonRecord;
 export declare function buildProjectContext(client: ProjectContextClient, args?: ProjectContextArgs, extras?: ProjectContextExtras): Promise<ProjectContextPayload>;

package/dist/core/capabilities/project-context.js

@@ -15,10 +15,18 @@
  * is client-side and every trim is declared (settingsTruncated, totalSettings,
  * settingsPrefixesIncluded, settingsPrefixesExcluded) — nothing is hidden,
  * only deferred behind settingsPrefixes.
+ *
+ * Compact default (the full capability lists plus a 200-node scene tree make
+ * a first call too large for a host to hand to the agent): the payload carries the
+ * project, the scene path with a one-line scene summary, a scalar health
+ * summary with capability COUNTS, projectMemory and every warning. The scene
+ * tree, the capability lists and the project settings come back only with
+ * include:['scene_tree' | 'capabilities' | 'settings']; `omitted` says how to
+ * ask for each one that was left out.
  */
 import { z } from "zod";
 import { EngineRebindError } from "../api-client.js";
-import { buildCapabilitySkewWarning } from "../capability-skew.js";
+import { buildCapabilitySkewWarning, parseEngineCapabilities } from "../capability-skew.js";
 import { isTrajectoryEvalMode } from "../trajectory.js";
 import { getProjectMemorySummary, } from "../../project-memory/project-memory.js";
 import { asRecord, stringFrom } from "../util/json.js";
@@ -48,8 +56,15 @@ export const DEFAULT_PROJECT_CONTEXT_SETTINGS_PREFIXES = [
  */
 export const DEFAULT_PROJECT_CONTEXT_SETTINGS_EXCLUDED = ["input/ui_"];
 export const MAX_SETTINGS_PREFIXES = 32;
+/** Heavy blocks the default (compact) payload leaves out; `include` opts in. */
+export const PROJECT_CONTEXT_INCLUDES = ["scene_tree", "capabilities", "settings"];
 // Mirrors library/tools/get-project-context/resource.yaml input_schema (parity-tested).
 export const projectContextInputShape = {
+    include: z
+        .array(z.enum(PROJECT_CONTEXT_INCLUDES))
+        .max(PROJECT_CONTEXT_INCLUDES.length)
+        .optional()
+        .describe("Heavy blocks to add to the compact default: 'scene_tree' (the open scene's node tree, up to 200 nodes), 'capabilities' (the engine's full op/capability lists), 'settings' (project settings, curated groups). settingsPrefix/settingsPrefixes imply 'settings'."),
     settingsPrefix: z
         .string()
         .optional()
@@ -183,9 +198,68 @@ export function resolveCurrentScene(projectState, sceneState, health) {
         pickString(asRecord(health), ["scene", "scenePath", "scene_path"]) ??
         null);
 }
+// ── Compact blocks ─────────────────────────────────────────────────────────
+/** Which heavy blocks the payload carries: `include`, plus 'settings' when a
+ *  settings prefix was named (asking for a group is asking for settings). */
+export function resolveIncludes(args) {
+    const included = new Set(args.include ?? []);
+    if (resolveSettingsSelection(args).explicit)
+        included.add("settings");
+    return included;
+}
+/** /api/health without its capability lists: every scalar field, plus counts
+ *  of what the engine advertises. */
+export function compactHealth(health) {
+    const root = asRecord(health);
+    if (!root)
+        return health;
+    const out = {};
+    for (const [key, value] of Object.entries(root)) {
+        if (value === null || ["string", "number", "boolean"].includes(typeof value))
+            out[key] = value;
+    }
+    if ("capabilities" in root) {
+        const caps = parseEngineCapabilities(root.capabilities);
+        out.capabilities = caps
+            ? {
+                ...(caps.protocolVersion !== undefined ? { protocolVersion: caps.protocolVersion } : {}),
+                ...(caps.opKinds ? { opKinds: caps.opKinds.length } : {}),
+                ...(caps.singleOnlyOps ? { singleOnlyOps: caps.singleOnlyOps.length } : {}),
+                events: !!caps.events,
+                runtimeControl: !!caps.runtimeControl,
+                ...(caps.navigation ? { navigationTargets: caps.navigation.targets.length } : {}),
+                ...(caps.launchPostures ? { launchPostures: caps.launchPostures } : {}),
+                summary: "counts only; include:['capabilities'] returns the lists",
+            }
+            : { summary: "the engine advertised no readable capabilities" };
+    }
+    return out;
+}
+/** Path, root node and size of the open scene, from the scene-state read. */
+export function summarizeScene(sceneState, currentScene) {
+    const root = asRecord(sceneState);
+    if (!root || root.ok === false) {
+        return { scenePath: currentScene, ...(root?.error ? { error: String(root.error) } : {}) };
+    }
+    const data = asRecord(root.data);
+    const children = Array.isArray(data?.children) ? data.children.length : undefined;
+    return {
+        scenePath: currentScene,
+        ...(typeof data?.name === "string" ? { rootName: data.name } : {}),
+        ...(typeof data?.class === "string" ? { rootClass: data.class } : {}),
+        ...(typeof data?.total_nodes === "number" ? { totalNodes: data.total_nodes } : {}),
+        ...(children !== undefined ? { topLevelChildren: children } : {}),
+    };
+}
+const OMITTED_HINTS = {
+    scene_tree: "include:['scene_tree'] for the open scene's tree (up to 200 nodes); for one subtree use summer_world_snapshot path_prefix or summer_get_scene_tree",
+    capabilities: "include:['capabilities'] for the engine's full op and capability lists",
+    settings: "include:['settings'] (curated groups) or settingsPrefixes:['audio/', ...] for project settings",
+};
 // ── The builder ────────────────────────────────────────────────────────────
 export async function buildProjectContext(client, args = {}, extras = {}) {
     const selection = resolveSettingsSelection(args);
+    const included = resolveIncludes(args);
     const [health, fullProjectState, sceneState] = await Promise.all([
         client.health(),
         // ?prefix= rides along for forward-compatibility (a single prefix is all
@@ -224,11 +298,20 @@ export async function buildProjectContext(client, args = {}, extras = {}) {
     const capabilitySkewWarning = buildCapabilitySkewWarning(health);
     if (capabilitySkewWarning)
         extras.onCapabilitySkew?.(capabilitySkewWarning);
+    const includedList = PROJECT_CONTEXT_INCLUDES.filter((block) => included.has(block));
+    const omitted = {};
+    for (const block of PROJECT_CONTEXT_INCLUDES) {
+        if (!included.has(block))
+            omitted[block] = OMITTED_HINTS[block];
+    }
     return {
-        health,
+        health: included.has("capabilities") ? health : compactHealth(health),
         ...(capabilitySkewWarning ? { capabilitySkewWarning } : {}),
-        project,
-        scene: sceneState,
+        ...(included.has("settings") ? { project } : {}),
+        ...(included.has("scene_tree") ? { scene: sceneState } : {}),
+        sceneSummary: summarizeScene(sceneState, currentScene),
+        included: includedList,
+        omitted,
         projectName,
         projectPath,
         currentScene,

package/dist/core/capabilities/replace-node.d.ts

@@ -0,0 +1,91 @@
+/**
+ * replace-node — ONE implementation of `summer_replace_node` for both faces
+ * (src/mcp/tools/scene-tools.ts and tool-dispatch.ts), built from ops whose
+ * results persist, and verified against the SAVED scene file.
+ *
+ * Why not the engine's ReplaceNode op for scenes: SceneOps::replace_node
+ * (engine modules/1summer_engine/editor/ops/scene_ops.cpp, scene branch and
+ * the async _finish_replace_node) instantiates the new PackedScene and hands
+ * it to SceneTreeDock::replace_node — the editor's "Change Type" path — which
+ * ends in Node::replace_by (scene/main/node.cpp). replace_by finishes with
+ * `p_node->set_scene_file_path(get_scene_file_path())`: the new instance is
+ * stamped with the OLD node's scene path. The editor draws the new subtree,
+ * the receipt says ok, and SaveScene packs the node as
+ * `instance=ExtResource(<old scene>)` with a fresh unique_id — the change is
+ * gone on reload. A plain
+ * node replaced by a scene loses the other way (scene_file_path cleared, the
+ * instance's children owned by the instance root and dropped on save), and a
+ * type change of an instanced node stays an instance of the old scene.
+ *
+ * So the scene branch (and a type change of an instanced node) runs as:
+ *   0. SaveScene, so the file on disk is exactly the editor state;
+ *   1. read + parse the saved .tscn (which children the scene added under the
+ *      node, which properties it overrides, its sibling index);
+ *   2. InstantiateScene / AddNode at the same parent under a temporary name;
+ *   3. SetProp every copyable property override (transform, visibility, ...);
+ *   4. ReparentNode each scene-added child onto the new node (local
+ *      transforms kept), then re-parent each deeper scene-added descendant in
+ *      place — the engine's ReparentNode re-owns only the node it moves, and
+ *      remove_child clears the owner of everything below it;
+ *   5. MoveNode to the old sibling index, RemoveNode the old node, SetProp
+ *      name back to the original name;
+ *   6. SaveScene, read the file back and check it: the node at the path
+ *      instances the new scene (or has the new type), the parent and every
+ *      scene-added descendant are there. persisted:false is reported as a
+ *      failure, never as success.
+ * A type change of a plain node keeps the engine's ReplaceNode (it persists:
+ * replace_by copies an empty scene path) and gets the same read-back check.
+ */
+import { z } from "zod";
+import { type CapabilityAdvertisingClient } from "../capability-skew.js";
+import { type JsonRecord } from "../util/json.js";
+import { type ParsedTscn, type TscnProp } from "./tscn.js";
+export declare const replaceNodeInputShape: {
+    scenePath: z.ZodString;
+    path: z.ZodString;
+    type: z.ZodOptional<z.ZodString>;
+    scene: z.ZodOptional<z.ZodString>;
+};
+export declare const replaceNodeInputSchema: z.ZodObject<{
+    scenePath: z.ZodString;
+    path: z.ZodString;
+    type: z.ZodOptional<z.ZodString>;
+    scene: z.ZodOptional<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    path: string;
+    scenePath: string;
+    type?: string | undefined;
+    scene?: string | undefined;
+}, {
+    path: string;
+    scenePath: string;
+    type?: string | undefined;
+    scene?: string | undefined;
+}>;
+export type ReplaceNodeArgs = z.infer<typeof replaceNodeInputSchema>;
+/** The engine reads the replacement needs — a structural subset of
+ *  EngineApiClient so tests can hand in a fake engine. */
+export interface ReplaceNodeClient extends CapabilityAdvertisingClient {
+    executeIdentityBoundOps(ops: Record<string, unknown>[], options?: Record<string, unknown>, timeoutMs?: number): Promise<unknown>;
+    readProjectFile(path: string, maxBytes?: number): Promise<unknown>;
+    getSceneState(scenePath?: string, options?: {
+        depth?: number;
+        limit?: number;
+        root?: string;
+    }): Promise<unknown>;
+}
+/** A property override as a SetProp value, or why it cannot be copied. */
+export declare function propSetValue(prop: TscnProp, parsed: ParsedTscn): {
+    value: string | number | boolean;
+} | {
+    reason: string;
+};
+/** summer_batch guard (both faces): a raw ReplaceNode with `scene` is the op
+ *  that saves the OLD scene reference. Refuse it before anything is sent and
+ *  point at the tool that persists. Null when the ops are fine. */
+export declare function rawSceneReplaceRefusal(ops: ReadonlyArray<Record<string, unknown>>): string | null;
+/**
+ * Replace the node at `path` in `scenePath` with `scene` (or a node of
+ * `type`) and prove the saved file holds the result.
+ */
+export declare function replaceNodePersisted(client: ReplaceNodeClient, args: ReplaceNodeArgs): Promise<JsonRecord>;