vitaminmcp 2.1.1 → 2.2.0

package/checksums.json

@@ -1,9 +1,9 @@
 {
-  "version": "2.1.1",
+  "version": "2.2.0",
   "jars": {
-    "mcp-server.jar": "fb87cad80a91518def06f89eaf82a277531b62caf9dc0d1f3f7a6ef17bda357a"
+    "mcp-server.jar": "27f1543ced4e59ed6501aa4238eab76473cbf4ff1612a4622b5bb27455447685"
   },
   "assets": {
-    "bot-runner-win-x64.exe": "15efc844b70a6cdbe190bec4420e31eacabf3d5e77596d81a38f99e3169929d9"
+    "bot-runner-win-x64.exe": "82438774fc5b43e1a348daade6cc22e5be1e97f39cd63ee8b8b65afa242b2109"
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vitaminmcp",
-  "version": "2.1.1",
+  "version": "2.2.0",
   "mcpName": "io.github.Backas03/vitaminmcp",
   "description": "MCP server for testing Minecraft plugins: drives a real Paper server and real protocol bots from an AI agent.",
   "keywords": [

package/runner/src/actions.mjs

@@ -45,24 +45,93 @@ function requireInWorld(bot, name) {
   }
 }
 
-export function breakBlock(bot, name, x, y, z) {
+/** How long the server gets to confirm a dig before it counts as never having arrived. */
+const DIG_ACK_TIMEOUT_MILLIS = 1500;
+
+/** How long the resulting block change gets to come back after the confirmation. */
+const DIG_SETTLE_MILLIS = 300;
+
+/**
+ * Breaks a block, and says what became of the attempt.
+ *
+ * <p>This used to write two packets and answer `sent`, which made a dig the server cancelled and
+ * a dig the server never received the same observation — and a plugin that cancels
+ * BlockBreakEvent silently is exactly the thing someone reaches for this tool to find. A whole
+ * dogfooding round went on telling those apart by hand (dogfood/JOURNAL.md, 2026-08-23).
+ *
+ * <p>The server settles it for us. Every block action carries a sequence number, and the server
+ * answers with the highest one it has resolved — that is what the field is for, so the client
+ * knows when to stop predicting and accept what it is told. An acknowledgement means the dig
+ * reached the world and was dealt with; the block then says whether it was allowed.
+ */
+export async function breakBlock(bot, name, x, y, z) {
   requireInWorld(bot, name);
   const location = { x, y, z };
+  const at = new Vec3(x, y, z);
+
+  const before = bot.blockAt(at)?.name ?? null;
+  if (before === null) {
+    // Not a refusal and not a failure to send: this client has never been told what is there,
+    // which usually means it has only just joined and its chunks have not arrived.
+    return `the bot's client has no block at ${x}, ${y}, ${z} yet, so nothing was dug`;
+  }
+
+  const started = nextSequence(bot);
+  const finished = nextSequence(bot);
+
+  // Registered before the packets go out. The acknowledgement can come back inside the same tick.
+  const confirmed = acknowledgement(bot, finished);
 
   bot._client.write('block_dig', {
     status: START_DIGGING,
     location,
     face: FACES.up,
-    sequence: nextSequence(bot),
+    sequence: started,
   });
   bot._client.write('block_dig', {
     status: FINISH_DIGGING,
     location,
     face: FACES.up,
-    sequence: nextSequence(bot),
+    sequence: finished,
+  });
+
+  if (!await confirmed) {
+    return `the server did not acknowledge the dig within ${DIG_ACK_TIMEOUT_MILLIS}ms, `
+      + 'so it never reached the world';
+  }
+
+  await delay(DIG_SETTLE_MILLIS);
+  const after = bot.blockAt(at)?.name ?? null;
+
+  return after === before
+    ? `the server acknowledged the dig and left ${before} in place, so something refused it`
+    : `broke ${before}`;
+}
+
+/** Resolves true once the server says it has resolved everything up to `sequence`. */
+function acknowledgement(bot, sequence) {
+  return new Promise((resolve) => {
+    const finish = (value) => {
+      clearTimeout(timer);
+      bot._client.removeListener('acknowledge_player_digging', onAcknowledged);
+      resolve(value);
+    };
+
+    const onAcknowledged = (packet) => {
+      if (packet?.sequenceId >= sequence) {
+        finish(true);
+      }
+    };
+
+    const timer = setTimeout(() => finish(false), DIG_ACK_TIMEOUT_MILLIS);
+    bot._client.on('acknowledge_player_digging', onAcknowledged);
   });
 }
 
+function delay(millis) {
+  return new Promise((resolve) => setTimeout(resolve, millis));
+}
+
 /** Runs a command as the bot. The leading slash is not part of the packet. */
 export function command(bot, name, line) {
   requireInWorld(bot, name);

package/runner/src/bots.mjs

@@ -16,6 +16,9 @@ const SETTLE_TIMEOUT_MILLIS = 15_000;
 const SETTLED_CHECKS = 5;
 const SETTLE_POLL_MILLIS = 50;
 
+/** How long the client gets to be sent the chunk it is standing in. */
+const WORLD_TIMEOUT_MILLIS = 15_000;
+
 /** The bots this runner holds, and the server they all connect to. */
 export class BotRegistry {
   #host;
@@ -73,6 +76,7 @@ export class BotRegistry {
     this.#bots.set(name, bot);
     configurePathfinder(bot);
     await settle(bot, name);
+    await worldKnown(bot, name);
     return position(bot);
   }
 
@@ -186,6 +190,36 @@ async function settle(bot, name) {
   );
 }
 
+/**
+ * Waits until the bot's client knows the world it is standing in.
+ *
+ * `spawn` fires on the position packet, which can arrive before the chunk does. A bot that acts in
+ * that gap sends block actions against blocks it has never been told about, and the server answers
+ * with nothing at all — indistinguishable, from the caller's side, from a plugin cancelling the
+ * action silently. A dogfooding round spent most of itself on that ambiguity
+ * (dogfood/JOURNAL.md, 2026-08-23).
+ *
+ * This closes the client half. The server half — a plugin, or Paper itself, dropping interactions
+ * from a player who has only just joined — cannot be waited out from here, and is why
+ * `breakBlock` reports whether the server acknowledged the dig.
+ */
+async function worldKnown(bot, name) {
+  const deadline = Date.now() + WORLD_TIMEOUT_MILLIS;
+
+  while (Date.now() < deadline) {
+    const at = bot.entity?.position;
+    if (at && bot.blockAt(at.offset(0, -1, 0))) {
+      return;
+    }
+    await delay(SETTLE_POLL_MILLIS);
+  }
+
+  throw new Error(
+    `Bot ${name} joined but its client was never sent the world around it within `
+      + `${WORLD_TIMEOUT_MILLIS}ms`,
+  );
+}
+
 /** Resolves when the bot is in the world; rejects on a kick, an error, or the timeout. */
 function joined(bot, name) {
   return new Promise((resolve, reject) => {

package/runner/src/dispatch.mjs

@@ -64,14 +64,15 @@ export class Dispatch {
       }
 
       case protocol.BREAK: {
-        actions.breakBlock(
+        // Carries what became of the dig, which is the whole point of waiting for it.
+        const outcome = await actions.breakBlock(
           this.#bots.require(command[1]),
           command[1],
           Number(command[2]),
           Number(command[3]),
           Number(command[4]),
         );
-        return ok(verb);
+        return protocol.encode(protocol.OK, verb, outcome);
       }
 
       case protocol.COMMAND: {