refactor(minecraft): restore services to neutral Minecraft semantics (#1950)

## Summary

Restores `services/minecraft` to own **only Minecraft semantics**,
decoupling the already-merged #1915 runtime contract from the (unmerged)
#1916 desktop-relay design — as requested by @shinohara-rin in the #1916
review:

> I'd prefer we first restore `services/minecraft` to only own Minecraft
semantics, then reintroduce desktop relay/read-aloud through a generic
module capability/tool contribution path or a Minecraft adapter.
Otherwise `main` now contains half of a cross-PR runtime contract whose
other half we are saying should not land as-is.

The perception/reflex/brain reliability work from #1915 is untouched.
This PR only removes the three desktop-coupling points baked into the
bot service.

## Changes

- **`airi-bridge.ts` — `handleActionIntent`**: a `spark:command` is
high-level guidance from the AIRI server, now attributed to a neutral
`'airi'` source. Removed the hardcoded `username = '主人'` / `relayedFrom:
'desktop-airi'` "treat it as if the master typed it in-game" framing.
The generic server→bot directive still routes through
`signal:chat_message` to trigger a fresh decision cycle, exactly as
before — only the identity/provenance is neutralized. Binding a relayed
command to the master's in-game identity is desktop-relay policy and
will live in the Minecraft adapter.
- **`minecraft-context-service.ts`**: stopped emitting the
machine-readable `master:` status hint (whose only consumer was the
desktop `gaming-minecraft` store) and removed the desktop-coupling
NOTICE. The owner identity remains in the human-readable status **text**
for the bot's own brain.
- **`cognitive/index.ts`**: stopped forwarding the bot's own in-game
chat over the `context:update` lane `minecraft:speech` (only meaningful
with the #1916 desktop TTS consumer). The bot still ignores its own
messages.

## How tested

- Updated `minecraft-context-service.test.ts` to assert the neutral
behavior (owner identity in status text, **never** as a `master:` hint).
2/2 pass.
- `pnpm exec eslint <changed files>` → 0 problems.
- The changed files typecheck clean. (Note: this worktree surfaces
pre-existing `vec3@0.1.10` vs `vec3@0.2.0` dependency-resolution errors
in unrelated files —
`gaze.ts`/`runtime.ts`/`patched-goto.ts`/`world.ts`/`map-renderer`/`brain`/`rules`
— present on `main` before this change too; not introduced here.)

## Follow-up

Desktop relay (`relayToMinecraft`) and read-aloud will be reintroduced
through a Minecraft adapter in the renderer (registering tools/prompts
into the existing generic stores), so the runtime contract is owned by
the Minecraft surface rather than baked into the neutral bot service.
The generic stage-ui robustness fixes are already split out in #1949.

---------

Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>
Co-authored-by: Rin <shinohara-rin@users.noreply.github.com>

Author: 3 people

services/minecraft/src/airi/airi-bridge.test.ts

@@ -0,0 +1,66 @@
+import { describe, expect, it, vi } from 'vitest'
+
+import { AiriBridge } from './airi-bridge'
+
+function createBridgeHarness() {
+  const handlers = new Map<string, (event: any) => void>()
+  const client = {
+    send: vi.fn(),
+    onEvent: vi.fn((type: string, handler: (event: any) => void) => {
+      handlers.set(type, handler)
+    }),
+    offEvent: vi.fn(),
+  }
+  const eventBus = {
+    emit: vi.fn(),
+  }
+  const bridge = new AiriBridge(client as any, eventBus as any)
+  bridge.init()
+
+  return { bridge, eventBus, handlers }
+}
+
+describe('airiBridge spark command routing', () => {
+  it('routes spark commands as AIRI commands instead of chat messages', () => {
+    const { bridge, eventBus, handlers } = createBridgeHarness()
+    const commandHandler = handlers.get('spark:command')
+
+    expect(commandHandler).toBeDefined()
+
+    commandHandler?.({
+      data: {
+        commandId: 'spark-1',
+        intent: 'action',
+        interrupt: false,
+        priority: 'normal',
+        guidance: {
+          options: [
+            {
+              label: 'collect wood',
+              steps: ['find a tree', 'chop it'],
+            },
+          ],
+        },
+      },
+    })
+
+    expect(eventBus.emit).toHaveBeenCalledWith(expect.objectContaining({
+      type: 'signal:airi_command',
+      payload: expect.objectContaining({
+        type: 'airi_command',
+        description: 'Directive from AIRI: "collect wood"',
+        sourceId: 'airi',
+        metadata: expect.objectContaining({
+          message: 'collect wood',
+          sparkCommandId: 'spark-1',
+          sparkIntent: 'action',
+        }),
+      }),
+    }))
+    expect(eventBus.emit).not.toHaveBeenCalledWith(expect.objectContaining({
+      type: 'signal:chat_message',
+    }))
+
+    bridge.destroy()
+  })
+})

services/minecraft/src/airi/airi-bridge.ts

@@ -44,16 +44,15 @@ export class AiriBridge {
         },
       } as Parameters<typeof this.client.send>[0])
 
-      // A spark:command IS a command. The user requires that a desktop-relayed command carry the
-      // EXACT same weight as the master typing in the in-game chat — i.e. it must trigger a fresh
-      // decision (Conscious) cycle, never be silently filed into history. So we always route through
-      // handleActionIntent (→ signal:chat_message → enqueueEvent → decision cycle).
+      // A spark:command is high-level guidance from the AIRI server. It must carry enough weight to
+      // trigger a fresh decision (Conscious) cycle, never be silently filed into history — so we
+      // always route it through handleActionIntent (→ signal:airi_command → enqueueEvent → decision cycle).
       //
-      // We intentionally no longer special-case `intent === 'context'`: that branch used to emit
+      // We intentionally do not special-case `intent === 'context'`: that branch used to emit
       // signal:airi_context which Brain pushes to conversationHistory WITHOUT waking the loop, so a
-      // desktop LLM that mislabels its intent as "context" would have its command silently dropped
-      // from action. True passive context still has its own dedicated channel — `context:update`
-      // (see contextUpdateHandler) — which remains history-only and is unaffected by this change.
+      // command that mislabels its intent as "context" would be silently dropped from action. True
+      // passive context still has its own dedicated channel — `context:update` (see
+      // contextUpdateHandler) — which remains history-only and is unaffected by this routing.
       this.handleActionIntent(cmd)
     }
 
@@ -180,43 +179,41 @@ export class AiriBridge {
   }
 
   private handleActionIntent(cmd: SparkCommandData): void {
-    // Treat a desktop-AIRI spark:command as if the master typed it in the in-game chat:
-    // route through the SAME `signal:chat_message` path so brain handles it identically to
-    // a real player chat (resetNoActionFollowupBudget('player_chat'), normal Conscious wake
-    // up, no special "another agent" framing). User intent: "the desktop AIRI is just an
-    // extension of me — when she relays a command, the in-game bot should feel it as me."
+    // A spark:command is high-level guidance from the AIRI server. Route it through the explicit
+    // `airi_command` signal so the brain runs a fresh decision cycle
+    // (resetNoActionFollowupBudget('airi_command'), normal Conscious wake-up) instead of silently
+    // filing it into history. The directive is attributed to the AIRI server as a neutral source,
+    // not to any specific in-game player. Binding a relayed command to the master's in-game identity
+    // is desktop-relay policy and lives in the desktop Minecraft adapter, not in this bot service.
     const firstOption = cmd.guidance?.options?.[0]
     const label = firstOption?.label?.trim()
     const steps = firstOption?.steps ?? []
-    // Prefer the short label (closest to what the user actually said). Fall back to joined
-    // steps so brain still has detail when label is missing.
+    // Prefer the short label (closest to the original instruction). Fall back to joined steps so the
+    // brain still has detail when label is missing.
     const message = label && label.length > 0
       ? label
       : (steps.length > 0 ? steps.join(' / ') : `${cmd.intent} command received`)
 
-    const username = '主人'
+    const sourceId = 'airi'
 
-    this.logger.log('Relaying AIRI spark:command as in-game chat from master', {
+    this.logger.log('Routing spark:command as an AIRI directive', {
       commandId: cmd.commandId,
       message,
     })
 
     this.eventBus.emit({
-      type: 'signal:chat_message',
+      type: 'signal:airi_command',
       payload: Object.freeze({
-        type: 'chat_message' as const,
-        description: `Chat from ${username}: "${message}"`,
-        sourceId: username,
+        type: 'airi_command' as const,
+        description: `Directive from AIRI: "${message}"`,
+        sourceId,
         confidence: 1.0,
         timestamp: Date.now(),
         metadata: {
-          username,
           message,
-          // Keep the spark provenance for debugging / future special-casing, but the brain
-          // doesn't need to know — it just sees a chat_message from the master.
+          // Keep the spark provenance for debugging; the brain sees a typed AIRI directive.
           sparkCommandId: cmd.commandId,
           sparkIntent: cmd.intent,
-          relayedFrom: 'desktop-airi',
         },
       }),
       source: { component: 'airi', id: 'bridge' },

services/minecraft/src/airi/minecraft-context-service.test.ts

@@ -30,18 +30,22 @@ function makeService(masterUsername?: string) {
   return { service, captured }
 }
 
-describe('minecraftContextService master propagation', () => {
-  it('carries the master username to the desktop via status hints and text', () => {
+describe('minecraftContextService master identity', () => {
+  it('surfaces the configured master username in the status text only', () => {
     const { service, captured } = makeService('dssadg')
     service.bindBot(fakeBot())
     const update = captured[0]
     expect(update.lane).toBe('minecraft:status')
-    expect(update.hints).toContain('master:dssadg')
     expect(update.text).toContain('Master (your owner) in-game username: dssadg')
+    // The owner identity rides only in the human-readable status text (for the bot's own brain). It
+    // must NOT leak as a machine-readable `master:` hint — that was a desktop-store coupling point,
+    // removed in the services/minecraft neutral restore. Desktop "主人" binding is reintroduced via
+    // the Minecraft adapter, not baked into the bot service.
+    expect(update.hints.some((hint: string) => hint.startsWith('master:'))).toBe(false)
     service.destroy()
   })
 
-  it('omits the master hint when no master username is configured', () => {
+  it('omits the master line when no master username is configured', () => {
     const { service, captured } = makeService(undefined)
     service.bindBot(fakeBot())
     const update = captured[0]

services/minecraft/src/airi/minecraft-context-service.ts

@@ -22,11 +22,6 @@ const STATUS_CONTEXT_ID = 'minecraft:status'
 const STATUS_LANE = 'minecraft:status'
 const STATUS_REFRESH_INTERVAL_MS = 5_000
 
-// NOTICE: hint prefix carrying the master's in-game username to the desktop. The desktop skips the
-// minecraft:status text for its runtime context, so the binding rides on `hints` instead, where the
-// desktop store extracts it (gaming-minecraft.ts). Keep this literal in sync with the desktop side.
-const MASTER_HINT_PREFIX = 'master:'
-
 function toPositionString(bot: MineflayerWithAgents) {
   const position = bot.bot.entity?.position
   return position
@@ -138,7 +133,6 @@ export class MinecraftContextService {
       hints: [
         'status',
         snapshot.botUsername,
-        ...(snapshot.masterUsername ? [`${MASTER_HINT_PREFIX}${snapshot.masterUsername}`] : []),
       ],
       strategy: ContextUpdateStrategy.ReplaceSelf,
     }

services/minecraft/src/cognitive/conscious/brain.test.ts

@@ -80,6 +80,38 @@ function createPerceptionEvent() {
   } as any
 }
 
+function createAiriCommandEvent() {
+  return {
+    type: 'perception',
+    payload: {
+      type: 'airi_command',
+      description: 'Directive from AIRI: "continue"',
+      sourceId: 'airi',
+      confidence: 1,
+      timestamp: Date.now(),
+      metadata: { message: 'continue', sparkCommandId: 'spark-1', sparkIntent: 'action' },
+    },
+    source: { type: 'airi', id: 'airi' },
+    timestamp: Date.now(),
+  } as any
+}
+
+function createNonResumingPerceptionEvent() {
+  return {
+    type: 'perception',
+    payload: {
+      type: 'saliency_high',
+      description: 'Distant noise',
+      sourceId: 'world',
+      confidence: 1,
+      timestamp: Date.now(),
+      metadata: { action: 'noise' },
+    },
+    source: { type: 'minecraft', id: 'world' },
+    timestamp: Date.now(),
+  } as any
+}
+
 function createAsyncControlAction(name: string = 'goToPlayer') {
   return {
     name,
@@ -262,6 +294,51 @@ inv;
     })
   })
 
+  it('clears giveUp and proceeds when player chat arrives', async () => {
+    const deps: any = createDeps('await skip()')
+    const brain: any = new Brain(deps)
+    brain.givenUp = true
+    brain.giveUpReason = 'stuck'
+
+    await brain.processEvent({} as any, createPerceptionEvent())
+
+    expect(brain.givenUp).toBe(false)
+    expect(brain.giveUpReason).toBeUndefined()
+    expect(deps.llmAgent.callLLM).toHaveBeenCalledTimes(1)
+  })
+
+  it('clears giveUp and proceeds when an AIRI command arrives', async () => {
+    const deps: any = createDeps('await skip()')
+    const brain: any = new Brain(deps)
+    brain.givenUp = true
+    brain.giveUpReason = 'stuck'
+    brain.setNoActionFollowupBudget(0)
+
+    await brain.processEvent({} as any, createAiriCommandEvent())
+
+    expect(brain.givenUp).toBe(false)
+    expect(brain.giveUpReason).toBeUndefined()
+    expect(brain.getNoActionBudgetState()).toEqual({
+      remaining: 3,
+      default: 3,
+      max: 8,
+    })
+    expect(deps.llmAgent.callLLM).toHaveBeenCalledTimes(1)
+  })
+
+  it('keeps suppressing non-chat and non-AIRI perceptions while giveUp is active', async () => {
+    const deps: any = createDeps('await skip()')
+    const brain: any = new Brain(deps)
+    brain.givenUp = true
+    brain.giveUpReason = 'stuck'
+
+    await brain.processEvent({} as any, createNonResumingPerceptionEvent())
+
+    expect(brain.givenUp).toBe(true)
+    expect(brain.giveUpReason).toBe('stuck')
+    expect(deps.llmAgent.callLLM).not.toHaveBeenCalled()
+  })
+
   it('does not queue follow-up when script uses skip()', async () => {
     const brain: any = new Brain(createDeps('await skip()'))
     const enqueueSpy = vi.fn(async () => undefined)
@@ -455,6 +532,23 @@ describe('brain queue coalescing', () => {
     expect((brain.queue[0].event.payload as any).type).toBe('chat_message')
   })
 
+  it('promotes AIRI commands ahead of queued ordinary perceptions', () => {
+    const brain: any = new Brain(createDeps('await skip()'))
+
+    brain.queue = [
+      { event: createNonResumingPerceptionEvent(), resolve: vi.fn(), reject: vi.fn() },
+      { event: createFeedbackEvent(), resolve: vi.fn(), reject: vi.fn() },
+      { event: createAiriCommandEvent(), resolve: vi.fn(), reject: vi.fn() },
+    ]
+
+    brain.coalesceQueue()
+
+    expect(brain.queue[0].event.type).toBe('perception')
+    expect((brain.queue[0].event.payload as any).type).toBe('airi_command')
+    expect((brain.queue[1].event.payload as any).type).toBe('saliency_high')
+    expect(brain.queue[2].event.type).toBe('feedback')
+  })
+
   it('drops no-action follow-ups when player chat is waiting', () => {
     const brain: any = new Brain(createDeps('await skip()'))
 

services/minecraft/src/cognitive/conscious/brain.ts

@@ -220,9 +220,9 @@ const NO_ACTION_BUDGET_ALERT_SOURCE_ID = 'brain:no_action_budget'
 
 /**
  * Priority tiers for event scheduling (lower = higher priority).
- * Player chat always takes precedence over stale system feedback.
+ * Player chat and AIRI commands always take precedence over stale system feedback.
  */
-const EVENT_PRIORITY_PLAYER_CHAT = 0
+const EVENT_PRIORITY_URGENT_PERCEPTION = 0
 const EVENT_PRIORITY_PERCEPTION = 1
 const EVENT_PRIORITY_FEEDBACK = 2
 const EVENT_PRIORITY_NO_ACTION_FOLLOWUP = 3
@@ -265,8 +265,8 @@ function augmentDecisionError(message: string): string {
 function getEventPriority(event: BotEvent): number {
   if (event.type === 'perception') {
     const signal = event.payload as PerceptionSignal
-    if (signal.type === 'chat_message')
-      return EVENT_PRIORITY_PLAYER_CHAT
+    if (signal.type === 'chat_message' || signal.type === 'airi_command')
+      return EVENT_PRIORITY_URGENT_PERCEPTION
     return EVENT_PRIORITY_PERCEPTION
   }
   if (event.source.type === 'system' && event.source.id === NO_ACTION_FOLLOWUP_SOURCE_ID)
@@ -1578,7 +1578,7 @@ export class Brain {
   }
 
   /**
-   * Coalesce the event queue: promote high-priority events (player chat)
+   * Coalesce the event queue: promote high-priority events (player chat, AIRI commands)
    * ahead of stale low-priority events (feedback, no-action follow-ups),
    * and drop redundant stale follow-ups when a higher-priority event exists.
    */
@@ -1592,11 +1592,11 @@ export class Brain {
     if (!hasHighPriority)
       return
 
-    // Drop redundant no-action follow-ups when a player chat is waiting
-    const hasPlayerChat = this.queue.some(
-      item => getEventPriority(item.event) === EVENT_PRIORITY_PLAYER_CHAT,
+    // Drop redundant no-action follow-ups when an urgent perception is waiting
+    const hasUrgentPerception = this.queue.some(
+      item => getEventPriority(item.event) === EVENT_PRIORITY_URGENT_PERCEPTION,
     )
-    if (hasPlayerChat) {
+    if (hasUrgentPerception) {
       const before = this.queue.length
       const dropped: QueuedEvent[] = []
       this.queue = this.queue.filter((item) => {
@@ -1618,12 +1618,12 @@ export class Brain {
           sourceType: 'system',
           sourceId: 'brain:coalesce',
           tags: ['scheduler', 'coalesce', 'drop_followups'],
-          text: `Coalesced queue: dropped ${before - this.queue.length} stale no-action follow-ups (player chat waiting)`,
+          text: `Coalesced queue: dropped ${before - this.queue.length} stale no-action follow-ups (urgent perception waiting)`,
         })
       }
     }
 
-    // Stable-sort by priority so player chat events are processed first
+    // Stable-sort by priority so urgent perception events are processed first
     this.queue.sort((a, b) => getEventPriority(a.event) - getEventPriority(b.event))
   }
 
@@ -2305,7 +2305,7 @@ export class Brain {
       return true
 
     const signal = event.payload as PerceptionSignal
-    return signal.type !== 'chat_message'
+    return !this.canResumeFromGiveUp(signal)
   }
 
   private resumeFromGiveUpIfNeeded(event: BotEvent): void {
@@ -2316,10 +2316,14 @@ export class Brain {
       return
 
     const signal = event.payload as PerceptionSignal
-    if (signal.type !== 'chat_message')
+    if (!this.canResumeFromGiveUp(signal))
       return
 
     this.givenUp = false
     this.giveUpReason = undefined
   }
+
+  private canResumeFromGiveUp(signal: PerceptionSignal): boolean {
+    return signal.type === 'chat_message' || signal.type === 'airi_command'
+  }
 }