Class: PiAgent::Event

Inherits:
Object
  • Object
show all
Defined in:
lib/pi_agent/event.rb

Overview

Thin typed wrapper over a pi RPC event message. The native JSON payload is preserved on #raw so callers can reach fields we haven't given a dedicated accessor yet.

Event types are exposed as Ruby symbols (e.g. :text_delta, :agent_settled) matching the upstream protocol's type field.

Constant Summary collapse

TERMINAL_TYPES =

Event types that terminate a single prompt's event stream. agent_end only finishes one low-level run; retries, compaction, or queued continuations may follow. agent_settled is emitted once all automatic work has finished.

%i[agent_settled].freeze

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(raw) ⇒ Event

Returns a new instance of Event.



19
20
21
22
 
# File 'lib/pi_agent/event.rb', line 19

def initialize(raw)
  @raw = raw
  @type = raw["type"]&.to_sym
end

Instance Attribute Details

#raw ⇒ Object (readonly)

Returns the value of attribute raw.



17
18
19
 
# File 'lib/pi_agent/event.rb', line 17

def raw
  @raw
end

#type ⇒ Object (readonly)

Returns the value of attribute type.



17
18
19
 
# File 'lib/pi_agent/event.rb', line 17

def type
  @type
end

Instance Method Details

#[](key) ⇒ Object 



28
29
30
 
# File 'lib/pi_agent/event.rb', line 28

def [](key)
  @raw[key.to_s]
end

#delta ⇒ Object

Common shorthand for streaming text deltas. message_update with assistantMessageEvent.type == "text_delta".



34
35
36
 
# File 'lib/pi_agent/event.rb', line 34

def delta
  assistant_event&.[]("delta")
end

#error? ⇒ Boolean

True for an extension_error event, or a message_update whose assistant event is an error (agent turn errored or was aborted).

Returns:

  • (Boolean) 


40
41
42
 
# File 'lib/pi_agent/event.rb', line 40

def error?
  @type == :extension_error || assistant_event_type == :error
end

#error_message ⇒ Object

Best-effort error text for an error event; nil if not an error.



45
46
47
48
49
50
 
# File 'lib/pi_agent/event.rb', line 45

def error_message
  return @raw["error"] if @type == :extension_error
  return nil unless assistant_event_type == :error

  assistant_event["error"] || assistant_event["message"]
end

#error_reason ⇒ Object

Reason for an assistant-event error: "aborted" or "error". nil otherwise. Use this to distinguish a user abort from a real failure.



54
55
56
57
58
 
# File 'lib/pi_agent/event.rb', line 54

def error_reason
  return nil unless assistant_event_type == :error

  assistant_event["reason"]
end

#inspect ⇒ Object 



64
65
66
 
# File 'lib/pi_agent/event.rb', line 64

def inspect
  "#<#{self.class.name} type=#{@type.inspect}>"
end

#terminal? ⇒ Boolean

Returns:

  • (Boolean) 


24
25
26
 
# File 'lib/pi_agent/event.rb', line 24

def terminal?
  TERMINAL_TYPES.include?(@type)
end

#to_h ⇒ Object 



60
61
62
 
# File 'lib/pi_agent/event.rb', line 60

def to_h
  @raw
end