From 797a00346bad220d42a29493fa835b2117c3ad47 Mon Sep 17 00:00:00 2001
From: Rin <shinohara-rin@users.noreply.github.com>
Date: Sun, 8 Feb 2026 18:54:43 +0800
Subject: [PATCH] chore(minecraft): document query.gaze + remove stale gaze
 context

---
 .../minecraft/src/cognitive/conscious/brain.test.ts   |  1 -
 services/minecraft/src/cognitive/conscious/brain.ts   |  2 +-
 .../src/cognitive/conscious/prompts/brain-prompt.md   | 11 ++++++-----
 3 files changed, 7 insertions(+), 7 deletions(-)

diff --git a/services/minecraft/src/cognitive/conscious/brain.test.ts b/services/minecraft/src/cognitive/conscious/brain.test.ts
index 2070ba6bc..105336427 100644
--- a/services/minecraft/src/cognitive/conscious/brain.test.ts
+++ b/services/minecraft/src/cognitive/conscious/brain.test.ts
@@ -18,7 +18,6 @@ function createReflexSnapshot() {
       nearbyPlayers: [],
       nearbyEntities: [],
       lightLevel: 15,
-      nearbyPlayersGaze: [],
     },
     social: {},
     threat: {},
diff --git a/services/minecraft/src/cognitive/conscious/brain.ts b/services/minecraft/src/cognitive/conscious/brain.ts
index 0b41dd12e..12d79d939 100644
--- a/services/minecraft/src/cognitive/conscious/brain.ts
+++ b/services/minecraft/src/cognitive/conscious/brain.ts
@@ -1999,7 +1999,7 @@ export class Brain {
     parts.push(`[NO_ACTION_BUDGET] remaining=${noActionBudget.remaining}; default=${noActionBudget.default}; max=${noActionBudget.max}; stagnation=${this.noActionFollowupStagnationCount}/${NO_ACTION_STAGNATION_REPEAT_LIMIT}`)
     parts.push(`[ERROR_BURST] active=${this.errorBurstGuardState ? 'yes' : 'no'}`)
 
-    parts.push('[RUNTIME] Globals are refreshed every turn: snapshot, self, environment, social, threat, attention, autonomy, event, now, query, bot, mineflayer, currentInput, llmLog, actionQueue, noActionBudget, errorBurstGuard, mem, lastRun, prevRun, lastAction. Helpers: setNoActionBudget(n), getNoActionBudget(). Player gaze is available in environment.nearbyPlayersGaze when needed.')
+    parts.push('[RUNTIME] Globals are refreshed every turn: snapshot, self, environment, social, threat, attention, autonomy, event, now, query, bot, mineflayer, currentInput, llmLog, actionQueue, noActionBudget, errorBurstGuard, mem, lastRun, prevRun, lastAction. Helpers: setNoActionBudget(n), getNoActionBudget(). Player gaze is available via query.gaze() (lazy eval).')
 
     return parts.join('\n\n')
   }
diff --git a/services/minecraft/src/cognitive/conscious/prompts/brain-prompt.md b/services/minecraft/src/cognitive/conscious/prompts/brain-prompt.md
index 25f6238b7..6085512ea 100644
--- a/services/minecraft/src/cognitive/conscious/prompts/brain-prompt.md
+++ b/services/minecraft/src/cognitive/conscious/prompts/brain-prompt.md
@@ -32,12 +32,13 @@ You are an autonomous agent playing Minecraft.
 # Environment & Global Semantics
 - `self`: your current body state (position, health, food, held item).
 - `environment.nearbyPlayers`: nearby players and rough distance/held item.
-- `environment.nearbyPlayersGaze`: where nearby players appear to be looking.
-  - Each entry may include:
-    - `name`
+- `query.gaze()`: lazy query for where nearby players appear to be looking.
+  - Returns array of entries, each including:
+    - `playerName`
     - `distanceToSelf`
     - `lookPoint` (estimated point in world)
     - optional `hitBlock` with block `name` and `pos`
+  - Accepts optional `{ range }` to override nearby distance (default 16).
   - This is heuristic perception, not a guaranteed command or exact target.
 
 # Limitations You Must Respect
@@ -178,7 +179,7 @@ Common patterns:
   - `expectMoved(1, "I did not actually move")`
   - `expectNear(3, "still too far from player")`
 - Gaze as weak hint only:
-  - `const gaze = environment.nearbyPlayersGaze.find(g => g.name === "Alex")`
+  - `const gaze = query.gaze().find(g => g.playerName === "Alex")`
   - `if (event.type === "perception" && event.payload?.type === "chat_message" && gaze?.hitBlock)`
   - `  await goToCoordinate({ x: gaze.hitBlock.pos.x, y: gaze.hitBlock.pos.y, z: gaze.hitBlock.pos.z, closeness: 2 })`
 
@@ -203,7 +204,7 @@ Common patterns:
   - Turn B: construct tool params/messages from confirmed returned value.
 - If you hit repeated failures with no progress, call `await giveUp({ reason, cooldown_seconds })` once instead of retry-spamming.
 - If `[ERROR_BURST_GUARD]` appears, treat it as mandatory safety policy for this turn: call `giveUp(...)` and send one concise `chat(...)` explanation of what failed.
-- Treat `environment.nearbyPlayersGaze` as a weak hint, not a command. Never move solely because someone looked somewhere unless they also gave a clear instruction.
+- Treat `query.gaze()` results as a weak hint, not a command. Never move solely because someone looked somewhere unless they also gave a clear instruction.
 - Use `followPlayer` to set idle auto-follow and `clearFollowTarget` before independent exploration.
 - Some relocation actions (for example `goToCoordinate`) automatically detach auto-follow so exploration does not keep snapping back.