agentshire 1.0.0

package/src/bridge/EventTranslator.ts

@@ -0,0 +1,142 @@
+// @desc Lightweight AgentEvent → GameEvent translator used as fallback by DirectorBridge
+import type { AgentEvent } from '../contracts/events.js'
+import type { StateTracker } from './StateTracker.js'
+import type { GameEvent } from '../../town-frontend/src/data/GameProtocol.js'
+
+export type { GameEvent } from '../../town-frontend/src/data/GameProtocol.js'
+
+const FILE_TOOLS = new Set(['read_file', 'write_file', 'edit_file'])
+
+function extractFilePath(toolName: string, input: Record<string, unknown>): string | null {
+  if (FILE_TOOLS.has(toolName)) return (input.path ?? input.file) as string | null
+  if (toolName === 'bash') {
+    const cmd = String(input.command ?? '')
+    const m = cmd.match(/(?:cat|head|tail|vi|vim|nano|code)\s+["']?([^\s"']+)/)
+    return m ? m[1] : null
+  }
+  return null
+}
+
+/** Translates AgentEvent (from the agent protocol) into GameEvent[] (consumed by the 3D frontend). Used by DirectorBridge as a default/fallback handler for event types it doesn't process directly. */
+export class EventTranslator {
+  private tracker: StateTracker
+
+  constructor(tracker: StateTracker) {
+    this.tracker = tracker
+  }
+
+  /** Main entry: switch on event type and return corresponding GameEvents */
+  translate(event: AgentEvent, contextNpcId?: string): GameEvent[] {
+    switch (event.type) {
+      case 'system':
+        return this.handleSystem(event)
+      case 'sub_agent':
+        return this.handleSubAgent(event)
+      case 'text_delta':
+        return [{ type: 'dialog_message', npcId: contextNpcId ?? this.tracker.stewardNpcId, text: event.delta, isStreaming: true }]
+      case 'text':
+        return [{ type: 'dialog_message', npcId: contextNpcId ?? this.tracker.stewardNpcId, text: event.content, isStreaming: false }]
+      case 'tool_use':
+        return this.handleToolUse(event, contextNpcId)
+      case 'tool_result':
+        return this.handleToolResult(event, contextNpcId)
+      case 'thinking_delta':
+        return contextNpcId
+          ? [{ type: 'npc_phase', npcId: contextNpcId, phase: 'thinking' }]
+          : [{ type: 'npc_phase', npcId: this.tracker.stewardNpcId, phase: 'thinking' }]
+      case 'turn_end':
+        return contextNpcId
+          ? [{ type: 'npc_phase', npcId: contextNpcId, phase: 'idle' }, { type: 'workstation_screen', stationId: '', state: { mode: 'off' } }]
+          : []
+      case 'bus_message': {
+        const fromNpc = this.tracker.resolveNpcId(event.from)
+        if (fromNpc) return [{ type: 'dialog_message', npcId: fromNpc, text: event.summary, isStreaming: false }]
+        return []
+      }
+      case 'world_control': {
+        if (event.target === 'time') {
+          return [{ type: 'set_time' as const, action: event.action, hour: event.hour }]
+        }
+        if (event.target === 'weather') {
+          return [{ type: 'set_weather' as const, action: event.action, weather: event.weather }]
+        }
+        return []
+      }
+      case 'error':
+        return contextNpcId
+          ? [{ type: 'npc_phase', npcId: contextNpcId, phase: 'error' }, { type: 'npc_emote', npcId: contextNpcId, emote: 'frustrated' }]
+          : []
+      default:
+        return []
+    }
+  }
+
+  private handleSystem(event: Extract<AgentEvent, { type: 'system' }>): GameEvent[] {
+    if (event.subtype === 'init') {
+      console.log('[EventTranslator] handleSystem init, sending world_init (NPCs already spawned by MainScene from town-defaults.json)')
+      return [
+        { type: 'world_init', config: { townName: '夏尔', stewardName: 'OpenClaw', citizenCount: 5 } },
+      ]
+    }
+    return []
+  }
+
+  private handleSubAgent(event: Extract<AgentEvent, { type: 'sub_agent' }>): GameEvent[] {
+    const { subtype, agentId } = event
+
+    if (subtype === 'started') {
+      const displayName = event.displayName ?? agentId
+      const npcId = agentId.replace(/^agent_/, '')
+      this.tracker.registerMapping(agentId, npcId)
+      const stationId = this.tracker.allocateStation()
+
+      const events: GameEvent[] = [
+        { type: 'npc_spawn', npcId, name: displayName, role: 'programming', category: 'citizen', task: event.task },
+      ]
+      if (stationId) {
+        this.tracker.setStationForNpc(npcId, stationId)
+        events.push({ type: 'workstation_assign', npcId, stationId })
+      }
+      return events
+    }
+
+    if (subtype === 'done') {
+      const npcId = this.tracker.resolveNpcId(agentId)
+      if (!npcId) return []
+      const status = event.status as string
+      const isError = status === 'failed'
+      this.tracker.removeMapping(agentId)
+      return [
+        { type: 'npc_phase', npcId, phase: isError ? 'error' : 'done' },
+        { type: 'npc_glow', npcId, color: isError ? 'red' : 'green' },
+        { type: 'fx', effect: isError ? 'error_sparks' : 'completion_stars', params: { npcId } },
+      ]
+    }
+
+    if (subtype === 'progress') {
+      const npcId = this.tracker.resolveNpcId(agentId)
+      if (!npcId) return []
+      return this.translate(event.event, npcId)
+    }
+
+    return []
+  }
+
+  private handleToolUse(event: Extract<AgentEvent, { type: 'tool_use' }>, contextNpcId?: string): GameEvent[] {
+    const npcId = contextNpcId ?? this.tracker.stewardNpcId
+    const filePath = extractFilePath(event.name, event.input)
+    const events: GameEvent[] = [{ type: 'npc_phase', npcId, phase: 'working' }]
+    if (filePath) {
+      const fileName = filePath.split('/').pop() ?? filePath
+      events.push({ type: 'workstation_screen', stationId: '', state: { mode: 'coding', fileName } })
+    }
+    return events
+  }
+
+  private handleToolResult(event: Extract<AgentEvent, { type: 'tool_result' }>, contextNpcId?: string): GameEvent[] {
+    if (event.meta?.filePath) {
+      return [{ type: 'workstation_screen', stationId: '', state: { mode: 'done' } }]
+    }
+    return []
+  }
+}

package/src/bridge/NpcEventQueue.ts

@@ -0,0 +1,61 @@
+// @desc Event queue that protects dialog bubbles from being overridden by rapid phase changes
+import type { GameEvent } from '../../town-frontend/src/data/GameProtocol.js'
+
+/** Calculate how long a dialog bubble should stay visible based on text length */
+export function calcDialogDuration(textLength: number): number {
+  return Math.min(8000, Math.max(1500, textLength * 120))
+}
+
+/** Queue that serializes dialog and phase events per NPC, ensuring dialogs display long enough before phase changes take effect */
+export class NpcEventQueue {
+  private pendingPhase: Array<{ events: GameEvent[] }> = []
+  private dialogProtected = false
+  private dialogTimer: ReturnType<typeof setTimeout> | null = null
+  private dialogTextLength = 0
+  private emitFn: (events: GameEvent[]) => void
+
+  constructor(emitFn: (events: GameEvent[]) => void) {
+    this.emitFn = emitFn
+  }
+
+  /** Emit dialog events immediately and protect the bubble for a duration proportional to text length */
+  enqueueDialog(events: GameEvent[], textLength: number): void {
+    this.emitFn(events)
+
+    this.dialogTextLength += textLength
+    this.dialogProtected = true
+
+    if (this.dialogTimer) clearTimeout(this.dialogTimer)
+    const duration = calcDialogDuration(this.dialogTextLength)
+    this.dialogTimer = setTimeout(() => {
+      this.dialogProtected = false
+      this.dialogTimer = null
+      this.dialogTextLength = 0
+      this.drainPending()
+    }, duration)
+  }
+
+  /** Emit phase events immediately if no dialog is protected, otherwise buffer until dialog expires */
+  enqueuePhase(events: GameEvent[]): void {
+    if (this.dialogProtected) {
+      this.pendingPhase.push({ events })
+    } else {
+      this.emitFn(events)
+    }
+  }
+
+  /** Cancel any active dialog protection and drain all pending phase events */
+  flush(): void {
+    if (this.dialogTimer) { clearTimeout(this.dialogTimer); this.dialogTimer = null }
+    this.dialogProtected = false
+    this.dialogTextLength = 0
+    this.drainPending()
+  }
+
+  private drainPending(): void {
+    const pending = this.pendingPhase.splice(0)
+    for (const p of pending) {
+      this.emitFn(p.events)
+    }
+  }
+}

package/src/bridge/ReconnectManager.ts

@@ -0,0 +1,42 @@
+// @desc Exponential backoff reconnection manager for WebSocket connections
+export type ReconnectCallback = () => void
+
+/** Schedules reconnection attempts with exponential backoff, resettable on success */
+export class ReconnectManager {
+  private attempt = 0
+  private maxDelay = 30_000
+  private timer: ReturnType<typeof setTimeout> | null = null
+  private onReconnect: ReconnectCallback
+
+  constructor(onReconnect: ReconnectCallback) {
+    this.onReconnect = onReconnect
+  }
+
+  /** Schedule the next reconnection attempt with exponential backoff */
+  scheduleReconnect(): void {
+    const delay = Math.min(1000 * Math.pow(2, this.attempt), this.maxDelay)
+    this.attempt++
+    console.log(`[ReconnectManager] Reconnecting in ${delay}ms (attempt ${this.attempt})`)
+    this.timer = setTimeout(() => {
+      this.onReconnect()
+    }, delay)
+  }
+
+  /** Reset attempt counter and cancel any pending reconnect timer */
+  onSuccess(): void {
+    this.attempt = 0
+    if (this.timer) {
+      clearTimeout(this.timer)
+      this.timer = null
+    }
+  }
+
+  /** Stop all reconnection attempts and reset state */
+  stop(): void {
+    if (this.timer) {
+      clearTimeout(this.timer)
+      this.timer = null
+    }
+    this.attempt = 0
+  }
+}

package/src/bridge/RouteManager.ts

@@ -0,0 +1,270 @@
+// @desc A* pathfinding, NPC movement requests with ack/timeout, and destination claim management
+import type { GameEvent } from '../../town-frontend/src/data/GameProtocol.js'
+import { CITIZEN_DESTINATION_POINTS, ROUTE_GRAPHS, type RouteNode, type RouteSceneId } from './data/route-config.js'
+
+export const CITIZEN_SPAWN_ORIGIN = { x: 20, z: 24 }
+export const PLAZA_CENTER = { x: 18, z: 13 }
+export const LEAVE_PLAZA_MIN_DISTANCE = 6.2
+export const GREET_RING_RADIUS = 2.2
+export const STEWARD_FACE_POS = { x: 17, z: 15.8 }
+
+/** Manages NPC navigation: A* route planning on the town/office graph, move-and-wait with timeout, and destination slot allocation to prevent overcrowding */
+export class RouteManager {
+  moveRequestSeq = 0
+  pendingMoveRequests = new Map<
+    string,
+    {
+      npcId: string
+      resolve: (status: 'arrived' | 'interrupted') => void
+      timer: ReturnType<typeof setTimeout>
+    }
+  >()
+  destinationClaimCount = new Map<string, number>()
+  npcDestinationClaim = new Map<string, string>()
+  npcLastDestination = new Map<string, string>()
+
+  private emitFn: (events: GameEvent[]) => void
+
+  constructor(emitFn: (events: GameEvent[]) => void) {
+    this.emitFn = emitFn
+  }
+
+  nextMoveRequestId(npcId: string): string {
+    this.moveRequestSeq += 1
+    return `${npcId}-move-${this.moveRequestSeq}`
+  }
+
+  /** Called by DirectorBridge when frontend reports NPC arrival or interruption */
+  resolveMoveRequest(requestId: string, npcId: string, status: 'arrived' | 'interrupted'): void {
+    if (!requestId) return
+    const pending = this.pendingMoveRequests.get(requestId)
+    if (!pending) return
+    clearTimeout(pending.timer)
+    this.pendingMoveRequests.delete(requestId)
+    if (pending.npcId !== npcId) {
+      console.warn(`[RouteManager][MoveAck] requestId=${requestId} npc mismatch expected=${pending.npcId} actual=${npcId}`)
+    }
+    pending.resolve(status)
+  }
+
+  /** Emit a move command and return a promise that resolves when the frontend acks arrival or timeout expires */
+  moveNpcAndWait(
+    npcId: string,
+    target: { x: number; y: number; z: number },
+    speed: number,
+    timeoutMs = 25000,
+  ): Promise<'arrived' | 'interrupted'> {
+    const requestId = this.nextMoveRequestId(npcId)
+    return new Promise<'arrived' | 'interrupted'>((resolve) => {
+      const timer = setTimeout(() => {
+        this.pendingMoveRequests.delete(requestId)
+        console.warn(`[RouteManager][MoveAck] timeout npc=${npcId} requestId=${requestId}`)
+        resolve('interrupted')
+      }, timeoutMs)
+
+      this.pendingMoveRequests.set(requestId, { npcId, resolve, timer })
+      this.emitFn([{ type: 'npc_move_to', npcId, target, speed, requestId }])
+    })
+  }
+
+  distance2D(a: { x: number; z: number }, b: { x: number; z: number }): number {
+    const dx = a.x - b.x
+    const dz = a.z - b.z
+    return Math.sqrt(dx * dx + dz * dz)
+  }
+
+  /** Calculate a position on the greeting ring around the steward for the Nth citizen */
+  getGreetPoint(idx: number): { x: number; z: number } {
+    const angle = (idx * 1.37) % (Math.PI * 2)
+    const r = GREET_RING_RADIUS + (Math.random() - 0.5) * 0.45
+    return {
+      x: STEWARD_FACE_POS.x + Math.cos(angle) * r,
+      z: STEWARD_FACE_POS.z + Math.sin(angle) * r,
+    }
+  }
+
+  computeLeavePlazaPoint(from: { x: number; z: number }): { x: number; z: number } {
+    let dx = from.x - PLAZA_CENTER.x
+    let dz = from.z - PLAZA_CENTER.z
+    const len = Math.sqrt(dx * dx + dz * dz)
+    if (len < 0.0001) {
+      const angle = Math.random() * Math.PI * 2
+      dx = Math.cos(angle)
+      dz = Math.sin(angle)
+    } else {
+      dx /= len
+      dz /= len
+    }
+    const targetDist = LEAVE_PLAZA_MIN_DISTANCE + 0.7 + Math.random() * 1.8
+    return {
+      x: PLAZA_CENTER.x + dx * targetDist,
+      z: PLAZA_CENTER.z + dz * targetDist,
+    }
+  }
+
+  /** Register that an NPC has claimed a destination slot */
+  claimDestinationForNpc(npcId: string, destinationId: string): void {
+    const prev = this.npcDestinationClaim.get(npcId)
+    if (prev === destinationId) return
+    if (prev) {
+      const prevCount = this.destinationClaimCount.get(prev) ?? 0
+      if (prevCount <= 1) this.destinationClaimCount.delete(prev)
+      else this.destinationClaimCount.set(prev, prevCount - 1)
+    }
+    this.npcDestinationClaim.set(npcId, destinationId)
+    this.destinationClaimCount.set(destinationId, (this.destinationClaimCount.get(destinationId) ?? 0) + 1)
+    this.npcLastDestination.set(npcId, destinationId)
+  }
+
+  /** Release a previously claimed destination slot */
+  releaseDestinationClaim(npcId: string, destinationId: string): void {
+    const current = this.npcDestinationClaim.get(npcId)
+    if (current !== destinationId) return
+    this.npcDestinationClaim.delete(npcId)
+    const count = this.destinationClaimCount.get(destinationId) ?? 0
+    if (count <= 1) this.destinationClaimCount.delete(destinationId)
+    else this.destinationClaimCount.set(destinationId, count - 1)
+  }
+
+  releaseDestinationClaimLater(npcId: string, destinationId: string, delayMs: number): void {
+    setTimeout(() => {
+      this.releaseDestinationClaim(npcId, destinationId)
+    }, delayMs)
+  }
+
+  /** Score and select the best destination point for a citizen, avoiding recently visited or overcrowded spots */
+  chooseCitizenDestination(npcId: string, from: { x: number; z: number }): { id: string; x: number; z: number; score: number } {
+    const last = this.npcLastDestination.get(npcId)
+    let best: { id: string; x: number; z: number; score: number } | null = null
+    const candidates = CITIZEN_DESTINATION_POINTS.filter((d) => {
+      const plazaDistance = this.distance2D({ x: d.x, z: d.z }, PLAZA_CENTER)
+      if (plazaDistance < LEAVE_PLAZA_MIN_DISTANCE) return false
+      return (this.destinationClaimCount.get(d.id) ?? 0) === 0
+    })
+    const pool = candidates.length > 0 ? candidates : CITIZEN_DESTINATION_POINTS
+
+    for (const d of pool) {
+      const plazaDistance = this.distance2D({ x: d.x, z: d.z }, PLAZA_CENTER)
+      if (plazaDistance < LEAVE_PLAZA_MIN_DISTANCE) continue
+      const distFromCurrent = this.distance2D(from, { x: d.x, z: d.z })
+      const claimCount = this.destinationClaimCount.get(d.id) ?? 0
+      const sameAsLastPenalty = d.id === last ? 8 : 0
+      const claimPenalty = claimCount * 6
+      const randomBonus = Math.random() * 2.5
+      const score = randomBonus - distFromCurrent * 0.42 - claimPenalty - sameAsLastPenalty
+      if (!best || score > best.score) {
+        best = { id: d.id, x: d.x, z: d.z, score }
+      }
+    }
+
+    if (best) return best
+    const fallback = CITIZEN_DESTINATION_POINTS[Math.floor(Math.random() * CITIZEN_DESTINATION_POINTS.length)]
+    return { id: fallback.id, x: fallback.x, z: fallback.z, score: -999 }
+  }
+
+  getRouteGraph(scene: RouteSceneId): Record<string, RouteNode> {
+    return ROUTE_GRAPHS[scene] ?? ROUTE_GRAPHS.town
+  }
+
+  inferRouteScene(from: { x: number; z: number }, to: { x: number; z: number }): RouteSceneId {
+    if (from.z <= 8.5 && to.z <= 8.5) return 'office'
+    return 'town'
+  }
+
+  isRouteDebugEnabled(): boolean {
+    try {
+      const g = globalThis as unknown as { location?: { search?: string }; localStorage?: { getItem?: (key: string) => string | null } }
+      const search = typeof g.location?.search === 'string'
+        ? new URLSearchParams(g.location.search)
+        : null
+      if (search?.get('routeDebug') === '1') return true
+      const local = g.localStorage?.getItem?.('agentshire_route_debug')
+      return local === '1' || local === 'true'
+    } catch {
+      return false
+    }
+  }
+
+  getNearestRouteNodeId(pos: { x: number; z: number }, scene: RouteSceneId): string {
+    const graph = this.getRouteGraph(scene)
+    const fallbackId = Object.keys(graph)[0] ?? 'plaza_c'
+    let bestId = fallbackId
+    let bestDist = Number.POSITIVE_INFINITY
+    for (const [id, node] of Object.entries(graph)) {
+      const d = this.distance2D(pos, node)
+      if (d < bestDist) {
+        bestDist = d
+        bestId = id
+      }
+    }
+    return bestId
+  }
+
+  planRouteNodePath(startId: string, endId: string, scene: RouteSceneId): string[] {
+    const graph = this.getRouteGraph(scene)
+    if (startId === endId) return [startId]
+    const open = new Set<string>([startId])
+    const cameFrom = new Map<string, string>()
+    const gScore = new Map<string, number>()
+    const fScore = new Map<string, number>()
+
+    const heuristic = (a: string, b: string): number =>
+      this.distance2D(graph[a], graph[b])
+
+    gScore.set(startId, 0)
+    fScore.set(startId, heuristic(startId, endId))
+
+    while (open.size > 0) {
+      let current: string | null = null
+      let bestF = Number.POSITIVE_INFINITY
+      for (const id of open) {
+        const f = fScore.get(id) ?? Number.POSITIVE_INFINITY
+        if (f < bestF) {
+          bestF = f
+          current = id
+        }
+      }
+      if (!current) break
+      if (current === endId) {
+        const path: string[] = [current]
+        while (cameFrom.has(current)) {
+          current = cameFrom.get(current)!
+          path.push(current)
+        }
+        path.reverse()
+        return path
+      }
+      open.delete(current)
+      const node = graph[current]
+      for (const neighbor of node.neighbors) {
+        const tentative = (gScore.get(current) ?? Number.POSITIVE_INFINITY)
+          + this.distance2D(node, graph[neighbor])
+        if (tentative < (gScore.get(neighbor) ?? Number.POSITIVE_INFINITY)) {
+          cameFrom.set(neighbor, current)
+          gScore.set(neighbor, tentative)
+          fScore.set(neighbor, tentative + heuristic(neighbor, endId))
+          open.add(neighbor)
+        }
+      }
+    }
+
+    return [startId, endId]
+  }
+
+  /** Plan a multi-waypoint route through the graph from source to destination */
+  planSceneRoute(scene: RouteSceneId, from: { x: number; z: number }, to: { x: number; z: number }): Array<{ x: number; z: number }> {
+    const graph = this.getRouteGraph(scene)
+    const start = this.getNearestRouteNodeId(from, scene)
+    const end = this.getNearestRouteNodeId(to, scene)
+    const nodePath = this.planRouteNodePath(start, end, scene)
+    const points: Array<{ x: number; z: number }> = []
+
+    for (const [idx, id] of nodePath.entries()) {
+      if (idx === 0 && this.distance2D(from, graph[id]) < 1.2) continue
+      if (idx === nodePath.length - 1 && this.distance2D(to, graph[id]) < 1.2) continue
+      points.push({ x: graph[id].x, z: graph[id].z })
+    }
+    points.push({ x: to.x, z: to.z })
+    return points
+  }
+}

package/src/bridge/StateTracker.ts

@@ -0,0 +1,100 @@
+// @desc Bidirectional agentId ↔ npcId mapping and workstation allocation
+export interface NPCState {
+  npcId: string
+  agentId: string
+  phase: string
+  stationId?: string
+}
+
+const WORKSTATION_IDS = ['B', 'C', 'F', 'G', 'D', 'E', 'H', 'A', 'I', 'J']
+
+/** Maintains bidirectional agentId ↔ npcId mappings and allocates workstation slots for sub-agent NPCs */
+export class StateTracker {
+  private agentToNpc = new Map<string, string>()
+  private npcToAgent = new Map<string, string>()
+  private npcStates = new Map<string, NPCState>()
+  private usedStations = new Set<string>()
+
+  readonly stewardNpcId = 'steward'
+
+  /** Resolve an agentId to its corresponding npcId */
+  resolveNpcId(agentId: string): string | undefined {
+    return this.agentToNpc.get(agentId)
+  }
+
+  resolveAgentId(npcId: string): string | undefined {
+    return this.npcToAgent.get(npcId)
+  }
+
+  getStationForNpc(npcId: string): string | undefined {
+    return this.npcStates.get(npcId)?.stationId
+  }
+
+  /** Register a bidirectional agentId ↔ npcId mapping */
+  registerMapping(agentId: string, npcId: string): void {
+    this.agentToNpc.set(agentId, npcId)
+    this.npcToAgent.set(npcId, agentId)
+  }
+
+  /** Remove a mapping and associated NPC state by agentId */
+  removeMapping(agentId: string): void {
+    const npcId = this.agentToNpc.get(agentId)
+    if (npcId) {
+      const state = this.npcStates.get(npcId)
+      if (state?.stationId) {
+        this.usedStations.delete(state.stationId)
+      }
+      this.npcToAgent.delete(npcId)
+      this.npcStates.delete(npcId)
+    }
+    this.agentToNpc.delete(agentId)
+  }
+
+  removeMappingByNpcId(npcId: string): void {
+    const agentId = this.npcToAgent.get(npcId)
+    if (agentId) {
+      this.removeMapping(agentId)
+    }
+  }
+
+  /** Allocate the next available workstation ID, or null if all are in use */
+  allocateStation(): string | null {
+    for (const id of WORKSTATION_IDS) {
+      if (!this.usedStations.has(id)) {
+        this.usedStations.add(id)
+        return id
+      }
+    }
+    return null
+  }
+
+  releaseStation(stationId: string): void {
+    this.usedStations.delete(stationId)
+  }
+
+  updatePhase(npcId: string, phase: string): void {
+    const state = this.npcStates.get(npcId)
+    if (state) state.phase = phase
+  }
+
+  setStationForNpc(npcId: string, stationId: string): void {
+    let state = this.npcStates.get(npcId)
+    if (!state) {
+      state = { npcId, agentId: this.npcToAgent.get(npcId) ?? '', phase: 'idle' }
+      this.npcStates.set(npcId, state)
+    }
+    state.stationId = stationId
+  }
+
+  getAllNpcStates(): NPCState[] {
+    return [...this.npcStates.values()]
+  }
+
+  /** Reset all mappings, NPC states, and station allocations */
+  clear(): void {
+    this.agentToNpc.clear()
+    this.npcToAgent.clear()
+    this.npcStates.clear()
+    this.usedStations.clear()
+  }
+}