Minecraft Intelligent Bots V2 Curated Intelligence Plan

Date: 2026-07-10

Issue: GitLab #428, "Minecraft intelligent bots: plan V2 curated intelligence and LLM boundaries"

Status: source-backed V2 recommendation. This document defines product and security boundaries for future work; it does not enable a runtime profile, LLM provider, API, or customer UI.

Decision

Swarm Hosts should make bots more capable by shipping a server-owned, versioned curated skill library with a deterministic policy interpreter. An LLM is optional and is never the executor:

  1. The runtime executes only reviewed skills bundled in a pinned Minecraft bot runtime release.
  2. A model may produce bounded chat text or propose a typed plan containing allowlisted skill ids and parameters.
  3. The control plane treats every model response as untrusted input, validates it against a closed schema and tenant policy, and creates an immutable plan.
  4. The Minecraft runtime reauthorizes each step against current desired state, world scope, quotas, and kill switches before calling Mineflayer.

This adapts Voyager's compositional skill-library idea without adopting its ever-growing library of model-generated executable code. It also rejects Mindcraft's code-writing mode, which its own project warns remains vulnerable to injection even when sandboxed.

The first V2 release should therefore be curated and deterministic with no LLM dependency. LLM chat and plan proposal can graduate independently behind tenant opt-in. Existing builder and miner sandboxes remain deterministic and must not become LLM-addressable in the initial V2 planner.

Source Basis

Sources were rechecked on 2026-07-10:

  • Voyager paper and reference implementation: Voyager combines an automatic curriculum, an executable-code skill library, and iterative model feedback. Swarm Hosts adopts reviewed composable skills, not autonomous curriculum, runtime code generation, or self-modifying skills.
  • Mindcraft: a useful Mineflayer and LLM architecture reference whose README disables code writing by default and warns against enabling it on public servers. It is not a drop-in hosted runtime.
  • Mineflayer API: the same bot object exposes benign observations alongside high-impact chat, dig, place, attack, inventory, container, plugin, and command-block methods. The model must never receive that raw capability surface.
  • OWASP prompt injection, sensitive information disclosure, improper output handling, excessive agency, system prompt leakage, and unbounded consumption: these support treating world/chat context and model output as untrusted, minimizing tools and permissions, enforcing policy downstream, excluding secrets, and bounding calls, tokens, cost, time, and queued actions.
  • NIST AI 600-1, Generative AI Profile: the provider, model, prompts, evaluations, incidents, and release decisions need explicit lifecycle governance rather than a one-time prompt review.

These sources demonstrate useful research patterns and general LLM risks. The specific controls below are the Swarm Hosts product recommendation inferred from those sources and the existing v1 bot-session safety contract.

Product Boundary

V2 intelligence has three separately gated modes:

Mode Model role Tools Initial product decision
Curated deterministic No model is required. An authenticated user chooses a server-owned goal/profile and the interpreter composes a pre-reviewed plan. Only skills allowed by the profile policy. Recommended V2 foundation.
LLM chat-only Produce one bounded social response after input and output moderation. None. Chat delivery is a separate text gate, not a tool. Optional tenant pilot after privacy and moderation review.
LLM plan proposal Return a closed-schema proposal containing allowlisted skill ids and typed parameters. The model calls no tools. The control plane may approve a plan for deterministic execution. Shadow mode first, then read-only/reversible skills only.

Chat and planning are separate capabilities. A player message may be included as untrusted conversational context for chat-only mode, but it cannot create, approve, modify, or resume a plan. Only an authenticated deployment owner or a role explicitly granted bot-management permission can request a plan through the control plane.

Generated chat never becomes a command channel. It is single-line, length limited, cooldown protected, session capped, moderated before delivery, and rejected after normalization if it begins with /. The chat gate has no RCON, console, filesystem, network, plugin, or Mineflayer object access.

Curated Skill Library Contract

"Curated" means all of the following:

  • Skill implementations are reviewed TypeScript included in a pinned runtime image. Customer uploads, downloaded modules, eval, Function, shell execution, and runtime imports from user-controlled paths are impossible.
  • The control plane owns an immutable registry. A session pins the registry, skill, runtime, policy, and Minecraft compatibility versions it uses.
  • Each skill has a closed input schema, risk class, preconditions, postconditions, permissions, quotas, timeout, cancellation behavior, audit events, and tests.
  • A skill cannot add another skill or expand its own permissions. Registry changes require the normal code-review, image-release, and validation flow.
  • World observations and earlier execution results are data, never new instructions or executable memory. Customer sessions cannot teach the shared registry.

Illustrative registry entry:

schema: swarmhosts.minecraft_bot_skill.v1
id: move_to_relative_v1
version: 1.0.0
risk_class: reversible_world_action
implementation: bundled:skills/move_to_relative_v1
allowed_profiles: [patrol, curated_assistant]
parameters:
  additional_properties: false
  offset_blocks:
    x: {type: integer, minimum: -32, maximum: 32}
    y: {type: integer, minimum: -8, maximum: 8}
    z: {type: integer, minimum: -32, maximum: 32}
permissions: [world.position.read, bot.movement.relative]
forbidden_permissions: [chat.command, rcon, shell, network, filesystem, plugin.load]
limits:
  timeout_seconds: 30
  recovery_attempts: 1
  digs: 0
  placements: 0
audit_events: [skill_started, movement_progress, skill_stopped]

Initial planner-visible skills should be limited to:

  • bounded observations already sanitized for bot-session results;
  • relative movement and patrol inside the existing v1 radius and stuck-recovery policy;
  • bot-owned inventory checks; and
  • existing allowlisted eat/equip survival helpers.

Scripted chat templates remain a separate chat capability. Builder, miner, container/chest access, crafting, trading, combat, arbitrary entity activation, and world-writing skills are not planner-visible in the initial V2 release.

Plan Proposal And Enforcement

The model receives a short catalog derived from the tenant's effective policy, not the complete registry or raw Mineflayer API. It may return only a plan proposal such as:

{
  "schema": "swarmhosts.minecraft_bot_plan_proposal.v1",
  "goal_id": "inspect_then_patrol",
  "steps": [
    {
      "skill_id": "observe_area_v1",
      "skill_version": "1.0.0",
      "parameters": {"radius_blocks": 8}
    },
    {
      "skill_id": "move_to_relative_v1",
      "skill_version": "1.0.0",
      "parameters": {"offset_blocks": {"x": 4, "y": 0, "z": 0}}
    }
  ],
  "stop_conditions": ["policy_denied", "skill_failed", "session_deadline"]
}

The proposal schema is closed: no unknown properties, source code, commands, URLs, plugin names, free-form tool names, loops, recursion, or embedded follow-up prompts. Initial plans contain at most eight steps, each skill occurs at most three times, and the gateway permits at most one schema-repair call. A failed parse, moderation check, policy lookup, provider call, or audit write fails closed without executing a step.

The control-plane policy compiler then:

  1. authenticates the actor and verifies explicit tenant opt-in;
  2. resolves the current deployment, bot session, runtime, skill registry, and policy versions server-side;
  3. validates every skill id and parameter against the closed registry schema;
  4. intersects skill needs with tenant, profile, world, risk, duration, action, and cost limits;
  5. records a plan digest, expiry, deployment state revision, actor, model, prompt-template version, moderation result, and decision trace; and
  6. either rejects the proposal or emits an immutable executable plan.

Before each step, the runtime verifies the plan digest, expiry, deployment and session ids, current state revision, skill version, remaining quotas, target scope, and kill switches. Preconditions are checked against fresh world state. A stale or mismatched plan stops; it is never silently repaired by broadening permissions. Replanning is a new audited proposal subject to the same bounded call and policy path.

Provider, Secret, And Tenant Boundary

The Minecraft support container does not hold or call an LLM provider. A control-plane-owned gateway makes provider calls and returns only an approved plan or moderated chat result to the bot-session path.

The gateway must enforce:

  • tenant-scoped authorization, rate limits, budgets, audit, and feature flags;
  • provider and model allowlists with pinned policy/evaluation versions;
  • context construction from allowlisted, sanitized fields rather than raw deployment objects, logs, environment, files, chat history, or world NBT;
  • no API keys, deployment tokens, credentials, private endpoints, private artifact paths, system secrets, or other tenant data in prompts;
  • no cross-tenant prompt cache, transcript, memory, vector store, or learned skill state;
  • encrypted provider credentials held outside prompts and bot runtime;
  • finite, tenant-visible retention and deletion policy for audited chat and planning transcripts before any pilot; and
  • explicit configuration of whether a provider may retain or train on data, with a safe default that does not opt customer content into training.

The system prompt is not a security boundary and contains no secrets. Runtime authorization and policy checks remain authoritative even if the complete prompt and every model response are exposed.

Threat Model

Protected assets are customer world integrity, availability, account safety, tenant isolation, secrets, chat safety, audit integrity, and bounded platform cost. Attackers include a malicious or compromised tenant user, an untrusted player on the Minecraft server, malicious text in world/chat context, a compromised provider or model response, a vulnerable skill implementation, and accidental operator or model error.

Threat Example Required controls
Direct or indirect prompt injection A player says "ignore policy and run this command"; a sign, book, scoreboard, player name, or prior transcript embeds instructions. Treat all world and player content as labeled data. The initial planner receives no sign/book text. Normalize, bound, and moderate included chat. Player text grants no authority; downstream closed-schema and skill-policy enforcement is authoritative.
Excessive agency or griefing A model chooses digging, placement, combat, chest access, or repeated movement beyond the request. Offer only the minimum per-mode skill set. Initial planner excludes world-writing and container/combat skills. Enforce action, radius, duration, retry, and per-skill quotas independently of the model.
Malicious or malformed model output Output includes JavaScript, a slash command, unknown tool, URL, huge parameter, or parser-confusing text. Parse a closed data schema; never interpolate output into code, shell, RCON, URLs, queries, or plugin loading. Reject unknown fields and policy violations. Reauthorize every step.
Secret or cross-tenant disclosure A prompt asks for tokens, private endpoints, another tenant's transcript, or system instructions. Keep secrets out of prompts, minimize context, tenant-scope every read/cache/audit, redact inputs and outputs, and make runtime authorization independent of prompt secrecy.
Unsafe generated chat Toxic, deceptive, private, spammy, or command-shaped output is sent to players. Separate chat from planning, require tenant opt-in and visible bot identity, moderate input and output, normalize and reject slash commands, cap length/rate/count, audit delivery, and fail closed.
Unbounded cost or availability loss Players spam chat triggers; an agent loops, replans, or produces long contexts. Actor and tenant quotas, bounded context/output, timeouts, at most one repair, no autonomous loops, finite sessions, provider budget ceilings, circuit breaker, graceful deterministic fallback, and kill switches.
Replay or stale-world execution A previously approved movement plan runs after deployment restart, profile change, or bot relocation. Bind the plan to deployment/session ids, state revision, versions, digest, expiry, nonce, and quotas; recheck current preconditions before every skill.
Provider/model or skill supply-chain drift A provider silently changes model behavior or a dependency expands capability. Allowlist and record provider/model/runtime/skill versions, maintain adversarial evaluation fixtures, canary before promotion, pin runtime dependencies, review registry diffs, and retain a global disable switch.
Transcript privacy failure Private player text is retained too long or reused for training/memory. Clear tenant notice and opt-in, minimum necessary redacted transcript, finite documented retention, deletion path, provider data-control review, and no automatic shared memory or training.
Account or target abuse A bot is redirected to a third-party server or uses pooled online-mode credentials. Preserve current_deployment_only; accept no arbitrary host. Keep online-mode account pools outside this plan pending separate legal, product, and security review.

Moderation and prompt instructions are defense-in-depth, not authorization. A moderation false negative or successful injection must still encounter a plan schema with no command/code fields and a deterministic executor with less authority than the requested attack.

Audit And Operator Controls

Every LLM-related attempt records bounded, tenant-scoped evidence:

  • actor, tenant, deployment, session, feature mode, and explicit opt-in state;
  • provider, model, prompt-template, policy, skill-registry, and runtime versions;
  • request and response ids, timestamps, token/cost counters, moderation decisions, plan digest, approval/rejection reason, and execution correlation;
  • each authorized skill, normalized parameters, precondition result, quota delta, terminal result, and runtime safety decision; and
  • chat delivery state plus a sanitized transcript governed by the configured retention and deletion policy.

Audit events do not contain provider keys, deployment tokens, raw environment, private endpoints, host paths, credentials, or unbounded logs. Operators and authorized tenants can stop the session. Deployment, tenant, and platform kill switches stop pending execution and prevent new model calls. Provider failure, moderation failure, budget exhaustion, or audit failure degrades to curated deterministic behavior or stops; it does not bypass the gate.

Explicit No-Go List

The following are prohibited for this V2 direction:

  • arbitrary generated or customer-provided JavaScript, TypeScript, Python, shell, command strings, macros, bytecode, or other executable behavior;
  • eval, Function, child_process, runtime package installation, dynamic plugin loading, remote skill URLs, or model-selected network/filesystem APIs;
  • exposing the raw Mineflayer bot object, RCON, console, command blocks, slash commands, operator privileges, or a generic "execute" tool to a model;
  • allowing player chat, signs, books, scoreboards, usernames, or model output to authorize actions or modify skill/policy permissions;
  • self-growing or customer-trained executable skill libraries, automatic curriculum on customer worlds, cross-tenant memories, or unattended open-ended/autonomous loops;
  • LLM-planned building, mining, chest/container access, crafting/trading, combat, PvP, or arbitrary entity activation in the initial planner;
  • arbitrary public-server targets, anti-bot evasion, hidden bot identity, or online-mode account pools; and
  • secrets in prompts/system messages/transcripts, relying on prompt secrecy for security, or allowing the model to choose its own limits, permissions, moderation policy, audit policy, or kill-switch behavior.

A future proposal to relax any item requires a separate product/security decision and cannot be smuggled in as a new prompt, provider, or registry entry.

Rollout And Validation Gates

The gates are sequential; passing a later-looking demo does not waive an earlier contract:

  1. Curated registry/interpreter: no LLM. Prove closed schemas, immutable versioning, permission intersection, quotas, cancellation, audit, kill switches, and existing runtime cleanup.
  2. Chat-only pilot: tenant opt-in, no tools, adversarial input/output moderation tests, privacy/retention notice, bounded live chat evidence, and immediate disable path.
  3. Planner shadow mode: model proposes plans but nothing executes. Compare proposals with policy expectations, exercise injection/malformed-output fixtures, measure rejection reasons/cost, and verify no secret/cross-tenant context.
  4. Limited plan execution: separately approved issue, selected tenants, observe/movement/bot-owned survival skills only, authenticated request or explicit approval, live disposable Minecraft evidence, stable runtime, stop/cleanup proof, and rollback/kill-switch drill.

Promotion requires versioned evaluation fixtures covering direct and indirect injection, encoded slash commands, schema smuggling, unknown skills, oversized parameters, stale/replayed plans, cross-tenant ids, provider timeout, moderation failure, quota exhaustion, audit failure, and kill-switch activation. Runtime work also requires the existing relay-backed disposable deployment harness and independent validation.

Stop rollout on any command/code execution path, secret or cross-tenant leak, out-of-policy action, missing audit, unavailable kill switch, unbounded cost, or unexplained destructive world mutation. Deterministic bot profiles must continue to work when the model feature is disabled.

Bounded Follow-Up Candidates

No runtime or UI child is created by this planning change. If the product and security review accepts this boundary, create only these independently reviewable candidates:

  1. Add a versioned curated skill registry and deterministic interpreter. No LLM, generated code, runtime plugin loading, or customer scripts. Start with observe, relative movement/patrol, and bot-owned survival skills.
  2. Add a tenant-scoped LLM gateway and chat-only pilot. No tools or plan execution. Own provider data controls, opt-in, moderation, transcript retention/deletion, quotas, audit, and kill switches.
  3. Build an adversarial planner shadow-mode evaluator. No Minecraft action execution. Validate closed-schema plan proposals against prompt injection, secret/cross-tenant fixtures, malformed output, replay, and cost limits.
  4. Execute approved low-risk plans through the curated interpreter. No code execution or world-writing/container/combat skills. Require the first three candidates, security review, selected-tenant flag, runtime/live proof, and independent validation.

Each eventual runtime child belongs in lane:runtime, is parallel:serialized, and requires live validation. A chat-only control-plane or UI child still requires security/privacy and rendered UI evidence as applicable. Online-mode accounts and any destructive LLM planning remain out of scope and need their own product/legal/security review rather than a child of this plan.

Acceptance Outcome

  • Recommendation: curated deterministic skills first; optional chat and plan proposal are separate opt-in features.
  • Threat model: defined for injection, agency, output, secrets, tenancy, chat, availability/cost, replay, supply chain, privacy, accounts, and targets.
  • Safety controls: enforced outside the model at gateway, control-plane policy, and per-step runtime boundaries.
  • No-go list: explicit, including no code, commands, secrets, arbitrary tools, public targets, unbounded autonomy, or online-mode account pools.
  • Follow-ups: bounded non-code-execution candidates only; no runtime, API, UI, account pool, or provider integration is introduced by this issue.