Package com.tnsai.agents.groups

Interface MembershipManager

public interface MembershipManager
Manages membership lifecycle for an AgentGroup.

MembershipManager handles agent registration, health monitoring, and membership state tracking. It enforces group policies and coordinates with the event bus to notify about membership changes.

Features

  • Health monitoring with configurable heartbeat
  • Automatic removal of unhealthy members
  • Membership history tracking
  • Capability-based member lookup

  • Method Details

    • register

      Optional<MembershipManager.MemberInfo> register(Agent agent)
      Registers an agent as a group member.
      Parameters:
      agent - agent to register
      Returns:
      membership info, or empty if rejected

    • unregister

      boolean unregister(String agentId, String reason)
      Unregisters an agent from the group.
      Parameters:
      agentId - agent ID
      reason - reason for leaving
      Returns:
      true if was a member

    • validate

      MembershipManager.MembershipValidation validate(Agent agent)
      Checks if an agent can join the group.
      Parameters:
      agent - agent to check
      Returns:
      validation result

    • heartbeat

      boolean heartbeat(String agentId)
      Records a heartbeat from a member.
      Parameters:
      agentId - agent ID
      Returns:
      true if member exists

    • getHealth

      Optional<MembershipManager.MemberHealth> getHealth(String agentId)
      Gets health status of a member.
      Parameters:
      agentId - agent ID
      Returns:
      health status

    • getUnhealthyMembers

      List<MembershipManager.MemberInfo> getUnhealthyMembers()
      Gets all unhealthy members.
      Returns:
      unhealthy members

    • checkAndRemoveUnhealthy

      int checkAndRemoveUnhealthy()
      Checks all members for health and removes unhealthy ones.
      Returns:
      number of members removed

    • startHealthCheck

      void startHealthCheck(Duration interval)
      Starts automatic health checking.
      Parameters:
      interval - check interval

    • stopHealthCheck

      void stopHealthCheck()
      Stops automatic health checking.

    • getMembers

      List<MembershipManager.MemberInfo> getMembers()
      Gets all current members.
      Returns:
      member list

    • getMember

      Optional<MembershipManager.MemberInfo> getMember(String agentId)
      Gets a member by ID.
      Parameters:
      agentId - agent ID
      Returns:
      member info

    • findByCapability

      List<MembershipManager.MemberInfo> findByCapability(String capability)
      Finds members with a specific capability.
      Parameters:
      capability - capability name
      Returns:
      matching members

    • getMemberCount

      int getMemberCount()
      Gets current member count.
      Returns:
      member count

    • recordTaskStart

      boolean recordTaskStart(String agentId)
      Records that a task has been assigned to a member. Increments the member's active task count.
      Parameters:
      agentId - agent ID
      Returns:
      true if recorded successfully

    • recordTaskComplete

      boolean recordTaskComplete(String agentId)
      Records that a task has been completed by a member. Decrements the member's active task count.
      Parameters:
      agentId - agent ID
      Returns:
      true if recorded successfully

    • getAvailableMembers

      List<MembershipManager.MemberInfo> getAvailableMembers()
      Gets members available for task assignment. Returns healthy members that can accept more tasks, sorted by priority (highest first).
      Returns:
      available members sorted by priority

    • getAvailableMembersWithCapability

      List<MembershipManager.MemberInfo> getAvailableMembersWithCapability(String capability)
      Gets members available for task assignment with specific capability. Returns healthy members that can accept more tasks and have the capability, sorted by priority (highest first).
      Parameters:
      capability - required capability
      Returns:
      available members sorted by priority

    • getStats

      MembershipManager.MembershipStats getStats()
      Gets membership statistics.
      Returns:
      statistics

    • getHistory

      List<MembershipManager.MembershipHistoryEntry> getHistory(int limit)
      Gets membership history.
      Parameters:
      limit - maximum entries
      Returns:
      history entries