phronomy 0.14.0 → 0.15.0

data/lib/phronomy/agent/invocation_session.rb

@@ -1,352 +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::Runtime.instance.event_loop.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,
-        runtime: Phronomy::Runtime.instance)
-        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,
-          event_loop: runtime.event_loop,
-          timer_queue_provider: -> { runtime.timer_queue }
-        )
-      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:,
-        runtime: Phronomy::Runtime.instance)
-        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,
-          event_loop: runtime.event_loop,
-          timer_queue_provider: -> { runtime.timer_queue },
-          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