Class: HermesAgent::Client::Entities::Run

Inherits:
HermesAgent::Client::Entity show all
Defined in:
lib/hermes_agent/client/entities/run.rb

Overview

A run from the Runs API (POST /v1/runs, GET /v1/runs/{id}). Unlike chat/responses a run is server-side asynchronous: create returns immediately with a minimal run (only #run_id and #status), and progress is tracked by polling (Resources::Runs#get) or subscribing to the event stream. #output and #usage are populated only once the run reaches a terminal completed status, and are absent before then and on a cancelled or failed run — so both readers tolerate a missing value. A failed run instead carries an #error message. Field readers are best-effort; HermesAgent::Client::Entity#to_h remains the source of truth.

Instance Method Summary collapse

Methods inherited from HermesAgent::Client::Entity

#==, #[], #eql?, #hash, #to_h

Instance Method Details

#created_at ⇒ Float?

When the run was created, as a Unix timestamp (seconds, fractional).

Returns:

  • (Float, nil) 


84
85
86
 
# File 'lib/hermes_agent/client/entities/run.rb', line 84

def created_at
  self["created_at"]
end

#error ⇒ String?

The failure message on a failed run (the upstream error, e.g. a model/provider error). Present only when #status is "failed"; nil otherwise. A failed run otherwise looks like a cancelled one — #output and #usage are absent.

Returns:

  • (String, nil) 


140
141
142
 
# File 'lib/hermes_agent/client/entities/run.rb', line 140

def error
  self["error"]
end

#last_event ⇒ String?

The name of the most recent event emitted on the run's event stream, e.g. "run.completed". Empty at the very start of a run.

Returns:

  • (String, nil) 


120
121
122
 
# File 'lib/hermes_agent/client/entities/run.rb', line 120

def last_event
  self["last_event"]
end

#model ⇒ String?

The model that produced the run, e.g. "hermes-test" (configured server-side).

Returns:

  • (String, nil) 


111
112
113
 
# File 'lib/hermes_agent/client/entities/run.rb', line 111

def model
  self["model"]
end

#object ⇒ String?

The object type, "hermes.run".

Returns:

  • (String, nil) 


66
67
68
 
# File 'lib/hermes_agent/client/entities/run.rb', line 66

def object
  self["object"]
end

#output ⇒ String?

The assembled final assistant text, present once the run completes. Absent (nil) before the run is terminal and on a cancelled run.

Returns:

  • (String, nil) 


129
130
131
 
# File 'lib/hermes_agent/client/entities/run.rb', line 129

def output
  self["output"]
end

#run_id ⇒ String? Also known as: id

The run id, e.g. "run_…" (run_ plus 32 hex characters). Pass it to Resources::Runs#get to poll, or to the streaming/stop/approval calls.

Returns:

  • (String, nil) 


57
58
59
 
# File 'lib/hermes_agent/client/entities/run.rb', line 57

def run_id
  self["run_id"]
end

#session_id ⇒ String?

The session correlation label for the run (defaults to the #run_id when none was supplied on create).

Returns:

  • (String, nil) 


102
103
104
 
# File 'lib/hermes_agent/client/entities/run.rb', line 102

def session_id
  self["session_id"]
end

#status ⇒ String?

The run status: "started" → "running" → terminal "completed" / "cancelled" / "failed", with "waiting_for_approval" while a gated tool awaits a response and a transient "stopping" after a stop.

Returns:

  • (String, nil) 


76
77
78
 
# File 'lib/hermes_agent/client/entities/run.rb', line 76

def status
  self["status"]
end

#updated_at ⇒ Float?

When the run was last updated, as a Unix timestamp (seconds, fractional).

Returns:

  • (Float, nil) 


93
94
95
 
# File 'lib/hermes_agent/client/entities/run.rb', line 93

def updated_at
  self["updated_at"]
end

#usage ⇒ RunUsage?

The token usage, wrapped in a HermesAgent::Client::Entities::RunUsage. Present once the run completes; returns nil when the field is absent (before terminal, or on a cancelled run).

Returns:



150
151
152
153
 
# File 'lib/hermes_agent/client/entities/run.rb', line 150

def usage
  raw = self["usage"]
  raw.is_a?(::Hash) ? RunUsage.new(raw) : nil
end