vitaminmcp 2.1.1 → 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.1.1",
+  "version": "3.0.0",
   "jars": {
-    "mcp-server.jar": "fb87cad80a91518def06f89eaf82a277531b62caf9dc0d1f3f7a6ef17bda357a"
+    "mcp-server.jar": "576610b6f7deb691fad5633533678ef7a9266574ad731094cc78a01bb24be480"
   },
   "assets": {
-    "bot-runner-win-x64.exe": "15efc844b70a6cdbe190bec4420e31eacabf3d5e77596d81a38f99e3169929d9"
+    "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.1.1",
+  "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

@@ -45,24 +45,99 @@ 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;
+
+/** 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.
+ *
+ * <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);
@@ -89,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()];
@@ -99,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 },
@@ -112,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. */
@@ -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;
@@ -55,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);
@@ -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);
   }
 
@@ -104,6 +108,7 @@ export class BotRegistry {
       return;
     }
     this.#bots.delete(name);
+    forget(name);
     stopBotView(bot);
     quietly(() => bot.quit());
   }
@@ -115,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();
@@ -186,6 +192,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/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

@@ -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: {
@@ -85,7 +86,7 @@ export class Dispatch {
       }
 
       case protocol.USE: {
-        actions.useBlock(
+        await actions.useBlock(
           this.#bots.require(command[1]),
           command[1],
           Number(command[2]),
@@ -207,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),
@@ -217,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),
         );
       }
 
@@ -263,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