agentshire 1.0.0

package/src/bridge/ToolVfxMapper.ts

@@ -0,0 +1,94 @@
+// @desc Pure functions mapping tool names to VFX events, emoji, and NPC animation phases
+import type { GameEvent } from '../../town-frontend/src/data/GameProtocol.js'
+
+const IMAGE_EXTENSIONS = new Set(['png', 'jpg', 'jpeg', 'gif', 'webp', 'svg'])
+const VIDEO_EXTENSIONS = new Set(['mp4', 'webm', 'mov', 'm4v'])
+const AUDIO_EXTENSIONS = new Set(['mp3', 'wav', 'ogg', 'm4a', 'aac', 'flac'])
+
+const CARD_TYPES: Record<string, string> = {
+  game: 'game', app: 'app', website: 'website',
+}
+
+/** Extract a file path from tool input args (supports read/write/edit_file and bash commands) */
+export function extractFilePath(toolName: string, input: Record<string, unknown>): string | null {
+  const FILE_TOOLS = new Set(['read_file', 'write_file', 'edit_file'])
+  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
+}
+
+/** Check if a file path refers to a persona directory */
+export function isPersonaPath(filePath: string | null): boolean {
+  if (!filePath) return false
+  return /\bpersonas?\b/i.test(filePath)
+}
+
+/** Return the emoji icon for a given tool name */
+export function toolEmoji(toolName: string): string {
+  if (['write_file', 'edit_file'].includes(toolName)) return '💻'
+  if (toolName === 'bash') return '⚡'
+  if (['read_file', 'grep', 'glob'].includes(toolName)) return '🔍'
+  if (toolName === 'web_search' || toolName === 'web_fetch') return '🌐'
+  if (toolName === 'skill') return '⚡'
+  return '🔧'
+}
+
+const MANAGEMENT_TOOLS = new Set([
+  'sessions_spawn', 'sessions_yield', 'next_step', 'create_plan',
+  'project_complete', 'register_project', 'spawn_agent',
+])
+
+/** Generate GameEvents for NPC animation, emoji, and VFX based on which tool is being used */
+export function toolToVfxEvents(toolName: string, npcId: string, input?: Record<string, unknown>): { events: GameEvent[], phase: string } {
+  const events: GameEvent[] = []
+  const filePath = extractFilePath(toolName, input ?? {})
+  const fileName = filePath?.split('/').pop() ?? ''
+  const isPersona = isPersonaPath(filePath)
+
+  if (MANAGEMENT_TOOLS.has(toolName)) {
+    events.push({ type: 'npc_emoji', npcId, emoji: toolEmoji(toolName) })
+    return { events, phase: 'thinking' }
+  }
+
+  if (['read_file', 'grep', 'glob'].includes(toolName)) {
+    if (isPersona) {
+      return { events, phase: 'documenting' }
+    }
+    events.push({ type: 'npc_anim', npcId, anim: 'reading' })
+    if (fileName) events.push({ type: 'fx', effect: 'fileIcon', params: { npcId, fileName } })
+    events.push({ type: 'npc_emoji', npcId, emoji: toolEmoji(toolName) })
+  } else if (['write_file', 'edit_file'].includes(toolName)) {
+    if (isPersona) {
+      return { events, phase: 'documenting' }
+    }
+    events.push({ type: 'npc_anim', npcId, anim: 'typing' })
+    if (fileName) events.push({ type: 'fx', effect: 'fileIcon', params: { npcId, fileName } })
+    events.push({ type: 'npc_emoji', npcId, emoji: toolEmoji(toolName) })
+  } else if (toolName === 'bash') {
+    events.push({ type: 'npc_anim', npcId, anim: 'typing' })
+    events.push({ type: 'npc_emoji', npcId, emoji: toolEmoji(toolName) })
+  } else if (toolName === 'web_search' || toolName === 'web_fetch') {
+    events.push({ type: 'npc_anim', npcId, anim: 'reading' })
+    events.push({ type: 'fx', effect: 'searchRadar', params: { npcId } })
+    events.push({ type: 'npc_emoji', npcId, emoji: toolEmoji(toolName) })
+  } else {
+    events.push({ type: 'npc_emoji', npcId, emoji: toolEmoji(toolName) })
+  }
+  return { events, phase: 'working' }
+}
+
+/** Infer the deliverable card type (image/video/audio/file) from a file extension */
+export function inferDeliverableCardType(filePath: string): 'image' | 'video' | 'audio' | 'file' {
+  const normalized = filePath.toLowerCase()
+  const extension = normalized.split('.').pop() ?? ''
+  if (IMAGE_EXTENSIONS.has(extension)) return 'image'
+  if (VIDEO_EXTENSIONS.has(extension)) return 'video'
+  if (AUDIO_EXTENSIONS.has(extension)) return 'audio'
+  return 'file'
+}
+
+export { CARD_TYPES }

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

@@ -0,0 +1,156 @@
+// @desc Tests for ActivityStream: thinking buffer and activity log
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest'
+import { ActivityStream } from '../ActivityStream.js'
+
+describe('ActivityStream', () => {
+  let emitFn: ReturnType<typeof vi.fn>
+  let stream: ActivityStream
+
+  beforeEach(() => {
+    vi.useFakeTimers()
+    emitFn = vi.fn()
+    stream = new ActivityStream(emitFn)
+  })
+
+  afterEach(() => {
+    vi.useRealTimers()
+  })
+
+  describe('emitActivity', () => {
+    it('emits npc_activity event with correct fields', () => {
+      stream.emitActivity('npc1', 'wrench', '执行命令')
+      expect(emitFn).toHaveBeenCalledWith([
+        expect.objectContaining({
+          type: 'npc_activity',
+          npcId: 'npc1',
+          icon: 'wrench',
+          message: '执行命令',
+          time: expect.any(String),
+        }),
+      ])
+    })
+  })
+
+  describe('emitActivityStatus', () => {
+    it('marks last activity entry as success', () => {
+      stream.emitActivity('npc1', 'wrench', 'task')
+      emitFn.mockClear()
+
+      stream.emitActivityStatus('npc1', true)
+      expect(emitFn).toHaveBeenCalledWith([
+        expect.objectContaining({
+          type: 'npc_activity_status',
+          npcId: 'npc1',
+          success: true,
+        }),
+      ])
+
+      const replay = stream.getActivityReplayEvents()
+      const activityEntry = replay.find(
+        (e: any) => e.type === 'npc_activity' && e.npcId === 'npc1',
+      )
+      expect(activityEntry.status).toBe(true)
+    })
+
+    it('marks last activity entry as failure', () => {
+      stream.emitActivity('npc1', 'wrench', 'task')
+      stream.emitActivityStatus('npc1', false)
+
+      const replay = stream.getActivityReplayEvents()
+      const activityEntry = replay.find(
+        (e: any) => e.type === 'npc_activity' && e.npcId === 'npc1',
+      )
+      expect(activityEntry.status).toBe(false)
+    })
+  })
+
+  describe('appendThinkingDelta + flushThinking', () => {
+    it('buffers text and flushes on interval', () => {
+      stream.appendThinkingDelta('npc1', 'hello ')
+      stream.appendThinkingDelta('npc1', 'world')
+
+      // startThinkingStream emits initial activity
+      expect(emitFn).toHaveBeenCalledWith([
+        expect.objectContaining({ type: 'npc_activity', npcId: 'npc1', icon: 'brain' }),
+      ])
+
+      emitFn.mockClear()
+      vi.advanceTimersByTime(500)
+
+      expect(emitFn).toHaveBeenCalledWith([
+        expect.objectContaining({
+          type: 'npc_activity_stream',
+          npcId: 'npc1',
+          delta: 'hello world',
+        }),
+      ])
+    })
+
+    it('flushThinking emits remaining buffer and stream_end', () => {
+      stream.appendThinkingDelta('npc1', 'remaining')
+      emitFn.mockClear()
+
+      stream.flushThinking('npc1')
+
+      expect(emitFn).toHaveBeenCalledWith([
+        expect.objectContaining({ type: 'npc_activity_stream', delta: 'remaining' }),
+      ])
+      expect(emitFn).toHaveBeenCalledWith([
+        expect.objectContaining({ type: 'npc_activity_stream_end', npcId: 'npc1' }),
+      ])
+    })
+  })
+
+  describe('getActivityReplayEvents', () => {
+    it('returns cached events as a copy', () => {
+      stream.emitActivity('npc1', 'wrench', 'a')
+      stream.emitActivity('npc1', 'wrench', 'b')
+
+      const replay = stream.getActivityReplayEvents()
+      expect(replay).toHaveLength(2)
+      expect(replay[0].message).toBe('a')
+      expect(replay[1].message).toBe('b')
+
+      replay.push({ type: 'fake' })
+      expect(stream.getActivityReplayEvents()).toHaveLength(2)
+    })
+  })
+
+  describe('activity log cap', () => {
+    it('does not exceed MAX_ACTIVITY_LOG (500)', () => {
+      for (let i = 0; i < 520; i++) {
+        stream.emitActivity('npc1', 'wrench', `msg-${i}`)
+      }
+      const replay = stream.getActivityReplayEvents()
+      expect(replay.length).toBeLessThanOrEqual(500)
+    })
+  })
+
+  describe('emitTodoActivity', () => {
+    it('emits npc_activity_todo event with todos', () => {
+      stream.emitTodoActivity('npc1', {
+        todos: [
+          { id: 1, content: 'task one', status: 'pending' },
+          { id: 2, content: 'task two', status: 'completed' },
+        ],
+      })
+
+      expect(emitFn).toHaveBeenCalledWith([
+        expect.objectContaining({
+          type: 'npc_activity_todo',
+          npcId: 'npc1',
+          todos: [
+            { id: 1, content: 'task one', status: 'pending' },
+            { id: 2, content: 'task two', status: 'completed' },
+          ],
+        }),
+      ])
+    })
+
+    it('does not emit when todos is missing or not an array', () => {
+      stream.emitTodoActivity('npc1', {})
+      stream.emitTodoActivity('npc1', { todos: 'invalid' })
+      expect(emitFn).not.toHaveBeenCalled()
+    })
+  })
+})

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

@@ -0,0 +1,174 @@
+// @desc Tests for CitizenManager: citizen detection, name matching, lifecycle
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+import { CitizenManager, type CitizenManagerDeps } from '../CitizenManager.js'
+
+vi.mock('../../town-frontend/src/data/CharacterRoster.js', () => ({
+  getCharacterKeyForNpc: (id: string) => `char_${id}`,
+}))
+
+function createMockDeps(overrides: Partial<CitizenManagerDeps> = {}): CitizenManagerDeps {
+  return {
+    emit: vi.fn(),
+    routes: {
+      getGreetPoint: vi.fn(() => ({ x: 17, z: 15 })),
+      moveNpcAndWait: vi.fn(async () => 'arrived' as const),
+      chooseCitizenDestination: vi.fn(() => ({ id: 'dest_a', x: 30, z: 20, score: 5 })),
+      claimDestinationForNpc: vi.fn(),
+      releaseDestinationClaim: vi.fn(),
+      releaseDestinationClaimLater: vi.fn(),
+      distance2D: vi.fn(() => 10),
+    } as any,
+    getConfig: vi.fn(() => ({
+      citizens: [
+        { id: 'citizen_alice', name: 'Alice' },
+        { id: 'citizen_bob', name: 'Bob' },
+      ],
+    })),
+    getCharacterAssignments: vi.fn(() => new Map()),
+    isStewardConfirmed: vi.fn(() => true),
+    getPersonaName: vi.fn(() => 'Steward'),
+    getStewardName: vi.fn(() => 'steward'),
+    onPersonaChanged: vi.fn(),
+    delayMs: vi.fn(async () => {}),
+    scheduleDelayedEmit: vi.fn(),
+    getLastToolInput: vi.fn(() => ({})),
+    ...overrides,
+  }
+}
+
+describe('CitizenManager', () => {
+  let deps: CitizenManagerDeps
+  let cm: CitizenManager
+
+  beforeEach(() => {
+    deps = createMockDeps()
+    cm = new CitizenManager(deps)
+  })
+
+  describe('findCitizenNpcId', () => {
+    it('returns exact match by name from config', () => {
+      expect(cm.findCitizenNpcId('Alice')).toBe('citizen_alice')
+      expect(cm.findCitizenNpcId('Bob')).toBe('citizen_bob')
+    })
+
+    it('returns null for unknown name', () => {
+      expect(cm.findCitizenNpcId('Charlie')).toBeNull()
+    })
+
+    it('matches by spawned IDs when not in config', () => {
+      cm.spawnedCitizenIds.add('citizen_charlie')
+      expect(cm.findCitizenNpcId('Charlie')).toBe('citizen_charlie')
+    })
+  })
+
+  describe('fuzzyMatchCitizen', () => {
+    it('matches partial name against config', () => {
+      expect(cm.fuzzyMatchCitizen('ali')).toBe('citizen_alice')
+    })
+
+    it('returns null for empty string', () => {
+      expect(cm.fuzzyMatchCitizen('')).toBeNull()
+    })
+
+    it('matches against spawned citizen IDs', () => {
+      cm.spawnedCitizenIds.add('citizen_diana_prince')
+      expect(cm.fuzzyMatchCitizen('diana')).toBe('citizen_diana_prince')
+    })
+  })
+
+  describe('looksLikeIdFragment', () => {
+    it('returns true for short ASCII strings', () => {
+      expect(cm.looksLikeIdFragment('abc123')).toBe(true)
+      expect(cm.looksLikeIdFragment('npc-1')).toBe(true)
+      expect(cm.looksLikeIdFragment('a')).toBe(true)
+    })
+
+    it('returns false for strings with Chinese characters', () => {
+      expect(cm.looksLikeIdFragment('小明')).toBe(false)
+    })
+
+    it('returns false for strings longer than 12 characters', () => {
+      expect(cm.looksLikeIdFragment('abcdefghijklm')).toBe(false)
+    })
+  })
+
+  describe('isStewardName', () => {
+    it('matches persona name', () => {
+      expect(cm.isStewardName('Steward')).toBe(true)
+    })
+
+    it('does not match random name', () => {
+      expect(cm.isStewardName('RandomPerson')).toBe(false)
+    })
+
+    it('matches when getStewardName returns a custom name', () => {
+      deps = createMockDeps({
+        getPersonaName: vi.fn(() => null),
+        getStewardName: vi.fn(() => 'CustomBot'),
+      })
+      cm = new CitizenManager(deps)
+      expect(cm.isStewardName('CustomBot')).toBe(true)
+    })
+  })
+
+  describe('isPersonaPath', () => {
+    it('returns true for persona directory paths', () => {
+      expect(cm.isPersonaPath('/workspace/personas/alice.md')).toBe(true)
+      expect(cm.isPersonaPath('/workspace/persona/bob.md')).toBe(true)
+    })
+
+    it('returns false for non-persona paths', () => {
+      expect(cm.isPersonaPath('/workspace/src/main.ts')).toBe(false)
+    })
+
+    it('returns false for null', () => {
+      expect(cm.isPersonaPath(null)).toBe(false)
+    })
+  })
+
+  describe('detectCitizenCreated', () => {
+    it('queues citizen for spawn on persona write_file event', () => {
+      cm.detectCitizenCreated({
+        name: 'write_file',
+        meta: { filePath: '/workspace/personas/Charlie.md' },
+      })
+
+      expect(cm.spawnedCitizenIds.has('citizen_charlie')).toBe(true)
+    })
+
+    it('ignores non-write_file events', () => {
+      cm.detectCitizenCreated({ name: 'read_file', meta: {} })
+      expect(cm.spawnedCitizenIds.size).toBe(0)
+    })
+
+    it('ignores non-persona paths', () => {
+      cm.detectCitizenCreated({
+        name: 'write_file',
+        meta: { filePath: '/workspace/src/main.ts' },
+      })
+      expect(cm.spawnedCitizenIds.size).toBe(0)
+    })
+
+    it('skips steward persona file', () => {
+      cm.detectCitizenCreated({
+        name: 'write_file',
+        meta: { filePath: '/workspace/personas/Steward.md' },
+      })
+      expect(cm.spawnedCitizenIds.has('citizen_steward')).toBe(true)
+      expect(cm.citizenSpawnQueue).toHaveLength(0)
+    })
+
+    it('does not duplicate already-spawned citizen', () => {
+      cm.detectCitizenCreated({
+        name: 'write_file',
+        meta: { filePath: '/workspace/personas/Charlie.md' },
+      })
+      const queueLen = cm.citizenSpawnQueue.length
+      cm.detectCitizenCreated({
+        name: 'write_file',
+        meta: { filePath: '/workspace/personas/Charlie.md' },
+      })
+      expect(cm.citizenSpawnQueue.length).toBeLessThanOrEqual(queueLen)
+    })
+  })
+})