agentshire 1.0.0

package/src/bridge/__tests__/EventTranslator.test.ts

@@ -0,0 +1,292 @@
+// @desc Tests for EventTranslator: AgentEvent → GameEvent mapping
+import { describe, it, expect, beforeEach } from 'vitest'
+import { EventTranslator } from '../EventTranslator.js'
+import { StateTracker } from '../StateTracker.js'
+import type { AgentEvent } from '../../contracts/events.js'
+
+describe('EventTranslator', () => {
+  let tracker: StateTracker
+  let translator: EventTranslator
+
+  beforeEach(() => {
+    tracker = new StateTracker()
+    translator = new EventTranslator(tracker)
+  })
+
+  describe('system.init', () => {
+    it('should return world_init GameEvent', () => {
+      const event: AgentEvent = { type: 'system', subtype: 'init', sessionId: 'sess-1', model: 'test' }
+      const result = translator.translate(event)
+
+      expect(result).toHaveLength(1)
+      expect(result[0]).toMatchObject({
+        type: 'world_init',
+        config: { townName: '夏尔', stewardName: 'OpenClaw', citizenCount: 5 },
+      })
+    })
+  })
+
+  describe('sub_agent.started', () => {
+    it('should return npc_spawn and workstation_assign when station available', () => {
+      const event: AgentEvent = {
+        type: 'sub_agent',
+        subtype: 'started',
+        agentId: 'agent_alice',
+        agentType: 'sub',
+        parentToolUseId: 'tool-1',
+        task: 'Build the frontend',
+        model: 'test',
+        displayName: 'Alice',
+      }
+      const result = translator.translate(event)
+
+      expect(result.length).toBeGreaterThanOrEqual(2)
+      expect(result[0]).toMatchObject({
+        type: 'npc_spawn',
+        npcId: 'alice',
+        name: 'Alice',
+        role: 'programming',
+        category: 'citizen',
+        task: 'Build the frontend',
+      })
+      expect(result[1]).toMatchObject({
+        type: 'workstation_assign',
+        npcId: 'alice',
+      })
+      expect((result[1] as any).stationId).toBeTruthy()
+    })
+
+    it('should register agent→NPC mapping in StateTracker', () => {
+      const event: AgentEvent = {
+        type: 'sub_agent',
+        subtype: 'started',
+        agentId: 'agent_bob',
+        agentType: 'sub',
+        parentToolUseId: 'tool-2',
+        task: 'Write tests',
+        model: 'test',
+      }
+      translator.translate(event)
+
+      expect(tracker.resolveNpcId('agent_bob')).toBe('bob')
+    })
+
+    it('should use agentId as displayName when displayName is absent', () => {
+      const event: AgentEvent = {
+        type: 'sub_agent',
+        subtype: 'started',
+        agentId: 'agent_charlie',
+        agentType: 'sub',
+        parentToolUseId: 'tool-3',
+        task: 'Deploy',
+        model: 'test',
+      }
+      const result = translator.translate(event)
+
+      expect(result[0]).toMatchObject({ type: 'npc_spawn', name: 'agent_charlie' })
+    })
+
+    it('should allocate all 10 office workstations before running out', () => {
+      const assignedStations = new Set<string>()
+
+      for (let i = 0; i < 10; i++) {
+        const event: AgentEvent = {
+          type: 'sub_agent',
+          subtype: 'started',
+          agentId: `agent_worker_${i}`,
+          agentType: 'sub',
+          parentToolUseId: `tool-${i}`,
+          task: 'Test allocation',
+          model: 'test',
+        }
+        const result = translator.translate(event)
+        const workstationAssign = result.find(e => e.type === 'workstation_assign')
+        expect(workstationAssign).toBeTruthy()
+        assignedStations.add((workstationAssign as { stationId: string }).stationId)
+      }
+
+      expect(assignedStations.size).toBe(10)
+
+      const overflowEvent: AgentEvent = {
+        type: 'sub_agent',
+        subtype: 'started',
+        agentId: 'agent_worker_overflow',
+        agentType: 'sub',
+        parentToolUseId: 'tool-overflow',
+        task: 'Overflow allocation',
+        model: 'test',
+      }
+      const overflowResult = translator.translate(overflowEvent)
+
+      expect(overflowResult.some(e => e.type === 'workstation_assign')).toBe(false)
+    })
+  })
+
+  describe('sub_agent.done (success)', () => {
+    it('should return npc_phase(done) + npc_glow(green) + fx(completion_stars)', () => {
+      tracker.registerMapping('agent_alice', 'alice')
+
+      const event: AgentEvent = {
+        type: 'sub_agent',
+        subtype: 'done',
+        agentId: 'agent_alice',
+        result: 'All done',
+        toolCalls: 5,
+        status: 'completed',
+      }
+      const result = translator.translate(event)
+
+      expect(result).toHaveLength(3)
+      expect(result[0]).toMatchObject({ type: 'npc_phase', npcId: 'alice', phase: 'done' })
+      expect(result[1]).toMatchObject({ type: 'npc_glow', npcId: 'alice', color: 'green' })
+      expect(result[2]).toMatchObject({ type: 'fx', effect: 'completion_stars', params: { npcId: 'alice' } })
+    })
+  })
+
+  describe('sub_agent.done (failed)', () => {
+    it('should return npc_phase(error) + npc_glow(red) + fx(error_sparks)', () => {
+      tracker.registerMapping('agent_bob', 'bob')
+
+      const event: AgentEvent = {
+        type: 'sub_agent',
+        subtype: 'done',
+        agentId: 'agent_bob',
+        result: 'Crashed',
+        toolCalls: 2,
+        status: 'failed',
+      }
+      const result = translator.translate(event)
+
+      expect(result).toHaveLength(3)
+      expect(result[0]).toMatchObject({ type: 'npc_phase', npcId: 'bob', phase: 'error' })
+      expect(result[1]).toMatchObject({ type: 'npc_glow', npcId: 'bob', color: 'red' })
+      expect(result[2]).toMatchObject({ type: 'fx', effect: 'error_sparks', params: { npcId: 'bob' } })
+    })
+
+    it('should return empty array when agentId has no mapping', () => {
+      const event: AgentEvent = {
+        type: 'sub_agent',
+        subtype: 'done',
+        agentId: 'unknown_agent',
+        result: '',
+        toolCalls: 0,
+        status: 'completed',
+      }
+      const result = translator.translate(event)
+
+      expect(result).toEqual([])
+    })
+  })
+
+  describe('text_delta', () => {
+    it('should return dialog_message with isStreaming: true', () => {
+      const event: AgentEvent = { type: 'text_delta', delta: 'Hello world' }
+      const result = translator.translate(event)
+
+      expect(result).toHaveLength(1)
+      expect(result[0]).toMatchObject({
+        type: 'dialog_message',
+        npcId: 'steward',
+        text: 'Hello world',
+        isStreaming: true,
+      })
+    })
+
+    it('should use contextNpcId when provided', () => {
+      const event: AgentEvent = { type: 'text_delta', delta: 'Working...' }
+      const result = translator.translate(event, 'alice')
+
+      expect(result[0]).toMatchObject({ type: 'dialog_message', npcId: 'alice', isStreaming: true })
+    })
+  })
+
+  describe('text', () => {
+    it('should return dialog_message with isStreaming: false', () => {
+      const event: AgentEvent = { type: 'text', content: 'Final answer' }
+      const result = translator.translate(event)
+
+      expect(result).toHaveLength(1)
+      expect(result[0]).toMatchObject({
+        type: 'dialog_message',
+        npcId: 'steward',
+        text: 'Final answer',
+        isStreaming: false,
+      })
+    })
+  })
+
+  describe('tool_use', () => {
+    it('should return npc_phase(working)', () => {
+      const event: AgentEvent = {
+        type: 'tool_use',
+        toolUseId: 'tu-1',
+        name: 'bash',
+        input: { command: 'echo hello' },
+      }
+      const result = translator.translate(event)
+
+      expect(result.length).toBeGreaterThanOrEqual(1)
+      expect(result[0]).toMatchObject({ type: 'npc_phase', npcId: 'steward', phase: 'working' })
+    })
+
+    it('should include workstation_screen when tool targets a file', () => {
+      const event: AgentEvent = {
+        type: 'tool_use',
+        toolUseId: 'tu-2',
+        name: 'read_file',
+        input: { path: '/src/index.ts' },
+      }
+      const result = translator.translate(event)
+
+      expect(result).toHaveLength(2)
+      expect(result[1]).toMatchObject({
+        type: 'workstation_screen',
+        state: { mode: 'coding', fileName: 'index.ts' },
+      })
+    })
+  })
+
+  describe('thinking_delta', () => {
+    it('should return npc_phase(thinking) for steward when no contextNpcId', () => {
+      const event: AgentEvent = { type: 'thinking_delta', delta: 'hmm...' }
+      const result = translator.translate(event)
+
+      expect(result).toHaveLength(1)
+      expect(result[0]).toMatchObject({ type: 'npc_phase', npcId: 'steward', phase: 'thinking' })
+    })
+
+    it('should use contextNpcId when provided', () => {
+      const event: AgentEvent = { type: 'thinking_delta', delta: 'considering...' }
+      const result = translator.translate(event, 'bob')
+
+      expect(result[0]).toMatchObject({ type: 'npc_phase', npcId: 'bob', phase: 'thinking' })
+    })
+  })
+
+  describe('error', () => {
+    it('should return npc_phase(error) + npc_emote(frustrated) when contextNpcId provided', () => {
+      const event: AgentEvent = { type: 'error', message: 'Something broke', recoverable: false }
+      const result = translator.translate(event, 'alice')
+
+      expect(result).toHaveLength(2)
+      expect(result[0]).toMatchObject({ type: 'npc_phase', npcId: 'alice', phase: 'error' })
+      expect(result[1]).toMatchObject({ type: 'npc_emote', npcId: 'alice', emote: 'frustrated' })
+    })
+
+    it('should return empty array when no contextNpcId', () => {
+      const event: AgentEvent = { type: 'error', message: 'fail', recoverable: true }
+      const result = translator.translate(event)
+
+      expect(result).toEqual([])
+    })
+  })
+
+  describe('unknown event type', () => {
+    it('should return empty array', () => {
+      const event = { type: 'debug', category: 'test', message: 'blah' } as AgentEvent
+      const result = translator.translate(event)
+
+      expect(result).toEqual([])
+    })
+  })
+})

package/src/bridge/__tests__/NpcEventQueue.test.ts

@@ -0,0 +1,92 @@
+// @desc Tests for NpcEventQueue: dialog protection and phase event buffering
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+import { NpcEventQueue, calcDialogDuration } from '../NpcEventQueue.js'
+
+describe('calcDialogDuration', () => {
+  it('returns minimum 1500 for very short text', () => {
+    expect(calcDialogDuration(0)).toBe(1500)
+    expect(calcDialogDuration(5)).toBe(1500)
+  })
+
+  it('scales linearly with text length', () => {
+    expect(calcDialogDuration(20)).toBe(2400) // 20 * 120
+  })
+
+  it('caps at 8000 for long text', () => {
+    expect(calcDialogDuration(200)).toBe(8000)
+    expect(calcDialogDuration(1000)).toBe(8000)
+  })
+})
+
+describe('NpcEventQueue', () => {
+  let emitFn: ReturnType<typeof vi.fn>
+  let queue: NpcEventQueue
+
+  beforeEach(() => {
+    vi.useFakeTimers()
+    emitFn = vi.fn()
+    queue = new NpcEventQueue(emitFn)
+  })
+
+  describe('enqueueDialog', () => {
+    it('emits events immediately', () => {
+      const events = [{ type: 'dialog_message', npcId: 'npc1', text: 'hi' }] as any
+      queue.enqueueDialog(events, 5)
+      expect(emitFn).toHaveBeenCalledWith(events)
+    })
+
+    it('starts protection timer that unblocks pending phases after duration', () => {
+      queue.enqueueDialog([{ type: 'dialog_message' }] as any, 20)
+
+      const phaseEvents = [{ type: 'npc_phase' }] as any
+      queue.enqueuePhase(phaseEvents)
+      expect(emitFn).toHaveBeenCalledTimes(1) // only dialog emitted
+
+      vi.advanceTimersByTime(calcDialogDuration(20))
+      expect(emitFn).toHaveBeenCalledTimes(2)
+      expect(emitFn).toHaveBeenLastCalledWith(phaseEvents)
+    })
+  })
+
+  describe('enqueuePhase', () => {
+    it('buffers events during dialog protection', () => {
+      queue.enqueueDialog([{ type: 'dialog_message' }] as any, 10)
+      emitFn.mockClear()
+
+      queue.enqueuePhase([{ type: 'phase_a' }] as any)
+      queue.enqueuePhase([{ type: 'phase_b' }] as any)
+      expect(emitFn).not.toHaveBeenCalled()
+    })
+
+    it('emits immediately when no dialog protection active', () => {
+      const events = [{ type: 'npc_phase' }] as any
+      queue.enqueuePhase(events)
+      expect(emitFn).toHaveBeenCalledWith(events)
+    })
+  })
+
+  describe('flush', () => {
+    it('drains all pending events immediately and cancels protection', () => {
+      queue.enqueueDialog([{ type: 'dialog_message' }] as any, 30)
+      emitFn.mockClear()
+
+      queue.enqueuePhase([{ type: 'phase_a' }] as any)
+      queue.enqueuePhase([{ type: 'phase_b' }] as any)
+
+      queue.flush()
+
+      expect(emitFn).toHaveBeenCalledTimes(2)
+      expect(emitFn).toHaveBeenNthCalledWith(1, [{ type: 'phase_a' }])
+      expect(emitFn).toHaveBeenNthCalledWith(2, [{ type: 'phase_b' }])
+    })
+
+    it('allows subsequent enqueuePhase to emit immediately after flush', () => {
+      queue.enqueueDialog([{ type: 'dialog_message' }] as any, 10)
+      queue.flush()
+      emitFn.mockClear()
+
+      queue.enqueuePhase([{ type: 'phase_c' }] as any)
+      expect(emitFn).toHaveBeenCalledWith([{ type: 'phase_c' }])
+    })
+  })
+})

package/src/bridge/__tests__/RouteManager.test.ts

@@ -0,0 +1,106 @@
+// @desc Tests for RouteManager: A* pathfinding and NPC movement
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+import { RouteManager } from '../RouteManager.js'
+
+vi.mock('../data/route-config.js', () => ({
+  CITIZEN_DESTINATION_POINTS: [
+    { id: 'dest_a', x: 30, z: 20 },
+    { id: 'dest_b', x: 35, z: 25 },
+    { id: 'dest_c', x: 40, z: 30 },
+  ],
+  ROUTE_GRAPHS: {
+    town: {
+      node_a: { x: 10, z: 10, neighbors: ['node_b'] },
+      node_b: { x: 15, z: 10, neighbors: ['node_a', 'node_c'] },
+      node_c: { x: 20, z: 10, neighbors: ['node_b', 'node_d'] },
+      node_d: { x: 20, z: 15, neighbors: ['node_c'] },
+    },
+    office: {
+      off_a: { x: 5, z: 3, neighbors: ['off_b'] },
+      off_b: { x: 8, z: 3, neighbors: ['off_a'] },
+    },
+  },
+}))
+
+describe('RouteManager', () => {
+  let emitFn: ReturnType<typeof vi.fn>
+  let rm: RouteManager
+
+  beforeEach(() => {
+    emitFn = vi.fn()
+    rm = new RouteManager(emitFn)
+  })
+
+  describe('distance2D', () => {
+    it('computes euclidean distance', () => {
+      expect(rm.distance2D({ x: 0, z: 0 }, { x: 3, z: 4 })).toBeCloseTo(5)
+    })
+
+    it('returns 0 for same point', () => {
+      expect(rm.distance2D({ x: 5, z: 5 }, { x: 5, z: 5 })).toBe(0)
+    })
+  })
+
+  describe('planRouteNodePath', () => {
+    it('returns [startId] when start equals end', () => {
+      expect(rm.planRouteNodePath('node_a', 'node_a', 'town')).toEqual(['node_a'])
+    })
+
+    it('returns correct path through graph', () => {
+      const path = rm.planRouteNodePath('node_a', 'node_d', 'town')
+      expect(path[0]).toBe('node_a')
+      expect(path[path.length - 1]).toBe('node_d')
+      expect(path.length).toBeGreaterThanOrEqual(3)
+    })
+
+    it('returns direct [start, end] for disconnected nodes', () => {
+      const path = rm.planRouteNodePath('off_a', 'off_b', 'office')
+      expect(path).toEqual(['off_a', 'off_b'])
+    })
+  })
+
+  describe('chooseCitizenDestination', () => {
+    it('returns a destination object with id, x, z, score', () => {
+      const dest = rm.chooseCitizenDestination('npc1', { x: 10, z: 10 })
+      expect(dest).toHaveProperty('id')
+      expect(dest).toHaveProperty('x')
+      expect(dest).toHaveProperty('z')
+      expect(dest).toHaveProperty('score')
+    })
+
+    it('avoids claimed destinations when unclaimed alternatives exist', () => {
+      rm.claimDestinationForNpc('other_npc', 'dest_a')
+      const results = new Set<string>()
+      for (let i = 0; i < 20; i++) {
+        results.add(rm.chooseCitizenDestination('npc1', { x: 10, z: 10 }).id)
+      }
+      expect(results.has('dest_a')).toBe(false)
+    })
+  })
+
+  describe('moveNpcAndWait', () => {
+    beforeEach(() => {
+      vi.useFakeTimers()
+    })
+
+    it('resolves as interrupted on timeout', async () => {
+      const promise = rm.moveNpcAndWait('npc1', { x: 0, y: 0, z: 0 }, 5, 1000)
+
+      expect(emitFn).toHaveBeenCalledWith([
+        expect.objectContaining({ type: 'npc_move_to', npcId: 'npc1' }),
+      ])
+
+      vi.advanceTimersByTime(1000)
+      await expect(promise).resolves.toBe('interrupted')
+    })
+
+    it('resolves as arrived when resolveMoveRequest is called', async () => {
+      const promise = rm.moveNpcAndWait('npc1', { x: 0, y: 0, z: 0 }, 5, 5000)
+
+      const requestId = emitFn.mock.calls[0][0][0].requestId
+      rm.resolveMoveRequest(requestId, 'npc1', 'arrived')
+
+      await expect(promise).resolves.toBe('arrived')
+    })
+  })
+})

package/src/bridge/data/route-config.json

@@ -0,0 +1,36 @@
+{
+  "citizenDestinationPoints": [
+    { "id": "house_a_door", "x": 5.5, "z": 7.2 },
+    { "id": "house_b_door", "x": 5.4, "z": 12.3 },
+    { "id": "house_c_door", "x": 5.5, "z": 17.1 },
+    { "id": "market_door", "x": 29.2, "z": 6.2 },
+    { "id": "cafe_door", "x": 29.1, "z": 12.0 },
+    { "id": "museum_door", "x": 29.0, "z": 18.0 },
+    { "id": "user_home_door", "x": 10.2, "z": 18.2 }
+  ],
+  "routeGraphs": {
+    "town": {
+      "plaza_n": { "x": 18, "z": 17, "neighbors": ["plaza_c", "west_n", "east_n"] },
+      "plaza_c": { "x": 18, "z": 13, "neighbors": ["plaza_n", "plaza_s", "west_c", "east_c"] },
+      "plaza_s": { "x": 18, "z": 9, "neighbors": ["plaza_c", "west_s", "east_s"] },
+      "west_n": { "x": 12, "z": 17, "neighbors": ["plaza_n", "west_c", "west_far_n"] },
+      "west_c": { "x": 12, "z": 13, "neighbors": ["west_n", "plaza_c", "west_s", "west_far_c"] },
+      "west_s": { "x": 12, "z": 9, "neighbors": ["west_c", "plaza_s", "west_far_s"] },
+      "east_n": { "x": 24, "z": 17, "neighbors": ["plaza_n", "east_c", "east_far_n"] },
+      "east_c": { "x": 24, "z": 13, "neighbors": ["east_n", "plaza_c", "east_s", "east_far_c"] },
+      "east_s": { "x": 24, "z": 9, "neighbors": ["east_c", "plaza_s", "east_far_s"] },
+      "west_far_n": { "x": 8, "z": 17, "neighbors": ["west_n", "west_far_c"] },
+      "west_far_c": { "x": 8, "z": 13, "neighbors": ["west_far_n", "west_c", "west_far_s"] },
+      "west_far_s": { "x": 8, "z": 9, "neighbors": ["west_far_c", "west_s"] },
+      "east_far_n": { "x": 28, "z": 17, "neighbors": ["east_n", "east_far_c"] },
+      "east_far_c": { "x": 28, "z": 13, "neighbors": ["east_far_n", "east_c", "east_far_s"] },
+      "east_far_s": { "x": 28, "z": 9, "neighbors": ["east_far_c", "east_s"] }
+    },
+    "office": {
+      "office_entry_l": { "x": 14, "z": 5, "neighbors": ["office_center"] },
+      "office_entry_c": { "x": 17, "z": 5, "neighbors": ["office_center"] },
+      "office_entry_r": { "x": 20, "z": 5, "neighbors": ["office_center"] },
+      "office_center": { "x": 17, "z": 12, "neighbors": ["office_entry_l", "office_entry_c", "office_entry_r"] }
+    }
+  }
+}

package/src/bridge/data/route-config.ts

@@ -0,0 +1,19 @@
+import config from './route-config.json'
+
+export type RouteSceneId = 'town' | 'office'
+
+export type RouteNode = {
+  x: number
+  z: number
+  neighbors: string[]
+}
+
+type RouteConfigSchema = {
+  citizenDestinationPoints: Array<{ id: string; x: number; z: number }>
+  routeGraphs: Record<RouteSceneId, Record<string, RouteNode>>
+}
+
+const typed = config as RouteConfigSchema
+
+export const CITIZEN_DESTINATION_POINTS = typed.citizenDestinationPoints
+export const ROUTE_GRAPHS = typed.routeGraphs