summer-engine 2.8.2 → 3.0.0

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

@@ -0,0 +1,485 @@
+import { z } from "zod";
+import { withEngine, missingEngineOpResult, ToolInputError, withOldEngineHint } from "./with-engine.js";
+import { executeSceneMutation } from "./scene-tools.js";
+// engine_lacks_op fallbacks: ONE copy for every face (E2E 2026-09-03 F-16).
+import { ALIGN_DISTRIBUTE_FALLBACK, NAVIGATION_PROBE_FALLBACK, SNAP_TO_SURFACE_FALLBACK, STARCAST_FALLBACK, TEST_PLACEMENT_FALLBACK, } from "../../core/capabilities/engine-fallbacks.js";
+/** Hard budget for one tool's model-visible result. These ops are designed to
+ *  answer in a few hundred bytes; anything past this means the engine returned
+ *  something this CLI does not understand (a newer/older receipt shape), and
+ *  forwarding 40 KB of it to the model is worse than a 300-byte honest failure.
+ *  Deliberately per-tool: v3 rejects a blanket cap in with-engine/server (see
+ *  installResultSizeLogger) because the big read tools legitimately exceed it. */
+const COMPACT_RESULT_LIMIT_BYTES = 5 * 1024;
+const SCENE_PATH_LIMIT_BYTES = 512;
+const NODE_PATH_LIMIT_BYTES = 256;
+const MIN_PLACEMENT_FLOOR_DISTANCE = 0.001;
+/** Mirrors the engine's SnapToSurface direction guard (length² > 1e-5). */
+const MIN_SNAP_DIRECTION_LENGTH_SQUARED = 0.00001;
+/** Starcast's own ceilings (engine spatial_ops.cpp starcast_3d): the engine
+ *  measures the compact receipt as UTF-8 JSON, downgrades full -> summary
+ *  above 12 KiB, and strips secondary paths above 5 KiB, so a receipt past the
+ *  ceiling for its returnedDetail is one this CLI does not understand. Unlike
+ *  COMPACT_RESULT_LIMIT_BYTES these are inclusive: the engine's contract is
+ *  "at most". */
+const STARCAST_SUMMARY_LIMIT_BYTES = 5 * 1024;
+const STARCAST_FULL_LIMIT_BYTES = 12 * 1024;
+// ---------------------------------------------------------------------------
+// Shared helpers
+// ---------------------------------------------------------------------------
+function snapDirectionExceedsNativeMinimum(direction) {
+    const lengthSquared = direction.reduce((sum, component) => sum + component * component, 0);
+    return Number.isFinite(lengthSquared) && lengthSquared > MIN_SNAP_DIRECTION_LENGTH_SQUARED;
+}
+/** Zod's .max() counts UTF-16 code units; the engine's limit is UTF-8 bytes.
+ *  The schemas below carry the same byte-boundary refine, so a host that
+ *  validates the schema never reaches these; they stay as the defence for
+ *  direct callers and throw ToolInputError (classified "input", nothing sent —
+ *  never "transport"). */
+function requireBoundedExactPath(value, label, limitBytes, emptyMessage) {
+    const exactPath = value.trim();
+    if (!exactPath) {
+        throw new ToolInputError(emptyMessage ?? `${label} must name one exact path.`);
+    }
+    const pathBytes = Buffer.byteLength(exactPath, "utf8");
+    if (pathBytes > limitBytes) {
+        throw new ToolInputError(`${label} must be at most ${limitBytes} UTF-8 bytes after trimming.`);
+    }
+    return exactPath;
+}
+function requireBoundedSubjects(subjectPaths, min, max, combinedLimitBytes) {
+    const subjects = subjectPaths.map((path, index) => requireBoundedExactPath(path, `subjectPaths[${index}]`, NODE_PATH_LIMIT_BYTES));
+    if (subjects.length < min || subjects.length > max) {
+        throw new ToolInputError(`subjectPaths must contain ${min}..${max} exact paths.`);
+    }
+    if (subjects.reduce((sum, path) => sum + Buffer.byteLength(path, "utf8"), 0) > combinedLimitBytes) {
+        throw new ToolInputError(`Combined subject paths exceed the ${combinedLimitBytes}-byte UTF-8 limit.`);
+    }
+    if (new Set(subjects).size !== subjects.length) {
+        throw new ToolInputError("subjectPaths must not contain duplicates.");
+    }
+    return subjects;
+}
+/** The receipt's entry for `op` (a mutation batch also carries the SaveScene
+ *  result), else the first result, else the raw receipt. */
+function opResult(receipt, op) {
+    const results = receipt?.results;
+    if (!Array.isArray(results))
+        return receipt;
+    return results.find((entry) => entry?.op === op) ?? results[0] ?? receipt;
+}
+/** withEngine options that return ONLY the compact native op result (not the
+ *  transport envelope) and fail loud with a tiny envelope if it is oversized. */
+function compactResult(options) {
+    const resultText = (receipt) => JSON.stringify(opResult(receipt, options.op));
+    return {
+        onResult: (receipt) => {
+            const text = resultText(receipt);
+            const bytes = Buffer.byteLength(text, "utf8");
+            if (bytes < COMPACT_RESULT_LIMIT_BYTES)
+                return null;
+            return {
+                isError: true,
+                content: [{
+                        type: "text",
+                        text: JSON.stringify({
+                            ok: false,
+                            op: options.op,
+                            failure_reason: options.failureReason,
+                            ...(options.extra ?? {}),
+                            actualBytes: bytes,
+                            limitBytes: COMPACT_RESULT_LIMIT_BYTES,
+                        }),
+                    }],
+            };
+        },
+        toContent: (receipt) => [{ type: "text", text: resultText(receipt) }],
+    };
+}
+const MUTATION_LANDED = { mutationApplied: true, saved: true, retrySafe: false };
+const READ_ONLY = { readOnly: true };
+/** withEngine options for summer_starcast: return ONLY the compact native op
+ *  result and fail loud when it exceeds the ceiling for its returnedDetail
+ *  (at most 5 KiB summary, at most 12 KiB full — the engine's own contract).
+ *  A downgraded receipt (requestedDetail full, returnedDetail summary) is
+ *  judged against the summary ceiling, exactly as the engine judged it. */
+function starcastResult() {
+    const op = "Starcast3D";
+    const resultText = (receipt) => JSON.stringify(opResult(receipt, op));
+    const returnedDetail = (receipt) => {
+        const detail = opResult(receipt, op)?.returnedDetail;
+        return detail === "full" ? "full" : "summary";
+    };
+    return {
+        onResult: (receipt) => {
+            const text = resultText(receipt);
+            const bytes = Buffer.byteLength(text, "utf8");
+            const detail = returnedDetail(receipt);
+            const limitBytes = detail === "full" ? STARCAST_FULL_LIMIT_BYTES : STARCAST_SUMMARY_LIMIT_BYTES;
+            if (bytes <= limitBytes)
+                return null;
+            return {
+                isError: true,
+                content: [{
+                        type: "text",
+                        text: JSON.stringify({
+                            ok: false,
+                            op,
+                            failure_reason: "starcast_result_exceeded_byte_limit",
+                            ...READ_ONLY,
+                            returnedDetail: detail,
+                            actualBytes: bytes,
+                            limitBytes,
+                            hint: "Update Summer Engine so Starcast3D returns its compact schema (schemaVersion 1).",
+                        }),
+                    }],
+            };
+        },
+        toContent: (receipt) => [{ type: "text", text: resultText(receipt) }],
+    };
+}
+// Every check the engine would reject on is expressed in the schema so the
+// MCP host rejects the call BEFORE the handler runs (an -32602 invalid-args
+// error, never a tool result that looks like an engine failure). Byte caps
+// and dedupe live here as refines; the fn-side helpers above repeat them only
+// for direct callers.
+const utf8Within = (limitBytes) => (value) => Buffer.byteLength(value, "utf8") <= limitBytes;
+const exactScenePath = z
+    .string()
+    .trim()
+    .min(1)
+    .max(SCENE_PATH_LIMIT_BYTES)
+    .refine(utf8Within(SCENE_PATH_LIMIT_BYTES), `scenePath must be at most ${SCENE_PATH_LIMIT_BYTES} UTF-8 bytes`);
+const exactNodePath = z
+    .string()
+    .trim()
+    .min(1)
+    .max(NODE_PATH_LIMIT_BYTES)
+    .refine(utf8Within(NODE_PATH_LIMIT_BYTES), `node paths must be at most ${NODE_PATH_LIMIT_BYTES} UTF-8 bytes`);
+const noDuplicates = (paths) => new Set(paths).size === paths.length;
+const combinedUtf8Within = (limitBytes) => (paths) => paths.reduce((sum, path) => sum + Buffer.byteLength(path, "utf8"), 0) <= limitBytes;
+/** Ordered, nonduplicate exact node paths with the engine's combined byte cap. */
+const subjectPathList = (min, max, combinedLimitBytes) => z
+    .array(exactNodePath)
+    .min(min)
+    .max(max)
+    .refine(noDuplicates, "subjectPaths must not contain duplicates")
+    .refine(combinedUtf8Within(combinedLimitBytes), `Combined subject paths exceed the ${combinedLimitBytes}-byte UTF-8 limit`);
+const finiteVector3 = z.tuple([z.number().finite(), z.number().finite(), z.number().finite()]);
+// ---------------------------------------------------------------------------
+// Registration
+// ---------------------------------------------------------------------------
+export function registerSpatialTools(server) {
+    server.tool("summer_test_placement", `Ghost-test one 3D node at an explicit candidate global pose without moving it or saving the scene.
+
+Use this before placing a prop in a shelf, cubby, doorway, platform, or dense set. The compact result reports known overlap evidence, grounded state, signed floor gap, and at most eight overlapping object paths. Physics evidence uses enabled collider shapes; because Godot exposes no query-completeness bit, its overlap count is labeled a lower bound and an otherwise-clear physics result reports fits:null rather than claiming proof. visual_aabb evidence is a broad-phase fallback that also catches visible mesh-only obstacles.
+
+The pose is always global/world-space: position and Euler rotation in degrees are both required, while the subject's current global scale is preserved. scenePath and subjectPath are exact; this tool never falls back to editor selection. The normal result is below 5 KB and the scene is never mutated. On an engine build that predates TestPlacement3D the result is a structured engine_lacks_op failure naming the fallback.`, {
+        scenePath: exactScenePath.describe("Exact scene path containing the subject, e.g. 'res://levels/workshop.tscn'."),
+        subjectPath: exactNodePath.describe("Exact node path relative to the scene root, e.g. './World/Crate'."),
+        candidateGlobalPosition: finiteVector3.describe("Candidate global/world position as [x, y, z]."),
+        candidateGlobalRotationDegrees: finiteVector3.describe("Candidate global/world Euler rotation in degrees as [x, y, z]; current global scale is preserved."),
+        collisionMask: z
+            .number()
+            .int()
+            .nonnegative()
+            .max(0xffffffff)
+            .optional()
+            .default(0xffffffff)
+            .describe("Godot 3D physics layers included in overlap and floor queries."),
+        collideWithAreas: z
+            .boolean()
+            .optional()
+            .default(true)
+            .describe("Include Area3D objects as placement obstacles/support candidates."),
+        maxFloorDistance: z
+            .number()
+            .min(MIN_PLACEMENT_FLOOR_DISTANCE)
+            .max(1000)
+            .optional()
+            .default(5)
+            .describe("Maximum world-space distance searched below the candidate footprint; range 0.001..1000."),
+        groundTolerance: z
+            .number()
+            .nonnegative()
+            .max(1)
+            .optional()
+            .default(0.05)
+            .describe("Absolute floor-gap tolerance used to classify grounded support."),
+        margin: z
+            .number()
+            .nonnegative()
+            .max(1)
+            .optional()
+            .default(0.001)
+            .describe("Physics shape-intersection margin; only an exact physics support collider+shape contact is excluded from overlaps."),
+    }, async ({ scenePath, subjectPath, candidateGlobalPosition, candidateGlobalRotationDegrees, collisionMask, collideWithAreas, maxFloorDistance, groundTolerance, margin, }) => withEngine(async (client) => {
+        const missing = missingEngineOpResult(client, "TestPlacement3D", TEST_PLACEMENT_FALLBACK);
+        if (missing)
+            return missing;
+        const exactScene = requireBoundedExactPath(scenePath, "scenePath", SCENE_PATH_LIMIT_BYTES);
+        const exactSubject = requireBoundedExactPath(subjectPath, "subjectPath", NODE_PATH_LIMIT_BYTES);
+        if (!Number.isFinite(maxFloorDistance) || maxFloorDistance < MIN_PLACEMENT_FLOOR_DISTANCE) {
+            throw new ToolInputError("maxFloorDistance must be at least 0.001.");
+        }
+        const receipt = await client.executeIdentityBoundOps([{
+                op: "TestPlacement3D",
+                subject_path: exactSubject,
+                candidate_global_position: candidateGlobalPosition,
+                candidate_global_rotation_degrees: candidateGlobalRotationDegrees,
+                collision_mask: collisionMask,
+                collide_with_areas: collideWithAreas,
+                max_floor_distance: maxFloorDistance,
+                ground_tolerance: groundTolerance,
+                margin,
+            }], { scenePath: exactScene });
+        return withOldEngineHint(receipt, "TestPlacement3D", TEST_PLACEMENT_FALLBACK);
+    }, compactResult({
+        op: "TestPlacement3D",
+        failureReason: "placement_result_exceeded_byte_limit",
+        extra: READ_ONLY,
+    })));
+    server.tool("summer_snap_to_surface", `Move one exact 3D subject along a world-space ray until its support face sits at the requested gap from the first surface. This changes only the subject's global transform, saves the scene, and is one reversible editor undo.
+
+Use the default downward direction to seat props on floors, ramps, tables, or shelves. Set alignUp only when the prop should tilt to match the support normal.
+
+EVIDENCE BOUNDARY:
+- physics means Godot swept the subject's enabled collider shapes against body colliders and refined the first-contact bracket.
+- visual_aabb is an explicit broad-phase fallback for mesh-only geometry; it does not prove triangle contact, and alignUp is not applied from that approximate normal.
+- initiallyOverlapping and backoffDistance expose bounded pre-sweep recovery. The tool fails instead of teleporting when the subject cannot be cleared within maxDistance.
+
+The normal result is bounded below 5 KB and returns before/after transforms, supportPath, finalGap with an error bound, slopeDeg, evidence, and warnings. scenePath and subjectPath are always required; there is no editor-selection fallback. On an engine build that predates SnapToSurface the result is a structured engine_lacks_op failure naming the fallback.`, {
+        scenePath: exactScenePath.describe("Exact scene containing the subject, e.g. 'res://levels/market.tscn'"),
+        subjectPath: exactNodePath.describe("Exact Node3D path relative to the scene root, e.g. './Props/Crate'"),
+        direction: finiteVector3
+            .refine(snapDirectionExceedsNativeMinimum, "direction squared length must exceed 0.00001")
+            .optional()
+            .default([0, -1, 0])
+            .describe("Finite world-space cast direction [x,y,z] whose squared length exceeds 0.00001. Defaults downward."),
+        maxDistance: z
+            .number()
+            .positive()
+            .max(10000)
+            .optional()
+            .default(20)
+            .describe("Maximum cast and overlap-recovery distance in scene units."),
+        gap: z
+            .number()
+            .nonnegative()
+            .max(10000)
+            .optional()
+            .default(0)
+            .describe("Requested separation from the support surface; must not exceed maxDistance."),
+        alignUp: z
+            .boolean()
+            .optional()
+            .default(false)
+            .describe("Rotate the subject's current world up toward an exact physics contact normal before seating it."),
+    }, async ({ scenePath, subjectPath, direction, maxDistance, gap, alignUp }) => withEngine(async (client) => {
+        const missing = missingEngineOpResult(client, "SnapToSurface", SNAP_TO_SURFACE_FALLBACK);
+        if (missing)
+            return missing;
+        const exactScene = requireBoundedExactPath(scenePath, "scenePath", SCENE_PATH_LIMIT_BYTES);
+        const exactSubject = requireBoundedExactPath(subjectPath, "subjectPath", NODE_PATH_LIMIT_BYTES, "subjectPath must name one exact Node3D; selection fallback is not supported.");
+        if (!snapDirectionExceedsNativeMinimum(direction)) {
+            throw new ToolInputError("direction squared length must exceed 0.00001.");
+        }
+        // Cross-field: a raw zod shape cannot express it, so it stays here.
+        if (gap > maxDistance)
+            throw new ToolInputError("gap must not exceed maxDistance.");
+        const receipt = await executeSceneMutation(client, exactScene, [{
+                op: "SnapToSurface",
+                subject_path: exactSubject,
+                direction,
+                max_distance: maxDistance,
+                gap,
+                align_up: alignUp,
+            }]);
+        return withOldEngineHint(receipt, "SnapToSurface", SNAP_TO_SURFACE_FALLBACK);
+    }, compactResult({
+        op: "SnapToSurface",
+        failureReason: "snap_to_surface_result_exceeded_byte_limit",
+        extra: MUTATION_LANDED,
+    })));
+    server.tool("summer_align_distribute_3d", `Align or equal-space an explicit ordered list of 3D subjects along one world-space axis, then save the exact target scene.
+
+Every anchor and extent comes from visible descendant GeometryInstance3D world AABBs (evidence: visual_aabb). The tool never uses editor selection and fails instead of fabricating bounds. It preserves each subject's authored basis and scale, translates only along the normalized axis, and records all changed transforms in one undoable editor operation.
+
+Alignment modes use the first ordered subject's minimum, center, or maximum projected anchor. Distribution modes keep the first and last subjects fixed and honor caller order. distribute_gaps accounts for each subject's projected half-extent and fails if the endpoint span cannot fit non-overlapping equal gaps. The compact result returns ordered before/after origins, resolved spacing, and numeric residuals under 5 KB. On an engine build that predates AlignDistribute3D the result is a structured engine_lacks_op failure naming the fallback.`, {
+        scenePath: exactScenePath.describe("Exact target scene, e.g. 'res://levels/market.tscn'."),
+        subjectPaths: subjectPathList(2, 16, 1536)
+            .describe("Two to sixteen exact nonduplicate Node3D paths in the order to align or distribute."),
+        axis: finiteVector3
+            .refine(([x, y, zValue]) => Math.hypot(x, y, zValue) > 1e-6, "axis must be non-zero")
+            .describe("Finite, non-zero world axis [x,y,z]; normalization is automatic."),
+        mode: z
+            .enum(["align_min", "align_center", "align_max", "distribute_centers", "distribute_gaps"])
+            .describe("Alignment anchor or equal-spacing policy."),
+    }, async ({ scenePath, subjectPaths, axis, mode }) => withEngine(async (client) => {
+        const missing = missingEngineOpResult(client, "AlignDistribute3D", ALIGN_DISTRIBUTE_FALLBACK);
+        if (missing)
+            return missing;
+        const exactScene = requireBoundedExactPath(scenePath, "scenePath", SCENE_PATH_LIMIT_BYTES);
+        const paths = requireBoundedSubjects(subjectPaths, 2, 16, 1536);
+        if (axis.some((component) => !Number.isFinite(component)) || Math.hypot(...axis) <= 1e-6) {
+            throw new ToolInputError("axis must contain three finite values and have non-zero length.");
+        }
+        const receipt = await executeSceneMutation(client, exactScene, [{
+                op: "AlignDistribute3D",
+                subject_paths: paths,
+                axis,
+                mode,
+            }]);
+        return withOldEngineHint(receipt, "AlignDistribute3D", ALIGN_DISTRIBUTE_FALLBACK);
+    }, compactResult({
+        op: "AlignDistribute3D",
+        failureReason: "align_result_exceeded_byte_limit",
+        extra: MUTATION_LANDED,
+    })));
+    server.tool("summer_navigation_probe", `Inspect whether two explicit world-space points are connected by the targeted 3D scene's built-in Godot navigation map without changing or saving the scene.
+
+Returns navigation readiness and its reason, map iteration and region counts, requested and layer-filtered snapped endpoints, snap distances, conservative reachability, full route length, and at most 16 deterministic route points. A path is reachable only when it terminates at both snapped endpoints within the reported tolerance.
+
+ready:false means navigation evidence is unavailable, not that the route is unreachable. In particular, map iteration 0 precedes the first usable synchronization and can return silently empty paths; iteration 1 and later are usable. evidence is always navigation. Normal results are capped below 5 KB.
+
+Always pass an exact scenePath and finite world-space start/end points. This read-only tool never uses editor selection, creates undo history, or calls SaveScene. On an engine build that predates NavigationProbe3D the result is a structured engine_lacks_op failure naming the fallback.`, {
+        scenePath: exactScenePath.describe("Exact 3D scene whose World3D navigation map should be queried."),
+        start: finiteVector3.describe("Requested world-space route start [x,y,z]."),
+        end: finiteVector3.describe("Requested world-space route destination [x,y,z]."),
+        navigationLayers: z
+            .number()
+            .int()
+            .min(1)
+            .max(0xffffffff)
+            .optional()
+            .default(1)
+            .describe("Godot navigation-layer bitmask; only enabled matching regions are used."),
+        optimize: z
+            .boolean()
+            .optional()
+            .default(true)
+            .describe("Use Godot's corridor-funnel path post-processing; false uses edge-centered points."),
+    }, async ({ scenePath, start, end, navigationLayers, optimize }) => withEngine(async (client) => {
+        const missing = missingEngineOpResult(client, "NavigationProbe3D", NAVIGATION_PROBE_FALLBACK);
+        if (missing)
+            return missing;
+        const exactScene = requireBoundedExactPath(scenePath, "scenePath", SCENE_PATH_LIMIT_BYTES);
+        if (start.length !== 3 || end.length !== 3 ||
+            !start.every(Number.isFinite) || !end.every(Number.isFinite)) {
+            throw new ToolInputError("start and end must each contain exactly three finite world-space numbers.");
+        }
+        if (!Number.isInteger(navigationLayers) || navigationLayers < 1 || navigationLayers > 0xffffffff) {
+            throw new ToolInputError("navigationLayers must be an integer from 1 through 4294967295.");
+        }
+        const receipt = await client.executeIdentityBoundOps([{
+                op: "NavigationProbe3D",
+                start,
+                end,
+                navigation_layers: navigationLayers,
+                optimize,
+            }], { scenePath: exactScene });
+        return withOldEngineHint(receipt, "NavigationProbe3D", NAVIGATION_PROBE_FALLBACK);
+    }, compactResult({
+        op: "NavigationProbe3D",
+        failureReason: "navigation_probe_result_exceeded_byte_limit",
+        extra: { ...READ_ONLY, evidence: "navigation" },
+    })));
+    server.tool("summer_starcast", `Read a 3D spatial rundown for one exact node in an exact scene without moving it or saving the scene: 26 directional clearance casts (6 axes, 12 edges, 8 corners) from the subject's bounds, contact-or-overlap evidence, grounded state, and, in full detail, bounded nearby-object lists. Use it before and after placing an object to learn which side is blocked, by what, and at what distance.
+
+detail 'summary' (default) is a placement report of at most 5 KB: subject position and size, grounded and contactStatus, deduplicated contact paths, one compact record per direction (status open|blocked, nearest distance, object, evidence, relationship), coverage, and warnings. detail 'full' adds per-direction hit geometry, an objects table, nearby lists, and the query echo, at most 12 KB; the engine downgrades to summary rather than exceed that (warning full_result_exceeded_12kb_returned_summary) and always reports requestedDetail vs returnedDetail.
+
+EVIDENCE BOUNDARY:
+- evidence 'physics' uses Godot's PhysicsDirectSpaceState3D against exact collider geometry on collisionMask. Shape intersections say contact_or_overlap because the query does not establish penetration depth; touching and anything within margin are included.
+- evidence 'visual_aabb' uses visible world-axis-aligned bounding boxes: it catches meshes without colliders but is broad-phase only, never triangle-level contact.
+- Lights, cameras, audio, navigation, scripts, and plain Nodes are not obstacles unless they own visual or collision geometry. One representative ray per direction can miss off-center geometry.
+
+scenePath and path are exact; editor selection is never consulted. This tool is read-only: it never moves the node or saves the scene. On an engine build that predates Starcast3D the result is a structured engine_lacks_op failure naming the fallback.`, {
+        scenePath: exactScenePath.describe("Exact scene containing the subject, e.g. 'res://levels/level1.tscn'."),
+        path: exactNodePath.describe("Exact Node3D path relative to the scene root, e.g. './World/Crate'."),
+        detail: z
+            .enum(["summary", "full"])
+            .optional()
+            .default("summary")
+            .describe("summary: compact placement report (at most 5 KB). full: adds bounded hit geometry, an objects table, and nearby lists (at most 12 KB; the engine downgrades to summary rather than exceed it)."),
+        maxDistance: z
+            .number()
+            .positive()
+            .max(10000)
+            .optional()
+            .default(20)
+            .describe("Maximum outward cast distance in scene units."),
+        nearbyRadius: z
+            .number()
+            .nonnegative()
+            .max(10000)
+            .optional()
+            .default(10)
+            .describe("Maximum gap from the subject bounds for the nearby-object lists (full detail)."),
+        directionSpace: z
+            .enum(["world", "local"])
+            .optional()
+            .default("world")
+            .describe("Cast along world axes, or along the subject's orthonormalized local axes when 'front', 'side', or 'up' mean the rotated subject's own orientation."),
+        collisionMask: z
+            .number()
+            .int()
+            .nonnegative()
+            .max(0xffffffff)
+            .optional()
+            .default(0xffffffff)
+            .describe("Godot 3D physics layer mask queried by rays, shape contacts/overlaps, and nearby-collider scans."),
+        collideWithAreas: z
+            .boolean()
+            .optional()
+            .default(true)
+            .describe("Include Area3D objects as well as physics bodies."),
+        maxHitsPerDirection: z
+            .number()
+            .int()
+            .min(1)
+            .max(8)
+            .optional()
+            .default(3)
+            .describe("Maximum physics hits and visual AABB hits retained for each direction."),
+        maxResults: z
+            .number()
+            .int()
+            .min(1)
+            .max(128)
+            .optional()
+            .default(64)
+            .describe("Maximum retained contact/overlap and nearby entries per evidence channel."),
+        margin: z
+            .number()
+            .nonnegative()
+            .max(1)
+            .optional()
+            .default(0.001)
+            .describe("Tolerance for exact-geometry physics shape intersection queries; touching and candidates within this margin are reported as contact_or_overlap."),
+    }, async ({ scenePath, path, detail, maxDistance, nearbyRadius, directionSpace, collisionMask, collideWithAreas, maxHitsPerDirection, maxResults, margin, }) => withEngine(async (client) => {
+        const missing = missingEngineOpResult(client, "Starcast3D", STARCAST_FALLBACK);
+        if (missing)
+            return missing;
+        const exactScene = requireBoundedExactPath(scenePath, "scenePath", SCENE_PATH_LIMIT_BYTES);
+        const exactSubject = requireBoundedExactPath(path, "path", NODE_PATH_LIMIT_BYTES, "path must name one exact Node3D; selection fallback is not supported.");
+        if (!Number.isFinite(maxDistance) || maxDistance <= 0) {
+            throw new ToolInputError("maxDistance must be positive.");
+        }
+        if (!Number.isFinite(nearbyRadius) || nearbyRadius < 0) {
+            throw new ToolInputError("nearbyRadius must be zero or positive.");
+        }
+        const receipt = await client.executeIdentityBoundOps([{
+                op: "Starcast3D",
+                path: exactSubject,
+                detail,
+                max_distance: maxDistance,
+                nearby_radius: nearbyRadius,
+                direction_space: directionSpace,
+                collision_mask: collisionMask,
+                collide_with_areas: collideWithAreas,
+                max_hits_per_direction: maxHitsPerDirection,
+                max_results: maxResults,
+                margin,
+            }], { scenePath: exactScene });
+        return withOldEngineHint(receipt, "Starcast3D", STARCAST_FALLBACK);
+    }, starcastResult()));
+}

package/dist/mcp/tools/text-json.d.ts

@@ -0,0 +1,8 @@
+/** Wrap a JSON-serializable value as an MCP text ToolResult. */
+export declare function textJson(value: unknown, isError?: boolean): {
+    isError?: boolean | undefined;
+    content: {
+        type: "text";
+        text: string;
+    }[];
+};

package/dist/mcp/tools/text-json.js

@@ -0,0 +1,12 @@
+/** Wrap a JSON-serializable value as an MCP text ToolResult. */
+export function textJson(value, isError = false) {
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify(value, null, 2),
+            },
+        ],
+        ...(isError ? { isError: true } : {}),
+    };
+}

package/dist/mcp/tools/{cloud-tools.d.ts → ui-tools.d.ts}

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

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

@@ -0,0 +1,82 @@
+import { withEngine, missingEngineOpResult, withOldEngineHint } from "./with-engine.js";
+import { buildUiActionsOp, buildUiActivateOp, buildUiScreenshotOp, buildUiTreeOp, executeUiOp, uiActionsArgsSchema, uiActivateArgsSchema, uiScreenshotArgsSchema, uiScreenshotCaption, uiScreenshotImage, uiTreeArgsSchema, withUiFailureDetails, } from "../../core/capabilities/ui-control.js";
+/**
+ * Editor UI control tools (editor UI control). The MCP face only — the op builders, the
+ * shared zod contracts, and the failure rendering live in
+ * core/capabilities/ui-control.ts and are used verbatim by the CLI dispatcher.
+ *
+ * Doctrine these descriptions teach (research/agent-platform/04-total-control
+ * §1): SEMANTIC FIRST. Scene work goes through the scene and perception tools;
+ * the UI ops are for editor-WORKFLOW steps a human would do with the mouse —
+ * open Project Settings, switch the main screen, clear a blocking dialog, read
+ * a dock. Within the UI ops: a named action beats a tree walk, a tree walk
+ * beats pixels, and pixels never drive clicks (there is no coordinate-click
+ * op). Quit / project-reload / delete-without-confirm actions are denied by
+ * the engine and are never attempted.
+ */
+const DOCTRINE = "SCENE WORK IS NOT UI WORK: to add, move, retune, or read nodes use summer_run_script, the scene tools, summer_world_snapshot and summer_screenshot — never by clicking through the editor. UI ops are for editor-workflow steps a human would do with the mouse: open Project Settings or the Import dock, switch the 2D/3D/Script main screen, clear a dialog that is blocking input, read what a dock currently shows.";
+const LADDER = "Order of preference: a dedicated tool -> summer_ui_actions mode:'invoke' by name -> summer_ui_tree + summer_ui_activate by control path -> summer_ui_screenshot (pixels, last, and only to LOOK — never to pick coordinates).";
+const DENY = "Never try to quit the editor, quit to the project list, reload the project, or delete without confirmation (editor/file_quit, editor/quit_to_project_list, editor/reload_current_project, scene_tree/delete_no_confirm, project_manager/*): the engine refuses them with denied_action, and buttons/menu items with those labels are denied the same way. They end the session you are talking over.";
+async function sendUiOp(client, built) {
+    const missing = missingEngineOpResult(client, built.kind, built.fallback);
+    if (missing)
+        return missing;
+    const result = await executeUiOp(client, built);
+    return withOldEngineHint(withUiFailureDetails(result), built.kind, built.fallback);
+}
+export function registerUiTools(server) {
+    server.tool("summer_ui_actions", `List the editor's named actions, or invoke ONE by name exactly as its menu item / shortcut would — the primary way to drive the editor UI. (preview — needs an engine build with UiListActions/UiInvoke)
+
+${DOCTRINE}
+
+mode:'list' -> {actions:[{name, label, shortcut_text, category, source:'shortcut'|'command', denied?}], total, truncated, filter}. name is the stable shortcut path ('editor/save_scene', 'editor/project_settings', 'spatial_editor/focus_selection', 'summer/design_mode'); filter is a case-insensitive substring over name and label. denied:true marks names mode:'invoke' will refuse — read it and do not try them.
+mode:'invoke' action_name:'<name>' -> {action, label, invoked:true, handled, via:'shortcut_event'|'command_palette', opened_dialog?, mutates:true}. The event runs through the same MenuBar/PopupMenu/EditorNode handlers the key would. opened_dialog is a window that appeared synchronously; a dialog shown deferred appears on the next summer_ui_tree root:'dialogs'.
+
+${LADDER} Read back, never assume: after an invoke, confirm the effect with summer_ui_tree root:'dialogs' (a dialog opened), summer_ui_tree root:'dock:<name>' (a dock changed), or the scene/perception tools (the scene changed).
+
+Failures carry failure_reason: unknown_action (+close_matches — pick the exact name) | denied_action (+reason — stop; do not route around it) | modal_open (+blocking_dialog — an exclusive dialog is eating input: summer_ui_tree root:'dialogs', then summer_ui_activate action:'dismiss_dialog', then retry) | not_handled (invoked but no live receiver — switch context first, e.g. summer_ui_activate path:'main_screen' action:'select_tab' value:'3D') | editor_unavailable. ${DENY} On an engine build without these ops the result is a structured engine_lacks_op failure (nothing is sent) naming the dedicated tools to use instead.`, uiActionsArgsSchema.shape, async (args) => withEngine(async (client) => sendUiOp(client, buildUiActionsOp(args))));
+    server.tool("summer_ui_tree", `Structured tree of the live editor UI — every visible Control with its class, path, rect, text/tooltip and state (checked, enabled, focused, tabs + current_tab, value/min/max, selected item) — or, with root:'dialogs', every visible dialog/popup and whether one is BLOCKING input. The structured alternative to a screenshot: the tree states outright what exists and what is clickable, at a fraction of the tokens, and its paths are what summer_ui_activate takes. (preview — needs an engine build with UiTree/UiDialogs)
+
+${DOCTRINE} Use this tree to READ editor state (which main screen is active, what a dock shows, what a dialog says and which buttons it has) and to find a control's path when no named action covers the step; use summer_get_scene_tree / summer_world_snapshot for the SCENE — the editor's Scene dock is a view of that data, not the data.
+
+root: 'main' (default; the editor chrome) | 'window' (incl. every sub-window) | 'dock:<title|id>' (file_system | scene_tree | inspector or any dock title) | 'dialog:<title>' | 'path:<node path>' (zoom into an earlier result) | 'dialogs' -> {count, blocking, blocking_dialog?, dialogs:[{title, path, class, kind, exclusive, popup, embedded, focused, text?, items?, buttons:[{text, path, kind:'ok'|'cancel'|'custom', enabled}]}]}.
+Tree results: {root, root_path, total_emitted, truncated, tree:{name, class, path, visible, rect, text?, tooltip?, enabled?, checked?, focused?, tabs?, current_tab?, value?, child_count, children_truncated?, children}}. Strings clip at 200 chars; icon-only toolbar buttons are named by tooltip; child_count is always the real count, so a children_truncated node can be re-read with root:'path:<its path>' and a larger depth/limit.
+
+Paths (@Panel@123) are stable within a session, not across builds — re-read instead of persisting them. The blocking-dialog pattern: root:'dialogs' -> blocking:true -> summer_ui_activate action:'dismiss_dialog' path:<blocking_dialog.path> -> root:'dialogs' again to confirm blocking:false. Failures: unknown_root (+available_docks, dock_ids) | not_found (+visible_titles) | ambiguous_dialog (+candidates) | editor_unavailable. Engine builds without these ops return a structured engine_lacks_op failure (nothing is sent).`, uiTreeArgsSchema.shape, async (args) => withEngine(async (client) => sendUiOp(client, buildUiTreeOp(args))));
+    server.tool("summer_ui_activate", `Activate ONE editor control by its summer_ui_tree path through the control's own input path — a synthetic click for buttons, the public setter + signal for tabs, text fields and ranges — or dismiss a visible dialog (action:'dismiss_dialog'). Mutates editor state; the result's state is READ BACK from the control after the action, not echoed. (preview — needs an engine build with UiActivate/UiDismissDialog)
+
+${DOCTRINE} Reach for this only when no named action covers the step (summer_ui_actions mode:'list' first). There is no coordinate click: if a thing is visible it is in the tree and this reaches it by path.
+
+actions: press (BaseButton: hover+press+release at the rect centre — pressed_emitted is observed, not assumed; ItemList/PopupMenu item by index; MenuBar -> unsupported_control, use summer_ui_actions) | toggle (toggle-mode button) | focus (any control/window) | select_tab (TabContainer/TabBar by value title or index; path:'main_screen' switches the 2D/3D/Script/Game/AssetLib editor by value or index and reads back current_tab + text) | set_text (LineEdit/TextEdit; submit:true also presses Enter; value '' clears) | set_value (Range number) | dismiss_dialog (path or title from summer_ui_tree root:'dialogs'; button 'cancel' default = the safe close, 'ok' or a button text to confirm — only when the user asked for that).
+
+Returns {path, class, action, via, state:{...the node's tree fields...}, mutates:true} plus clicked_at/hover_established/pressed_emitted for press, item_text for menus, submitted for set_text; dismiss_dialog returns {title, class, button, via, visible_after} — visible_after:true means the dialog re-validated and stayed up (read it: summer_ui_tree root:'dialog:<title>'). Verify with the read-back (state.checked, state.current_tab, state.text, visible_after), never by assumption.
+
+Failures: not_found | not_visible (hidden — reveal the dock/tab first) | disabled | unsupported_control (+supported_actions) | obscured (+hit_control — something on top, usually a dialog) | modal_open (+blocking_dialog — dismiss it first) | no_activation_path (use the named action instead) | denied_action / denied_path (safety: quit/reload labels, file-dialog paths outside the project) | tab_not_found (+tabs) | index_out_of_range | missing_value | not_selected | button_not_found (+buttons) | ambiguous_dialog (+candidates). ${DENY} Engine builds without these ops return a structured engine_lacks_op failure (nothing is sent).`, uiActivateArgsSchema.shape, async (args) => withEngine(async (client) => sendUiOp(client, buildUiActivateOp(args))));
+    server.tool("summer_ui_screenshot", `PNG of the editor window (or one dock / dialog / control's rect) returned as an image you can look at — the PIXELS-LAST fallback of the UI ladder: use it to see layout, an unfamiliar panel, or to sanity-check what the tree described, never to pick click coordinates (there is no coordinate click; summer_ui_activate takes paths). For the 3D/2D viewport, a scene render, or the running game use summer_screenshot instead — that is the visual-verification tool for scene work, and scene work itself goes through summer_run_script and the scene tools, never through the editor UI. (preview — needs an engine build with UiScreenshot)
+
+${LADDER} Prefer summer_ui_tree for state: a control's checked/current_tab/text is exact there and costs a fraction of an image.
+
+root: 'window' (default; the whole editor window incl. embedded dialogs) | 'main' | 'dock:<title|id>' | 'dialog:<title>' | 'path:<node path>' — a Control or embedded dialog is cropped out of the root viewport texture; a native OS sub-window is not in it (native_subwindow). max_size caps the longest edge (default 1024, 16-4096). Captured from the editor's own root viewport texture, never the OS screen (safety_boundary:'no_os_screen_capture').
+
+Headless is honest: under a headless editor (dummy rendering driver) the result is failure_reason no_renderer — nothing was drawn, so there are no pixels; summer_ui_tree is the structured view of the same UI and a display (Linux: --xvfb) is needed for pixels. Other failures: texture_unavailable | zero_size | native_subwindow | unknown_root | not_found | encode_failed. Engine builds without the op return a structured engine_lacks_op failure (nothing is sent).`, uiScreenshotArgsSchema.shape, async (args) => withEngine(async (client) => sendUiOp(client, buildUiScreenshotOp(args)), {
+        // withEngine calls toContent only on genuine success (extractOpError
+        // cleared): hand the frame back as an image block, or fall back to
+        // text when a "success" carries no bytes rather than emit a broken
+        // image.
+        toContent: (result) => {
+            const image = uiScreenshotImage(result);
+            if (!image) {
+                return [
+                    {
+                        type: "text",
+                        text: "UiScreenshot succeeded but returned no image data. Retry once; if it persists, read the UI structurally with summer_ui_tree.",
+                    },
+                ];
+            }
+            return [
+                { type: "image", data: image.base64, mimeType: image.mime },
+                { type: "text", text: uiScreenshotCaption(image) },
+            ];
+        },
+    }));
+}

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

@@ -1,9 +1,4 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-/**
- * Visual capture tools. Unlike the in-product chat agent (a text-only "brain"
- * that needs a separate vision model to describe frames for it), an MCP client
- * like Claude Code can SEE images directly. So we hand the raw engine frame back
- * as an MCP image content block — no vision-model prepass, no paraphrase. The
- * model reviews the actual pixels.
- */
+import { analyzedSnapshot, captureScene, captureViewport, VIEWPORT_RECAPTURE_DELAY_MS, type CaptureResult, type RecaptureInfo } from "../../core/capabilities/capture.js";
+export { analyzedSnapshot, captureScene, captureViewport, VIEWPORT_RECAPTURE_DELAY_MS, type CaptureResult, type RecaptureInfo };
 export declare function registerVisualTools(server: McpServer): void;