phronomy 0.11.0 → 0.12.0

data/lib/phronomy/agent/concerns/suspendable.rb

@@ -1,190 +0,0 @@
-# frozen_string_literal: true
-
-require "securerandom"
-
-module Phronomy
-  module Agent
-    module Concerns
-      # Adds suspend/resume and tool-approval support to an agent.
-      #
-      # Included in {Phronomy::Agent::Base}. When a tool decorated with
-      # +requires_approval true+ is called and no synchronous approval handler
-      # has been registered, the invocation is suspended and a
-      # @api private
-      # {Phronomy::Agent::Checkpoint} is returned so the caller can resume later.
-      module Suspendable
-        # Registers a callback that is invoked before executing any tool that has
-        # +requires_approval true+ set. The block receives the tool name (String)
-        # and the arguments Hash, and must return a truthy value to allow execution.
-        # Returning a falsy value causes the tool to return a denial message instead
-        # of executing.
-        #
-        # When no handler is registered and a tool with +requires_approval+ is
-        # called, #invoke returns a suspended result hash containing a
-        # {Phronomy::Agent::Checkpoint}. Call #resume to continue execution after
-        # obtaining an approval decision from the user or an external system.
-        #
-        # @example Synchronous handler
-        #   agent = MyAgent.new
-        #   agent.on_approval_required { |tool_name, args| prompt_user(tool_name, args) }
-        # @return [self]
-        # @api private
-        def on_approval_required(&block)
-          @approval_handler = block
-          self
-        end
-
-        # Registers a scope policy callable for this agent instance.
-        #
-        # The callable receives +(tool_class, scope, agent)+ and must return
-        # +:allow+, +:reject+, or +:approve+.
-        #
-        # @example Reject all write-scoped tools
-        #   agent.scope_policy = ->(_tc, scope, _agent) { scope == :write ? :reject : :allow }
-        #
-        # @param policy [#call]
-        # @return [void]
-        # @api public
-        def scope_policy=(policy)
-          @scope_policy = policy
-        end
-
-        # Sets the idempotency store used to guard against duplicate resumes.
-        #
-        # The store must respond to:
-        # - +consumed?(checkpoint_id)+ ⇒ Boolean
-        # - +consume!(checkpoint_id)+  ⇒ void; raises {Phronomy::CheckpointAlreadyResumedError} on duplicate
-        #
-        # Defaults to a per-instance {Phronomy::Agent::CheckpointStore} (in-memory, not thread-safe).
-        # Assign a shared persistent store when resuming across processes (e.g. Redis-backed).
-        # Custom stores are responsible for ensuring thread-safety if shared across threads.
-        #
-        # @param store [#consumed?, #consume!]
-        # @return [void]
-        # @api public
-        def checkpoint_store=(store)
-          @checkpoint_store = store
-        end
-
-        # Resumes a previously suspended invocation from a {Phronomy::Agent::Checkpoint}.
-        #
-        # This method reconstructs the conversation state captured at suspension
-        # time, injects the tool result (executed or denied), and continues the
-        # LLM loop until it produces a final answer.
-        #
-        # @param checkpoint [Phronomy::Agent::Checkpoint] the checkpoint returned by
-        #   the suspended #invoke call
-        # @param approved   [Boolean] +true+ to execute the pending tool; +false+
-        #   to inject a denial message and let the LLM handle it gracefully
-        # @param config     [Hash] same runtime options as #invoke
-        # @return [Hash] +{ output: String, suspended: false, messages: Array, usage: Phronomy::TokenUsage }+
-        #   or +{ output: nil, suspended: true, checkpoint: Phronomy::Agent::Checkpoint, messages: Array }+
-        #   when a second approval-required tool is encountered during continuation
-        # @raise [Phronomy::FilterBlockError] when an output filter rejects the value
-        # @raise [Phronomy::CheckpointAlreadyResumedError] when the checkpoint has already been consumed
-        # @api private
-        def resume(checkpoint, approved:, config: {})
-          # Guard against duplicate resumes using the idempotency store.
-          _checkpoint_store.consume!(checkpoint.checkpoint_id)
-          # Build a fresh chat with all tools registered.
-          chat = build_chat
-
-          # Re-apply system instructions and register tools so the LLM has the
-          # same persona/context as the original invocation. build_context
-          # includes all tool classes (static + handoff) via add_capability.
-          context = build_context(checkpoint.original_input, messages: [])
-          apply_instructions(chat, context[:system]) if context[:system]
-          (context[:tool_classes] || []).each { |tc| chat.with_tool(prepare_tool_class(tc)) }
-
-          # Restore the full conversation (history + user + assistant with tool call).
-          checkpoint.messages.each { |msg| chat.messages << msg }
-
-          # Determine the tool result: execute it or inject a denial string.
-          tool_result =
-            if approved
-              tool_instance = chat.tools[checkpoint.pending_tool_name.to_sym]
-              tool_instance ? tool_instance.call(checkpoint.pending_tool_args) : "Tool not found."
-            else
-              "Tool execution denied."
-            end
-
-          # Inject the tool result so the LLM can continue.
-          chat.add_message(
-            role: :tool,
-            content: tool_result.to_s,
-            tool_call_id: checkpoint.pending_tool_call_id
-          )
-
-          # Re-register the suspension hook so that any further requires_approval
-          # tools encountered during continuation are intercepted rather than
-          # executed without approval (cascading / chained approval scenario).
-          _register_suspension_hook!(chat)
-
-          # Continue the LLM loop. Rescue SuspendSignal so that a second
-          # approval-required tool produces a new checkpoint instead of running
-          # without consent.
-          begin
-            response = chat.complete
-          rescue SuspendSignal => signal
-            new_checkpoint = Checkpoint.new(
-              checkpoint_id: SecureRandom.uuid,
-              agent_class: self.class.name,
-              requested_at: Time.now.utc,
-              thread_id: checkpoint.thread_id,
-              original_input: checkpoint.original_input,
-              messages: chat.messages.dup,
-              pending_tool_name: signal.tool_name,
-              pending_tool_args: signal.args,
-              pending_tool_call_id: signal.tool_call_id
-            )
-            return {output: nil, suspended: true, checkpoint: new_checkpoint, messages: chat.messages}
-          end
-
-          output = response.content
-          usage = Phronomy::TokenUsage.from_tokens(response.tokens)
-
-          output = run_output_filters!(output)
-
-          {output: output, suspended: false, messages: chat.messages, usage: usage}
-        end
-
-        private
-
-        # Registers an on_tool_call hook on the chat object that raises SuspendSignal
-        # when an approval-required tool is about to be executed and no synchronous
-        # on_approval_required handler has been registered.
-        #
-        # Does nothing when:
-        #   - a synchronous handler is already registered (@approval_handler is set), or
-        #   - none of the agent's tools have requires_approval set.
-        #
-        # @param chat [RubyLLM::Chat]
-        # @api private
-        def _register_suspension_hook!(chat)
-          return if @approval_handler
-          return if self.class.tools.none? { |tc| tc.requires_approval }
-
-          chat.on_tool_call do |tool_call|
-            tool_instance = chat.tools[tool_call.name.to_sym]
-            if tool_instance&.requires_approval
-              raise SuspendSignal.new(
-                tool_name: tool_call.name,
-                args: tool_call.arguments,
-                tool_call_id: tool_call.id
-              )
-            end
-          end
-        end
-
-        # Returns the checkpoint idempotency store for this instance, lazily
-        # initialising a default in-memory {Phronomy::Agent::CheckpointStore}.
-        #
-        # @return [#consumed?, #consume!]
-        # @api private
-        def _checkpoint_store
-          @checkpoint_store ||= CheckpointStore.new
-        end
-      end
-    end
-  end
-end

data/lib/phronomy/agent/suspend_signal.rb

@@ -1,37 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  module Agent
-    # Raised internally inside the on_tool_call hook when an approval-required
-    # tool is encountered and no synchronous on_approval_required handler has
-    # been registered.  Caught by Agent::Base#invoke_once to produce a
-    # suspended result hash containing a Checkpoint.
-    #
-    # This class is intentionally NOT part of the public API.  Callers should
-    # @api private
-    # inspect the +:suspended+ key in the result hash returned by #invoke.
-    #
-    # @api private
-    class SuspendSignal < StandardError
-      # @return [String] the name of the tool that triggered the suspension
-      attr_reader :tool_name
-
-      # @return [Hash] the arguments the LLM passed to the tool
-      attr_reader :args
-
-      # @return [String] the tool_call_id from the LLM response
-      attr_reader :tool_call_id
-
-      # @param tool_name    [String]
-      # @param args         [Hash]
-      # @param tool_call_id [String]
-      # @api private
-      def initialize(tool_name:, args:, tool_call_id:)
-        super("Agent suspended waiting for approval of tool: #{tool_name}")
-        @tool_name = tool_name
-        @args = args
-        @tool_call_id = tool_call_id
-      end
-    end
-  end
-end

data/lib/phronomy/context.rb

@@ -1,12 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  # Context management utilities: token estimation, budget calculation, and
-  # context assembly.
-  #
-  # Sub-modules are auto-loaded by Zeitwerk:
-  #   Phronomy::LlmContextWindow::TokenEstimator
-  #   Phronomy::LlmContextWindow::TokenBudget
-  module Context
-  end
-end

data/lib/phronomy/tool.rb

@@ -1,9 +0,0 @@
-# frozen_string_literal: true
-
-# This file is intentionally empty.
-# Tool definitions have moved to Phronomy::Agent::Context::Capability.
-# See lib/phronomy/agent/context/capability/.
-module Phronomy
-  module Tool
-  end
-end

data/lib/phronomy/workflow/fsm_session.rb

@@ -1,249 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  class Workflow
-    # 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