Class: ActiveMatrix::PresenceManager

Inherits:
Object
  • Object
show all
Includes:
Instrumentation
Defined in:
lib/active_matrix/presence_manager.rb

Overview

Manages Matrix presence for agents Provides automatic presence updates, wake hour awareness, and graceful shutdown

Examples:

Basic usage

presence = ActiveMatrix::PresenceManager.new(api: api, user_id: '@bot:example.com')
presence.start
presence.set_online(status_msg: 'Ready to help')
# ... later
presence.stop

With wake hours

presence = ActiveMatrix::PresenceManager.new(
  api: api,
  user_id: '@bot:example.com',
  wake_hour: 6,
  sleep_hour: 22
)
presence.start # Will auto-set unavailable outside 6:00-22:00

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(api:, user_id:, refresh_interval: 300, wake_hour: nil, sleep_hour: nil, timezone: nil) ⇒ PresenceManager

Returns a new instance of PresenceManager.

Parameters:

  • api (ActiveMatrix::Api) —

    Matrix API instance

  • user_id (String) —

    The user ID to manage presence for

  • refresh_interval (Integer) (defaults to: 300) —

    Seconds between presence refreshes (default: 300)

  • wake_hour (Integer, nil) (defaults to: nil) —

    Hour (0-23) when bot becomes available (optional)

  • sleep_hour (Integer, nil) (defaults to: nil) —

    Hour (0-23) when bot becomes unavailable (optional)

  • timezone (String) (defaults to: nil) —

    Timezone for wake/sleep hours (default: system timezone)



36
37
38
39
40
41
42
43
44
45
46
47
48
49
 
# File 'lib/active_matrix/presence_manager.rb', line 36

def initialize(api:, user_id:, refresh_interval: 300, wake_hour: nil, sleep_hour: nil, timezone: nil)
  @api = api
  @user_id = user_id
  @refresh_interval = refresh_interval
  @wake_hour = wake_hour
  @sleep_hour = sleep_hour
  @timezone = timezone

  @current_status = 'offline'
  @current_message = nil
  @running = Concurrent::AtomicBoolean.new(false)
  @task = nil
  @mutex = Mutex.new
end

Instance Attribute Details

#current_message ⇒ Object (readonly)

Returns the value of attribute current_message.



28
29
30
 
# File 'lib/active_matrix/presence_manager.rb', line 28

def current_message
  @current_message
end

#current_status ⇒ Object (readonly)

Returns the value of attribute current_status.



28
29
30
 
# File 'lib/active_matrix/presence_manager.rb', line 28

def current_status
  @current_status
end

#user_id ⇒ Object (readonly)

Returns the value of attribute user_id.



28
29
30
 
# File 'lib/active_matrix/presence_manager.rb', line 28

def user_id
  @user_id
end

Instance Method Details

#get_status ⇒ Hash

Get current presence status from server

Returns:

  • (Hash) —

    Presence status including :presence and :status_msg



114
115
116
117
118
119
120
121
 
# File 'lib/active_matrix/presence_manager.rb', line 114

def get_status
  instrument_operation(:get_presence, user_id: @user_id) do
    @api.get_presence_status(@user_id)
  end
rescue StandardError => e
  ActiveMatrix.logger.warn("Failed to get presence for #{@user_id}: #{e.message}")
  { presence: @current_status, status_msg: @current_message }
end

#set_offline ⇒ Object

Set presence to offline



90
91
92
 
# File 'lib/active_matrix/presence_manager.rb', line 90

def set_offline
  set_presence('offline', nil)
end

#set_online(status_msg: nil) ⇒ Object

Set presence to online

Parameters:

  • status_msg (String, nil) (defaults to: nil) —

    Optional status message



78
79
80
 
# File 'lib/active_matrix/presence_manager.rb', line 78

def set_online(status_msg: nil)
  set_presence('online', status_msg)
end

#set_unavailable(status_msg: nil) ⇒ Object

Set presence to unavailable

Parameters:

  • status_msg (String, nil) (defaults to: nil) —

    Optional status message



85
86
87
 
# File 'lib/active_matrix/presence_manager.rb', line 85

def set_unavailable(status_msg: nil)
  set_presence('unavailable', status_msg)
end

#start ⇒ Object

Start the presence manager Begins periodic presence updates



53
54
55
56
57
58
59
 
# File 'lib/active_matrix/presence_manager.rb', line 53

def start
  return if @running.true?

  @running.make_true
  schedule_refresh
  ActiveMatrix.logger.info("PresenceManager started for #{@user_id}")
end

#stop ⇒ Object

Stop the presence manager Sets presence to offline and stops refresh loop



63
64
65
66
67
68
69
70
71
72
73
 
# File 'lib/active_matrix/presence_manager.rb', line 63

def stop
  return unless @running.true?

  @running.make_false
  @task&.cancel
  @task = nil

  # Set offline on shutdown
  set_offline
  ActiveMatrix.logger.info("PresenceManager stopped for #{@user_id}")
end

#within_wake_hours? ⇒ Boolean

Check if currently within wake hours

Returns:

  • (Boolean) —

    true if within wake hours or no wake hours configured



97
98
99
100
101
102
103
104
105
106
107
108
109
 
# File 'lib/active_matrix/presence_manager.rb', line 97

def within_wake_hours?
  return true if @wake_hour.nil? || @sleep_hour.nil?

  current_hour = current_time.hour

  if @wake_hour < @sleep_hour
    # Normal case: wake 6, sleep 22 -> active from 6:00 to 21:59
    current_hour >= @wake_hour && current_hour < @sleep_hour
  else
    # Overnight case: wake 22, sleep 6 -> active from 22:00 to 5:59
    current_hour >= @wake_hour || current_hour < @sleep_hour
  end
end