summer-engine 3.0.0 → 3.2.0

package/dist/core/capabilities/tscn.js

@@ -0,0 +1,391 @@
+/**
+ * tscn — a small reader for the Godot text scene format (`.tscn`, format 3),
+ * enough to answer "what did the editor actually SAVE": which ext_resources
+ * the file references, every [node] entry (name, parent, type/instance,
+ * groups, its property overrides as raw text), [connection] and [editable]
+ * entries.
+ *
+ * Used by summer_replace_node to read the scene before a replacement (which
+ * children the user added under the node, which properties it overrides) and
+ * to verify afterwards that the saved file really references the new scene.
+ * Property values stay raw Godot literal text; nothing here evaluates them.
+ */
+/** Advance bracket depth / string state over `text`. */
+function scanDepth(text, state) {
+    let { depth, inString, escape } = state;
+    for (const ch of text) {
+        if (inString) {
+            if (escape)
+                escape = false;
+            else if (ch === "\\")
+                escape = true;
+            else if (ch === '"')
+                inString = false;
+            continue;
+        }
+        if (ch === '"')
+            inString = true;
+        else if (ch === "(" || ch === "[" || ch === "{")
+            depth++;
+        else if (ch === ")" || ch === "]" || ch === "}")
+            depth--;
+    }
+    // A newline inside a string keeps the string open; an escape never spans lines.
+    return { depth, inString, escape: false };
+}
+/** Decode a Godot quoted string body (without the quotes). */
+export function decodeGodotString(body) {
+    let out = "";
+    for (let i = 0; i < body.length; i++) {
+        const ch = body[i];
+        if (ch !== "\\" || i === body.length - 1) {
+            out += ch;
+            continue;
+        }
+        const next = body[++i];
+        switch (next) {
+            case "n":
+                out += "\n";
+                break;
+            case "t":
+                out += "\t";
+                break;
+            case "r":
+                out += "\r";
+                break;
+            case "b":
+                out += "\b";
+                break;
+            case "f":
+                out += "\f";
+                break;
+            case "u": {
+                const hex = body.slice(i + 1, i + 5);
+                if (/^[0-9a-fA-F]{4}$/.test(hex)) {
+                    out += String.fromCharCode(Number.parseInt(hex, 16));
+                    i += 4;
+                }
+                else {
+                    out += "u";
+                }
+                break;
+            }
+            default: out += next;
+        }
+    }
+    return out;
+}
+/** If `raw` is exactly one quoted string literal (optionally prefixed with
+ *  & for StringName or ^ for NodePath), its decoded text; else undefined. */
+export function quotedLiteral(raw) {
+    const text = raw.trim();
+    const body = text.startsWith("&\"") || text.startsWith("^\"") ? text.slice(1) : text;
+    if (body.length < 2 || !body.startsWith('"') || !body.endsWith('"'))
+        return undefined;
+    const inner = body.slice(1, -1);
+    // Reject `"a" + "b"`-like shapes: an unescaped quote inside means two literals.
+    let escape = false;
+    for (const ch of inner) {
+        if (escape) {
+            escape = false;
+            continue;
+        }
+        if (ch === "\\") {
+            escape = true;
+            continue;
+        }
+        if (ch === '"')
+            return undefined;
+    }
+    return decodeGodotString(inner);
+}
+/** Split a tag body (`name a=1 b="x y" c=ExtResource("1")`) into its name
+ *  and attribute map (raw value text). */
+function parseTag(line) {
+    const trimmed = line.trim();
+    if (!trimmed.startsWith("[") || !trimmed.endsWith("]"))
+        return null;
+    const body = trimmed.slice(1, -1);
+    const nameMatch = /^([A-Za-z_][A-Za-z0-9_]*)/.exec(body);
+    if (!nameMatch)
+        return null;
+    const attrs = new Map();
+    let i = nameMatch[1].length;
+    while (i < body.length) {
+        while (i < body.length && /\s/.test(body[i]))
+            i++;
+        if (i >= body.length)
+            break;
+        const keyMatch = /^([A-Za-z_][A-Za-z0-9_]*)=/.exec(body.slice(i));
+        if (!keyMatch)
+            break;
+        const key = keyMatch[1];
+        i += keyMatch[0].length;
+        const start = i;
+        let depth = 0;
+        let inString = false;
+        while (i < body.length) {
+            const ch = body[i];
+            if (inString) {
+                if (ch === "\\") {
+                    i += 2; // the escaped character belongs to the string
+                    continue;
+                }
+                if (ch === '"')
+                    inString = false;
+                i++;
+                continue;
+            }
+            if (depth === 0 && /\s/.test(ch))
+                break;
+            if (ch === '"')
+                inString = true;
+            else if (ch === "(" || ch === "[" || ch === "{")
+                depth++;
+            else if (ch === ")" || ch === "]" || ch === "}")
+                depth--;
+            i++;
+        }
+        attrs.set(key, body.slice(start, Math.min(i, body.length)));
+    }
+    return { tag: nameMatch[1], attrs };
+}
+function attrString(attrs, key) {
+    const raw = attrs.get(key);
+    if (raw === undefined)
+        return undefined;
+    return quotedLiteral(raw) ?? raw;
+}
+/** `ExtResource("1_ab")` / `ExtResource( 1 )` -> "1_ab" / "1". */
+export function extResourceId(raw) {
+    if (!raw)
+        return undefined;
+    const match = /^ExtResource\(\s*(?:"((?:[^"\\]|\\.)*)"|([^)\s]+))\s*\)$/.exec(raw.trim());
+    if (!match)
+        return undefined;
+    return match[1] !== undefined ? decodeGodotString(match[1]) : match[2];
+}
+/** `SubResource("Box_x")` -> "Box_x". */
+export function subResourceId(raw) {
+    const match = /^SubResource\(\s*(?:"((?:[^"\\]|\\.)*)"|([^)\s]+))\s*\)$/.exec(raw.trim());
+    if (!match)
+        return undefined;
+    return match[1] !== undefined ? decodeGodotString(match[1]) : match[2];
+}
+function parseStringArray(raw) {
+    if (!raw)
+        return [];
+    const out = [];
+    const pattern = /[&^]?"((?:[^"\\]|\\.)*)"/g;
+    for (const match of raw.matchAll(pattern))
+        out.push(decodeGodotString(match[1]));
+    return out;
+}
+/** A property line `key = value` (key may be a quoted string). */
+function parsePropStart(line) {
+    if (line.startsWith('"')) {
+        let i = 1;
+        let escape = false;
+        for (; i < line.length; i++) {
+            const ch = line[i];
+            if (escape) {
+                escape = false;
+                continue;
+            }
+            if (ch === "\\") {
+                escape = true;
+                continue;
+            }
+            if (ch === '"')
+                break;
+        }
+        const rest = line.slice(i + 1);
+        const eq = /^\s*=\s?/.exec(rest);
+        if (!eq)
+            return null;
+        return { key: decodeGodotString(line.slice(1, i)), value: rest.slice(eq[0].length) };
+    }
+    const match = /^([^\s=]+)\s*=\s?(.*)$/s.exec(line);
+    if (!match)
+        return null;
+    return { key: match[1], value: match[2] };
+}
+// ---------------------------------------------------------------------------
+// Paths
+// ---------------------------------------------------------------------------
+/** Normalize a scene-relative node path the way the engine resolves it:
+ *  "", ".", "./" and "/" are the root (returned as "."); a leading "./" is
+ *  dropped; trailing slashes are dropped. */
+export function normalizeNodePath(path) {
+    let p = path.trim().replace(/\\/g, "/");
+    if (p === "" || p === "." || p === "./" || p === "/")
+        return ".";
+    while (p.startsWith("./"))
+        p = p.slice(2);
+    p = p.replace(/\/+$/, "");
+    return p === "" ? "." : p;
+}
+/** Join a parent path ("." or "A/B") and a child name. */
+export function joinNodePath(parent, name) {
+    return parent === "." ? name : `${parent}/${name}`;
+}
+/** Parent of a normalized path ("A/B" -> "A", "A" -> "."). The root has none. */
+export function parentNodePath(path) {
+    if (path === ".")
+        return null;
+    const slash = path.lastIndexOf("/");
+    return slash < 0 ? "." : path.slice(0, slash);
+}
+/** True when `path` is `ancestor` or below it. */
+export function isAtOrBelow(path, ancestor) {
+    if (ancestor === ".")
+        return true;
+    return path === ancestor || path.startsWith(`${ancestor}/`);
+}
+// ---------------------------------------------------------------------------
+// Parser
+// ---------------------------------------------------------------------------
+export function parseTscn(text) {
+    const extResources = new Map();
+    const nodes = [];
+    const connections = [];
+    const editable = [];
+    let format;
+    let currentNode = null;
+    let pending = null;
+    const finishPending = () => {
+        if (pending && currentNode)
+            currentNode.props.push({ key: pending.key, value: pending.value });
+        pending = null;
+    };
+    const lines = text.replace(/\r\n?/g, "\n").split("\n");
+    for (const line of lines) {
+        if (pending) {
+            pending.value += `\n${line}`;
+            pending.state = scanDepth(`\n${line}`, pending.state);
+            if (pending.state.depth <= 0 && !pending.state.inString)
+                finishPending();
+            continue;
+        }
+        if (line.startsWith("[")) {
+            const tag = parseTag(line);
+            currentNode = null;
+            if (!tag)
+                continue;
+            const { attrs } = tag;
+            switch (tag.tag) {
+                case "gd_scene":
+                case "gd_resource": {
+                    const raw = attrs.get("format");
+                    if (raw && /^\d+$/.test(raw))
+                        format = Number(raw);
+                    break;
+                }
+                case "ext_resource": {
+                    const id = attrString(attrs, "id");
+                    if (id !== undefined) {
+                        extResources.set(id, {
+                            id,
+                            type: attrString(attrs, "type"),
+                            path: attrString(attrs, "path"),
+                            uid: attrString(attrs, "uid"),
+                        });
+                    }
+                    break;
+                }
+                case "node": {
+                    const name = attrString(attrs, "name") ?? "";
+                    const parentRaw = attrString(attrs, "parent");
+                    const parent = parentRaw === undefined ? null : normalizeNodePath(parentRaw);
+                    const instance = extResourceId(attrs.get("instance"));
+                    const indexRaw = attrString(attrs, "index");
+                    const node = {
+                        name,
+                        path: parent === null ? "." : joinNodePath(parent, name),
+                        parent,
+                        groups: parseStringArray(attrs.get("groups")),
+                        props: [],
+                        order: nodes.length,
+                    };
+                    const type = attrString(attrs, "type");
+                    if (type !== undefined)
+                        node.type = type;
+                    if (instance !== undefined) {
+                        node.instance = instance;
+                        const resolved = extResources.get(instance)?.path;
+                        if (resolved)
+                            node.instancePath = resolved;
+                    }
+                    const placeholder = attrString(attrs, "instance_placeholder");
+                    if (placeholder !== undefined)
+                        node.instancePlaceholder = placeholder;
+                    if (indexRaw !== undefined && /^-?\d+$/.test(indexRaw))
+                        node.index = Number(indexRaw);
+                    nodes.push(node);
+                    currentNode = node;
+                    break;
+                }
+                case "connection": {
+                    const flagsRaw = attrs.get("flags");
+                    connections.push({
+                        signal: attrString(attrs, "signal") ?? "",
+                        from: normalizeNodePath(attrString(attrs, "from") ?? "."),
+                        to: normalizeNodePath(attrString(attrs, "to") ?? "."),
+                        method: attrString(attrs, "method") ?? "",
+                        ...(flagsRaw && /^\d+$/.test(flagsRaw) ? { flags: Number(flagsRaw) } : {}),
+                        raw: line.trim(),
+                    });
+                    break;
+                }
+                case "editable": {
+                    const path = attrString(attrs, "path");
+                    if (path !== undefined)
+                        editable.push(normalizeNodePath(path));
+                    break;
+                }
+                default:
+                    // sub_resource / resource bodies are not needed; their property
+                    // lines are skipped because currentNode is null.
+                    break;
+            }
+            continue;
+        }
+        if (!currentNode || line.trim() === "")
+            continue;
+        const prop = parsePropStart(line);
+        if (!prop)
+            continue;
+        const state = scanDepth(prop.value, { depth: 0, inString: false, escape: false });
+        if (state.depth > 0 || state.inString) {
+            pending = { key: prop.key, value: prop.value, state };
+        }
+        else {
+            currentNode.props.push({ key: prop.key, value: prop.value });
+        }
+    }
+    finishPending();
+    // An ext_resource listed after the node that uses it (never written by the
+    // editor, but cheap to tolerate).
+    for (const node of nodes) {
+        if (node.instance && !node.instancePath) {
+            const resolved = extResources.get(node.instance)?.path;
+            if (resolved)
+                node.instancePath = resolved;
+        }
+    }
+    return { ...(format !== undefined ? { format } : {}), extResources, nodes, connections, editable };
+}
+export function findTscnNode(parsed, path) {
+    const target = normalizeNodePath(path);
+    return parsed.nodes.find((node) => node.path === target);
+}
+/** A node the scene itself creates (and owns): it has a type, an instance or
+ *  a placeholder. An entry with none of those is a property override of a
+ *  node that an instanced (or inherited) scene creates. */
+export function isSceneCreatedNode(node) {
+    return node.type !== undefined || node.instance !== undefined || node.instancePlaceholder !== undefined;
+}
+/** Normalize a res:// path for comparison. */
+export function normalizeResPath(path) {
+    return path.trim().replace(/\\/g, "/");
+}

package/dist/core/capabilities/world-snapshot.d.ts

@@ -0,0 +1,58 @@
+/**
+ * world-snapshot — the shared request builder and result filter of
+ * `summer_world_snapshot` (src/mcp/tools/perception-tools.ts and
+ * tool-dispatch.ts).
+ *
+ * The engine's GetWorldSnapshot (world_snapshot_ops.cpp) takes only
+ * scene_path / max_nodes / max_lights / include_2d and returns every node it
+ * walked, about 250 bytes each: a scene of a few thousand nodes is far too
+ * big to read.
+ * The engine snapshot is still taken whole — its snapshot_id is the baseline
+ * summer_snapshot_diff compares against, and capping it would hide changes —
+ * but the agent gets a filtered, capped view: a subtree (path_prefix), some
+ * classes, some fields, a page (offset/max_nodes), plus class counts of what
+ * matched. Whole-scene `counts` and `total_nodes` stay as the engine sent them.
+ */
+import { z } from "zod";
+import { type JsonRecord } from "../util/json.js";
+/** Node entries returned to the agent unless max_nodes says otherwise. */
+export declare const WORLD_SNAPSHOT_DEFAULT_MAX_NODES = 200;
+/** The engine's own default cap (SNAPSHOT_MAX_NODES_DEFAULT) for the stored snapshot. */
+export declare const ENGINE_SNAPSHOT_MAX_NODES = 4000;
+/** Per-node fields the engine writes (path is always kept). */
+export declare const WORLD_SNAPSHOT_NODE_FIELDS: readonly string[];
+export declare const worldSnapshotInputShape: {
+    scene_path: z.ZodOptional<z.ZodString>;
+    max_nodes: z.ZodOptional<z.ZodNumber>;
+    offset: z.ZodOptional<z.ZodNumber>;
+    path_prefix: z.ZodOptional<z.ZodString>;
+    classes: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    fields: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+};
+export declare const worldSnapshotInputSchema: z.ZodObject<{
+    scene_path: z.ZodOptional<z.ZodString>;
+    max_nodes: z.ZodOptional<z.ZodNumber>;
+    offset: z.ZodOptional<z.ZodNumber>;
+    path_prefix: z.ZodOptional<z.ZodString>;
+    classes: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    fields: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+}, "strict", z.ZodTypeAny, {
+    scene_path?: string | undefined;
+    offset?: number | undefined;
+    max_nodes?: number | undefined;
+    path_prefix?: string | undefined;
+    classes?: string[] | undefined;
+    fields?: string[] | undefined;
+}, {
+    scene_path?: string | undefined;
+    offset?: number | undefined;
+    max_nodes?: number | undefined;
+    path_prefix?: string | undefined;
+    classes?: string[] | undefined;
+    fields?: string[] | undefined;
+}>;
+export type WorldSnapshotArgs = z.infer<typeof worldSnapshotInputSchema>;
+export declare function buildWorldSnapshotOp(args: WorldSnapshotArgs): JsonRecord;
+/** Filter and cap a successful snapshot for the agent. Anything that is not a
+ *  snapshot payload (a failure, an older shape) passes through untouched. */
+export declare function shapeWorldSnapshot(result: unknown, args: WorldSnapshotArgs): unknown;

package/dist/core/capabilities/world-snapshot.js

@@ -0,0 +1,150 @@
+/**
+ * world-snapshot — the shared request builder and result filter of
+ * `summer_world_snapshot` (src/mcp/tools/perception-tools.ts and
+ * tool-dispatch.ts).
+ *
+ * The engine's GetWorldSnapshot (world_snapshot_ops.cpp) takes only
+ * scene_path / max_nodes / max_lights / include_2d and returns every node it
+ * walked, about 250 bytes each: a scene of a few thousand nodes is far too
+ * big to read.
+ * The engine snapshot is still taken whole — its snapshot_id is the baseline
+ * summer_snapshot_diff compares against, and capping it would hide changes —
+ * but the agent gets a filtered, capped view: a subtree (path_prefix), some
+ * classes, some fields, a page (offset/max_nodes), plus class counts of what
+ * matched. Whole-scene `counts` and `total_nodes` stay as the engine sent them.
+ */
+import { z } from "zod";
+import { asRecord } from "../util/json.js";
+import { isAtOrBelow, normalizeNodePath } from "./tscn.js";
+/** Node entries returned to the agent unless max_nodes says otherwise. */
+export const WORLD_SNAPSHOT_DEFAULT_MAX_NODES = 200;
+/** The engine's own default cap (SNAPSHOT_MAX_NODES_DEFAULT) for the stored snapshot. */
+export const ENGINE_SNAPSHOT_MAX_NODES = 4000;
+/** Per-node fields the engine writes (path is always kept). */
+export const WORLD_SNAPSHOT_NODE_FIELDS = [
+    "class", "name", "pos", "rot_deg", "scale", "visible", "aabb", "scene_file",
+    "script_fp", "material_fps", "material_fps_truncated", "z_index", "rect", "view_rect", "limit_rect",
+];
+// Mirrors library/tools/world-snapshot/resource.yaml input_schema (parity-tested).
+export const worldSnapshotInputShape = {
+    scene_path: z
+        .string()
+        .optional()
+        .describe("Scene to snapshot, e.g. 'res://main.tscn'. Omit for the currently edited scene."),
+    max_nodes: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe(`Most node entries to return (default ${WORLD_SNAPSHOT_DEFAULT_MAX_NODES}). The engine still snapshots the whole scene for the diff baseline; the result says when the list is cut (truncated, next_offset).`),
+    offset: z
+        .number()
+        .int()
+        .min(0)
+        .optional()
+        .describe("Skip this many matching nodes (path-sorted) before listing — page with the result's next_offset."),
+    path_prefix: z
+        .string()
+        .optional()
+        .describe("Only this subtree: the node at this scene-relative path and everything below it, e.g. 'House3' or 'Lane2/Props'."),
+    classes: z
+        .array(z.string())
+        .max(32)
+        .optional()
+        .describe("Only nodes of these classes, e.g. ['MeshInstance3D', 'OmniLight3D'] (* wildcards allowed)."),
+    fields: z
+        .array(z.string())
+        .max(16)
+        .optional()
+        .describe("Only these per-node fields (path is always kept): class, name, pos, rot_deg, scale, visible, aabb, scene_file, script_fp, material_fps, z_index, rect, view_rect, limit_rect."),
+};
+export const worldSnapshotInputSchema = z.object(worldSnapshotInputShape).strict();
+export function buildWorldSnapshotOp(args) {
+    const op = { op: "GetWorldSnapshot" };
+    if (args.scene_path)
+        op.scene_path = args.scene_path;
+    // The stored snapshot is the diff baseline: never smaller than the engine
+    // default, larger only when the caller asks to see more than that.
+    if (args.max_nodes !== undefined && args.max_nodes > ENGINE_SNAPSHOT_MAX_NODES)
+        op.max_nodes = args.max_nodes;
+    return op;
+}
+function globMatcher(patterns) {
+    const regexes = patterns.map((glob) => new RegExp(`^${glob.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*/g, ".*").replace(/\?/g, ".")}$`));
+    return (value) => regexes.some((regex) => regex.test(value));
+}
+/** The GetWorldSnapshot payload inside an /api/ops envelope (or the envelope itself). */
+function snapshotPayload(result) {
+    const root = asRecord(result);
+    if (!root)
+        return null;
+    if (Array.isArray(root.nodes))
+        return { holder: root, index: null };
+    const results = Array.isArray(root.results) ? root.results : [];
+    const index = results.findIndex((entry) => {
+        const record = asRecord(entry);
+        return record?.op === "GetWorldSnapshot" && Array.isArray(record.nodes);
+    });
+    return index >= 0 ? { holder: root, index } : null;
+}
+/** Filter and cap a successful snapshot for the agent. Anything that is not a
+ *  snapshot payload (a failure, an older shape) passes through untouched. */
+export function shapeWorldSnapshot(result, args) {
+    const found = snapshotPayload(result);
+    if (!found)
+        return result;
+    const payload = (found.index === null ? found.holder : asRecord(found.holder.results[found.index]));
+    const nodes = payload.nodes.map((node) => asRecord(node)).filter((node) => !!node);
+    const prefix = args.path_prefix !== undefined ? normalizeNodePath(args.path_prefix) : undefined;
+    const classMatch = args.classes && args.classes.length > 0 ? globMatcher(args.classes) : undefined;
+    const inSubtree = (path) => prefix === undefined || (typeof path === "string" && isAtOrBelow(normalizeNodePath(path), prefix));
+    const matched = nodes.filter((node) => inSubtree(node.path) && (!classMatch || classMatch(String(node.class ?? ""))));
+    const offset = args.offset ?? 0;
+    const maxNodes = args.max_nodes ?? WORLD_SNAPSHOT_DEFAULT_MAX_NODES;
+    const page = matched.slice(offset, offset + maxNodes);
+    const keep = args.fields && args.fields.length > 0 ? new Set(["path", ...args.fields]) : undefined;
+    const listed = keep
+        ? page.map((node) => Object.fromEntries(Object.entries(node).filter(([key]) => keep.has(key))))
+        : page;
+    const engineTruncated = payload.truncated === true;
+    const end = offset + page.length;
+    const filtered = prefix !== undefined || classMatch !== undefined;
+    const shaped = {
+        ...payload,
+        nodes: listed,
+        // truncated: this list is not every matching node (page cut, or the engine's own cap).
+        truncated: end < matched.length || engineTruncated,
+        engine_truncated: engineTruncated,
+        engine_listed_nodes: nodes.length,
+        matched_nodes: matched.length,
+        returned_nodes: listed.length,
+        offset,
+        next_offset: end < matched.length ? end : null,
+        ...(filtered ? { filter: { ...(prefix !== undefined ? { path_prefix: prefix } : {}), ...(args.classes ? { classes: args.classes } : {}) } } : {}),
+        ...(keep ? { fields: [...keep] } : {}),
+    };
+    if (filtered) {
+        const counts = {};
+        for (const node of matched) {
+            const cls = String(node.class ?? "?");
+            counts[cls] = (counts[cls] ?? 0) + 1;
+        }
+        shaped.matched_counts = counts;
+    }
+    if (prefix !== undefined) {
+        for (const key of ["lights", "cameras"]) {
+            if (Array.isArray(payload[key])) {
+                shaped[key] = payload[key].filter((entry) => inSubtree(asRecord(entry)?.path));
+            }
+        }
+    }
+    if (end < matched.length || offset > 0 || filtered) {
+        shaped.note =
+            "nodes is a filtered/paged view; counts and total_nodes describe the whole scene, and snapshot_id covers the whole scene for summer_snapshot_diff.";
+    }
+    if (found.index === null)
+        return shaped;
+    const results = [...found.holder.results];
+    results[found.index] = shaped;
+    return { ...found.holder, results };
+}

package/dist/core/capability-skew.d.ts

@@ -27,11 +27,11 @@ export declare const CLI_PROTOCOL_VERSION = 1;
  * inside the engine monorepo (never send an op the engine has no branch for).
  *
  * Deliberately NOT listed: ops an agent may compose by hand through
- * summer_batch / `summer tool batch` (MoveNode, ReparentNode, DisconnectSignal,
- * Undo, Git*, RunCommand, ExtractZipFromUrl, CustomBake, ...). The CLI only
- * classifies those for dispatch (single-only / scene-mutation sets) and never
- * sends them on its own, so listing them would warn about skew the CLI cannot
- * cause; the engine's per-op "unknown op" error still covers them at call time.
+ * summer_batch / `summer tool batch` (DisconnectSignal, Undo, Git*,
+ * RunCommand, ExtractZipFromUrl, CustomBake, ...). The CLI only classifies
+ * those for dispatch (single-only / scene-mutation sets) and never sends them
+ * on its own, so listing them would warn about skew the CLI cannot cause; the
+ * engine's per-op "unknown op" error still covers them at call time.
  */
 export declare const CLI_KNOWN_OP_NEEDS: readonly string[];
 /** The `capabilities` block of /api/health, shape-checked. Every field is

package/dist/core/capability-skew.js

@@ -27,16 +27,24 @@ export const CLI_PROTOCOL_VERSION = 1;
  * inside the engine monorepo (never send an op the engine has no branch for).
  *
  * Deliberately NOT listed: ops an agent may compose by hand through
- * summer_batch / `summer tool batch` (MoveNode, ReparentNode, DisconnectSignal,
- * Undo, Git*, RunCommand, ExtractZipFromUrl, CustomBake, ...). The CLI only
- * classifies those for dispatch (single-only / scene-mutation sets) and never
- * sends them on its own, so listing them would warn about skew the CLI cannot
- * cause; the engine's per-op "unknown op" error still covers them at call time.
+ * summer_batch / `summer tool batch` (DisconnectSignal, Undo, Git*,
+ * RunCommand, ExtractZipFromUrl, CustomBake, ...). The CLI only classifies
+ * those for dispatch (single-only / scene-mutation sets) and never sends them
+ * on its own, so listing them would warn about skew the CLI cannot cause; the
+ * engine's per-op "unknown op" error still covers them at call time.
  */
 export const CLI_KNOWN_OP_NEEDS = [
     // Scene graph + properties
+    // (No ConnectSignal: it never saves the connection, so summer_connect_signal
+    // connects through RunSceneScript and summer_batch refuses the raw op —
+    // core/capabilities/connect-signal.ts.)
     "AddNode", "RemoveNode", "ReplaceNode", "SetProp", "SetResourceProperty",
-    "ConnectSignal", "SelectNode", "OpenScene", "SaveScene", "InstantiateScene",
+    "SelectNode", "OpenScene", "SaveScene", "InstantiateScene",
+    // summer_replace_node's instantiate/move/remove path (core/capabilities/replace-node.ts)
+    // and summer_batch's ReparentNode re-owning (core/capabilities/scene-batch.ts)
+    "MoveNode", "ReparentNode",
+    // summer_grep (core/capabilities/grep.ts)
+    "Grep",
     // Navigation (summer_open: core/capabilities/navigation/) — Navigate is the
     // one-table op (engine navigate_ops.cpp); the other three are the legacy
     // fallbacks on engines that predate it.

package/dist/core/headless/worker-engine-client.d.ts

@@ -45,7 +45,7 @@ export declare class WorkerEngineClient {
     getProjectState(_prefix?: string): Promise<unknown>;
     getDiagnostics(): Promise<unknown>;
     inspectNode(_path: string): Promise<unknown>;
-    inspectResource(_path: string): Promise<unknown>;
+    inspectNodeResource(_nodePath: string, _property: string): Promise<unknown>;
     getScriptErrors(_path: string): Promise<unknown>;
     getSelection(): Promise<unknown>;
     viewportSnapshot(): Promise<EngineSnapshot>;

package/dist/core/headless/worker-engine-client.js

@@ -222,8 +222,8 @@ export class WorkerEngineClient {
     async inspectNode(_path) {
         unsupported("inspectNode");
     }
-    async inspectResource(_path) {
-        unsupported("inspectResource");
+    async inspectNodeResource(_nodePath, _property) {
+        unsupported("inspectNodeResource");
     }
     async getScriptErrors(_path) {
         unsupported("getScriptErrors");