Module: Aidp::Interfaces::ActivityMonitorInterface

Included in:
ActivityMonitor, NullActivityMonitor
Defined in:
lib/aidp/interfaces/activity_monitor_interface.rb

Overview

ActivityMonitorInterface defines the contract for activity monitoring implementations. Activity monitoring tracks the state of long-running provider operations, detecting stuck processes and enabling timeout/cancellation logic.

States:

  • :idle - No operation in progress
  • :working - Active and producing output
  • :stuck - No activity detected for stuck_timeout seconds
  • :completed - Operation finished successfully
  • :failed - Operation failed with an error

Examples:

Implementing the interface

class MyActivityMonitor
  include Aidp::Interfaces::ActivityMonitorInterface

  def start(step_name:, stuck_timeout:, on_state_change: nil)
    # Implementation
  end
  # ... other methods
end

Using an activity monitor

monitor = ActivityMonitor.new
monitor.start(step_name: "sending_prompt", stuck_timeout: 60)
monitor.record_activity("Received response")
monitor.complete

Constant Summary collapse

STATES =

Valid activity states

[:idle, :working, :stuck, :completed, :failed].freeze

Instance Method Summary collapse

Instance Method Details

#complete ⇒ void

This method returns an undefined value.

Mark the operation as completed successfully.

Raises:

  • (NotImplementedError) 


57
58
59
 
# File 'lib/aidp/interfaces/activity_monitor_interface.rb', line 57

def complete
  raise NotImplementedError, "#{self.class} must implement #complete"
end

#elapsed_time ⇒ Float

Get elapsed time since start.

Returns:

  • (Float) —

    seconds since monitoring started, or 0 if not started

Raises:

  • (NotImplementedError) 


86
87
88
 
# File 'lib/aidp/interfaces/activity_monitor_interface.rb', line 86

def elapsed_time
  raise NotImplementedError, "#{self.class} must implement #elapsed_time"
end

#fail(error_message = nil) ⇒ void

This method returns an undefined value.

Mark the operation as failed.

Parameters:

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

    optional error description

Raises:

  • (NotImplementedError) 


65
66
67
 
# File 'lib/aidp/interfaces/activity_monitor_interface.rb', line 65

def fail(error_message = nil)
  raise NotImplementedError, "#{self.class} must implement #fail"
end

#record_activity(message = nil) ⇒ void

This method returns an undefined value.

Record activity, resetting the stuck timer.

Parameters:

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

    optional message describing the activity

Raises:

  • (NotImplementedError) 


50
51
52
 
# File 'lib/aidp/interfaces/activity_monitor_interface.rb', line 50

def record_activity(message = nil)
  raise NotImplementedError, "#{self.class} must implement #record_activity"
end

#start(step_name:, stuck_timeout:, on_state_change: nil) ⇒ void

This method returns an undefined value.

Start monitoring an operation.

Parameters:

  • step_name (String) —

    name of the operation being monitored

  • stuck_timeout (Integer) —

    seconds before considering the operation stuck

  • on_state_change (Proc, nil) (defaults to: nil) —

    callback for state changes (state, message)

Raises:

  • (NotImplementedError) 


42
43
44
 
# File 'lib/aidp/interfaces/activity_monitor_interface.rb', line 42

def start(step_name:, stuck_timeout:, on_state_change: nil)
  raise NotImplementedError, "#{self.class} must implement #start"
end

#state ⇒ Symbol

Get the current activity state.

Returns:

  • (Symbol) —

    one of STATES

Raises:

  • (NotImplementedError) 


79
80
81
 
# File 'lib/aidp/interfaces/activity_monitor_interface.rb', line 79

def state
  raise NotImplementedError, "#{self.class} must implement #state"
end

#stuck? ⇒ Boolean

Check if the operation appears to be stuck.

Returns:

  • (Boolean) —

    true if no activity for stuck_timeout seconds

Raises:

  • (NotImplementedError) 


72
73
74
 
# File 'lib/aidp/interfaces/activity_monitor_interface.rb', line 72

def stuck?
  raise NotImplementedError, "#{self.class} must implement #stuck?"
end

#summary ⇒ Hash

Get a summary of the monitoring session.

Returns:

  • (Hash) —

    summary with keys :step_name, :state, :elapsed_time, :stuck_detected, :output_count

Raises:

  • (NotImplementedError) 


93
94
95
 
# File 'lib/aidp/interfaces/activity_monitor_interface.rb', line 93

def summary
  raise NotImplementedError, "#{self.class} must implement #summary"
end