Class: Phronomy::Agent::InvocationContext Private

Inherits:
Object
  • Object
show all
Defined in:
lib/phronomy/agent/invocation_context.rb

Overview

This class is part of a private API. You should avoid using this class if possible, as it may be removed or be changed in the future.

Holds the mutable state for a single Agent#invoke execution.

An InvocationContext is created at the start of each invoke call and passed through every FSM state as the context object. It plays the same role as WorkflowContext does for Workflow executions.

Fields:

input                  — the (possibly filter-transformed) user input
messages               — conversation history (Array of RubyLLM::Message)
chat                   — the RubyLLM::Chat object built during :building_context
output                 — the final LLM text response
usage                  — Phronomy::TokenUsage after completion
tool_call_pending      — whether the last LLM response contained a tool call
approval_required      — whether the pending tool requires human approval
input_blocked          — whether an input filter called block!
output_blocked         — whether an output filter called block!
block_error            — the FilterBlockError raised (for :blocked terminal)
pending_tool_call      — the intercepted tool_call object (name/arguments/id)
user_message_sent      — true after the first LLM call (continuation uses nil msg)
sync_approval_handler  — true when agent has an on_approval_required block
session_id             — FSM session id (set by set_graph_metadata)
phase                  — terminal FSM phase (set by set_graph_metadata)

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(agent:, input:, messages:, config:) ⇒ InvocationContext

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns a new instance of InvocationContext.

Parameters:



97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
 
# File 'lib/phronomy/agent/invocation_context.rb', line 97

def initialize(agent:, input:, messages:, config:)
  @agent = agent
  @input = input
  @messages = Array(messages)
  @config = config
  @thread_id = config[:thread_id]
  @chat = nil
  @output = nil
  @usage = nil
  @tool_call_pending = false
  @approval_required = false
  @input_blocked = false
  @output_blocked = false
  @block_error = nil
  @pending_tool_call = nil
  @user_message_sent = false
  @approved = false
  @rejected = false
  @sync_approval_handler = !agent.instance_variable_get(:@approval_handler).nil?
  @session_id = nil
  @phase = nil
end

Instance Attribute Details

#agent ⇒ Phronomy::Agent::Base (readonly)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns the agent instance driving this invocation.

Returns:



84
85
86
 
# File 'lib/phronomy/agent/invocation_context.rb', line 84

def agent
  @agent
end

#approval_required ⇒ Boolean

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns true when the pending tool requires human approval.

Returns:

  • (Boolean) —

    true when the pending tool requires human approval



49
50
51
 
# File 'lib/phronomy/agent/invocation_context.rb', line 49

def approval_required
  @approval_required
end

#approved ⇒ Boolean

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns true when Agent.approve was called (signals executing_tool to execute the pending tool rather than re-suspending).

Returns:

  • (Boolean) —

    true when Agent.approve was called (signals executing_tool to execute the pending tool rather than re-suspending)



68
69
70
 
# File 'lib/phronomy/agent/invocation_context.rb', line 68

def approved
  @approved
end

#block_error ⇒ Phronomy::FilterBlockError?

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns:



58
59
60
 
# File 'lib/phronomy/agent/invocation_context.rb', line 58

def block_error
  @block_error
end

#chat ⇒ Object?

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns RubyLLM::Chat instance.

Returns:

  • (Object, nil) —

    RubyLLM::Chat instance



37
38
39
 
# File 'lib/phronomy/agent/invocation_context.rb', line 37

def chat
  @chat
end

#config ⇒ Hash (readonly)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns the config hash passed to invoke.

Returns:

  • (Hash) —

    the config hash passed to invoke



87
88
89
 
# File 'lib/phronomy/agent/invocation_context.rb', line 87

def config
  @config
end

#input ⇒ String, Hash

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns user input (may be transformed by input filters).

Returns:

  • (String, Hash) —

    user input (may be transformed by input filters)



31
32
33
 
# File 'lib/phronomy/agent/invocation_context.rb', line 31

def input
  @input
end

#input_blocked ⇒ Boolean

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns true when an input filter called block!.

Returns:

  • (Boolean) —

    true when an input filter called block!



52
53
54
 
# File 'lib/phronomy/agent/invocation_context.rb', line 52

def input_blocked
  @input_blocked
end

#messages ⇒ Array

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns conversation history.

Returns:

  • (Array) —

    conversation history



34
35
36
 
# File 'lib/phronomy/agent/invocation_context.rb', line 34

def messages
  @messages
end

#output ⇒ String?

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns final LLM output text.

Returns:

  • (String, nil) —

    final LLM output text



40
41
42
 
# File 'lib/phronomy/agent/invocation_context.rb', line 40

def output
  @output
end

#output_blocked ⇒ Boolean

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns true when an output filter called block!.

Returns:

  • (Boolean) —

    true when an output filter called block!



55
56
57
 
# File 'lib/phronomy/agent/invocation_context.rb', line 55

def output_blocked
  @output_blocked
end

#pending_tool_call ⇒ Object?

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns intercepted RubyLLM tool_call (name/arguments/id).

Returns:

  • (Object, nil) —

    intercepted RubyLLM tool_call (name/arguments/id)



61
62
63
 
# File 'lib/phronomy/agent/invocation_context.rb', line 61

def pending_tool_call
  @pending_tool_call
end

#phase ⇒ Symbol? (readonly)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns terminal FSM phase (set by set_graph_metadata).

Returns:

  • (Symbol, nil) —

    terminal FSM phase (set by set_graph_metadata)



78
79
80
 
# File 'lib/phronomy/agent/invocation_context.rb', line 78

def phase
  @phase
end

#rejected ⇒ Boolean

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns true when the pending tool call was rejected via Agent.approve(session_id, approved: false).

Returns:

  • (Boolean) —

    true when the pending tool call was rejected via Agent.approve(session_id, approved: false)



72
73
74
 
# File 'lib/phronomy/agent/invocation_context.rb', line 72

def rejected
  @rejected
end

#session_id ⇒ String? (readonly)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns FSM session id (set by set_graph_metadata).

Returns:

  • (String, nil) —

    FSM session id (set by set_graph_metadata)



75
76
77
 
# File 'lib/phronomy/agent/invocation_context.rb', line 75

def session_id
  @session_id
end

#sync_approval_handler ⇒ Boolean (readonly)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns true when agent has a synchronous on_approval_required handler.

Returns:

  • (Boolean) —

    true when agent has a synchronous on_approval_required handler



81
82
83
 
# File 'lib/phronomy/agent/invocation_context.rb', line 81

def sync_approval_handler
  @sync_approval_handler
end

#thread_id ⇒ String? (readonly)

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns thread_id from config.

Returns:

  • (String, nil) —

    thread_id from config



90
91
92
 
# File 'lib/phronomy/agent/invocation_context.rb', line 90

def thread_id
  @thread_id
end

#tool_call_pending ⇒ Boolean

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns true when calling_llm returned a tool call.

Returns:

  • (Boolean) —

    true when calling_llm returned a tool call



46
47
48
 
# File 'lib/phronomy/agent/invocation_context.rb', line 46

def tool_call_pending
  @tool_call_pending
end

#usage ⇒ Phronomy::TokenUsage?

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns:



43
44
45
 
# File 'lib/phronomy/agent/invocation_context.rb', line 43

def usage
  @usage
end

#user_message_sent ⇒ Boolean

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns true after the first LLM call (continuation passes nil msg).

Returns:

  • (Boolean) —

    true after the first LLM call (continuation passes nil msg)



64
65
66
 
# File 'lib/phronomy/agent/invocation_context.rb', line 64

def user_message_sent
  @user_message_sent
end

Instance Method Details

#approval_required? ⇒ Boolean

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns:

  • (Boolean) 


166
167
168
 
# File 'lib/phronomy/agent/invocation_context.rb', line 166

def approval_required?
  @approval_required
end

#input_blocked? ⇒ Boolean

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns:

  • (Boolean) 


142
143
144
 
# File 'lib/phronomy/agent/invocation_context.rb', line 142

def input_blocked?
  @input_blocked
end

#input_passed? ⇒ Boolean

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns:

  • (Boolean) 


136
137
138
 
# File 'lib/phronomy/agent/invocation_context.rb', line 136

def input_passed?
  !@input_blocked
end

#output_blocked? ⇒ Boolean

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns:

  • (Boolean) 


154
155
156
 
# File 'lib/phronomy/agent/invocation_context.rb', line 154

def output_blocked?
  @output_blocked
end

#output_passed? ⇒ Boolean

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns:

  • (Boolean) 


148
149
150
 
# File 'lib/phronomy/agent/invocation_context.rb', line 148

def output_passed?
  !@output_blocked
end

#set_graph_metadata(thread_id: nil, phase: nil) ⇒ void

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

This method returns an undefined value.

Called by FSMSession#finish! and FSMSession#halt! to record the terminal/halted phase and the session id. Mirrors the WorkflowContext interface so FSMSession works with both.

Parameters:

  • thread_id (String, nil) (defaults to: nil)
  • phase (Symbol, nil) (defaults to: nil) 


127
128
129
130
 
# File 'lib/phronomy/agent/invocation_context.rb', line 127

def set_graph_metadata(thread_id: nil, phase: nil)
  @session_id = thread_id if thread_id
  @phase = phase
end

#tool_call_pending? ⇒ Boolean

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns:

  • (Boolean) 


160
161
162
 
# File 'lib/phronomy/agent/invocation_context.rb', line 160

def tool_call_pending?
  @tool_call_pending
end