vitaminmcp 2.2.0 → 3.0.0

package/README.md

@@ -60,6 +60,7 @@ agent leaves its host, ports and token where this server reads them.
 | `VITAMINMCP_RUNNER_JAR` | use this runner path instead of automatic selection |
 | `VITAMINMCP_NODE` | Node executable for the source runner fallback |
 | `VITAMINMCP_NODE_RUNNER` | bundled `runner.mjs` path when Node is available |
+| `VITAMINMCP_VIEWER_PATH` | local viewer module to use instead of the pinned optional asset |
 
 ## What it downloads
 
@@ -71,8 +72,15 @@ matching this package's version, into `~/.vitaminmcp/jars/<version>/`:
 - otherwise one platform runner asset (`win-x64`, `linux-x64`, `linux-arm64`, `darwin-x64` or
   `darwin-arm64`), checked against a SHA-256 pinned into this package
 
-Both are checked against a SHA-256 pinned into this package at publish time. A file that does not
-match is deleted rather than run.
+The trimmed `bot-runner-viewer-win-x64.tgz` is separate and is downloaded into
+`~/.vitaminmcp/assets/<version>/` only when `bot_view` asks for a world view. It is checked against
+the SHA-256 pinned into this package at publish time, extracted on first use, and never fetched by
+an installation that only spawns bots or uses the inventory viewer. The current native viewer asset
+is Windows x64; on Linux and macOS, set `VITAMINMCP_VIEWER_PATH` to a local sidecar until those
+assets are released.
+
+Every downloaded file is checked against its pinned SHA-256. A file that does not match is deleted
+rather than run.
 
 Full documentation, design notes and the plugin itself:
 **[github.com/Backas03/VitaminMCP-minecraft](https://github.com/Backas03/VitaminMCP-minecraft)**

package/bin/vitaminmcp.mjs

@@ -10,7 +10,7 @@ import {
   MCP_SERVER_JAR, assetPath, ensureAsset, ensureJar,
 } from '../lib/jars.mjs';
 import { checkJava, findJava } from '../lib/java.mjs';
-import { checkNode, findNode, runnerAssetName } from '../lib/node.mjs';
+import { checkNode, findNode, runnerAssetName, viewerAssetName } from '../lib/node.mjs';
 
 const HERE = path.dirname(fileURLToPath(import.meta.url));
 
@@ -91,6 +91,13 @@ async function main() {
   const configuredRunner = process.env.VITAMINMCP_RUNNER_JAR;
   const node = findNode();
   const nodeCheck = checkNode(node);
+  let viewerAsset;
+  try {
+    viewerAsset = viewerAssetName();
+  } catch {
+    // The source runner can still be used on platforms whose native viewer asset is not released.
+    viewerAsset = '';
+  }
   const sourceRunner = process.env.VITAMINMCP_NODE_RUNNER
     ?? path.join(HERE, '..', 'runner', 'runner.mjs');
   let runner;
@@ -114,7 +121,7 @@ async function main() {
   }
 
   await runnerReady;
-  return await run(java, server, runner);
+  return await run(java, server, runner, release, viewerAsset);
 }
 
 /**
@@ -124,10 +131,20 @@ async function main() {
  * `.part` file it leaves is claimed again by the next start, and a client waiting on a process
  * that no longer serves anything is worse than a jar fetched twice.
  */
-function run(java, server, runner) {
+function run(java, server, runner, release, viewerAsset) {
+  const env = {
+    ...process.env,
+    VITAMINMCP_RUNNER_JAR: runner,
+    VITAMINMCP_VERSION: release,
+    VITAMINMCP_VIEWER_ASSET: viewerAsset,
+  };
+  // The loader imports the pinned archive only when the Node runner receives bot_view(world).
+  if (!env.VITAMINMCP_VIEWER_PATH) {
+    env.VITAMINMCP_VIEWER_PATH = path.join(HERE, '..', 'lib', 'viewer-loader.mjs');
+  }
   const child = spawn(java, ['-jar', server], {
     stdio: 'inherit',
-    env: { ...process.env, VITAMINMCP_RUNNER_JAR: runner },
+    env,
   });
 
   return new Promise((resolve) => {

package/checksums.json

@@ -1,9 +1,14 @@
 {
-  "version": "2.2.0",
+  "version": "3.0.0",
   "jars": {
-    "mcp-server.jar": "27f1543ced4e59ed6501aa4238eab76473cbf4ff1612a4622b5bb27455447685"
+    "mcp-server.jar": "576610b6f7deb691fad5633533678ef7a9266574ad731094cc78a01bb24be480"
   },
   "assets": {
-    "bot-runner-win-x64.exe": "82438774fc5b43e1a348daade6cc22e5be1e97f39cd63ee8b8b65afa242b2109"
+    "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-viewer-win-x64.tgz": "e39a36cdf92b9223aa7c9610f8231afc7a577e8ed007bc3571895bd945baf3e1"
   }
 }

package/lib/jars.mjs

@@ -14,6 +14,9 @@ const RELEASES = 'https://github.com/Backas03/VitaminMCP-minecraft/releases/down
 /** The jar this package launches, and the one it launches in turn. */
 export const MCP_SERVER_JAR = 'mcp-server.jar';
 
+/** The optional viewer archive fetched only when a world view is requested. */
+export const VIEWER_ASSET = 'bot-runner-viewer-win-x64.tgz';
+
 let checksumsPromise;
 let manifestPromise;
 

package/lib/node.mjs

@@ -33,11 +33,21 @@ export function checkNode(node) {
 /** The release asset name for the current SEA target. */
 export function runnerAssetName(platform = process.platform, arch = process.arch) {
   if (platform === 'win32' && arch === 'x64') return 'bot-runner-win-x64.exe';
+  if (platform === 'linux' && arch === 'x64') return 'bot-runner-linux-x64';
+  if (platform === 'linux' && arch === 'arm64') return 'bot-runner-linux-arm64';
+  if (platform === 'darwin' && arch === 'x64') return 'bot-runner-darwin-x64';
+  if (platform === 'darwin' && arch === 'arm64') return 'bot-runner-darwin-arm64';
+  throw new Error(`No VitaminMCP runner asset exists for ${platform}-${arch}.`);
+}
+
+/** The optional world-view asset for the platforms currently published. */
+export function viewerAssetName(platform = process.platform, arch = process.arch) {
+  if (platform === 'win32' && arch === 'x64') return 'bot-runner-viewer-win-x64.tgz';
   if (platform === 'linux' || platform === 'darwin') {
     throw new Error(
-      `Native runner assets for ${platform}-${arch} are planned but not released yet. `
-        + 'Install Node 18.17 or later to use the source runner.',
+      `Optional world viewer assets for ${platform}-${arch} are planned but not released yet. `
+        + 'Set VITAMINMCP_VIEWER_PATH to a local prismarine-viewer sidecar.',
     );
   }
-  throw new Error(`No VitaminMCP runner asset exists for ${platform}-${arch}.`);
+  throw new Error(`No VitaminMCP world viewer asset exists for ${platform}-${arch}.`);
 }

package/lib/viewer-loader.mjs

@@ -0,0 +1,74 @@
+/**
+ * Lazy bridge from the npm launcher's pinned asset fetcher to the Node runner's viewer import.
+ *
+ * This module is imported only when `bot_view` asks for a world view. The normal runner startup
+ * therefore never downloads or extracts the optional viewer archive.
+ */
+
+import { spawn } from 'node:child_process';
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+import {
+  assetCacheDirectory,
+  ensureAsset,
+} from './jars.mjs';
+
+const version = process.env.VITAMINMCP_VERSION;
+if (!version) throw new Error('VITAMINMCP_VERSION is required to load the optional viewer asset.');
+const asset = process.env.VITAMINMCP_VIEWER_ASSET;
+if (!asset) {
+  throw new Error(
+    'No packaged world viewer asset exists for this platform. '
+      + 'Set VITAMINMCP_VIEWER_PATH to a local prismarine-viewer sidecar.',
+  );
+}
+
+const archive = await ensureAsset(version, asset, {
+  log: (message) => process.stderr.write(`[vitaminmcp] ${message}\n`),
+});
+const extractionRoot = path.join(assetCacheDirectory(version), 'viewer');
+const entry = path.join(extractionRoot, 'package', 'node_modules', 'prismarine-viewer', 'index.js');
+const marker = path.join(extractionRoot, '.ready');
+
+if (!(await exists(marker)) || !(await exists(entry))) {
+  await fs.rm(extractionRoot, { recursive: true, force: true });
+  await fs.mkdir(extractionRoot, { recursive: true });
+  await extract(archive, extractionRoot);
+  if (!(await exists(entry))) {
+    throw new Error(`The viewer asset did not contain ${entry}.`);
+  }
+  await fs.writeFile(marker, 'ready\n');
+}
+
+const viewerModule = await import(pathToFileURL(entry).href);
+const viewer = viewerModule.default ?? viewerModule;
+
+export default viewer;
+export const mineflayer = viewer.mineflayer;
+export const supportedVersions = viewer.supportedVersions;
+
+async function exists(file) {
+  try {
+    await fs.access(file);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function extract(file, directory) {
+  return new Promise((resolve, reject) => {
+    const child = spawn('tar', ['-xzf', file, '-C', directory], {
+      stdio: ['ignore', 'ignore', 'pipe'],
+    });
+    let error = '';
+    child.stderr.on('data', (chunk) => { error += chunk; });
+    child.once('error', reject);
+    child.once('close', (code) => {
+      if (code === 0) resolve();
+      else reject(new Error(`Could not extract viewer asset (tar exited ${code}): ${error}`));
+    });
+  });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vitaminmcp",
-  "version": "2.2.0",
+  "version": "3.0.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

@@ -51,6 +51,12 @@ const DIG_ACK_TIMEOUT_MILLIS = 1500;
 /** How long the resulting block change gets to come back after the confirmation. */
 const DIG_SETTLE_MILLIS = 300;
 
+/** How long a client gets to receive the block before an interaction is sent. */
+const BLOCK_KNOWN_TIMEOUT_MILLIS = 15_000;
+
+/** One client tick for a block update already queued by a preceding server command. */
+const BLOCK_UPDATE_SETTLE_MILLIS = 50;
+
 /**
  * Breaks a block, and says what became of the attempt.
  *
@@ -158,7 +164,7 @@ export function chat(bot, name, message) {
 }
 
 /** Right-clicks a block — which is how a container or a plugin menu gets opened. */
-export function useBlock(bot, name, x, y, z, face) {
+export async function useBlock(bot, name, x, y, z, face) {
   requireInWorld(bot, name);
 
   const direction = !face || !face.trim() ? FACES.up : FACES[face.trim().toLowerCase()];
@@ -168,6 +174,9 @@ export function useBlock(bot, name, x, y, z, face) {
     );
   }
 
+  const location = new Vec3(x, y, z);
+  await blockKnown(bot, name, location);
+
   bot._client.write('block_place', {
     hand: MAIN_HAND,
     location: { x, y, z },
@@ -181,6 +190,33 @@ export function useBlock(bot, name, x, y, z, face) {
   });
 }
 
+/**
+ * Waits until the client has a block record for an interaction target.
+ *
+ * <p>A console command can change a block before its block update reaches the bot. Sending the
+ * interaction in that gap is legal at the protocol level, but the client has not loaded the target
+ * yet and Paper may drop the window-opening packet. This was the intermittent compatibility
+ * failure on the otherwise deterministic chest check.
+ */
+async function blockKnown(bot, name, location) {
+  const deadline = Date.now() + BLOCK_KNOWN_TIMEOUT_MILLIS;
+  while (Date.now() < deadline) {
+    if (bot.blockAt(location)) {
+      // A command_exec that changed this block has already completed on the server, but the
+      // corresponding packet may still be queued on the bot socket. Give that one client tick
+      // a chance to settle before sending the interaction packet.
+      await delay(BLOCK_UPDATE_SETTLE_MILLIS);
+      return;
+    }
+    await delay(50);
+  }
+
+  throw new Error(
+    `Bot ${name} was not told about the block at ${location.x} ${location.y} ${location.z} within `
+      + `${BLOCK_KNOWN_TIMEOUT_MILLIS}ms`,
+  );
+}
+
 /** Right-clicks the nearest entity to a point, and returns which one it was. */
 export function useEntity(bot, name, x, y, z, radius, type) {
   requireInWorld(bot, name);

package/runner/src/bots.mjs

@@ -3,7 +3,7 @@ import { configurePathfinder, loadPathfinder, moveTo } from './movement.mjs';
 import { reachable } from './movement.mjs';
 import { stopAllViews, stopView as stopBotView, view as startView } from './viewer.mjs';
 
-import { collect } from './clientview.mjs';
+import { collect, forget } from './clientview.mjs';
 import { addressField, identity } from './identity.mjs';
 
 /** How long a bot has to get from a socket to standing in the world. */
@@ -58,7 +58,7 @@ export class BotRegistry {
     // 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);
+    collect(bot, name);
 
     try {
       await joined(bot, name);
@@ -108,6 +108,7 @@ export class BotRegistry {
       return;
     }
     this.#bots.delete(name);
+    forget(name);
     stopBotView(bot);
     quietly(() => bot.quit());
   }
@@ -119,7 +120,8 @@ export class BotRegistry {
   /** Disconnects every bot. */
   shutdown() {
     stopAllViews();
-    for (const bot of this.#bots.values()) {
+    for (const [name, bot] of this.#bots) {
+      forget(name);
       quietly(() => bot.quit());
     }
     this.#bots.clear();

package/runner/src/clientview.mjs

@@ -1,3 +1,5 @@
+import { randomUUID } from 'node:crypto';
+
 import { menu } from './actions.mjs';
 import { plainText, stripLegacyCodes, untag } from './text.mjs';
 
@@ -20,27 +22,63 @@ const MAX_MESSAGES = 100;
 
 const state = new WeakMap();
 
+/**
+ * The active message stream for each bot name.
+ *
+ * Each client connection gets a random id, so a cursor cannot be mistaken for one from another
+ * session, runner process or same-named replacement bot.
+ */
+const messageStreamsByName = new Map();
+
+/**
+ * Drops the message stream a despawned bot left behind.
+ *
+ * The stream outlives the bot on purpose while a replacement is connecting, but a bot that is gone
+ * for good would otherwise keep its entry for the lifetime of the runner. The next bot of the same
+ * name gets a new id either way, so nothing that survives here is ever reused.
+ */
+export function forget(name) {
+  const stream = messageStreamsByName.get(name);
+  if (stream) stream.activeCollector = null;
+  messageStreamsByName.delete(name);
+}
+
 /**
  * Starts collecting what the server tells this bot.
  *
  * Must be called as soon as the bot exists: this is all events, so anything said before the
  * listeners attach is gone, and a plugin greets or refuses within a tick of the bot arriving.
  */
-export function collect(bot) {
+export function collect(bot, name) {
+  const previous = messageStreamsByName.get(name);
+  if (previous) previous.activeCollector = null;
+
+  const stream = { id: randomUUID(), nextSequence: 0, activeCollector: null };
+
   const own = {
     messages: [],
     bossBars: new Map(),
     objectiveTitles: new Map(),
     objectiveScores: new Map(),
     sidebar: null,
+    messageStream: stream,
   };
+  stream.activeCollector = own;
+  messageStreamsByName.set(name, stream);
   state.set(bot, own);
 
   const remember = (text) => {
+    // Closing a replaced bot is asynchronous. Ignore anything its socket delivers after the new
+    // bot took over, otherwise an invisible message would consume a sequence and look like loss.
+    if (stream.activeCollector !== own) {
+      return;
+    }
     if (text == null || String(text).trim() === '') {
       return;
     }
-    own.messages.push(String(text));
+    const sequence = stream.nextSequence;
+    stream.nextSequence += 1;
+    own.messages.push({ sequence, timestamp: Date.now(), text: String(text) });
     while (own.messages.length > MAX_MESSAGES) {
       own.messages.shift();
     }
@@ -90,10 +128,13 @@ export function collect(bot) {
 /** Everything the client was told, in the shape `RunnerDispatch` writes. */
 export function inspect(bot, name) {
   const own = state.get(bot) ?? { messages: [], bossBars: new Map() };
+  const stream = own.messageStream ?? messageStreamsByName.get(name);
   return {
     menu: menu(bot, name),
     items: menuItems(bot),
     messages: [...own.messages],
+    nextMessageSequence: stream?.nextSequence ?? 0,
+    messageStreamId: stream?.id ?? '',
     bossBars: [...own.bossBars.values()],
     scoreboard: sidebarOf(own),
     health: Number.isFinite(bot.health) ? bot.health : null,

package/runner/src/dispatch.mjs

@@ -86,7 +86,7 @@ export class Dispatch {
       }
 
       case protocol.USE: {
-        actions.useBlock(
+        await actions.useBlock(
           this.#bots.require(command[1]),
           command[1],
           Number(command[2]),
@@ -208,7 +208,7 @@ export class Dispatch {
           String(open === null ? -1 : open.containerId),
           open === null ? '' : protocol.sanitize(open.title),
           items(view.items),
-          recordList(view.messages),
+          messageList(view.messages),
           bossBarList(view.bossBars),
           board === null ? '' : protocol.sanitize(board.title),
           board === null ? '' : recordList(board.lines),
@@ -218,6 +218,8 @@ export class Dispatch {
           view.totalExperience == null ? '' : String(view.totalExperience),
           view.experienceProgress == null ? '' : protocol.javaFloat(view.experienceProgress),
           recordList(view.effects),
+          String(view.nextMessageSequence),
+          protocol.sanitize(view.messageStreamId),
         );
       }
 
@@ -264,6 +266,17 @@ function items(list) {
     .join(protocol.RECORD_SEPARATOR);
 }
 
+/** `sequence ␟ timestamp ␟ text`, oldest first, joined by ␞. */
+function messageList(messages) {
+  return messages
+    .map((message) => [
+      message.sequence,
+      message.timestamp,
+      protocol.sanitize(message.text),
+    ].join(protocol.UNIT_SEPARATOR))
+    .join(protocol.RECORD_SEPARATOR);
+}
+
 /** `title ␟ progress ␟ colour`, one record each. */
 function bossBarList(bars) {
   return bars