Class: HermesAgent::Client::Entities::RunEvent

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

Overview

One event in a streamed run (Resources::Runs#stream_events).

Unlike chat and the Responses API, the run events stream uses plain data: frames — there is no SSE event: line and no [DONE] sentinel — so each event carries its type in an "event" payload field (read via #event) alongside #run_id and a #timestamp. The stream has no head frame; it begins at the first content event. Which other readers are meaningful depends on #event; the rest return nil. Observed types: tool.started/tool.completed, message.delta, reasoning.available, the terminal run.completed/run.cancelled/ run.failed (the last carries an #error string), and approval.request/approval.responded.

Class Method Summary collapse

Instance Method Summary collapse

Methods inherited from HermesAgent::Client::Entity

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

Class Method Details

.terminal(events) ⇒ RunEvent?

The terminal lifecycle event of a streamed run: the last event whose #event type is a run.* frame (run.completed, run.cancelled, or run.failed). Returns nil if the stream closed without one (e.g. it was cut short). Used as the aggregated Stream#result of Resources::Runs#stream_events.

Parameters:

  • events (Array<RunEvent>) —

    The streamed events, in order.

Returns:



207
208
209
 
# File 'lib/hermes_agent/client/entities/run.rb', line 207

def self.terminal(events)
  events.reverse_each.find { |event| event.event&.start_with?("run.") }
end

Instance Method Details

#choice ⇒ String?

The choice that resolved an approval on an approval.responded event.

Returns:

  • (String, nil) 


369
370
371
 
# File 'lib/hermes_agent/client/entities/run.rb', line 369

def choice
  self["choice"]
end

#choices ⇒ Array<String>?

The valid approval choices on an approval.request event (e.g. ["once", "session", "always", "deny"]). Returns nil when the field is absent.

Returns:

  • (Array<String>, nil) 


361
362
363
 
# File 'lib/hermes_agent/client/entities/run.rb', line 361

def choices
  self["choices"]
end

#command ⇒ String?

The command awaiting approval on an approval.request event.

Returns:

  • (String, nil) 


325
326
327
 
# File 'lib/hermes_agent/client/entities/run.rb', line 325

def command
  self["command"]
end

#delta ⇒ String?

The incremental assistant text on a message.delta event.

Returns:

  • (String, nil) 


291
292
293
 
# File 'lib/hermes_agent/client/entities/run.rb', line 291

def delta
  self["delta"]
end

#description ⇒ String?

A human-readable description of the gated command on an approval.request event.

Returns:

  • (String, nil) 


351
352
353
 
# File 'lib/hermes_agent/client/entities/run.rb', line 351

def description
  self["description"]
end

#duration ⇒ Float?

The tool's execution time on a tool.completed event, in seconds.

Returns:

  • (Float, nil) 


257
258
259
 
# File 'lib/hermes_agent/client/entities/run.rb', line 257

def duration
  self["duration"]
end

#error ⇒ String?

The failure message on a run.failed event (a string — the upstream error). nil on any other event, including a tool.completed whose error is the boolean result flag (read that via #error?). The two readers split the overloaded error payload field by type.

Returns:

  • (String, nil) 


282
283
284
285
 
# File 'lib/hermes_agent/client/entities/run.rb', line 282

def error
  value = self["error"]
  value if value.is_a?(::String)
end

#error? ⇒ boolean?

Whether the tool reported an error on a tool.completed event. This is the tool result signal, not a lifecycle marker: a failed command — or a denied approval — reports true yet the run can still complete. Returns nil when there is no boolean flag (the field is absent, or the event is a run.failed whose error is a message string — read that via #error).

Returns:

  • (boolean, nil) 


270
271
272
273
 
# File 'lib/hermes_agent/client/entities/run.rb', line 270

def error?
  value = self["error"]
  value if [true, false].include?(value)
end

#event ⇒ String?

The event type, e.g. "message.delta" or "run.completed".

Returns:

  • (String, nil) 


215
216
217
 
# File 'lib/hermes_agent/client/entities/run.rb', line 215

def event
  self["event"]
end

#output ⇒ String?

The assembled final assistant text on a run.completed event.

Returns:

  • (String, nil) 


307
308
309
 
# File 'lib/hermes_agent/client/entities/run.rb', line 307

def output
  self["output"]
end

#pattern_key ⇒ String?

The matched approval pattern key on an approval.request event.

Returns:

  • (String, nil) 


333
334
335
 
# File 'lib/hermes_agent/client/entities/run.rb', line 333

def pattern_key
  self["pattern_key"]
end

#pattern_keys ⇒ Array<String>?

All matched approval pattern keys on an approval.request event. Returns nil when the field is absent.

Returns:

  • (Array<String>, nil) 


342
343
344
 
# File 'lib/hermes_agent/client/entities/run.rb', line 342

def pattern_keys
  self["pattern_keys"]
end

#preview ⇒ String?

A preview of the tool invocation on a tool.started event (e.g. the command to be run).

Returns:

  • (String, nil) 


249
250
251
 
# File 'lib/hermes_agent/client/entities/run.rb', line 249

def preview
  self["preview"]
end

#resolved ⇒ Integer?

The count of approvals resolved on an approval.responded event.

Returns:

  • (Integer, nil) 


377
378
379
 
# File 'lib/hermes_agent/client/entities/run.rb', line 377

def resolved
  self["resolved"]
end

#run_id ⇒ String?

The id of the run this event belongs to ("run_…").

Returns:

  • (String, nil) 


223
224
225
 
# File 'lib/hermes_agent/client/entities/run.rb', line 223

def run_id
  self["run_id"]
end

#text ⇒ String?

The full reasoning text on a reasoning.available event.

Returns:

  • (String, nil) 


299
300
301
 
# File 'lib/hermes_agent/client/entities/run.rb', line 299

def text
  self["text"]
end

#timestamp ⇒ Float?

When the event was emitted, as a Unix timestamp (seconds, fractional).

Returns:

  • (Float, nil) 


231
232
233
 
# File 'lib/hermes_agent/client/entities/run.rb', line 231

def timestamp
  self["timestamp"]
end

#tool ⇒ String?

The tool name on a tool.started / tool.completed event, e.g. "terminal".

Returns:

  • (String, nil) 


240
241
242
 
# File 'lib/hermes_agent/client/entities/run.rb', line 240

def tool
  self["tool"]
end

#usage ⇒ RunUsage?

The token usage on a run.completed event, wrapped in a HermesAgent::Client::Entities::RunUsage. Returns nil when the field is absent.

Returns:



316
317
318
319
 
# File 'lib/hermes_agent/client/entities/run.rb', line 316

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