vitaminmcp 3.0.0 → 3.0.2

package/README.md

@@ -64,7 +64,7 @@ agent leaves its host, ports and token where this server reads them.
 
 ## What it downloads
 
-On first run, from [the GitHub release](https://github.com/Backas03/VitaminMCP-minecraft/releases)
+On first run, from [the GitHub release](https://github.com/Backas03/VitaminMCP/releases)
 matching this package's version, into `~/.vitaminmcp/jars/<version>/`:
 
 - `mcp-server.jar` (~2 MB) — waited for, since nothing works without it
@@ -83,6 +83,6 @@ Every downloaded file is checked against its pinned SHA-256. A file that does no
 rather than run.
 
 Full documentation, design notes and the plugin itself:
-**[github.com/Backas03/VitaminMCP-minecraft](https://github.com/Backas03/VitaminMCP-minecraft)**
+**[github.com/Backas03/VitaminMCP](https://github.com/Backas03/VitaminMCP)**
 
 MIT.

package/checksums.json

@@ -1,14 +1,14 @@
 {
-  "version": "3.0.0",
+  "version": "3.0.2",
   "jars": {
-    "mcp-server.jar": "576610b6f7deb691fad5633533678ef7a9266574ad731094cc78a01bb24be480"
+    "mcp-server.jar": "452ed2928e9e0a6ddcb25dab4586999012b334f9994a0aff8c305148fde0c7ae"
   },
   "assets": {
-    "bot-runner-win-x64.exe": "1a762d0773269ea3205ccb6816e964f33f3ddd15fd1003c6cadd5af4460572ca",
-    "bot-runner-linux-x64": "a2e975d331461fc699c1998e86a847f8ca161a266caae57c6060bc74bf87569c",
-    "bot-runner-linux-arm64": "31aad6207a268ddb70298ca1eaa2d443c2f097e1e5b714a2db6b40eea57ec749",
-    "bot-runner-darwin-x64": "573eb872b1965fe6b8575611f42336fd4dda436e749196e4a1373cffd2939bde",
-    "bot-runner-darwin-arm64": "853183f7da381f9b831aef9824c69563a732205c61d300fad908cd0f502a73e0",
+    "bot-runner-win-x64.exe": "d263637058d5e4a894d1765cfa79de528774a36d9d4c5132c0bb5e9c5b1ae0d0",
+    "bot-runner-linux-x64": "dcac4f6a1e7c9ad9228a95cee4a59925973616eab9214b4bc81ad338ae398de5",
+    "bot-runner-linux-arm64": "08642a57deec10a1d967bc95e5e4fc35cfb4de5cdcd31c391f90829fdc569ac7",
+    "bot-runner-darwin-x64": "0f2e229cbb94ef65ff79336b517489a9c2fa715c42a86e5d4da5a2df510f48ba",
+    "bot-runner-darwin-arm64": "3e570c14a11d0df7eb84bcdce15acb5fbcabbda0f64ceb1c1f389d9ee2a43fef",
     "bot-runner-viewer-win-x64.tgz": "e39a36cdf92b9223aa7c9610f8231afc7a577e8ed007bc3571895bd945baf3e1"
   }
 }

package/lib/jars.mjs

@@ -9,7 +9,7 @@ import { fileURLToPath } from 'node:url';
 
 const HERE = path.dirname(fileURLToPath(import.meta.url));
 
-const RELEASES = 'https://github.com/Backas03/VitaminMCP-minecraft/releases/download';
+const RELEASES = 'https://github.com/Backas03/VitaminMCP/releases/download';
 
 /** The jar this package launches, and the one it launches in turn. */
 export const MCP_SERVER_JAR = 'mcp-server.jar';
@@ -20,7 +20,7 @@ export const VIEWER_ASSET = 'bot-runner-viewer-win-x64.tgz';
 let checksumsPromise;
 let manifestPromise;
 
-const REPORT = 'https://github.com/Backas03/VitaminMCP-minecraft/issues';
+const REPORT = 'https://github.com/Backas03/VitaminMCP/issues';
 
 /**
  * The exact bytes this version of the package expects, stamped in at release.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vitaminmcp",
-  "version": "3.0.0",
+  "version": "3.0.2",
   "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": [
@@ -13,11 +13,11 @@
     "plugin-testing",
     "end-to-end-testing"
   ],
-  "homepage": "https://github.com/Backas03/VitaminMCP-minecraft#readme",
-  "bugs": "https://github.com/Backas03/VitaminMCP-minecraft/issues",
+  "homepage": "https://github.com/Backas03/VitaminMCP#readme",
+  "bugs": "https://github.com/Backas03/VitaminMCP/issues",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/Backas03/VitaminMCP-minecraft.git",
+    "url": "git+https://github.com/Backas03/VitaminMCP.git",
     "directory": "npm"
   },
   "license": "MIT",

package/runner/src/bots.mjs

@@ -5,6 +5,7 @@ import { stopAllViews, stopView as stopBotView, view as startView } from './view
 
 import { collect, forget } from './clientview.mjs';
 import { addressField, identity } from './identity.mjs';
+import { answerResourcePacks, describeProgress, traceProgress } from './join.mjs';
 
 /** How long a bot has to get from a socket to standing in the world. */
 const LOGIN_TIMEOUT_MILLIS = 30_000;
@@ -55,13 +56,19 @@ export class BotRegistry {
     );
     loadPathfinder(bot);
 
+    // Both before anything is awaited. A server can push a resource pack the moment login
+    // succeeds, and a request that arrives before its listener does is a connection that
+    // hangs in configuration until the timeout below gives up on it.
+    answerResourcePacks(bot);
+    const progress = traceProgress(bot);
+
     // Before waiting to join, not after: messages are events, and a plugin that greets or refuses
     // on join says so within a tick of the bot arriving. Attaching afterwards loses exactly the
     // messages most worth having.
     collect(bot, name);
 
     try {
-      await joined(bot, name);
+      await joined(bot, name, progress);
     } catch (failure) {
       quietly(() => bot.end());
       throw failure;
@@ -223,7 +230,7 @@ async function worldKnown(bot, name) {
 }
 
 /** Resolves when the bot is in the world; rejects on a kick, an error, or the timeout. */
-function joined(bot, name) {
+function joined(bot, name, progress) {
   return new Promise((resolve, reject) => {
     const finish = (settleFn, value) => {
       clearTimeout(timer);
@@ -238,7 +245,10 @@ function joined(bot, name) {
     const onError = (error) => finish(reject, error);
 
     const timer = setTimeout(
-      () => finish(reject, new Error(`Bot ${name} did not join within ${LOGIN_TIMEOUT_MILLIS}ms`)),
+      () => finish(reject, new Error(
+        `Bot ${name} did not join within ${LOGIN_TIMEOUT_MILLIS}ms `
+          + `(${describeProgress(bot, progress)})`,
+      )),
       LOGIN_TIMEOUT_MILLIS,
     );
 

package/runner/src/join.mjs

@@ -0,0 +1,93 @@
+/**
+ * Getting a bot from an open socket to standing in the world.
+ *
+ * Since 1.20.2 that path runs through the configuration phase, where the server may hold the
+ * connection open waiting for answers a headless client has no reason to send on its own.
+ * minecraft-protocol answers the vanilla ones (client settings, known packs, finish), and what is
+ * left over is here.
+ */
+
+/**
+ * The client's answers to a resource pack request — vanilla's `ResourcePack.Action` ordinals.
+ *
+ * Only the two used below are named. `DECLINED` is deliberately not among them: a plugin that
+ * forces a pack kicks on a decline, and a bot that cannot join is no better than one that hangs.
+ */
+const ACCEPTED = 3;
+const SUCCESSFULLY_LOADED = 0;
+
+/**
+ * Answers every resource pack the server sends, without downloading it.
+ *
+ * A plugin that pushes a pack from `AsyncPlayerConnectionConfigureEvent` blocks that connection
+ * until the client reports what became of the pack, and until then no `PlayerJoinEvent` happens
+ * and no play state is entered. mineflayer only *emits* `resourcePack` and leaves the answer to
+ * the bot author, so a bot that never answers waits out the whole login timeout on a server that
+ * would have let it in. That is what happens on any server hosting its own pack — CraftEngine,
+ * Oraxen, ItemsAdder — which is most of them.
+ *
+ * Nothing is fetched: the URL is usually only reachable from inside the network the server is on,
+ * and a test bot has no use for textures. `SUCCESSFULLY_LOADED` is what a client that applied the
+ * pack reports, and it is the only answer that satisfies both a required pack and an optional one.
+ *
+ * `bot.acceptResourcePack()` is not used for this. It answers with mineflayer's own tracked
+ * `latestUUID`, which is a `uuid-1345` object where the protocol writer expects the string form —
+ * it serialises to the nil UUID, naming a pack the server has never heard of, and the connection
+ * goes on waiting. The uuid is echoed straight back off the request here instead.
+ */
+export function answerResourcePacks(bot) {
+  const client = bot._client;
+
+  const answer = (request) => {
+    // ACCEPTED first, then the terminal result, in the order a real client reports them: a server
+    // that tracks the intermediate state sees the same sequence it would see from a player.
+    send(client, request, ACCEPTED);
+    send(client, request, SUCCESSFULLY_LOADED);
+  };
+
+  // 1.20.3 renamed the request and started identifying packs by uuid; both names are registered
+  // because only one of them exists in any given version's protocol.
+  client.on('add_resource_pack', answer);
+  client.on('resource_pack_send', answer);
+}
+
+/** One response, built from whatever identified the request, since that differs by version. */
+function send(client, request, result) {
+  const response = { result };
+  if (request?.uuid !== undefined) {
+    response.uuid = request.uuid;
+  }
+  if (request?.hash !== undefined) {
+    response.hash = request.hash;
+  }
+
+  try {
+    client.write('resource_pack_receive', response);
+  } catch (error) {
+    // A bot that cannot answer is about to time out with a message that says where it stopped.
+    // Throwing from a packet handler would instead take the whole runner, and every other bot in
+    // it, down with an unhandled error.
+    process.stderr.write(`could not answer a resource pack request: ${error?.message ?? error}\n`);
+  }
+}
+
+/**
+ * Records how far a connection got, so a failure can say so.
+ *
+ * `did not join within 30000ms` is the same sentence whether the server refused the handshake,
+ * dropped the login, or is sitting in configuration waiting for something. The protocol state and
+ * the last packet that arrived separate those three at a glance, and cost one listener.
+ */
+export function traceProgress(bot) {
+  const trace = { packet: null };
+  bot._client.on('packet', (_data, meta) => {
+    trace.packet = meta?.name ?? null;
+  });
+  return trace;
+}
+
+/** Where the connection had got to, in the words the protocol uses for it. */
+export function describeProgress(bot, trace) {
+  return `last state: ${bot._client?.state ?? 'unknown'}, `
+    + `last packet received: ${trace?.packet ?? 'none'}`;
+}