phronomy 0.13.0 → 0.15.0

data/lib/phronomy/agent/invocation_session.rb

@@ -1,346 +0,0 @@
-# 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, config: ctx.config)
-        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/suspended_session_registry.rb

@@ -1,54 +0,0 @@
-# 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/engine/concurrency/concurrency_gate.rb

@@ -1,157 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  module Concurrency
-    # A counting semaphore that enforces a concurrency cap across a named
-    # resource category (e.g. agent tasks, tool tasks, LLM calls).
-    #
-    # When +max_concurrent+ is +nil+ the gate is a no-op and all callers
-    # pass through immediately without acquiring a slot.
-    #
-    # Backpressure behaviour when the gate is full is controlled by the
-    # +on_full:+ keyword:
-    #   +:reject+  — raise {Phronomy::BackpressureError} immediately
-    #   +:wait+    — block the calling fiber/thread until a slot is free
-    #   +:timeout+ — like +:wait+ but raises {Phronomy::BackpressureError}
-    #               after +timeout:+ seconds if no slot becomes available
-    #
-    # @example
-    #   gate = Phronomy::Concurrency::ConcurrencyGate.new(max_concurrent: 5, name: :agent)
-    #   gate.acquire(on_full: :reject) do
-    #     run_agent_task
-    #   end
-    class ConcurrencyGate
-      # @param max_concurrent [Integer, nil] concurrency cap; nil = unlimited
-      # @param name [Symbol, String, nil] human-readable label used in error messages
-      # @api private
-      def initialize(max_concurrent:, name: nil)
-        @max = max_concurrent
-        @name = name
-        @mutex = Mutex.new
-        @cond = ConditionVariable.new
-        @count = 0
-      end
-
-      # Returns the configured cap (or nil when unlimited).
-      attr_reader :max
-
-      # Returns the name label.
-      attr_reader :name
-
-      # Returns the number of slots currently in use.
-      def current_count
-        @mutex.synchronize { @count }
-      end
-
-      # Acquires a slot, executes +block+, then releases the slot.
-      # When the gate is unlimited (max is nil) the block runs directly.
-      #
-      # @param on_full [:reject, :wait, :timeout] backpressure strategy
-      # @param timeout [Numeric, nil] seconds before +:timeout+ gives up
-      # @yield
-      # @return block return value
-      # @raise [Phronomy::BackpressureError] when +:reject+ or +:timeout+ fires
-      # @api private
-      def acquire(on_full: :wait, timeout: nil, &block)
-        return block.call if @max.nil?
-
-        _acquire_slot(on_full: on_full, timeout: timeout)
-        begin
-          block.call
-        ensure
-          _release_slot
-        end
-      end
-
-      private
-
-      def _acquire_slot(on_full:, timeout:)
-        scheduler = Phronomy::Runtime::Scheduler.current
-        if scheduler
-          _acquire_slot_coop(scheduler, on_full: on_full, timeout: timeout)
-        else
-          _acquire_slot_threaded(on_full: on_full, timeout: timeout)
-        end
-      end
-
-      def _acquire_slot_coop(scheduler, on_full:, timeout:)
-        # In cooperative mode all tasks run on the same thread, so no mutex needed.
-        deadline = timeout ? (scheduler.virtual_time + timeout) : nil
-        @coop_signal ||= scheduler.new_signal
-
-        loop do
-          if @count < @max
-            @count += 1
-            return
-          end
-
-          case on_full
-          when :reject
-            raise Phronomy::BackpressureError,
-              "ConcurrencyGate[#{@name}] at capacity (#{@max}); " \
-              "increase max_concurrent_#{@name}_tasks or retry later"
-          when :timeout
-            if deadline && scheduler.virtual_time >= deadline
-              raise Phronomy::BackpressureError,
-                "ConcurrencyGate[#{@name}] timed out waiting for a free slot (cap: #{@max})"
-            end
-            scheduler.wait_for_signal(@coop_signal)
-            if deadline && scheduler.virtual_time >= deadline
-              raise Phronomy::BackpressureError,
-                "ConcurrencyGate[#{@name}] timed out waiting for a free slot (cap: #{@max})"
-            end
-          else # :wait
-            scheduler.wait_for_signal(@coop_signal)
-          end
-        end
-      end
-
-      def _acquire_slot_threaded(on_full:, timeout:)
-        deadline = timeout ? (Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout) : nil
-
-        @mutex.synchronize do
-          loop do
-            if @count < @max
-              @count += 1
-              return
-            end
-
-            case on_full
-            when :reject
-              raise Phronomy::BackpressureError,
-                "ConcurrencyGate[#{@name}] at capacity (#{@max}); " \
-                "increase max_concurrent_#{@name}_tasks or retry later"
-            when :timeout
-              remaining = deadline ? (deadline - Process.clock_gettime(Process::CLOCK_MONOTONIC)) : nil
-              if remaining && remaining <= 0
-                raise Phronomy::BackpressureError,
-                  "ConcurrencyGate[#{@name}] timed out waiting for a free slot (cap: #{@max})"
-              end
-              @cond.wait(@mutex, remaining || nil)
-              # re-check deadline after wakeup
-              if deadline && Process.clock_gettime(Process::CLOCK_MONOTONIC) >= deadline
-                raise Phronomy::BackpressureError,
-                  "ConcurrencyGate[#{@name}] timed out waiting for a free slot (cap: #{@max})"
-              end
-            else # :wait
-              @cond.wait(@mutex)
-            end
-          end
-        end
-      end
-
-      def _release_slot
-        scheduler = Phronomy::Runtime::Scheduler.current
-        if scheduler && @coop_signal
-          @count -= 1
-          scheduler.raise_signal(@coop_signal)
-        else
-          @mutex.synchronize do
-            @count -= 1
-            @cond.signal
-          end
-        end
-      end
-    end
-  end
-end

data/lib/phronomy/engine/concurrency/gate_registry.rb

@@ -1,51 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  module Concurrency
-    # Lazy cache of {ConcurrencyGate} instances, keyed by resource name.
-    #
-    # Gate concurrency caps are read from {Phronomy::Configuration} when a gate
-    # is first accessed; subsequent calls return the cached instance.  Call
-    # {#reset} to drop the cache and force a rebuild on the next access.
-    # @api private
-    class GateRegistry
-      GATE_CONFIG_MAP = {
-        agent: :max_concurrent_agent_tasks,
-        tool: :max_concurrent_tool_tasks,
-        workflow: :max_concurrent_workflow_tasks,
-        llm: :max_concurrent_llm_calls,
-        vector: :max_concurrent_vector_searches
-      }.freeze
-      private_constant :GATE_CONFIG_MAP
-
-      def initialize
-        @mutex = Mutex.new
-        @gates = {}
-      end
-
-      # Returns (or lazily creates) the gate for +name+.
-      # @param name [Symbol]
-      # @return [ConcurrencyGate]
-      # @api private
-      def get(name)
-        @mutex.synchronize { @gates[name] ||= _build(name) }
-      end
-
-      # Drops the cached gate for +name+ so the next {#get} rebuilds it.
-      # @param name [Symbol]
-      # @return [void]
-      # @api private
-      def reset(name)
-        @mutex.synchronize { @gates.delete(name) }
-      end
-
-      private
-
-      def _build(name)
-        config_key = GATE_CONFIG_MAP[name]
-        max = config_key ? Phronomy.configuration.public_send(config_key) : nil
-        ConcurrencyGate.new(max_concurrent: max, name: name)
-      end
-    end
-  end
-end