phronomy 0.14.0 → 0.15.1

data/docs/decisions/011-delegate-transport-policy-to-adapters.md

@@ -0,0 +1,82 @@
+# ADR-011: Delegate Transport Timeout and Retry to Adapters
+
+## Status
+
+Accepted
+
+## Context
+
+Phronomy accumulated execution-policy settings at several layers:
+
+- `Agent::Base.retry_policy`, which replayed the complete Agent invocation;
+- `Agent::Base.invoke_timeout`, which imposed an Agent-class deadline;
+- `config[:llm_timeout]`, applied outside RubyLLM;
+- Tool `retry_on` and `config[:tool_timeout]`;
+- `max_parallel_tools` and the unused `InvocationContext#provider_limits`.
+
+The policies did not share a reliable resource model. In particular, replaying
+an Agent or Tool can repeat external side effects, and a pool-level timeout does
+not terminate a blocking provider call that is already running. RubyLLM already
+owns LLM request timeout, transient-error retry, backoff, and jitter. Tool
+implementations commonly use clients that own equivalent transport behavior.
+
+## Decision
+
+1. RubyLLM, or another configured LLM adapter, owns LLM transport timeout,
+   retry, backoff, jitter, and provider rate-limit handling.
+2. Phronomy translates final provider errors but does not replay the complete
+   Agent invocation.
+3. Tool implementations or their underlying clients own Tool-specific timeout
+   and retry. Phronomy does not provide a generic Tool replay policy.
+4. Agent classes do not own a default invocation timeout. Callers may pass an
+   `InvocationContext` containing a `deadline` or `cancellation_token` when a
+   specific root operation needs a boundary.
+5. Phronomy retains the timeout mechanisms for boundaries it owns: Workflow
+   actions, authorization evaluation, Orchestrator aggregate waits, Runtime
+   shutdown/drain, and generic concurrency primitives.
+6. Parallel Tool execution is a boolean mode. When enabled, all authorized
+   calls in the intercepted batch are dispatched. Runtime's bounded workers and
+   queues remain the coarse process-protection mechanism.
+7. No resource manager, provider limiter, priority scheduler, or compatibility
+   shim is introduced by this change.
+
+## Consequences
+
+### Positive
+
+- LLM transport behavior has one configuration authority.
+- Agent and Tool side effects are not implicitly replayed by the framework.
+- Timeout behavior is controlled at the layer capable of interrupting or
+  cancelling the underlying I/O safely.
+- Invocation context remains small and contains only values consumed by the
+  execution path.
+- The Agent FSM has one invocation attempt and one error propagation path.
+
+### Tradeoffs
+
+- Applications must configure RubyLLM explicitly when its defaults are not
+  appropriate for production.
+- Custom LLM adapters must document and implement their own transport policy.
+- Tool authors are responsible for idempotency when they choose to retry in a
+  Tool or client.
+- Enabling parallel Tool execution dispatches the complete authorized batch;
+  applications should leave it disabled when unbounded batch fan-out is not
+  acceptable.
+
+## Example
+
+```ruby
+RubyLLM.configure do |config|
+  config.request_timeout = 120
+  config.max_retries = 3
+  config.retry_interval = 0.1
+  config.retry_backoff_factor = 2
+  config.retry_interval_randomness = 0.5
+end
+
+context = Phronomy::InvocationContext.new(
+  deadline: Phronomy::Concurrency::Deadline.in(30)
+)
+
+result = MyAgent.new.invoke("Hello", invocation_context: context)
+```

data/examples/workflows/agent_event_mapping.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require "phronomy"
+require "securerandom"
+
+class GenerationContext
+  include Phronomy::WorkflowContext
+
+  field :prompt
+  field :generation_request_id
+  field :answer
+  field :error_message
+
+  # This is application logic. Phronomy transports the event and payload but
+  # does not decide which Agent invocation is current or where the result lives.
+  def handle_fsm_event(event)
+    request_id = event.payload[:generation_request_id]
+    return :consume unless request_id == generation_request_id
+
+    case event.type
+    when :generation_completed
+      self.answer = event.payload[:agent_result][:output]
+    when :generation_failed
+      self.error_message = event.payload[:error].message
+    end
+    false
+  end
+end
+
+class AnswerAgent < Phronomy::Agent::Base
+  model "gpt-4o-mini"
+  instructions "Answer clearly and briefly."
+end
+
+agent = AnswerAgent.new
+workflow = nil
+
+workflow = Phronomy::Workflow.define(GenerationContext) do
+  initial :generating
+
+  state :generating, action: ->(context) {
+    request_id = context.generation_request_id
+
+    # The Agent Task is intentionally not returned from the entry action.
+    # on_event is the application-level integration channel.
+    agent.invoke_async(
+      context.prompt,
+      on_event: ->(agent_event) {
+        workflow_event =
+          case agent_event.type
+          when :done
+            :generation_completed
+          when :error, :timeout, :cancelled, :approval_required
+            :generation_failed
+          end
+        next unless workflow_event
+
+        workflow.signal(
+          thread_id: context.thread_id,
+          event: workflow_event,
+          payload: {
+            generation_request_id: request_id,
+            agent_result: (
+              agent_event.payload if agent_event.type == :done
+            ),
+            error:
+              agent_event.payload[:error] ||
+              Phronomy::Error.new(
+                "Agent requested Tool approval"
+              )
+          }
+        )
+      }
+    )
+
+    context
+  }
+
+  state :succeeded
+  state :failed
+
+  transition(
+    from: :generating,
+    on: :generation_completed,
+    to: :succeeded
+  )
+  transition(
+    from: :generating,
+    on: :generation_failed,
+    to: :failed
+  )
+  transition from: :succeeded, to: :__finish__
+  transition from: :failed, to: :__finish__
+end
+
+result = workflow.invoke(
+  {
+    prompt: "What is Run-to-Completion?",
+    generation_request_id: SecureRandom.uuid
+  },
+  config: {thread_id: SecureRandom.uuid}
+)
+
+puts(result.answer || result.error_message)

data/examples/workflows/generic_task_event_mapping.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+require "phronomy"
+
+class ImportContext
+  include Phronomy::WorkflowContext
+
+  field :record_count, default: 0
+  field :error_message
+
+  def handle_fsm_event(event)
+    case event.type
+    when :import_completed
+      self.record_count = event.payload[:record_count]
+    when :import_failed
+      self.error_message = event.payload[:error].message
+    end
+    false
+  end
+end
+
+workflow = nil
+
+workflow = Phronomy::Workflow.define(ImportContext) do
+  initial :importing
+
+  state :importing, action: ->(context) {
+    task = Phronomy::Runtime.instance.spawn do
+      # Replace with application-owned asynchronous work.
+      100
+    end
+
+    task.on_complete do |record_count, error|
+      workflow.signal(
+        thread_id: context.thread_id,
+        event: error ? :import_failed : :import_completed,
+        payload: {
+          record_count: record_count,
+          error: error
+        }
+      )
+    end
+
+    # Do not return task. The state is active after this synchronous entry ends.
+    context
+  }
+
+  state :completed
+  state :failed
+
+  transition from: :importing, on: :import_completed, to: :completed
+  transition from: :importing, on: :import_failed, to: :failed
+  transition from: :completed, to: :__finish__
+  transition from: :failed, to: :__finish__
+end
+
+result = workflow.invoke({})
+puts "Imported #{result.record_count} records"

data/lib/phronomy/agent/agent_invocation.rb

@@ -0,0 +1,385 @@
+# frozen_string_literal: true
+
+require "securerandom"
+
+module Phronomy
+  module Agent
+    # Mutable domain state for one Agent invocation.
+    #
+    # AgentInvocation interprets Agent-internal events. FSMSession owns the
+    # transition mechanics, while Agent::Base projects the terminal outcome to
+    # both the Application listener and the returned Task.
+    #
+    # @api private
+    class AgentInvocation
+      TOOL_EVENT_TYPES = %i[
+        tool_authorized
+        tool_approval_required
+        tool_completed
+        tool_failed
+        tool_rejected
+        tool_cancelled
+      ].freeze
+
+      LLM_EVENT_TYPES = %i[
+        llm_completed
+        llm_failed
+      ].freeze
+
+      attr_accessor :input,
+        :messages,
+        :chat,
+        :output,
+        :usage,
+        :input_blocked,
+        :output_blocked,
+        :block_error,
+        :user_message_sent,
+        :event_listener,
+        :approval_request,
+        :rejected,
+        :error
+
+      attr_reader :id,
+        :agent,
+        :config,
+        :thread_id,
+        :approval_policy,
+        :approval_listener,
+        :pending_tool_calls,
+        :tool_invocations,
+        :session_id,
+        :phase,
+        :mode
+
+      def initialize(
+        agent:,
+        input:,
+        messages:,
+        config:,
+        approval_policy: nil,
+        approval_listener: nil,
+        event_listener: nil,
+        stream_listener: nil,
+        mode: nil,
+        id: nil
+      )
+        @agent = agent
+        @input = input
+        @messages = Array(messages)
+        @config = config
+        @thread_id = config[:thread_id]
+        @id = (id || config[:agent_invocation_id] || SecureRandom.uuid).to_s
+        invocation_context = config[:invocation_context]
+        invocation_policy = if invocation_context&.respond_to?(:approval_policy)
+          invocation_context.approval_policy
+        end
+        @approval_policy = invocation_policy || approval_policy
+        @approval_listener = approval_listener
+        @event_listener = event_listener || stream_listener
+        @mode = (mode || (stream_listener ? :stream : :invoke)).to_sym
+
+        @chat = nil
+        @output = nil
+        @usage = nil
+        @input_blocked = false
+        @output_blocked = false
+        @block_error = nil
+        @user_message_sent = false
+        @pending_tool_calls = []
+        @tool_invocations = []
+        @approval_request = nil
+        @rejected = false
+        @human_rejection = false
+        @approval_resume_in_progress = false
+        @pending_approval_resolution_ids = []
+        @error = nil
+        @session_id = nil
+        @phase = nil
+      end
+
+      # Compatibility aliases for existing internal callers.
+      def stream_listener
+        @event_listener
+      end
+
+      def stream_listener=(listener)
+        @event_listener = listener
+      end
+
+      def streaming?
+        @mode == :stream
+      end
+
+      def set_graph_metadata(thread_id: nil, phase: nil)
+        @session_id = thread_id if thread_id
+        @phase = phase
+      end
+
+      def pending_tool_calls=(calls)
+        @pending_tool_calls = Array(calls)
+      end
+
+      def tool_invocations=(invocations)
+        @tool_invocations = Array(invocations)
+      end
+
+      def clear_tool_batch!
+        @pending_tool_calls = []
+        @tool_invocations = []
+        @approval_request = nil
+      end
+
+      def handle_fsm_event(event)
+        if event.type == :llm_stream_chunk
+          deliver_event(
+            StreamEvent.new(
+              type: :token,
+              payload: {content: event.payload.fetch(:content)}
+            )
+          )
+          return true
+        end
+
+        if LLM_EVENT_TYPES.include?(event.type)
+          apply_llm_event(event)
+          return true
+        end
+
+        return false unless TOOL_EVENT_TYPES.include?(event.type)
+
+        invocation = tool_invocation(
+          event.payload&.fetch(:tool_invocation_id, nil)
+        )
+        return true unless invocation
+
+        @error ||= invocation.error if invocation.failed? || invocation.cancelled?
+        @rejected = true if invocation.rejected?
+        if @approval_resume_in_progress &&
+            @pending_approval_resolution_ids.delete(invocation.id)
+          if @pending_approval_resolution_ids.empty?
+            @approval_resume_in_progress = false
+          end
+        end
+        true
+      end
+
+      # Deprecated internal compatibility hook. FSMSession no longer calls
+      # this method; asynchronous results enter through explicit events.
+      def apply_fsm_action_result(result)
+        event_type =
+          if result.respond_to?(:error) &&
+              result.error &&
+              !result.error.is_a?(ToolCallIntercepted)
+            :llm_failed
+          else
+            :llm_completed
+          end
+        handle_fsm_event(
+          Phronomy::Event.new(
+            type: event_type,
+            target_id: @id,
+            payload: result
+          )
+        )
+        self
+      end
+
+      def accept_tool_calls!(tool_calls)
+        @user_message_sent = true
+        @pending_tool_calls = Array(tool_calls)
+        @messages = @chat.messages
+        @pending_tool_calls.each do |tool_call|
+          deliver_event(
+            StreamEvent.new(
+              type: :tool_call,
+              payload: {tool_call: tool_call}
+            )
+          )
+        end
+        self
+      end
+
+      def apply_llm_response!(response)
+        unless response
+          raise Phronomy::Error, "LLM operation completed without a response"
+        end
+
+        @user_message_sent = true
+        @output = response.content
+        @usage = Phronomy::TokenUsage.from_tokens(response.tokens)
+        @messages = @chat.messages
+        @pending_tool_calls = []
+        self
+      end
+
+      def tool_invocation(id)
+        @tool_invocations.find { |invocation| invocation.id == id.to_s }
+      end
+
+      def merge_config!(values)
+        @config.merge!(values) unless values.empty?
+        self
+      end
+
+      def approval_context
+        return @config[:approval_context] if @config[:approval_context]
+
+        context = @config[:invocation_context]
+        return {} unless context
+
+        %i[
+          thread_id session_id user_id token_budget
+          task_id parent_task_id
+        ].each_with_object({}) do |name, result|
+          if context.respond_to?(name)
+            result[name] = context.public_send(name)
+          end
+        end
+      end
+
+      def begin_approval_resume!(approved:)
+        @human_rejection = !approved
+        @pending_approval_resolution_ids = @tool_invocations
+          .select(&:awaiting_approval?)
+          .map(&:id)
+        @approval_resume_in_progress =
+          !@pending_approval_resolution_ids.empty?
+        self
+      end
+
+      def prepare_approval_request!
+        @approval_request = ToolApprovalRequest.build(self)
+        self
+      end
+
+      def record_tool_results!
+        @tool_invocations.each do |invocation|
+          @chat.add_message(
+            role: :tool,
+            content: invocation.result.to_s,
+            tool_call_id: invocation.tool_call_id
+          )
+          deliver_event(
+            StreamEvent.new(
+              type: :tool_result,
+              payload: {
+                tool_call_id: invocation.tool_call_id,
+                tool_name: invocation.tool_name,
+                tool_result: invocation.result
+              }
+            )
+          )
+        end
+        @messages = @chat.messages
+        clear_tool_batch!
+        self
+      end
+
+      def input_passed?
+        !@input_blocked
+      end
+
+      def input_blocked?
+        @input_blocked
+      end
+
+      def output_passed?
+        !@output_blocked
+      end
+
+      def output_blocked?
+        @output_blocked
+      end
+
+      def tool_call_pending?
+        !@pending_tool_calls.empty?
+      end
+
+      def preflight_complete?
+        !@tool_invocations.empty? &&
+          @tool_invocations.all?(&:preflight_settled?)
+      end
+
+      def approval_required?
+        !@human_rejection &&
+          !@approval_resume_in_progress &&
+          preflight_complete? &&
+          @tool_invocations.any?(&:awaiting_approval?)
+      end
+
+      def ready_to_dispatch?
+        !@approval_resume_in_progress &&
+          preflight_complete? &&
+          @tool_invocations.none?(&:awaiting_approval?) &&
+          @tool_invocations.none?(&:rejected?) &&
+          @tool_invocations.none?(&:failed?) &&
+          @tool_invocations.none?(&:cancelled?) &&
+          @tool_invocations.any?(&:authorized?)
+      end
+
+      def tool_batch_terminal?
+        !@tool_invocations.empty? &&
+          @tool_invocations.all?(&:terminal?)
+      end
+
+      def tool_batch_failed?
+        return false if @human_rejection || @approval_resume_in_progress
+
+        no_rejection = @tool_invocations.none?(&:rejected?)
+        preflight_failure =
+          preflight_complete? &&
+          @tool_invocations.any? do |invocation|
+            invocation.failed? || invocation.cancelled?
+          end
+        terminal_failure =
+          tool_batch_terminal? &&
+          @tool_invocations.any? do |invocation|
+            invocation.failed? || invocation.cancelled?
+          end
+        no_rejection && (preflight_failure || terminal_failure)
+      end
+
+      def tool_batch_rejected?
+        return false unless @tool_invocations.any?(&:rejected?)
+
+        @human_rejection ? tool_batch_terminal? : preflight_complete?
+      end
+
+      def tool_batch_completed?
+        tool_batch_terminal? &&
+          @tool_invocations.all?(&:execution_completed?)
+      end
+
+      private
+
+      def apply_llm_event(event)
+        result = event.payload
+        unless result.is_a?(LLMOperationResult)
+          raise Phronomy::Error,
+            "Expected LLMOperationResult, got #{result.class}"
+        end
+
+        if event.type == :llm_failed
+          @error = result.error ||
+            Phronomy::Error.new("LLM operation failed without an error")
+          return
+        end
+
+        if result.error
+          if result.error.is_a?(ToolCallIntercepted)
+            accept_tool_calls!(result.error.tool_calls)
+          else
+            @error = result.error
+          end
+        else
+          apply_llm_response!(result.response)
+        end
+      end
+
+      def deliver_event(event)
+        @event_listener&.call(event)
+      end
+    end
+  end
+end

data/lib/phronomy/agent/agent_invocation_registry.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Agent
+    # In-process registry for suspended AgentInvocation aggregates.
+    #
+    # The registry is the single in-process source for pending Human approval.
+    # Cross-process persistence remains outside the scope of this implementation.
+    #
+    # @api private
+    module AgentInvocationRegistry
+      Entry = Struct.new(:invocation, :approval_request)
+
+      @entries = {}
+      @approval_index = {}
+      @mutex = Mutex.new
+
+      def self.store_suspended(invocation, approval_request)
+        @mutex.synchronize do
+          invocation_id = invocation.id
+          request_id = approval_request.id
+          if @entries.key?(invocation_id) || @approval_index.key?(request_id)
+            raise Phronomy::Error,
+              "Suspended AgentInvocation is already registered: #{invocation_id}"
+          end
+
+          @entries[invocation_id] = Entry.new(
+            invocation: invocation,
+            approval_request: approval_request
+          )
+          @approval_index[request_id] = invocation_id
+        end
+        approval_request
+      end
+
+      # Atomically removes and returns one pending approval aggregate.
+      # Duplicate approval commands therefore cannot execute the Tool twice.
+      def self.consume_approval(agent_invocation_id, approval_request_id)
+        @mutex.synchronize do
+          indexed_invocation_id = @approval_index[approval_request_id.to_s]
+          return nil unless indexed_invocation_id == agent_invocation_id.to_s
+
+          entry = @entries.delete(indexed_invocation_id)
+          return nil unless entry
+
+          @approval_index.delete(entry.approval_request.id)
+          entry
+        end
+      end
+
+      def self.lookup(agent_invocation_id)
+        @mutex.synchronize { @entries[agent_invocation_id.to_s] }
+      end
+
+      def self.exists?(agent_invocation_id)
+        @mutex.synchronize { @entries.key?(agent_invocation_id.to_s) }
+      end
+
+      def self.remove_terminal(agent_invocation_id)
+        @mutex.synchronize do
+          entry = @entries.delete(agent_invocation_id.to_s)
+          @approval_index.delete(entry.approval_request.id) if entry
+          entry
+        end
+      end
+
+      def self.clear!
+        @mutex.synchronize do
+          @entries.clear
+          @approval_index.clear
+        end
+      end
+    end
+  end
+end