Finish absolute build-plan execution and auto-fix flow

Author: aaronaalmendarez

README.md

@@ -392,6 +392,12 @@ The build-plan tool accepts either:
 - a root object that is itself the build plan
 - 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
+- `offset`: optional extra relative shift after the base origin
+- `autoFix`: allows safe grounding fixes like small auto-lowers and limited support repair
+
 Minimal example:
 
 ```json
@@ -418,20 +424,27 @@ 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`.
 - `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.
 - `clear` volumes remove space before building and use the same bounds formats as cuboids, but without a block id.
 - `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`.
-- The planner can auto-add support pillars using `minecraft:stone_bricks`, but only up to 24 lowest columns. Beyond that, the agent should add an explicit foundation or split the build into phases.
+- 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.
+- `resolvedOrigin` in the result tells you the exact world origin that was actually used.
+- `autoFixAvailable` tells you whether the planner believes a safe grounding fix exists.
 
 If an agent gets a support-pillar failure, the correct response is usually:
 
 1. Re-read `minecraft_buildsite`
-2. Lower the build or move the player to the intended surface level
-3. Add a foundation phase in `steps`
-4. Retry with a grounded plan
+2. Inspect `issues` and `suggestedY`
+3. Lower the build or move the player to the intended surface level
+4. Add a foundation phase in `steps`
+5. Retry with a grounded plan
 
 Do not keep retrying the same floating `y=0` structure and assume the JSON schema is wrong.
 
@@ -445,9 +458,20 @@ For terrain-sensitive or unfamiliar builds, agents should use:
    - `repairs`
    - `appliedRotation`
    - `phaseCount`
+   - `resolvedOrigin`
+   - `issues`
    - `previewCommands`
-4. Revise the plan if needed
-5. Then call `minecraft_execute_build_plan`
+4. Save the returned `planId` if the preview looks good
+5. Revise the plan if needed
+6. Then call `minecraft_execute_build_plan`
+
+Best practice is:
+
+```json
+{ "executePlanId": "plan-..." }
+```
+
+That makes execute run the exact cached preview instead of recompiling a fresh variant.
 
 `minecraft_preview_build_plan` uses the same planner and command validation as the real build path, but it does not mutate the world and does not create an undo batch.
 

run-mcp-sidecar-node.js

@@ -302,14 +302,20 @@ const TOOLS = {
     inputSchema: objectSchema(),
   },
   minecraft_preview_build_plan: {
-    description: "Compile and validate a structured voxel build plan without executing it, returning repairs, preview commands, rotation, and phase data.",
+    description: "Compile and validate a structured voxel build plan without executing it, returning 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.",
+      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.",
       additionalProperties: true,
-      properties: {},
+      properties: {
+        build_plan: { type: "object", additionalProperties: true },
+        coordMode: { type: "string", enum: ["player", "absolute"] },
+        origin: { type: "object", additionalProperties: true },
+        offset: { type: "object", additionalProperties: true },
+        autoFix: { type: "boolean" },
+      },
     },
   },
   minecraft_highlight: {
@@ -319,14 +325,22 @@ const TOOLS = {
     inputSchema: highlightSchema(),
   },
   minecraft_execute_build_plan: {
-    description: "Compile and execute a structured voxel build plan using the mod's planner, with validation, rotation, support repair, and undo-aware batching.",
+    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.",
     method: "POST",
     path: "/v1/actions/execute_build_plan",
     inputSchema: {
       type: "object",
-      description: "Either provide build_plan explicitly or pass the build_plan object as the root arguments 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.",
       additionalProperties: true,
-      properties: {},
+      properties: {
+        build_plan: { type: "object", additionalProperties: true },
+        executePlanId: { type: "string" },
+        planId: { type: "string" },
+        coordMode: { type: "string", enum: ["player", "absolute"] },
+        origin: { type: "object", additionalProperties: true },
+        offset: { type: "object", additionalProperties: true },
+        autoFix: { type: "boolean" },
+      },
     },
   },
   minecraft_execute_commands: {
@@ -729,6 +743,10 @@ function buildResponseFieldsForTool(name) {
         { name: "summary", description: "Planner summary of the build." },
         { name: "appliedRotation", description: "Final normalized rotation." },
         { name: "phaseCount", description: "Number of compiled direct-operation phases." },
+        { name: "resolvedOrigin", description: "Exact world origin the planner actually used." },
+        { name: "issues", description: "Structured floating/grounding issues with cuboid names, gaps, and suggestedY." },
+        { name: "autoFixAvailable", description: "Whether the planner believes a safe grounding fix exists." },
+        { name: "planId", description: "Cached preview id that execute can reuse unchanged via executePlanId." },
         { name: "previewCommands", description: "The exact validated Minecraft commands that would run." },
       ];
     case "minecraft_execute_build_plan":
@@ -742,6 +760,10 @@ function buildResponseFieldsForTool(name) {
         { name: "summary", description: "Planner summary of what was built or attempted." },
         { name: "appliedRotation", description: "Final normalized rotation used: 0, 90, 180, or 270." },
         { name: "phaseCount", description: "How many direct-operation phases the planner compiled." },
+        { name: "resolvedOrigin", description: "Exact world origin the planner actually used." },
+        { name: "issues", description: "Structured floating/grounding issues for failed or revised builds." },
+        { name: "autoFixAvailable", description: "Whether the planner believed a safe grounding fix was available." },
+        { name: "planId", description: "Preview cache id if the build was executed from a cached preview." },
       ];
     default:
       return [];
@@ -818,7 +840,10 @@ function buildBuildPlanGuide() {
     "## Common Top-Level Fields",
     "",
     "- `summary`: short description of the structure",
-    "- `origin` or `offset`: optional relative origin shift",
+    "- `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.",
+    "- `offset`: optional extra relative shift applied after the base origin",
+    "- `autoFix`: whether the planner may auto-lower near-ground builds and add limited support repair",
     "- `rotate`: `0`, `90`, `180`, `270`, `cw`, or `ccw`",
     "- `palette`: aliases for block ids, useful for custom mod blocks",
     "- `clear`: volumes to clear before building",
@@ -828,11 +853,13 @@ function buildBuildPlanGuide() {
     "",
     "## Coordinate Rules",
     "",
-    "- Coordinates are relative to the active player unless you intentionally offset them.",
+    "- `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`.",
     "- 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.",
-    "- `origin`/`offset` still remain relative. They do not switch the planner into unrestricted absolute world coordinates.",
+    "- Absolute `origin` is not clamped into the player's safe window. Relative cuboid/block coordinates still are.",
     "",
     "## Aligning The Build With Real Terrain",
     "",
@@ -841,6 +868,7 @@ function buildBuildPlanGuide() {
     "- In that situation, a plan with its floor at relative `y=0` starts nine blocks above nearby surface and will likely trigger support repairs or failure.",
     "- Best practice: move the player to the intended build level or lower the foundation/floor phase to match the surface you actually want to build on.",
     "- If `clearPercent` is low, do not brute-force retries. Either choose another spot, clear space explicitly, or use a phased plan.",
+    "- If you want a structure at a stable world location, prefer `coordMode=absolute` with an explicit `origin` rather than relying on wherever the player happens to be standing.",
     "",
     "## Accepted Geometry Forms",
     "",
@@ -988,11 +1016,24 @@ function buildBuildPlanGuide() {
     "",
     "## Foundations And Support Pillars",
     "",
-    "- After compiling placements, the planner checks whether the lowest occupied columns have solid terrain below them.",
-    "- If the build is nearly grounded, it can auto-add support pillars using `minecraft:stone_bricks`.",
-    "- Auto-support is capped at 24 columns. If more would be needed, the planner rejects the build and tells the agent to add an explicit foundation or split the build into phases.",
+    "- After compiling placements, the planner checks the lowest support targets, not just the raw command list.",
+    "- It returns structured `issues` identifying which cuboids or block targets are floating, their `gapBelow`, and a `suggestedY` for grounding.",
+    "- Only columns with real air/fluid gaps below them are considered for auto-support pillars.",
+    "- If more than 80% of the lowest-layer columns are within 2 blocks of valid ground and `autoFix=true`, the planner can auto-lower the whole build instead of spamming pillars.",
+    "- Auto-support pillars use `minecraft:stone_bricks` and are capped at 24 columns.",
     "- If there is no valid solid ground below some lowest columns at all, the planner rejects the build and tells the agent to lower the build or add a foundation.",
-    "- This is why repeated retries with the same floating `y=0` plan are the wrong response. Fix the base Y or add a foundation phase instead.",
+    "- Repeated retries with the same floating `y=0` plan are the wrong response. Fix the base Y, add a foundation phase, or use preview issues plus `suggestedY` to revise the plan.",
+    "",
+    "Example issue payload:",
+    "",
+    "```json",
+    "{",
+    "  \"issues\": [",
+    "    {\"cuboid\":\"floor\",\"issue\":\"floating\",\"gapBelow\":14,\"suggestedY\":65}",
+    "  ],",
+    "  \"autoFixAvailable\": true",
+    "}",
+    "```",
     "",
     "## Why Agents Should Prefer Build Plans",
     "",
@@ -1008,9 +1049,12 @@ function buildBuildPlanGuide() {
     "",
     "1. `minecraft_buildsite`",
     "2. `minecraft_preview_build_plan`",
-    "3. Inspect `repairs`, `appliedRotation`, `phaseCount`, and `previewCommands`",
-    "4. Revise if needed",
-    "5. `minecraft_execute_build_plan` only after the preview looks sane",
+    "3. Inspect `repairs`, `appliedRotation`, `phaseCount`, `resolvedOrigin`, `issues`, and `previewCommands`",
+    "4. Keep the returned `planId` if the preview is good",
+    "5. Revise if needed",
+    "6. Execute either the same payload again or, preferably, `minecraft_execute_build_plan {\"executePlanId\":\"...\"}` so the exact cached preview runs unchanged",
+    "",
+    "The `planId` path is the strongest option when preview parity matters because preview and execute then use the same compiled command list.",
     "",
     "## Failure Prevention",
     "",
@@ -1032,6 +1076,10 @@ function buildBuildPlanGuide() {
     "- `summary`: human-readable summary of the compiled build",
     "- `appliedRotation`: final normalized rotation",
     "- `phaseCount`: number of compiled direct-operation phases",
+    "- `resolvedOrigin`: the world origin actually used after coordMode/origin fallback resolution",
+    "- `issues`: structured floating/grounding issues for failing or revised builds",
+    "- `autoFixAvailable`: whether the planner believes a safe grounding fix is available",
+    "- `planId`: returned by preview so execute can run the exact cached plan",
     "",
   ].join("\n");
 }