phronomy 0.11.0 → 0.12.0

data/lib/phronomy/agent/invocation_session.rb

@@ -0,0 +1,346 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module Phronomy
+  module Agent
+    # Factory that builds a Phronomy::FSMSession configured for a single
+    # Agent#invoke execution.
+    #
+    # This is the Agent counterpart to WorkflowRunner — it assembles the
+    # FSMSession with the correct phase machine class, entry actions, and
+    # context, then hands it to EventLoop for execution.
+    #
+    # == Usage
+    #
+    #   session = Agent::InvocationSession.build(
+    #     agent:    my_agent,
+    #     input:    "What is Ruby?",
+    #     messages: [],
+    #     config:   { thread_id: "t-1" }
+    #   )
+    #   completion_queue = Phronomy::EventLoop.instance.register(session)
+    #   ctx = completion_queue.pop
+    #
+    # == Streaming mode
+    #
+    # Pass +mode: :stream+ and an +on_event:+ block to receive token/tool events.
+    # The state graph is identical; only the +:calling_llm+ entry action differs.
+    #
+    # @api private
+    class InvocationSession
+      # States that have an automatic transition after their action completes.
+      AUTO_STATE_SET = {
+        idle: true,
+        filtering_input: true,
+        building_context: true,
+        calling_llm: true,
+        executing_tool: true,
+        output_filtering: true
+      }.freeze
+
+      # All declared action states (terminals excluded).
+      DECLARED_STATES = %i[
+        idle filtering_input building_context calling_llm
+        executing_tool awaiting_approval output_filtering
+        completed blocked
+      ].freeze
+
+      # Builds a Phronomy::FSMSession for the given agent invocation.
+      #
+      # @param agent    [Phronomy::Agent::Base]
+      # @param input    [String, Hash]
+      # @param messages [Array]
+      # @param config   [Hash]
+      # @param mode     [:invoke, :stream]
+      # @param on_event [Proc, nil] stream event callback (stream mode only)
+      # @return [Phronomy::FSMSession]
+      # @api private
+      def self.build(agent:, input:, messages:, config:, mode: :invoke, on_event: nil)
+        ctx = Agent::InvocationContext.new(
+          agent: agent,
+          input: input,
+          messages: messages,
+          config: config
+        )
+
+        actions = (mode == :stream && on_event) ?
+          build_stream_entry_actions(agent, on_event) :
+          build_entry_actions(agent)
+
+        # Calculate recursion_limit for the FSM:
+        # Base states: idle→filtering_input→building_context→calling_llm→
+        #              output_filtering→completed = 6 transitions
+        # Each tool call loop: calling_llm→executing_tool→calling_llm = 2 transitions
+        # Safety margin: +4
+        iterations = agent.class.max_iterations || 10
+        fsm_recursion_limit = 6 + (iterations * 2) + 4
+
+        # Entry actions are registered as after_transition callbacks in the
+        # phase machine class. Pass empty hash to FSMSession (it uses @entry_actions
+        # only for the entry_point state, which has no action for :idle).
+        phase_machine = Agent::PhaseMachineBuilder.new(entry_actions: actions).build
+        session_id = config[:thread_id] || SecureRandom.uuid
+
+        Phronomy::FSMSession.new(
+          id: session_id,
+          context: ctx,
+          entry_point: :idle,
+          phase_machine_class: phase_machine,
+          entry_actions: {},
+          auto_state_set: AUTO_STATE_SET,
+          declared_states: DECLARED_STATES,
+          wait_state_names: %i[awaiting_approval],
+          external_events: {
+            approve: [{from: :awaiting_approval, to: :executing_tool, guard: nil}],
+            reject: [{from: :awaiting_approval, to: :blocked, guard: nil}]
+          },
+          recursion_limit: fsm_recursion_limit
+        )
+      end
+
+      # Builds a FSMSession that resumes an existing InvocationContext
+      # from a wait state (e.g. :awaiting_approval) using an external event.
+      #
+      # @param agent        [Phronomy::Agent::Base]
+      # @param context      [Phronomy::Agent::InvocationContext] suspended context
+      # @param resume_event [Symbol] e.g. :approve or :reject
+      # @param resume_phase [Symbol] the wait state to resume from
+      # @return [Phronomy::FSMSession]
+      # @api private
+      def self.build_for_resume(agent:, context:, resume_event:, resume_phase:)
+        actions = build_entry_actions(agent)
+        phase_machine = Agent::PhaseMachineBuilder.new(entry_actions: actions).build
+
+        iterations = agent.class.max_iterations || 10
+        fsm_recursion_limit = 6 + (iterations * 2) + 4
+
+        Phronomy::FSMSession.new(
+          id: context.session_id || SecureRandom.uuid,
+          context: context,
+          entry_point: :idle,
+          phase_machine_class: phase_machine,
+          entry_actions: {},
+          auto_state_set: AUTO_STATE_SET,
+          declared_states: DECLARED_STATES,
+          wait_state_names: %i[awaiting_approval],
+          external_events: {
+            approve: [{from: :awaiting_approval, to: :executing_tool, guard: nil}],
+            reject: [{from: :awaiting_approval, to: :blocked, guard: nil}]
+          },
+          recursion_limit: fsm_recursion_limit,
+          resume_event: resume_event,
+          resume_phase: resume_phase
+        )
+      end
+
+      # ---------------------------------------------------------------------------
+      # Entry action builders
+      # ---------------------------------------------------------------------------
+
+      # @api private
+      def self.build_entry_actions(agent)
+        {
+          # :idle has no action — FSMSession auto-transitions to :filtering_input
+          filtering_input: [method(:filtering_input_action).curry.call(agent)],
+          building_context: [method(:building_context_action).curry.call(agent)],
+          calling_llm: [method(:calling_llm_action).curry.call(agent)],
+          executing_tool: [method(:executing_tool_action).curry.call(agent)],
+          output_filtering: [method(:output_filtering_action).curry.call(agent)]
+        }
+      end
+      private_class_method :build_entry_actions
+
+      # @api private
+      def self.build_stream_entry_actions(agent, on_event)
+        build_entry_actions(agent).merge(
+          calling_llm: [method(:calling_llm_stream_action).curry.call(agent, on_event)]
+        )
+      end
+      private_class_method :build_stream_entry_actions
+
+      # ----------------------------------------------------------------
+      # Individual entry action implementations
+      # ----------------------------------------------------------------
+
+      def self.filtering_input_action(agent, ctx)
+        begin
+          ctx.input = agent.send(:run_input_filters!, ctx.input)
+        rescue Phronomy::FilterBlockError => e
+          ctx.input_blocked = true
+          ctx.block_error = e
+        end
+        ctx
+      end
+      private_class_method :filtering_input_action
+
+      def self.building_context_action(agent, ctx)
+        ctx.chat = agent.send(:build_chat)
+        context = agent.send(
+          :build_context,
+          ctx.input,
+          messages: ctx.messages,
+          thread_id: ctx.thread_id,
+          config: ctx.config,
+          budget: agent.send(:build_token_budget),
+          instruction: agent.send(:build_instructions, ctx.input),
+          tools: agent.class.tools + agent.send(:_handoff_tools)
+        )
+        agent.send(:_apply_context_to_chat, ctx.chat, context)
+        # Run before-completion hooks (e.g. memory injection) once per invocation.
+        agent.send(:run_before_completion_hooks!, ctx.chat, ctx.config)
+        # Register the tool-call interceptor so every tool call routes through
+        # :executing_tool in the FSM instead of executing inside RubyLLM's loop.
+        ctx.chat.on_tool_call do |tool_call|
+          raise Phronomy::Agent::ToolCallIntercepted.new(tool_call)
+        end
+        ctx
+      end
+      private_class_method :building_context_action
+
+      def self.calling_llm_action(agent, ctx)
+        # Returns a Task.deferred — no extra OS thread is created.
+        # The BlockingAdapterPool worker thread completes the LLM call and
+        # resolves result_task via on_complete, which then triggers the
+        # FSMSession's dispatch_task_in_event_loop on_complete callback to
+        # post :action_completed back to the EventLoop.
+        user_message = ctx.user_message_sent ? nil : agent.send(:extract_message, ctx.input)
+        agent.send(:check_cancellation!, ctx.config, "invocation cancelled before LLM call")
+        adapter = Phronomy.configuration.llm_adapter
+        op = adapter.complete_async(ctx.chat, user_message, config: ctx.config)
+        result_task = Phronomy::Task.deferred(name: "agent-llm:#{ctx.thread_id}")
+        op.on_complete do |response, error|
+          if error.is_a?(Phronomy::Agent::ToolCallIntercepted)
+            ctx.user_message_sent = true
+            ctx.pending_tool_call = error.tool_call
+            ctx.tool_call_pending = true
+            ctx.messages = ctx.chat.messages
+            result_task.backend.unblock(ctx, nil)
+            result_task.transition!(:completed, value: ctx)
+          elsif error
+            result_task.backend.unblock(nil, error)
+            result_task.transition!(:failed, error: error)
+          else
+            ctx.user_message_sent = true
+            ctx.output = response.content
+            ctx.usage = Phronomy::TokenUsage.from_tokens(response.tokens)
+            ctx.messages = ctx.chat.messages
+            ctx.tool_call_pending = false
+            result_task.backend.unblock(ctx, nil)
+            result_task.transition!(:completed, value: ctx)
+          end
+        end
+        result_task
+      end
+      private_class_method :calling_llm_action
+
+      def self.calling_llm_stream_action(agent, on_event, ctx)
+        user_message = ctx.user_message_sent ? nil : agent.send(:extract_message, ctx.input)
+        # Streaming requires a background thread because chunk_queue.pop is a
+        # blocking drain loop that must not run on the EventLoop thread.
+        # The on_complete pattern used in calling_llm_action cannot be applied
+        # here because tokens must be delivered incrementally via on_event
+        # before the final response arrives.  This spawn is therefore
+        # intentional and classified under ADR-010 Rule 2 (blocking loop).
+        Phronomy::Runtime.instance.spawn(name: "agent-llm-stream:#{ctx.thread_id}") do
+          adapter = Phronomy.configuration.llm_adapter
+          chunk_queue = Phronomy::Concurrency::AsyncQueue.new(
+            max_size: Phronomy.configuration.stream_queue_max_size
+          )
+          pending = adapter.stream_async(
+            ctx.chat, user_message,
+            config: ctx.config,
+            enqueue_to: chunk_queue
+          )
+          loop do
+            chunk = chunk_queue.pop
+            break if chunk.nil?
+            on_event.call(Phronomy::Agent::StreamEvent.new(
+              type: :token, payload: {content: chunk.content}
+            ))
+          end
+          response = pending.blocking_wait
+          ctx.user_message_sent = true
+          ctx.output = response.content
+          ctx.usage = Phronomy::TokenUsage.from_tokens(response.tokens)
+          ctx.messages = ctx.chat.messages
+          ctx.tool_call_pending = false
+          ctx
+        end
+      end
+      private_class_method :calling_llm_stream_action
+
+      def self.executing_tool_action(agent, ctx)
+        tc = ctx.pending_tool_call
+        tool_instance = ctx.chat.tools[tc.name.to_sym]
+
+        unless tool_instance
+          # Tool not found — inject an error result and continue the LLM loop.
+          ctx.chat.add_message(
+            role: :tool,
+            content: "Tool not found.",
+            tool_call_id: tc.id
+          )
+          ctx.pending_tool_call = nil
+          ctx.tool_call_pending = false
+          ctx.approval_required = false
+          return ctx
+        end
+
+        if tool_instance.requires_approval && !ctx.sync_approval_handler
+          if ctx.approved
+            # Human approved via Agent.approve — execute the tool and continue.
+            ctx.approved = false  # consume the approval flag
+          else
+            # No sync handler and not yet approved — suspend for HITL.
+            ctx.approval_required = true
+            return ctx
+          end
+        end
+
+        # Dispatch the tool off the EventLoop thread via ToolExecutor, which
+        # routes based on the tool's execution_mode class attribute:
+        #   :blocking_io (default) → BlockingAdapterPool (bounded thread pool)
+        #   :cooperative           → Runtime.instance.spawn (scheduler task)
+        # Wrap the awaitable in Task.deferred so FSMSession recognises it as
+        # an async action and sets async_pending = true.
+        tc_id = tc.id
+        tc_args = tc.arguments
+        tc_name = tc.name
+        ct = ctx.config[:cancellation_token]
+        awaitable = tool_instance.call_async(tc_args, cancellation_token: ct)
+        result_task = Phronomy::Task.deferred(name: "tool-exec:#{tc_name}")
+        awaitable.on_complete do |result, error|
+          if error
+            result_task.backend.unblock(nil, error)
+            result_task.transition!(:failed, error: error)
+          else
+            ctx.chat.add_message(
+              role: :tool,
+              content: result.to_s,
+              tool_call_id: tc_id
+            )
+            ctx.pending_tool_call = nil
+            ctx.tool_call_pending = false
+            ctx.approval_required = false
+            result_task.backend.unblock(ctx, nil)
+            result_task.transition!(:completed, value: ctx)
+          end
+        end
+        result_task
+      end
+      private_class_method :executing_tool_action
+
+      def self.output_filtering_action(agent, ctx)
+        begin
+          ctx.output = agent.send(:run_output_filters!, ctx.output)
+        rescue Phronomy::FilterBlockError => e
+          ctx.output_blocked = true
+          ctx.block_error = e
+        end
+        ctx
+      end
+      private_class_method :output_filtering_action
+    end
+  end
+end

data/lib/phronomy/agent/phase_machine_builder.rb

@@ -0,0 +1,189 @@
+# frozen_string_literal: true
+
+require "state_machines"
+
+module Phronomy
+  module Agent
+    # Builds the state_machines-backed PhaseTracker class for Agent invocations.
+    #
+    # This is the Agent counterpart to Workflow::PhaseMachineBuilder.
+    # Unlike the Workflow version (which builds a dynamic graph from user-defined
+    # DSL), this always generates the same fixed graph representing the
+    # Agent invoke execution phases.
+    #
+    # The generated class holds a single +:phase+ state machine with:
+    #   - One automatic event (+:state_completed+) that FSMSession fires after
+    #     each entry action completes.
+    #   - Two external events (+:approve+, +:reject+) for HITL.
+    #   - after_transition callbacks for each state's entry actions.
+    #
+    # Guard methods (+input_passed?+, +tool_call_pending?+, etc.) are delegated
+    # to the +InvocationContext+ stored in +attr_accessor :context+.
+    #
+    # @api private
+    class PhaseMachineBuilder
+      # @param entry_actions   [Hash{Symbol => Array<#call>}]
+      # @param action_timeouts [Hash{Symbol => Numeric}]
+      # @api private
+      def initialize(entry_actions: {}, action_timeouts: {})
+        @entry_actions = entry_actions
+        @action_timeouts = action_timeouts
+      end
+
+      # Builds and returns the PhaseTracker class.
+      # @return [Class]
+      # @api private
+      def build
+        entry_acts = @entry_actions
+        act_timeouts = @action_timeouts
+        build_cb = method(:build_entry_callback)
+
+        Class.new do
+          # state_machines requires a class-level state machine definition.
+          state_machine :phase, initial: :idle do
+            # ----------------------------------------------------------------
+            # State declarations
+            # ----------------------------------------------------------------
+            state :idle
+            state :filtering_input
+            state :building_context
+            state :calling_llm
+            state :executing_tool
+            state :awaiting_approval  # wait_state: external event required
+            state :output_filtering
+            state :completed          # terminal
+            state :blocked            # terminal
+
+            # ----------------------------------------------------------------
+            # Automatic transitions (fired by FSMSession on state_completed)
+            # Guards are evaluated on the InvocationContext via #context.
+            # ----------------------------------------------------------------
+            event :state_completed do
+              # idle → filtering_input (unconditional)
+              transition idle: :filtering_input
+
+              # filtering_input → building_context | blocked
+              transition filtering_input: :building_context, if: ->(m) { m.context&.input_passed? }
+              transition filtering_input: :blocked, if: ->(m) { m.context&.input_blocked? }
+
+              # building_context → calling_llm (unconditional)
+              transition building_context: :calling_llm
+
+              # calling_llm → executing_tool | output_filtering
+              transition calling_llm: :executing_tool, if: ->(m) { m.context&.tool_call_pending? }
+              transition calling_llm: :output_filtering
+
+              # executing_tool → awaiting_approval | calling_llm
+              transition executing_tool: :awaiting_approval, if: ->(m) { m.context&.approval_required? }
+              transition executing_tool: :calling_llm
+
+              # output_filtering → completed | blocked
+              transition output_filtering: :completed, if: ->(m) { m.context&.output_passed? }
+              transition output_filtering: :blocked, if: ->(m) { m.context&.output_blocked? }
+            end
+
+            # ----------------------------------------------------------------
+            # External events (human-in-the-loop)
+            # ----------------------------------------------------------------
+            event :approve do
+              transition awaiting_approval: :executing_tool
+            end
+
+            event :reject do
+              transition awaiting_approval: :blocked
+            end
+
+            # ----------------------------------------------------------------
+            # Entry action after_transition callbacks
+            # Each state's callables are fired after entering that state.
+            # ----------------------------------------------------------------
+            entry_acts.each do |state_name, callables|
+              callables.each do |callable|
+                timeout_secs = act_timeouts[state_name]
+                cb = build_cb.call(callable, state_name, timeout_secs)
+                after_transition to: state_name, do: cb
+              end
+            end
+          end
+
+          # Holds the InvocationContext so guard lambdas can access it.
+          attr_accessor :context
+
+          # async_pending flag: set when an entry action returns a Task.
+          attr_accessor :async_pending
+
+          # FSM session id — set by FSMSession so async task spawns know the
+          # target_id for EventLoop events.
+          attr_accessor :session_id
+
+          def initialize
+            super
+            @context = nil
+            @async_pending = false
+            @session_id = nil
+          end
+        end
+      end
+
+      private
+
+      # Returns a proc suitable for use as an after_transition callback.
+      # @api private
+      def build_entry_callback(callable, state_name, timeout_secs)
+        handle = method(:handle_entry_action_result)
+        ->(machine) {
+          result = callable.call(machine.context)
+          handle.call(machine, result, state_name, timeout_secs)
+        }
+      end
+
+      # Dispatches the return value of an entry action.
+      # - Task    → async: set async_pending and spawn a background task
+      # - context → sync:  update machine.context
+      # @api private
+      def handle_entry_action_result(machine, result, state_name, timeout_secs)
+        if result.is_a?(Phronomy::Task)
+          dispatch_task(machine, result, state_name, timeout_secs)
+        elsif result.respond_to?(:set_graph_metadata)
+          machine.context = result
+        end
+      end
+
+      # Marks the machine async-pending and spawns a Task to await the result.
+      # @api private
+      def dispatch_task(machine, result, state_name, timeout_secs)
+        machine.async_pending = true
+        session_id = machine.session_id
+        if timeout_secs
+          Phronomy::Runtime.instance.timer_queue.schedule(seconds: timeout_secs) do
+            next if result.done?
+
+            Phronomy::EventLoop.instance.post(
+              Phronomy::Event.new(
+                type: :error,
+                target_id: Phronomy::EventLoop::SYSTEM_CHANNEL_ID,
+                payload: {session_id: session_id, result: Phronomy::ActionTimeoutError.new(
+                  "Action in state #{state_name.inspect} timed out after #{timeout_secs}s"
+                )}
+              )
+            )
+          end
+        end
+        result.on_complete do |task_result, error|
+          if error
+            Phronomy::EventLoop.instance.post(
+              Phronomy::Event.new(type: :error, target_id: Phronomy::EventLoop::SYSTEM_CHANNEL_ID, payload: {session_id: session_id, result: error})
+            )
+            next
+          end
+          ev = if task_result.respond_to?(:set_graph_metadata)
+            Phronomy::Event.new(type: :action_completed, target_id: session_id, payload: task_result)
+          else
+            Phronomy::Event.new(type: :state_completed, target_id: session_id, payload: nil)
+          end
+          Phronomy::EventLoop.instance.post(ev)
+        end
+      end
+    end
+  end
+end

data/lib/phronomy/agent/suspended_session_registry.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Agent
+    # In-process registry for Agent invocations suspended at :awaiting_approval.
+    #
+    # When an agent invocation halts waiting for human approval, the
+    # InvocationContext is stored here keyed by session_id.
+    # Agent::Base.approve / Agent::Base.reject look up and remove the context
+    # to build a resume session.
+    #
+    # Thread-safe. Each process has one shared instance via module methods.
+    # Cross-process persistence is out of scope (future SessionStore feature).
+    #
+    # @api private
+    module SuspendedSessionRegistry
+      @sessions = {}
+      @mutex = Mutex.new
+
+      # Stores a suspended context under the given session_id.
+      # @param session_id [String]
+      # @param ctx [Phronomy::Agent::InvocationContext]
+      # @return [void]
+      # @api private
+      def self.store(session_id, ctx)
+        @mutex.synchronize { @sessions[session_id] = ctx }
+      end
+
+      # Retrieves and removes the suspended context for session_id.
+      # Returns nil when no matching session exists.
+      # @param session_id [String]
+      # @return [Phronomy::Agent::InvocationContext, nil]
+      # @api private
+      def self.fetch(session_id)
+        @mutex.synchronize { @sessions.delete(session_id) }
+      end
+
+      # Returns true when a session is suspended under the given id.
+      # @param session_id [String]
+      # @return [Boolean]
+      # @api private
+      def self.exists?(session_id)
+        @mutex.synchronize { @sessions.key?(session_id) }
+      end
+
+      # Clears all suspended sessions. Intended for test teardown only.
+      # @return [void]
+      # @api private
+      def self.clear!
+        @mutex.synchronize { @sessions.clear }
+      end
+    end
+  end
+end

data/lib/phronomy/agent/tool_call_intercepted.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Agent
+    # Raised inside the on_tool_call hook registered by InvocationSession
+    # to intercept every tool call before RubyLLM executes it.
+    #
+    # Catching this exception in calling_llm_action lets the Agent FSM
+    # route through :executing_tool (and possibly :awaiting_approval) rather
+    # than executing the tool inside RubyLLM's internal loop.
+    #
+    # This class is intentionally NOT part of the public API.
+    # @api private
+    class ToolCallIntercepted < StandardError
+      # @return [Object] the RubyLLM tool_call object (responds to #name, #arguments, #id)
+      attr_reader :tool_call
+
+      # @param tool_call [Object] the RubyLLM tool_call object
+      # @api private
+      def initialize(tool_call)
+        super("Tool call intercepted: #{tool_call.name}")
+        @tool_call = tool_call
+      end
+    end
+  end
+end

data/lib/phronomy/configuration.rb

@@ -28,11 +28,6 @@ module Phronomy
     # Recursion limit for graph execution (default: 25)
     attr_accessor :recursion_limit
 
-    # When true, workflow execution is driven by EventLoop instead of a
-    # synchronous loop in the calling thread. Defaults to false (sync mode).
-    # @see Phronomy::EventLoop
-    attr_accessor :event_loop
-
     # When true, agent LLM calls use {Phronomy::MultiAgent::ParallelToolChat}
     # for concurrent tool dispatch within a single agent turn.
     # Defaults to false.
@@ -197,7 +192,6 @@ module Phronomy
       @recursion_limit = 25
       @tracer = Phronomy::Tracing::NullTracer.new
       @trace_pii = false
-      @event_loop = false
       @parallel_tool_execution = false
       @event_loop_stop_grace_seconds = 5
       @llm_adapter = Phronomy::LLMAdapter::RubyLLM.new