State to Brand Mapping

The state-to-brand.ts module maps internal agent states to brand-facing presence states consumed by TUI components.

Interface

interface StateMapper {
  map(internalState: InternalState): BrandState
  getVisualStyle(state: BrandState): VisualStyle
  getAnimation(state: BrandState): Animation | null
}
 
interface InternalState {
  coordinatorStatus: 'idle' | 'dispatching' | 'executing' | 'reflecting'
  loopEngineStatus: 'stopped' | 'running' | 'circuit_open'
  memoryStatus: 'loaded' | 'loading' | 'unavailable'
  errorState: ErrorState | null
}
 
interface BrandState {
  status: 'idle' | 'active' | 'thinking' | 'executing' | 'error' | 'complete'
  priority: 'low' | 'normal' | 'high' | 'urgent'
  displayText: string
  subtext: string | null
}
 
interface VisualStyle {
  color: 'muted' | 'active' | 'thinking' | 'success' | 'warning' | 'error'
  weight: 'dim' | 'normal' | 'bold'
  animation: 'none' | 'pulse' | 'spin' | 'bounce'
}
 
type Animation = {
  type: 'pulse' | 'spin' | 'bounce'
  speed: 'slow' | 'normal' | 'fast'
  repeat: boolean
}

Mapping Rules

Internal State	Brand State	Visual	Priority
`coordinator: idle`	`idle`	muted, dim	low
`coordinator: dispatching`	`active`	active, normal	normal
`loop: running`	`executing`	active, bold	high
`loop: circuit_open`	`error`	error, bold	urgent
`coordinator: reflecting`	`thinking`	thinking, normal	normal
`memory: loading`	`active`	active, dim	low
`memory: unavailable`	`error`	warning, dim	normal

Composite State Resolution

When multiple internal states are active simultaneously, the mapper applies a priority hierarchy:

error > executing > thinking > active > idle

function map(internalState: InternalState): BrandState {
  // Error takes priority
  if (internalState.errorState) {
    return {
      status: 'error',
      priority: 'urgent',
      displayText: `Error: ${internalState.errorState.type}`,
      subtext: internalState.errorState.recoverable ? 'Recovering...' : 'Needs attention'
    }
  }
 
  // Loop execution
  if (internalState.loopEngineStatus === 'running') {
    return {
      status: 'executing',
      priority: 'high',
      displayText: 'Executing loop',
      subtext: `Circuit: CLOSED`
    }
  }
 
  // Coordinator reflecting
  if (internalState.coordinatorStatus === 'reflecting') {
    return {
      status: 'thinking',
      priority: 'normal',
      displayText: 'Analyzing',
      subtext: null
    }
  }
 
  // Coordinator dispatching
  if (internalState.coordinatorStatus === 'dispatching') {
    return {
      status: 'active',
      priority: 'normal',
      displayText: 'Working',
      subtext: null
    }
  }
 
  // Default: idle
  return {
    status: 'idle',
    priority: 'low',
    displayText: 'Standing by',
    subtext: null
  }
}

The state mapper ensures that the brand representation always reflects the most significant internal state. A thinking animation during a circuit breaker open would be misleading — the mapper prevents that.

Brand Voice TUI Surfaces