Class: SimpleAcp::Models::Run

Inherits:
Base
  • Object
show all
Defined in:
lib/simple_acp/models/run.rb

Overview

Represents a single agent execution.

Tracks the lifecycle of an agent run from creation through completion, including status, output messages, errors, and timing.

Status Lifecycle

  • created -> in_progress -> completed | failed | cancelled | awaiting
  • awaiting -> in_progress (on resume)
  • cancelling -> cancelled

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods inherited from Base

#==, attribute, attributes, #hash, own_attributes, #to_h, #to_json

Constructor Details

#initialize(**kwargs) ⇒ Run

Returns a new instance of Run.



52
53
54
55
56
57
 
# File 'lib/simple_acp/models/run.rb', line 52

def initialize(**kwargs)
  super
  @run_id ||= Types.generate_uuid
  @output ||= []
  @created_at ||= Time.now
end

Instance Attribute Details

#agent_name ⇒ String (readonly)

Returns name of the agent being executed.

Returns:

  • (String) —

    name of the agent being executed



22
 
# File 'lib/simple_acp/models/run.rb', line 22

attribute :agent_name, required: true

#await_request ⇒ AwaitRequest? (readonly)

Returns request for client input (when awaiting).

Returns:

  • (AwaitRequest, nil) —

    request for client input (when awaiting)



34
 
# File 'lib/simple_acp/models/run.rb', line 34

attribute :await_request

#created_at ⇒ Time? (readonly)

Returns when the run was created.

Returns:

  • (Time, nil) —

    when the run was created



46
 
# File 'lib/simple_acp/models/run.rb', line 46

attribute :created_at

#error ⇒ Error? (readonly)

Returns error details if failed.

Returns:

  • (Error, nil) —

    error details if failed



42
 
# File 'lib/simple_acp/models/run.rb', line 42

attribute :error

#finished_at ⇒ Time? (readonly)

Returns when the run finished (completed, failed, or cancelled).

Returns:

  • (Time, nil) —

    when the run finished (completed, failed, or cancelled)



50
 
# File 'lib/simple_acp/models/run.rb', line 50

attribute :finished_at

#output ⇒ Array<Message> (readonly)

Returns output messages from the agent.

Returns:

  • (Array<Message>) —

    output messages from the agent



38
 
# File 'lib/simple_acp/models/run.rb', line 38

attribute :output, default: -> { [] }

#run_id ⇒ String (readonly)

Returns unique UUID for this run.

Returns:

  • (String) —

    unique UUID for this run



18
 
# File 'lib/simple_acp/models/run.rb', line 18

attribute :run_id, required: true

#session_id ⇒ String? (readonly)

Returns optional session ID.

Returns:

  • (String, nil) —

    optional session ID



26
 
# File 'lib/simple_acp/models/run.rb', line 26

attribute :session_id

#status ⇒ String (readonly)

Returns current status (created, in-progress, completed, failed, cancelled, awaiting).

Returns:

  • (String) —

    current status (created, in-progress, completed, failed, cancelled, awaiting)



30
 
# File 'lib/simple_acp/models/run.rb', line 30

attribute :status, default: Types::RunStatus::CREATED

Class Method Details

.from_hash(hash) ⇒ Run?

Create from a hash (JSON deserialization).

Parameters:

  • hash (Hash, nil) —

    run data

Returns:

  • (Run, nil) —

    the run or nil



63
64
65
66
67
68
69
 
# File 'lib/simple_acp/models/run.rb', line 63

def self.from_hash(hash)
  return nil if hash.nil?

  instance = allocate
  instance.send(:initialize_from_hash, hash)
  instance
end

Instance Method Details

#add_output(message) ⇒ self

Add a message to the output.

Parameters:

  • message (Message, Hash) —

    the message to add

Returns:

  • (self) —

    for chaining



181
182
183
184
 
# File 'lib/simple_acp/models/run.rb', line 181

def add_output(message)
  @output << (message.is_a?(Message) ? message : Message.from_hash(message))
  self
end

#await!(request) ⇒ self

Transition to awaiting status.

Parameters:

Returns:

  • (self) —

    for chaining



132
133
134
135
136
 
# File 'lib/simple_acp/models/run.rb', line 132

def await!(request)
  @status = Types::RunStatus::AWAITING
  @await_request = request
  self
end

#awaiting? ⇒ Boolean

Check if the run is waiting for client input.

Returns:

  • (Boolean) —

    true if awaiting



88
89
90
 
# File 'lib/simple_acp/models/run.rb', line 88

def awaiting?
  @status == Types::RunStatus::AWAITING
end

#cancel! ⇒ self

Transition to cancelling status.

Returns:

  • (self) —

    for chaining



163
164
165
166
 
# File 'lib/simple_acp/models/run.rb', line 163

def cancel!
  @status = Types::RunStatus::CANCELLING
  self
end

#cancelled! ⇒ self

Transition to cancelled status.

Returns:

  • (self) —

    for chaining



171
172
173
174
175
 
# File 'lib/simple_acp/models/run.rb', line 171

def cancelled!
  @status = Types::RunStatus::CANCELLED
  @finished_at = Time.now
  self
end

#cancelled? ⇒ Boolean

Check if the run was cancelled.

Returns:

  • (Boolean) —

    true if cancelled



109
110
111
 
# File 'lib/simple_acp/models/run.rb', line 109

def cancelled?
  @status == Types::RunStatus::CANCELLED
end

#cancelling? ⇒ Boolean

Check if the run is being cancelled.

Returns:

  • (Boolean) —

    true if cancelling



116
117
118
 
# File 'lib/simple_acp/models/run.rb', line 116

def cancelling?
  @status == Types::RunStatus::CANCELLING
end

#complete!(output = nil) ⇒ self

Transition to completed status.

Parameters:

  • output (Array<Message>, nil) (defaults to: nil) —

    optional output messages

Returns:

  • (self) —

    for chaining



142
143
144
145
146
147
 
# File 'lib/simple_acp/models/run.rb', line 142

def complete!(output = nil)
  @status = Types::RunStatus::COMPLETED
  @output = output if output
  @finished_at = Time.now
  self
end

#completed? ⇒ Boolean

Check if the run completed successfully.

Returns:

  • (Boolean) —

    true if completed



95
96
97
 
# File 'lib/simple_acp/models/run.rb', line 95

def completed?
  @status == Types::RunStatus::COMPLETED
end

#fail!(error) ⇒ self

Transition to failed status.

Parameters:

  • error (Error, String) —

    the error or error message

Returns:

  • (self) —

    for chaining



153
154
155
156
157
158
 
# File 'lib/simple_acp/models/run.rb', line 153

def fail!(error)
  @status = Types::RunStatus::FAILED
  @error = error.is_a?(Error) ? error : Error.server_error(error.to_s)
  @finished_at = Time.now
  self
end

#failed? ⇒ Boolean

Check if the run failed.

Returns:

  • (Boolean) —

    true if failed



102
103
104
 
# File 'lib/simple_acp/models/run.rb', line 102

def failed?
  @status == Types::RunStatus::FAILED
end

#in_progress? ⇒ Boolean

Check if the run is currently executing.

Returns:

  • (Boolean) —

    true if in_progress



81
82
83
 
# File 'lib/simple_acp/models/run.rb', line 81

def in_progress?
  @status == Types::RunStatus::IN_PROGRESS
end

#raise_for_status! ⇒ self

Raise an exception if the run failed.

Returns:

  • (self) —

    if not failed

Raises:



190
191
192
193
194
 
# File 'lib/simple_acp/models/run.rb', line 190

def raise_for_status!
  return self unless failed?

  raise SimpleAcp::RunError, @error&.message || "Run failed"
end

#start! ⇒ self

Transition to in_progress status.

Returns:

  • (self) —

    for chaining



123
124
125
126
 
# File 'lib/simple_acp/models/run.rb', line 123

def start!
  @status = Types::RunStatus::IN_PROGRESS
  self
end

#terminal? ⇒ Boolean

Check if the run is in a terminal state.

Returns:

  • (Boolean) —

    true if completed, failed, or cancelled



74
75
76
 
# File 'lib/simple_acp/models/run.rb', line 74

def terminal?
  Types::RunStatus.terminal?(@status)
end

#valid? ⇒ Boolean

Validate the run.

Returns:

  • (Boolean) —

    true if run_id, agent_name, and status are valid



199
200
201
202
203
204
205
 
# File 'lib/simple_acp/models/run.rb', line 199

def valid?
  return false unless Types.valid_uuid?(@run_id)
  return false unless Types.valid_agent_name?(@agent_name)
  return false unless Types::RunStatus.valid?(@status)

  true
end