Fix Gemini empty build retries and expand build-plan v2 support

Author: aaronaalmendarez

README.md

@@ -393,10 +393,18 @@ The build-plan tool accepts either:
 - or a wrapper object with top-level `build_plan`
 
 Important top-level planning fields:
-- `coordMode`: `player` or `absolute`
-- `origin`: in `player` mode this is a relative shift from the player; in `absolute` mode it is an explicit world origin
+- `label` or `summary`: human-readable build name
+- `version`: set `2` for the richer semantic build-plan contract
+- `coordMode`: `player`, `absolute`, or `anchor`
+- `origin`: in `absolute` mode this is an explicit world origin
 - `offset`: optional extra relative shift after the base origin
+- `anchor`: anchor reference such as `last_build:door` when `coordMode=anchor`
 - `autoFix`: allows safe grounding fixes like small auto-lowers and limited support repair
+- `snapToGround`: opt-in grounding adjustment
+- `flattenTerrain`: opt-in terrain flattening across the footprint
+- `clearVegetation`: opt-in replaceable-plant clearing in the footprint
+- `options.rotation`: `0`, `90`, `180`, `270`, `cw`, or `ccw`
+- `anchors`: named relative anchor points remembered after successful builds
 
 Minimal example:
 
@@ -417,6 +425,18 @@ Supported aliases are intentionally flexible:
 - block id: `block`, `material`, or `id`
 - properties: `properties` or `state`
 - geometry: `from/to`, `start/end`, `start + size`, `location + size`, `location + dimensions`
+- vanilla-style block-state strings also work, for example `minecraft:oak_stairs[facing=east,half=top]`
+
+Semantic step types in `steps[]` now include:
+- `cuboid`
+- `hollow_cuboid`
+- `columns`
+- `blocks`
+- `windows`
+- `roof`
+- `fill`
+- `repeat`
+- `scatter`
 
 #### Planner Semantics Agents Should Follow
 
@@ -425,13 +445,17 @@ Agents should not treat the build planner as a black box. The most important rul
 - `minecraft_buildsite` returns terrain deltas relative to the player’s current block Y, not absolute world Y.
 - If `maxDy` is negative, the surrounding surface is below the player. A build with floor `y=0` will float unless the plan is lowered or the player moves.
 - `coordMode=absolute` is the right choice when the structure needs to stay locked to a specific world location instead of wherever the player happens to be standing.
-- If `coordMode=absolute` is used without `origin`, the planner falls back to the player’s block position and reports that fallback in `repairs`.
+- `coordMode=anchor` lets one build attach to anchors created by an earlier successful build, for example `last_build:door`.
+- If `coordMode=absolute` is used without `origin`, the planner now rejects the plan instead of silently falling back.
 - `clearPercent` is headroom above sampled surface columns, not proof that the terrain is flat.
 - The planner clamps relative X/Z into `[-32, 32]` and relative Y into `[-24, 24]`. If a plan is too large or too far away, the result includes repairs saying it was clamped into the safe build window.
-- `steps` should be used for phased builds like foundation -> shell -> roof -> details.
+- `steps` should be used for phased builds like foundation -> shell -> roof -> details, and step order is preserved unless `options.phaseReorder=true`.
 - `clear` volumes remove space before building and use the same bounds formats as cuboids, but without a block id.
+- `clear` can also use the v2 object form with `enabled`, `dx`, `dy`, `dz`, `offset`, and `replaceWith`.
 - `rotate` accepts `0`, `90`, `180`, `270`, `cw`, and `ccw`, and the result reports the final normalized value in `appliedRotation`.
 - `phaseCount` reports how many direct-operation phases were compiled from `clear`, `cuboids`, `blocks`, and `steps`.
+- `hollow_cuboid` should be preferred over solid-fill-then-air hacks for rooms and wall shells.
+- `roof` lets the planner generate common roof forms directly instead of forcing the agent to hand-author every shrinking rectangle.
 - The planner now returns structured `issues` identifying floating cuboids or block targets, their `gapBelow`, and a `suggestedY` to ground them correctly.
 - The planner only adds support pillars for real unsupported columns and caps auto-support at 24 columns.
 - If more than 80% of the lowest build columns are already within 2 blocks of solid ground and `autoFix=true`, the planner can auto-lower the whole build instead of spamming pillars.

run-mcp-sidecar-node.js

@@ -302,19 +302,24 @@ const TOOLS = {
     inputSchema: objectSchema(),
   },
   minecraft_preview_build_plan: {
-    description: "Compile and validate a structured voxel build plan without executing it, returning previewCommands, planId, resolvedOrigin, issues, repairs, rotation, and phase data.",
+    description: "Compile and validate a structured voxel build plan without executing it, including v2 semantic steps like hollow_cuboid, columns, windows, roof, repeat, and scatter. Returns previewCommands, planId, resolvedOrigin, issues, repairs, rotation, and phase data.",
     method: "POST",
     path: "/v1/actions/preview_build_plan",
     inputSchema: {
       type: "object",
-      description: "Either provide build_plan explicitly or pass the build_plan object as the root arguments object. Supports coordMode=player|absolute, explicit origin, offset, autoFix, clear, cuboids, blocks, and steps.",
+      description: "Either provide build_plan explicitly or pass the build_plan object as the root arguments object. Supports version=2 plans, coordMode=player|absolute|anchor, explicit origin, offset, anchors, snapToGround, flattenTerrain, clearVegetation, autoFix, clear, cuboids, blocks, and typed semantic steps.",
       additionalProperties: true,
       properties: {
         build_plan: { type: "object", additionalProperties: true },
-        coordMode: { type: "string", enum: ["player", "absolute"] },
+        coordMode: { type: "string", enum: ["player", "absolute", "anchor"] },
         origin: { type: "object", additionalProperties: true },
         offset: { type: "object", additionalProperties: true },
+        anchor: { type: "string" },
         autoFix: { type: "boolean" },
+        snapToGround: { type: "boolean" },
+        flattenTerrain: { type: "boolean" },
+        clearVegetation: { type: "boolean" },
+        options: { type: "object", additionalProperties: true },
       },
     },
   },
@@ -325,21 +330,26 @@ const TOOLS = {
     inputSchema: highlightSchema(),
   },
   minecraft_execute_build_plan: {
-    description: "Compile and execute a structured voxel build plan using the mod's planner, with validation, absolute/player origins, support diagnostics, preview parity via planId, and undo-aware batching.",
+    description: "Compile and execute a structured voxel build plan using the mod's planner, including v2 semantic steps, terrain options, anchor origins, support diagnostics, preview parity via planId, and undo-aware batching.",
     method: "POST",
     path: "/v1/actions/execute_build_plan",
     inputSchema: {
       type: "object",
-      description: "Either provide build_plan explicitly, pass the build_plan object as the root arguments object, or send executePlanId/planId from minecraft_preview_build_plan to execute the exact cached preview unchanged.",
+      description: "Either provide build_plan explicitly, pass the build_plan object as the root arguments object, or send executePlanId/planId from minecraft_preview_build_plan to execute the exact cached preview unchanged. Supports the v2 semantic build vocabulary and terrain flags.",
       additionalProperties: true,
       properties: {
         build_plan: { type: "object", additionalProperties: true },
         executePlanId: { type: "string" },
         planId: { type: "string" },
-        coordMode: { type: "string", enum: ["player", "absolute"] },
+        coordMode: { type: "string", enum: ["player", "absolute", "anchor"] },
         origin: { type: "object", additionalProperties: true },
         offset: { type: "object", additionalProperties: true },
+        anchor: { type: "string" },
         autoFix: { type: "boolean" },
+        snapToGround: { type: "boolean" },
+        flattenTerrain: { type: "boolean" },
+        clearVegetation: { type: "boolean" },
+        options: { type: "object", additionalProperties: true },
       },
     },
   },
@@ -839,23 +849,33 @@ function buildBuildPlanGuide() {
     "",
     "## Common Top-Level Fields",
     "",
-    "- `summary`: short description of the structure",
-    "- `coordMode`: `player` or `absolute`",
-    "- `origin`: explicit origin. In `player` mode it is a relative shift from the player. In `absolute` mode it is a real world origin.",
+    "- `label` or `summary`: short description of the structure",
+    "- `version`: schema version. `2` enables the richer semantic build-plan style.",
+    "- `coordMode`: `player`, `absolute`, or `anchor`",
+    "- `origin`: explicit origin. In `absolute` mode it is a real world origin.",
     "- `offset`: optional extra relative shift applied after the base origin",
+    "- `anchor`: anchor reference such as `last_build:door` when `coordMode=anchor`",
     "- `autoFix`: whether the planner may auto-lower near-ground builds and add limited support repair",
+    "- `snapToGround`: opt-in origin grounding adjustment",
+    "- `flattenTerrain`: opt-in flattening of the footprint to origin Y",
+    "- `clearVegetation`: opt-in clearing of replaceable plants in the footprint",
     "- `rotate`: `0`, `90`, `180`, `270`, `cw`, or `ccw`",
+    "- `options.rotation`: v2 rotation field if you keep metadata under `options`",
+    "- `options.phaseReorder`: default false. If false, step order is sacred.",
     "- `palette`: aliases for block ids, useful for custom mod blocks",
+    "- `anchors`: named relative points created by the build for later attachment",
     "- `clear`: volumes to clear before building",
     "- `cuboids`: bulk structural geometry",
     "- `blocks`: single-block details",
     "- `steps`: phased sub-plans for larger structures",
+    "- Semantic step `type`s: `cuboid`, `hollow_cuboid`, `columns`, `blocks`, `windows`, `roof`, `fill`, `repeat`, `scatter`",
     "",
     "## Coordinate Rules",
     "",
     "- `coordMode=player` means the plan is relative to the active player.",
     "- `coordMode=absolute` means `origin` is an explicit world coordinate and cuboid/block coordinates are relative to that absolute origin.",
-    "- If `coordMode=absolute` is used without `origin`, the planner falls back to the player's current block position and reports that fallback in `repairs`.",
+    "- `coordMode=anchor` means the planner resolves a previously remembered anchor reference such as `last_build:door` or `Some Label:door` and uses that as the base origin.",
+    "- If `coordMode=absolute` is used without `origin`, the planner rejects the plan.",
     "- Positive `x` is east, positive `y` is up, positive `z` is south.",
     "- Keep small test structures close to the origin, for example between `-8` and `8` on x/z.",
     "- The planner clamps X/Z into `[-32, 32]` and Y into `[-24, 24]`. If you exceed that window, the plan is repaired and reported as clamped.",
@@ -889,11 +909,23 @@ function buildBuildPlanGuide() {
     "- `block`",
     "- `material`",
     "- `id`",
+    "- full vanilla-style blockstate strings like `minecraft:oak_stairs[facing=east,half=top]`",
     "",
     "Block properties may be provided as:",
     "- `properties`",
     "- `state`",
     "",
+    "## Semantic Step Vocabulary",
+    "",
+    "- `cuboid`: solid rectangular fill",
+    "- `hollow_cuboid`: shell-only room or wall box",
+    "- `columns`: repeat vertical pillars at listed x/z positions",
+    "- `blocks`: individual entries with exact block ids and optional block states",
+    "- `windows`: semantic glass replacement regions",
+    "- `roof`: declarative roof generator for `flat`, `pyramid`, `gable`, `hip`, or `dome`-style output",
+    "- `repeat`: repeated posts or details using `start`, `step`, and `count`",
+    "- `scatter`: decorative random surface placement in a bounded region",
+    "",
     "## Good Planning Habits",
     "",
     "- Keep plans compact and structural.",
@@ -902,6 +934,8 @@ function buildBuildPlanGuide() {
     "- If terrain is uneven, inspect with `minecraft_buildsite` first.",
     "- If the structure is larger, use `steps` so the plan reads like phases instead of one giant blob.",
     "- Treat `clear` as a surgical pre-build removal step, not a vague instruction to hollow things out automatically.",
+    "- Prefer `hollow_cuboid` for rooms instead of solid-fill-then-air tricks.",
+    "- Prefer `roof` for small structures if you want the planner to own the roof geometry.",
     "",
     "## Minimal Valid Plan",
     "",