phronomy 0.9.0 → 0.9.1

data/lib/phronomy/agent/fsm.rb

@@ -1,157 +0,0 @@
-# frozen_string_literal: true
-
-require "securerandom"
-
-module Phronomy
-  module Agent
-    # EventLoop-registered execution unit for a single agent invocation.
-    #
-    # +AgentFSM+ implements the minimal interface expected by {Phronomy::EventLoop}
-    # (+#id+, +#start+, +#handle+) so it can be managed alongside
-    # {Phronomy::Agent::Lifecycle::FSMSession} instances.  It is *not* a traditional finite-state
-    # machine; the name reflects its role in the EventLoop rather than internal
-    # state transitions.
-    #
-    # == Execution model
-    #
-    # {#start} is called by the EventLoop on the +:start+ event.  It immediately
-    # returns after spawning a {Phronomy::Task} that runs the agent's full
-    # invocation pipeline (via +_invoke_impl+).  The EventLoop thread is never
-    # blocked by agent execution.
-    #
-    # Inside the task, {Agent::Base#build_chat} returns a
-    # {ParallelToolChat} instance when EventLoop mode is enabled, allowing
-    # concurrent tool dispatch when the LLM returns multiple tool calls in one
-    # response.
-    #
-    # == Completion events
-    #
-    # On *success*:
-    #   - Posts +:finished+ to this FSM's own +#id+ so the EventLoop cleans up
-    #     its registry entry and unblocks any +completion_queue.pop+ caller.
-    #   - When +parent_id+ is set (child-FSM pattern), additionally posts
-    #     +:child_completed+ to +parent_id+, carrying the result hash as the
-    #     event payload.  The parent {FSMSession} must declare an +on:+ transition
-    #     for +:child_completed+ to advance correctly.
-    #
-    # On *error*:
-    #   - Posts +:error+ to this FSM's own +#id+.  The EventLoop propagates the
-    #     exception through the +completion_queue+ so that the original caller of
-    #     +Agent::Base#invoke+ (in EventLoop mode) receives and re-raises it.
-    #
-    # == Standalone usage (blocking caller)
-    #
-    #   Phronomy.configure { |c| c.event_loop = true }
-    #   result = MyAgent.new.invoke("Hello!")   # => { output:, messages:, usage: }
-    #
-    # {Agent::Base#invoke} detects EventLoop mode, creates an +AgentFSM+, registers
-    # it via {EventLoop#register}, and blocks the *calling* thread on the returned
-    # +completion_queue+ until the agent finishes.
-    #
-    # == Child-FSM usage (non-blocking, inside a Workflow)
-    #
-    #   state :run_agent
-    #   entry :run_agent, ->(ctx) { MyAgent.new.run_as_child(ctx.query, ctx: ctx) }
-    #   transition from: :run_agent, on: :child_completed, to: :process_result
-    #
-    # {Agent::Base#run_as_child} creates an +AgentFSM+ with +parent_id+ set to
-    # +ctx.thread_id+, registers it with the EventLoop, and returns immediately.
-    # The parent {FSMSession} waits for the +:child_completed+ event.
-    # @api private
-    class FSM
-      # @return [String] unique identifier used as the EventLoop target_id
-      attr_reader :id
-
-      # @return [Symbol] current internal phase (:idle, :running)
-      attr_reader :current_phase
-
-      # @param agent     [Phronomy::Agent::Base]  agent instance to run
-      # @param input     [String, Hash]           user input passed to +invoke_once+
-      # @param messages  [Array]                  prior conversation history
-      # @param thread_id [String, nil]            conversation thread id;
-      #                                           auto-generated when nil
-      # @param config    [Hash]                   invocation config forwarded to
-      #                                           +_invoke_impl+
-      # @param parent_id [String, nil]  EventLoop id of the parent FSMSession;
-      #                                  when set, a +:child_completed+ event
-      #                                  is posted on completion.  The result
-      #                                  is delivered exclusively as the event
-      #                                  payload — no cross-thread writes to the
-      #                                  parent WorkflowContext are performed.
-      #
-      # @api private
-      def initialize(agent:, input:, messages: [], thread_id: nil, config: {}, parent_id: nil)
-        @agent = agent
-        @input = input
-        @messages = Array(messages).dup
-        @thread_id = thread_id || SecureRandom.uuid
-        @config = config
-        @parent_id = parent_id
-        @id = @thread_id
-        @current_phase = :idle
-      end
-
-      # Called by {EventLoop} on the +:start+ event.
-      # Transitions to +:running+ and spawns the agent task.
-      def start
-        @current_phase = :running
-        spawn_agent_task
-      end
-
-      # Called by {EventLoop} for external events dispatched to this id.
-      # +AgentFSM+ is fully driven by its own IO thread and does not respond
-      # to external events after {#start}.
-      def handle(_event)
-        # No-op: AgentFSM is driven entirely by its IO thread.
-      end
-
-      private
-
-      # Spawns a {Phronomy::Task} that runs the agent invocation pipeline.
-      # Captures all instance variables by value so the task closure is
-      # safe even if the FSM object is modified (though it is not in practice).
-      def spawn_agent_task
-        agent = @agent
-        input = @input
-        messages = @messages
-        thread_id = @thread_id
-        config = @config
-        fsm_id = @id
-        parent_id = @parent_id
-
-        Phronomy::Runtime.instance.spawn(name: "agent-fsm:#{fsm_id}") do
-          result = agent.send(:_invoke_impl,
-            input,
-            messages: messages,
-            thread_id: thread_id,
-            config: config)
-
-          if parent_id
-            # Result is delivered exclusively as the :child_completed payload.
-            # The parent Workflow task is the sole owner of WorkflowContext
-            # and applies the result after receiving the event.
-            Phronomy::EventLoop.instance.post(
-              Phronomy::Event.new(type: :child_completed, target_id: parent_id, payload: result)
-            )
-          end
-
-          Phronomy::EventLoop.instance.post(
-            Phronomy::Event.new(type: :finished, target_id: fsm_id, payload: result)
-          )
-        rescue => e
-          if parent_id
-            Phronomy::EventLoop.instance.post(
-              Phronomy::Event.new(type: :child_failed, target_id: parent_id, payload: e)
-            )
-          end
-
-          Phronomy::EventLoop.instance.post(
-            Phronomy::Event.new(type: :error, target_id: fsm_id, payload: e)
-          )
-
-          # Context caches are instance variables; no thread-local cleanup needed.
-        end
-      end
-    end
-  end
-end

data/lib/phronomy/agent/invocation_pipeline.rb

@@ -1,108 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  module Agent
-    # Encapsulates the core per-invocation LLM round-trip for {Agent::Base}.
-    #
-    # {Agent::Base#invoke_once} delegates the body of each LLM turn to this
-    # class, keeping the caller to a thin setup + trace frame (span≈2).
-    # The pipeline executes inside the agent's binding via +instance_exec+
-    # so that private concern methods (guardrails, hooks, cancellation) remain
-    # encapsulated in their original modules while the orchestration logic lives
-    # here.
-    #
-    # @api private
-    class InvocationPipeline
-      # @param agent [Agent::Base] the agent instance driving this invocation
-      # @api private
-      def initialize(agent)
-        @agent = agent
-      end
-
-      # Runs one LLM round-trip inside the agent's execution context.
-      #
-      # Calls private {Agent::Base} concern methods (guardrails, hooks,
-      # cancellation) via +instance_exec+ so that their encapsulation is
-      # preserved, then routes the LLM request through the configured adapter.
-      #
-      # @param input      [String, Hash] the user input for this turn
-      # @param messages   [Array]        prior conversation messages
-      # @param thread_id  [String, nil]  persistence thread identifier
-      # @param config     [Hash]         per-invocation options
-      # @return [Array(Hash, Phronomy::TokenUsage, nil)]
-      #   A two-element array: the result hash and the token usage (or nil on
-      #   suspension).
-      # @api private
-      def run(input, messages:, thread_id:, config:)
-        @agent.instance_exec(input, messages, thread_id, config) do |inp, msgs, tid, cfg|
-          # Run input guardrails before touching the LLM.
-          run_input_guardrails!(inp)
-
-          user_message = extract_message(inp)
-          chat = build_chat
-
-          # Assemble context (system prompt + history). Override #build_context to
-          # inject custom context editing logic at the Agent subclass level.
-          context = build_context(
-            inp,
-            messages: msgs,
-            thread_id: tid,
-            config: cfg,
-            budget: build_token_budget,
-            instruction: build_instructions(inp),
-            tools: self.class.tools + _handoff_tools
-          )
-          apply_instructions(chat, context[:system]) if context[:system]
-          (context[:tool_classes] || []).each { |tc| chat.with_tool(prepare_tool_class(tc)) }
-          context[:messages].each { |msg| chat.messages << msg }
-
-          # Run before_completion hooks (global → class → instance) before the LLM call.
-          run_before_completion_hooks!(chat, cfg)
-
-          # Register suspension hook for approval-required tools (no-op when a
-          # synchronous on_approval_required handler is already registered).
-          _register_suspension_hook!(chat)
-
-          # Check for cancellation immediately before the LLM call.
-          check_cancellation!(cfg, "invocation cancelled before LLM call")
-
-          # Forward the cancellation token to ParallelToolChat explicitly
-          # via the chat instance so that tool dispatch batches can observe
-          # cancellation without needing Thread.current.
-          chat.cancellation_token = cfg[:cancellation_token] if chat.respond_to?(:cancellation_token=)
-
-          begin
-            # Route the LLM call through the configured LLMAdapter so that the
-            # blocking HTTP request runs inside BlockingAdapterPool and the
-            # adapter can be swapped without changing agent code.
-            adapter = Phronomy.configuration.llm_adapter
-            response = adapter.complete_async(chat, user_message, config: cfg).await
-          rescue SuspendSignal => signal
-            checkpoint = Checkpoint.new(
-              thread_id: tid,
-              original_input: inp,
-              messages: chat.messages.dup,
-              pending_tool_name: signal.tool_name,
-              pending_tool_args: signal.args,
-              pending_tool_call_id: signal.tool_call_id
-            )
-            suspended_result = {output: nil, suspended: true, checkpoint: checkpoint, messages: chat.messages}
-            next [suspended_result, nil]
-          ensure
-            # Clear the chat's cancellation token reference after each LLM call.
-            chat.cancellation_token = nil if chat.respond_to?(:cancellation_token=)
-          end
-
-          output = response.content
-          usage = Phronomy::TokenUsage.from_tokens(response.tokens)
-
-          # Run output guardrails before returning to the caller.
-          run_output_guardrails!(output)
-
-          result = {output: output, messages: chat.messages, usage: usage}
-          [result, usage]
-        end
-      end
-    end
-  end
-end

data/lib/phronomy/agent/lifecycle/fsm_session.rb

@@ -1,251 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  module Agent
-    module Lifecycle
-      # Event-driven execution wrapper for a single workflow run.
-      #
-      # Created by WorkflowRunner and registered with EventLoop. All public methods
-      # are called from the EventLoop thread — FSMSession is NOT thread-safe and must
-      # not be accessed concurrently from multiple threads.
-      #
-      # == Lifecycle
-      #
-      #   register(session) → EventLoop posts :start → session.start
-      #                                 ↓ (auto-transition present)
-      #                        EventLoop posts :state_completed → session.handle
-      #                                 ↓ (repeat)
-      #                        session posts :finished or :halted
-      #                                 ↓
-      #                        EventLoop pushes ctx to completion_queue → caller unblocks
-      #
-      # == Async IO pattern (EventLoop mode only)
-      #
-      # When a state has no auto-transition and is not a wait_state, but has an
-      # external event registered (e.g. +transition from: :fetching, on: :fetch_done+),
-      # the FSMSession stays registered in the EventLoop and waits for that event.
-      # The entry action is expected to spawn an IO thread that posts the event back:
-      #
-      #   entry :fetching, ->(ctx) {
-      #     Thread.new {
-      #       ctx.result = http.get(ctx.url)
-      #       Phronomy::EventLoop.instance.post(
-      #         Phronomy::Event.new(type: :fetch_done, target_id: ctx.thread_id, payload: nil)
-      #       )
-      #     }
-      #   }
-      #   transition from: :fetching, on: :fetch_done, to: :process
-      class FSMSession
-        FINISH = WorkflowRunner::FINISH
-
-        # @return [String] workflow thread_id (matches WorkflowContext#thread_id)
-        attr_reader :id
-
-        # @param id                  [String]
-        # @param context             [Object]        includes Phronomy::WorkflowContext
-        # @param entry_point         [Symbol]        initial state name
-        # @param entry_actions       [Hash]          { state_name => [callable, ...] }
-        # @param auto_state_set      [Hash]          { state_name => true }
-        # @param declared_states     [Array<Symbol>] all action state names
-        # @param wait_state_names    [Array<Symbol>]
-        # @param external_events     [Hash]          { event_name => [{from:, to:, guard:}] }
-        # @param phase_machine_class [Class]         state_machines-backed phase tracker class
-        # @param recursion_limit     [Integer]
-        # @param action_timeouts     [Hash]          { state_name => seconds }
-        # @param resume_event        [Symbol, nil]   external event to fire when resuming
-        # @param resume_phase        [Symbol, nil]   wait state name to resume from
-        # @api private
-        def initialize(id:, context:, entry_point:, entry_actions:, auto_state_set:,
-          declared_states:, wait_state_names:, external_events:, phase_machine_class:,
-          recursion_limit:, action_timeouts: {}, resume_event: nil, resume_phase: nil)
-          @id = id
-          @ctx = context
-          @entry_point = entry_point
-          @entry_actions = entry_actions
-          @auto_state_set = auto_state_set
-          @declared_states = declared_states
-          @wait_state_names = wait_state_names
-          @external_events = external_events
-          @phase_machine_class = phase_machine_class
-          @recursion_limit = recursion_limit
-          @action_timeouts = action_timeouts
-          @resume_event = resume_event
-          @resume_phase = resume_phase
-          @step = 0
-          @done = false
-          @current_state = nil
-          @tracker = nil
-        end
-
-        # Begins workflow execution. Called by EventLoop on :start event.
-        def start
-          if @resume_event
-            # Resume from wait state: position tracker at the wait state, then fire the
-            # external event. state_machines fires before_transition (exit) and
-            # after_transition (entry) callbacks, so both actions execute here.
-            @current_state = @resume_phase
-            @tracker = build_tracker(@current_state)
-            @tracker.context = @ctx
-            fire_and_advance!(@resume_event)
-          else
-            # Fresh start: state_machines does not fire callbacks on initialization,
-            # so we invoke the entry action for the initial state manually.
-            @current_state = @entry_point
-            @tracker = build_tracker(@current_state)
-            @tracker.context = @ctx
-            (@entry_actions[@current_state] || []).each do |c|
-              result = c.call(@ctx)
-              if result.is_a?(Phronomy::Task)
-                # Awaitable action: spawn a task to await without blocking EventLoop.
-                @tracker.async_pending = true
-                session_id = @id
-                current_state_name = @current_state
-                timeout_secs = @action_timeouts[current_state_name]
-                Phronomy::Runtime.instance.spawn(name: "fsm-await-#{session_id}") do
-                  if timeout_secs
-                    if result.join(timeout_secs).nil?
-                      result.cancel!
-                      raise Phronomy::ActionTimeoutError,
-                        "Action in state #{current_state_name.inspect} timed out after #{timeout_secs}s"
-                    end
-                  end
-                  task_result = result.await
-                  if task_result.is_a?(Phronomy::WorkflowContext)
-                    event_loop.post(Event.new(type: :action_completed, target_id: session_id, payload: task_result))
-                  else
-                    event_loop.post(Event.new(type: :state_completed, target_id: session_id, payload: nil))
-                  end
-                rescue => e
-                  event_loop.post(Event.new(type: :error, target_id: session_id, payload: e))
-                end
-                break # Only one async action at a time per state
-              elsif result.is_a?(Phronomy::WorkflowContext)
-                @ctx = result
-              end
-            end
-            @tracker.context = @ctx
-            advance_or_halt unless @tracker.async_pending
-          end
-        rescue => e
-          finish_with_error(e)
-        end
-
-        # Processes an event dispatched from EventLoop.
-        # Called for :state_completed, :action_completed, and all user-defined external events.
-        #
-        # @param event [Phronomy::Event]
-        # @api private
-        def handle(event)
-          return if @done
-
-          if event.type == :action_completed
-            # An awaitable entry action completed: update context and advance.
-            @ctx = event.payload if event.payload.is_a?(Phronomy::WorkflowContext)
-            @tracker.context = @ctx
-            @tracker.async_pending = false  # Reset flag set by start or fire_and_advance!
-            advance_or_halt
-            return
-          end
-
-          fire_and_advance!(event.type)
-        rescue => e
-          finish_with_error(e)
-        end
-
-        private
-
-        # Fires event_name on the phase tracker, updates @current_state, then
-        # calls advance_or_halt to decide what to do next.
-        def fire_and_advance!(event_name)
-          if @step >= @recursion_limit
-            raise Phronomy::RecursionLimitError,
-              "Recursion limit (#{@recursion_limit}) exceeded"
-          end
-
-          fire_event!(@tracker, event_name, @current_state)
-          @ctx = @tracker.context
-          next_phase = @tracker.phase.to_sym
-          # When next_phase == @current_state, no transition matched → treat as terminal.
-          @current_state = (next_phase == @current_state) ? FINISH : next_phase
-          @step += 1
-
-          # If an entry action returned a Task, the after_transition callback set
-          # async_pending = true and spawned a thread. Skip advance_or_halt — the
-          # background thread will post :action_completed or :state_completed.
-          if @tracker.async_pending
-            @tracker.async_pending = false
-            return
-          end
-
-          advance_or_halt
-        end
-
-        # Determines the next action after the FSM has entered @current_state.
-        def advance_or_halt
-          return finish! if @current_state == FINISH
-
-          if @wait_state_names.include?(@current_state)
-            return halt!
-          end
-
-          if @auto_state_set.key?(@current_state)
-            event_loop.post(Event.new(type: :state_completed, target_id: @id, payload: nil))
-            return
-          end
-
-          if has_external_event_from?(@current_state)
-            # Async IO pattern: the entry action spawned an IO thread that will post
-            # an external event back. Stay registered; do nothing here.
-            return
-          end
-
-          # No transition declared — validate the state is known, then treat as terminal.
-          unless @declared_states.include?(@current_state)
-            raise ArgumentError, "State #{@current_state.inspect} is not defined"
-          end
-
-          finish!
-        end
-
-        def finish!
-          @done = true
-          @ctx.set_graph_metadata(thread_id: @id, phase: :__end__)
-          event_loop.post(Event.new(type: :finished, target_id: @id, payload: @ctx))
-        end
-
-        def halt!
-          @done = true
-          @ctx.set_graph_metadata(thread_id: @id, phase: @current_state)
-          event_loop.post(Event.new(type: :halted, target_id: @id, payload: @ctx))
-        end
-
-        def finish_with_error(err)
-          @done = true
-          event_loop.post(Event.new(type: :error, target_id: @id, payload: err))
-        end
-
-        def fire_event!(tracker, event_name, from_state)
-          return if tracker.send(event_name)
-
-          raise ArgumentError,
-            "Transition from #{from_state.inspect} via event #{event_name.inspect} failed. " \
-            "Ensure at least one guard matches or add a fallback (no-guard) transition."
-        end
-
-        def has_external_event_from?(state)
-          @external_events.any? { |_, transitions| transitions.any? { |t| t[:from] == state } }
-        end
-
-        def build_tracker(from_state)
-          machine = @phase_machine_class.new
-          machine.instance_variable_set(:@phase, from_state.to_s)
-          machine
-        end
-
-        def event_loop
-          Phronomy::EventLoop.instance
-        end
-      end
-    end
-  end
-end