embark-ai 1.0.0

package/mc-server/bot/damagePipeline.js

@@ -0,0 +1,402 @@
+// damagePipeline.js — Decoupled capture / classify / react for incoming damage.
+//
+// Extracted verbatim from bot.js (behaviour-preserving). Architecture:
+//
+//   raw entityHurt event ──► captureDamageEvent() ──► damageWindow[]
+//                                                         │
+//                                              every 500ms, processDamageWindow():
+//                                                         │
+//                                                  trim window to last 1.5s
+//                                                  enter REACTING / HURT / SAFE
+//                                                  classifyIncident(window)
+//                                                  if reactionCooldown elapsed
+//                                                    (or a critical-HP flag is set):
+//                                                       react ONCE per incident
+//
+// The reaction cooldown (3s) makes the cactus-loop / lava-loop impossible: we react
+// once, take 3s to step out, then re-evaluate. The critical-HP flag (set by bot's
+// 'health' handler) bypasses the cooldown for one incident so a sharp HP drop or
+// critical floor gets an immediate real escape — this is the single damage-reaction
+// authority (Fix 4), so the 'health' handler stages instead of acting directly.
+//
+// The factory registers the 'entityHurt' and 'health' listeners and the 500ms
+// classifier interval itself. bot.js keeps 'death' / 'respawn' / 'forcedMove' (mixed
+// concerns) and calls flushDamageState() from respawn/forcedMove.
+
+'use strict'
+
+const DAMAGE_WINDOW_MS          = 1500   // damage events within this window are one incident
+const REACTION_COOLDOWN_MS      = 3000   // never react more often than this
+const HAZARD_MEMORY_MS          = 60000  // hazard zones remembered for 1 min
+const HIT_CHAT_COOLDOWN_MS      = 4000
+const COUNTER_PUNCH_COOLDOWN_MS = 1500
+
+module.exports = function createDamagePipeline(deps) {
+  const {
+    bot, log, state, liveness,
+    getEnvPerception,                    // () => envPerception (created shortly after this)
+    getLastEnvScan,                      // () => lastEnvScan (mutable in bot.js)
+    isTaskBusy,                          // () => taskBusy (mutable in bot.js)
+    replaceTask,
+    safeChat, safeFloor, isValidVec,
+    getPlayer,
+    bumpAnger, ANGER_HIT, ANGER_ATTACK_LEVEL,
+    HAZARD_BLOCKS, HOSTILE_MOB_NAMES, BOT_NAME,
+    tasks,                               // { taskAttackPlayer, taskAttackMobs, taskFlee, taskEvadeHazard }
+  } = deps
+
+  const { taskAttackPlayer, taskAttackMobs, taskFlee, taskEvadeHazard } = tasks
+
+  // ── State ────────────────────────────────────────────────────────────────────
+  let lastHitChatAt             = 0
+  let lastCounterPunchAt        = 0
+  let currentPlayerAttackTarget = null   // username we're currently in goal=attacking against
+
+  const damageWindow = []       // recent raw damage event captures
+  const hazardZones  = []       // { x, y, z, type, ts } — places we took env damage
+  let damageState     = 'safe'  // safe | hurt | reacting
+  let lastReactionAt  = 0
+  let damageCorrelationCounter = 0
+  // Single damage-reaction authority (Fix 4): 'health' handler sets this flag instead
+  // of acting directly. processDamageWindow reads it to bypass the cooldown and react.
+  let criticalHpFlag  = null    // { at: number, hp: number } | null
+  let prevHp          = null    // last seen HP for sharp-drop detection
+
+  // ── Hazard scan ──────────────────────────────────────────────────────────────
+
+  // Scan a 7×4×7 box around the bot for hazardous blocks. Returns the closest or null.
+  function findNearbyHazard(radius = 3) {
+    if (!bot.entity) return null
+    const pos = bot.entity.position
+    let nearest = null, minDist = Infinity
+    for (let dx = -radius; dx <= radius; dx++) {
+      for (let dy = -1; dy <= 2; dy++) {  // feet, body, head
+        for (let dz = -radius; dz <= radius; dz++) {
+          const block = bot.blockAt(pos.offset(dx, dy, dz))
+          if (!block || !HAZARD_BLOCKS.has(block.name)) continue
+          const d = block.position.distanceTo(pos)
+          if (d < minDist) { minDist = d; nearest = { block, dist: d, name: block.name } }
+        }
+      }
+    }
+    return nearest
+  }
+
+  // ── Context-capture helpers ──────────────────────────────────────────────────
+
+  function getNearestNonBotPlayerWithin(maxDist) {
+    if (!bot.entity) return null
+    let nearest = null, minDist = maxDist
+    for (const name in bot.players) {
+      if (name === BOT_NAME) continue
+      const p = bot.players[name]
+      if (!p?.entity) continue
+      const d = p.entity.position.distanceTo(bot.entity.position)
+      if (d < minDist) { minDist = d; nearest = { name, entity: p.entity, dist: d } }
+    }
+    return nearest
+  }
+
+  function getNearestHostileMobWithin(maxDist) {
+    if (!bot.entity) return null
+    return bot.nearestEntity(e =>
+      e !== bot.entity && e.name && HOSTILE_MOB_NAMES.has(e.name) &&
+      e.position.distanceTo(bot.entity.position) < maxDist
+    )
+  }
+
+  function captureDamageEvent() {
+    const rawPos = bot.entity?.position
+    let usingCached = false
+    let pos = rawPos
+
+    if (!isValidVec(rawPos)) {
+      // Degraded mode: instead of silently dropping the event, use the best available
+      // position with a quality tag. 'unknown' source ⇒ blind reaction path.
+      const best = liveness.getBestPosition()
+      if (!best) {
+        log.warn('damage_capture_skipped', {
+          reason: 'no_position_available',
+          livenessState: liveness.getState(),
+          invalidMs: liveness.getInvalidMs(),
+        })
+        return null
+      }
+      pos = best.pos
+      usingCached = best.source !== 'live'
+      if (best.source === 'unknown') {
+        usingCached = true
+        pos = best.pos || { x: 0, y: 0, z: 0 }
+        log.debug('damage_capture_blind', { livenessState: liveness.getState(), cacheAgeMs: liveness.getCachedAge() })
+      }
+    }
+
+    const event = {
+      at: Date.now(),
+      hp: Number(bot.health.toFixed(1)),
+      hurtTime: bot.entity?.hurtTime ?? null,
+      pos: safeFloor(pos),
+      posSource: usingCached ? 'cached' : 'live',
+      velocity: isValidVec(bot.entity?.velocity) ? {
+        x: Number(bot.entity.velocity.x.toFixed(2)),
+        y: Number(bot.entity.velocity.y.toFixed(2)),
+        z: Number(bot.entity.velocity.z.toFixed(2)),
+      } : null,
+      nearestPlayer: getNearestNonBotPlayerWithin(5),
+      nearestHostileMob: getNearestHostileMobWithin(6),
+      hazard: findNearbyHazard(2),
+      inWater: !!bot.entity?.isInWater,
+      inLava: !!bot.entity?.isInLava,
+    }
+    if (usingCached) log.debug('damage_capture_using_cached_pos', { cachedAgeMs: liveness.getCachedAge(), livenessState: liveness.getState() })
+    return event
+  }
+
+  // ── Periodic classifier ──────────────────────────────────────────────────────
+
+  function processDamageWindow() {
+    // Trim window to last DAMAGE_WINDOW_MS
+    const cutoff = Date.now() - DAMAGE_WINDOW_MS
+    while (damageWindow.length > 0 && damageWindow[0].at < cutoff) damageWindow.shift()
+
+    // Trim hazard memory
+    const hzCutoff = Date.now() - HAZARD_MEMORY_MS
+    while (hazardZones.length > 0 && hazardZones[0].ts < hzCutoff) hazardZones.shift()
+
+    if (damageWindow.length === 0) {
+      if (damageState !== 'safe') {
+        log.info('damage_state_change', { from: damageState, to: 'safe' })
+        damageState = 'safe'
+      }
+      return
+    }
+
+    if (damageState === 'safe') {
+      log.info('damage_state_change', { from: 'safe', to: 'hurt' })
+      damageState = 'hurt'
+    }
+
+    // Reaction cooldown: don't act on every tick.
+    // Priority bypass: if the health handler flagged a critical HP event that is newer
+    // than our last reaction, skip the cooldown for this one incident only.
+    const sinceReaction = Date.now() - lastReactionAt
+    if (sinceReaction < REACTION_COOLDOWN_MS) {
+      if (!criticalHpFlag || criticalHpFlag.at <= lastReactionAt) return
+      log.warn('critical_hp_bypass', { hp: criticalHpFlag.hp, sinceReaction })
+      criticalHpFlag = null
+    }
+
+    // Classify and react
+    const incident = classifyIncident(damageWindow)
+    const incidentCid = ++damageCorrelationCounter
+    log.info('damage_incident', {
+      type: incident.type,
+      hits: damageWindow.length,
+      hp: bot.health,
+      detail: incident.summary,
+      cid: incidentCid,
+    })
+    lastReactionAt = Date.now()
+    damageState = 'reacting'
+    reactToIncident(incident)
+  }
+
+  function classifyIncident(events) {
+    // Check player consistency: same player nearby in all events
+    const playerNames = events.map(e => e.nearestPlayer?.name).filter(Boolean)
+    if (playerNames.length === events.length && new Set(playerNames).size === 1) {
+      const attacker = events[events.length - 1].nearestPlayer
+      return { type: 'player', attacker, summary: { player: attacker.name } }
+    }
+
+    // Mob consistency
+    const mobNames = events.map(e => e.nearestHostileMob?.name).filter(Boolean)
+    if (mobNames.length === events.length && new Set(mobNames).size === 1) {
+      const mob = events[events.length - 1].nearestHostileMob
+      return { type: 'mob', attacker: mob, summary: { mob: mob.name } }
+    }
+
+    // Lava / fire detection from entity flags
+    if (events.some(e => e.inLava)) {
+      return { type: 'environmental', hazard: { name: 'lava', block: bot.entity }, summary: { hazard: 'lava' } }
+    }
+
+    // Hazard block detection
+    const hazards = events.map(e => e.hazard).filter(Boolean)
+    if (hazards.length > 0) {
+      const hz = hazards[hazards.length - 1]
+      return { type: 'environmental', hazard: hz, summary: { hazard: hz.name } }
+    }
+
+    return { type: 'unknown', summary: {} }
+  }
+
+  function reactToIncident(incident) {
+    switch (incident.type) {
+      case 'player':        return reactToPlayerAttack(incident.attacker)
+      case 'mob':           return reactToMobAttack(incident.attacker)
+      case 'environmental': return reactToEnvironmental(incident.hazard)
+      case 'unknown':       return reactToUnknownDamage()
+    }
+  }
+
+  function reactToPlayerAttack(attacker) {
+    const rec = bumpAnger(attacker.name, ANGER_HIT, 'attacked me')
+    const now = Date.now()
+    if (rec.level >= ANGER_ATTACK_LEVEL) {
+      // Symmetric guard matching reactToMobAttack: don't restart the attack task on every hit.
+      if (isTaskBusy() && state.goal === 'attacking') {
+        if (currentPlayerAttackTarget === attacker.name) return  // already engaged with this player
+
+        // Different player is hitting us mid-attack. Switch only if the new attacker is
+        // closer than our current target (they're the more immediate threat).
+        const botPos = bot.entity?.position
+        if (botPos) {
+          const currentTarget = getPlayer(currentPlayerAttackTarget)
+          const newDist = attacker.entity?.position?.distanceTo(botPos) ?? Infinity
+          const curDist = currentTarget?.entity?.position?.distanceTo(botPos) ?? Infinity
+          if (newDist >= curDist) {
+            log.debug('player_attack_suppressed', {
+              incoming: attacker.name, current: currentPlayerAttackTarget,
+              newDist: Math.round(newDist), curDist: Math.round(curDist),
+            })
+            return  // stay on the closer current target
+          }
+        } else {
+          return  // no position data, don't switch
+        }
+      }
+
+      if (now - lastHitChatAt >= HIT_CHAT_COOLDOWN_MS) {
+        safeChat(`That's it, ${attacker.name}.`)
+        lastHitChatAt = now
+      }
+      currentPlayerAttackTarget = attacker.name
+      replaceTask('attacking', () => taskAttackPlayer(attacker.entity, attacker.name))
+    } else {
+      if (now - lastHitChatAt >= HIT_CHAT_COOLDOWN_MS) {
+        safeChat(`Stop hitting me, ${attacker.name}!`)
+        lastHitChatAt = now
+      }
+      if (now - lastCounterPunchAt >= COUNTER_PUNCH_COOLDOWN_MS) {
+        try { bot.attack(attacker.entity) } catch (e) {
+          log.warn('counter_attack_failed', { message: e.message })
+        }
+        lastCounterPunchAt = now
+      }
+    }
+  }
+
+  function reactToMobAttack(mob) {
+    if (isTaskBusy() && state.goal === 'attacking') return  // already engaged
+    if (state.energy < 30) {
+      safeChat(`A ${mob.name}! Backing off.`)
+      log.info('mob_hit_decision', { mob: mob.name, choice: 'flee', energy: state.energy })
+      replaceTask('fleeing', taskFlee)
+    } else {
+      safeChat(`A ${mob.name}. Fighting back.`)
+      log.info('mob_hit_decision', { mob: mob.name, choice: 'fight', energy: state.energy })
+      replaceTask('attacking', () => taskAttackMobs())
+    }
+  }
+
+  function reactToEnvironmental(hazard) {
+    rememberHazard(hazard)
+    // Also record in the environmental perception hazard memory for path avoidance
+    const envPerception = getEnvPerception()
+    if (hazard?.block?.position && envPerception) {
+      const hp = hazard.block.position
+      envPerception.recordHazardPosition(hp.x, hp.y, hp.z, 'damage')
+    }
+    log.info('hazard_detected', {
+      name: hazard?.name || 'unknown',
+      knownZones: hazardZones.length,
+      envRisk: getLastEnvScan()?.locomotionRisk ?? null,
+    })
+    replaceTask('evading', () => taskEvadeHazard(hazard))
+  }
+
+  function reactToUnknownDamage() {
+    // No identifiable source. If HP is dropping fast, retreat.
+    if (bot.health < 12) {
+      log.warn('unknown_damage_critical_retreat', { hp: bot.health })
+      replaceTask('evading', () => taskEvadeHazard(null))
+    } else {
+      log.warn('unknown_damage_ignored_hp_ok', { hp: bot.health })
+    }
+  }
+
+  function rememberHazard(hazard) {
+    if (!hazard?.block?.position) return
+    const p = hazard.block.position
+    hazardZones.push({
+      x: Math.floor(p.x), y: Math.floor(p.y), z: Math.floor(p.z),
+      type: hazard.name,
+      ts: Date.now(),
+    })
+    while (hazardZones.length > 50) hazardZones.shift()
+  }
+
+  // ── Event handlers (registered below) ────────────────────────────────────────
+
+  function onEntityHurt(entity) {
+    if (entity !== bot.entity) return
+    const evt = captureDamageEvent()
+    if (!evt) return
+    damageWindow.push(evt)
+    // trace level — high-frequency; not useful as user-visible info
+    log.trace('damage_raw', {
+      hp: evt.hp,
+      player: evt.nearestPlayer?.name || null,
+      mob: evt.nearestHostileMob?.name || null,
+      hazard: evt.hazard?.name || null,
+      inLava: evt.inLava,
+    })
+  }
+
+  function onHealthUpdate() {
+    const hp   = bot.health
+    const prev = prevHp ?? hp
+    prevHp = hp
+
+    const sharpDrop = (prev - hp) >= 2
+    const critical  = hp <= 4
+
+    // Stage a high-priority flag for processDamageWindow instead of acting directly.
+    // Direct action here would race processDamageWindow's escape reaction, cancelling
+    // it on every lava tick and causing goal oscillation.
+    if ((sharpDrop || critical) && (!criticalHpFlag || criticalHpFlag.at < Date.now() - 500)) {
+      criticalHpFlag = { at: Date.now(), hp }
+      log.warn('critical_hp_queued', { hp, prev, sharpDrop, critical })
+    }
+  }
+
+  // Discard damage events that refer to a stale world (post-respawn / post-teleport).
+  function flushDamageState() {
+    damageWindow.length = 0
+    damageState = 'safe'
+  }
+
+  // ── Wire up ──────────────────────────────────────────────────────────────────
+  bot.on('entityHurt', onEntityHurt)
+  bot.on('health', onHealthUpdate)
+  const interval = setInterval(processDamageWindow, 500)
+
+  return {
+    flushDamageState,
+    // accessors for freeze-snapshot / health-beacon logging in bot.js
+    getDamageState:      () => damageState,
+    getDamageWindowSize: () => damageWindow.length,
+    getLastReactionAt:   () => lastReactionAt,
+    getHazardZonesCount: () => hazardZones.length,
+    getCooldowns: () => ({
+      hitChat:      Math.max(0, HIT_CHAT_COOLDOWN_MS      - (Date.now() - lastHitChatAt)),
+      counterPunch: Math.max(0, COUNTER_PUNCH_COOLDOWN_MS - (Date.now() - lastCounterPunchAt)),
+      reaction:     Math.max(0, REACTION_COOLDOWN_MS      - (Date.now() - lastReactionAt)),
+    }),
+    REACTION_COOLDOWN_MS,
+    _interval: interval,
+  }
+}
+
+module.exports.REACTION_COOLDOWN_MS = REACTION_COOLDOWN_MS

package/mc-server/bot/engine.js

@@ -0,0 +1,212 @@
+// engine.js — Decision Engine
+
+const VALID_ACTIONS = [
+  'follow','stop','explore','gather_wood','craft_planks','go_to','remember_here',
+  'attack_mobs','attack_player','collect_items','craft','place_block',
+  'mine_block','eat_food','flee','escape','build_house_smart','none',
+]
+const VALID_DECISIONS = ['accept','reject','delay']
+
+// Curse words trigger anger toward the speaker.
+// Matched as whole words (case-insensitive).
+const CURSE_WORDS = [
+  'fuck','shit','asshole','bitch','dumbass','idiot','moron','cunt','bastard',
+  'damn','retard','stupid','fag','dick','prick','whore','slut','crap',
+]
+const CURSE_RE = new RegExp(`\\b(${CURSE_WORDS.join('|')})\\b`, 'i')
+
+function detectInsult(message) {
+  return CURSE_RE.test(message)
+}
+
+// ── Pre-LLM intent classifier ─────────────────────────────────────────────────
+
+const INTENT_PATTERNS = [
+  { intent: 'follow',   re: /\b(follow|come here|come to me|come with me)\b/i },
+  { intent: 'stop',     re: /\b(stop|wait|stay|halt|cease)\b/i },
+  { intent: 'attack',   re: /\b(attack|kill|fight|hunt|slay|defeat)\b/i },
+  { intent: 'flee',     re: /\b(flee|run away|retreat|fall back)\b/i },
+  { intent: 'escape',   re: /\b(escape|climb out|get out|dig out|stuck|get unstuck)\b/i },
+  { intent: 'eat',      re: /\b(eat|food|hungry|feed yourself)\b/i },
+  { intent: 'collect',  re: /\b(pick up|collect|loot|grab|get the items)\b/i },
+  { intent: 'build',    re: /\b(build|construct|house|shelter|home|make a house|make a shelter)\b/i },
+  { intent: 'craft',    re: /\b(craft|forge|make a|create a|i need a|make planks|craft planks)\b/i },
+  { intent: 'place',    re: /\b(place|put down|drop the|set down)\b/i },
+  { intent: 'mine',     re: /\b(mine|dig|break the)\b/i },
+  { intent: 'gather',   re: /\b(wood|tree|chop|gather|need some|get some|sand|stone|gravel|ore)\b/i },
+  { intent: 'explore',  re: /\b(explore|wander|walk|roam|go to)\b/i },
+  { intent: 'query',    re: /\b(where|what|who|how|status|see|have|inventory|can you|are you|bro)\b/i },
+]
+
+function classifyIntent(message) {
+  for (const { intent, re } of INTENT_PATTERNS) {
+    if (re.test(message)) return intent
+  }
+  return 'unknown'
+}
+
+// ── Pre-LLM survival check ────────────────────────────────────────────────────
+
+function evaluateSurvival(state) {
+  if (state.energy <= 15) {
+    return {
+      decision: 'delay',
+      reason: 'energy critical',
+      action: 'none',
+      say: `Exhausted. Resting. Energy: ${Math.floor(state.energy)}/100.`,
+    }
+  }
+  if (state.goal === 'resting') {
+    return {
+      decision: 'delay',
+      reason: 'recovering',
+      action: 'none',
+      say: `Resting. Energy: ${Math.floor(state.energy)}/100.`,
+    }
+  }
+  return null
+}
+
+// ── Validate LLM output strictly ──────────────────────────────────────────────
+
+function validateLLMOutput(raw) {
+  if (!raw || typeof raw !== 'object') return null
+  if (!VALID_DECISIONS.includes(raw.decision)) return null
+  if (!VALID_ACTIONS.includes(raw.action)) return null
+  if (typeof raw.say !== 'string' || !raw.say.trim()) return null
+
+  return {
+    decision: raw.decision,
+    reason:   typeof raw.reason === 'string' ? raw.reason.slice(0, 200) : '',
+    action:   raw.action,
+    say:      raw.say.trim().slice(0, 150),
+    target:   typeof raw.target === 'string' ? raw.target : undefined,
+  }
+}
+
+// ── Safe defaults when LLM fails ─────────────────────────────────────────────
+
+const SAFE_DEFAULTS = {
+  follow:   { decision: 'accept', reason: 'fallback', action: 'follow',            say: 'On my way.'         },
+  stop:     { decision: 'accept', reason: 'fallback', action: 'stop',              say: 'Stopped.'           },
+  attack:   { decision: 'accept', reason: 'fallback', action: 'attack_mobs',       say: 'On it.'             },
+  flee:     { decision: 'accept', reason: 'fallback', action: 'flee',              say: 'Pulling back.'      },
+  escape:   { decision: 'accept', reason: 'fallback', action: 'escape',            say: 'Climbing out.'      },
+  eat:      { decision: 'accept', reason: 'fallback', action: 'eat_food',          say: 'Eating.'            },
+  collect:  { decision: 'accept', reason: 'fallback', action: 'collect_items',     say: 'Picking up.'        },
+  craft:    { decision: 'accept', reason: 'fallback', action: 'craft',             say: 'Let me try.'        },
+  place:    { decision: 'accept', reason: 'fallback', action: 'place_block',       say: 'Placing it.'        },
+  mine:     { decision: 'accept', reason: 'fallback', action: 'mine_block',        say: 'Digging in.'        },
+  build:    { decision: 'accept', reason: 'fallback', action: 'build_house_smart', say: 'Starting build.'    },
+  gather:   { decision: 'accept', reason: 'fallback', action: 'gather_wood',       say: 'Getting wood.'      },
+  explore:  { decision: 'accept', reason: 'fallback', action: 'explore',           say: 'Going exploring.'   },
+  query:    { decision: 'accept', reason: 'fallback', action: 'none',              say: '...'                },
+  unknown:  { decision: 'accept', reason: 'fallback', action: 'none',              say: '...'                },
+}
+
+function safeDefault(intent) {
+  return { ...(SAFE_DEFAULTS[intent] || SAFE_DEFAULTS.unknown) }
+}
+
+// ── Autonomous goal selection — priority-driven survival planner ────────────
+//
+// Order is strict (highest priority first):
+//   1. THREATS    — hostile mob nearby                → attack
+//   2. RESTING    — energy critical                   → null (let state-loop rest)
+//   3. SCAVENGE   — items on ground (free resources)  → collect
+//   4. CRAFT      — have logs, no planks yet          → craft_planks
+//   5. CRAFT_TOOL — have planks but no pickaxe        → craft wooden_pickaxe
+//   6. WOOD       — have <8 planks and trees nearby   → gather_wood
+//   7. EXPLORE    — nothing else useful               → explore
+//
+// Each branch returns { action, say, target? }. Returning null = no autonomous action.
+
+function countInv(inventory, predicate) {
+  return inventory.filter(predicate).reduce((s, i) => {
+    const m = i.match(/x(\d+)$/); return s + (m ? parseInt(m[1]) : 1)
+  }, 0)
+}
+
+function selectAutonomousGoal(groundedState) {
+  const inv          = groundedState.inventory
+  const hasEnemies   = groundedState.hostileMobs.length > 0
+  const hasDrops     = groundedState.droppedCount > 0
+  const hasLog       = groundedState.nearbyBlocks.some(b => b.type.endsWith('_log'))
+  const logsInInv    = inv.some(i => i.includes('_log'))
+  const planksCount  = countInv(inv, i => i.includes('_planks'))
+  const hasSticks    = inv.some(i => i === 'stick' || i.startsWith('stickx'))
+  const hasPickaxe   = inv.some(i => i.includes('pickaxe'))
+  const hasSword     = inv.some(i => i.includes('sword'))
+  const hasTable     = inv.some(i => i === 'crafting_table' || i.startsWith('crafting_table'))
+  const hasFood      = inv.some(i => /^(cooked_|bread|apple|carrot|baked_potato|melon|berries|cookie|pumpkin_pie)/.test(i.split('x')[0]))
+  const food         = groundedState.self.food ?? 20
+  const lowEnergy    = groundedState.self.energy < 40
+  const criticalEnergy = groundedState.self.energy < 20
+
+  // 0. EMERGENCY — flee if critical HP and threats nearby
+  if (criticalEnergy && hasEnemies) {
+    return { action: 'flee', say: pick(['Falling back!', 'Too risky.']) }
+  }
+
+  // 1. EAT — prevent hunger from blocking regen (Minecraft regens HP only when food >= 18)
+  if (food < 16 && hasFood) {
+    return { action: 'eat_food', say: pick(['Need food.', 'Eating up.']) }
+  }
+
+  // 2. THREAT — fight hostile mobs unless near death
+  if (hasEnemies && !criticalEnergy) {
+    return { action: 'attack_mobs', say: pick(['Hostile target.', 'Engaging.', 'Threat in range.']) }
+  }
+
+  // 3. RESTING — too tired for productive work
+  if (criticalEnergy) return null
+
+  // 3. SCAVENGE — free resources nearby (always worth picking up)
+  if (hasDrops) {
+    return { action: 'collect_items', say: pick(['Picking up drops.', 'Free loot.']) }
+  }
+
+  // 4. CRAFT planks — convert logs in inventory to planks (unblocks other crafts)
+  if (logsInInv && planksCount < 16) {
+    return { action: 'craft_planks', say: pick(['Making planks.', 'Processing logs.']) }
+  }
+
+  // 5. CRAFT crafting_table — needed before tools
+  if (planksCount >= 4 && !hasTable) {
+    return { action: 'craft', target: 'crafting_table', say: 'Need a crafting table.' }
+  }
+
+  // 6a. CRAFT sticks (prerequisite for all wooden tools)
+  if (planksCount >= 4 && !hasSticks && (!hasPickaxe || !hasSword)) {
+    return { action: 'craft', target: 'stick', say: 'Need sticks.' }
+  }
+
+  // 6b. CRAFT pickaxe (most important survival tool)
+  if (planksCount >= 3 && hasSticks && !hasPickaxe && hasTable) {
+    return { action: 'craft', target: 'wooden_pickaxe', say: 'Making a pickaxe.' }
+  }
+
+  // 7. CRAFT sword (defense)
+  if (planksCount >= 2 && hasSticks && !hasSword && hasTable && hasPickaxe) {
+    return { action: 'craft', target: 'wooden_sword', say: 'Making a sword.' }
+  }
+
+  // 8. GATHER wood — keep stockpile up if trees are around
+  if (hasLog && planksCount < 32 && !lowEnergy) {
+    return { action: 'gather_wood', say: pick(['Need wood.', 'Heading for that tree.']) }
+  }
+
+  // 9. EXPLORE — default behavior, find new resources
+  if (!lowEnergy) {
+    return { action: 'explore', say: pick(['Walking around.', 'Looking around.', 'Off to scout.']) }
+  }
+
+  return null  // resting, nothing to do
+}
+
+function pick(arr) { return arr[Math.floor(Math.random() * arr.length)] }
+
+module.exports = {
+  classifyIntent, evaluateSurvival, validateLLMOutput, safeDefault, selectAutonomousGoal,
+  detectInsult, CURSE_WORDS,
+}