phronomy 0.13.0 → 0.15.0

data/lib/phronomy.rb

@@ -12,10 +12,12 @@ loader.inflector.inflect("ruby_llm_embeddings" => "RubyLLMEmbeddings")
 loader.inflector.inflect("rag" => "RAG")
 # FSMSession: Zeitwerk would infer "FsmSession" — override to "FSMSession".
 # Phronomy::FSMSession is the top-level cooperative execution engine shared by
-# WorkflowRunner and Agent::InvocationSession.
+# WorkflowRunner, AgentInvocationSessionBuilder, and ToolInvocationSessionBuilder.
 loader.inflector.inflect("fsm_session" => "FSMSession")
 # LLMAdapter: Zeitwerk would infer "LlmAdapter" — override to "LLMAdapter".
 loader.inflector.inflect("llm_adapter" => "LLMAdapter")
+# LLMOperationResult: preserve the LLM acronym for the Agent result carrier.
+loader.inflector.inflect("llm_operation_result" => "LLMOperationResult")
 # LLMAdapter::RubyLLM: "ruby_llm" maps to "RubyLLM" (not "RubyLlm").
 loader.inflector.inflect("ruby_llm" => "RubyLLM")
 # Collapse engine/ so that its contents autoload directly under Phronomy::
@@ -34,7 +36,7 @@ module Phronomy
   class ParseError < Error; end
   class RecursionLimitError < Error; end
   class ToolError < Error; end
-  # Raised when an agent invocation exceeds the timeout set via +invoke_timeout+.
+  # Base error for Phronomy-owned timed boundaries and generic timeout primitives.
   class TimeoutError < Error; end
 
   class ConfigurationError < Error; end
@@ -77,6 +79,13 @@ module Phronomy
   # @see Phronomy::Runtime.in_scheduler_context?
   class SchedulerReentrancyError < Error; end
 
+  # Raised when work is submitted to a Runtime whose shutdown has begun, or
+  # when a Runtime cannot be reset because owned resources are still alive.
+  class RuntimeShutdownError < Error; end
+
+  # Raised when Runtime#shutdown is invoked from inside a Phronomy::Task.
+  class RuntimeShutdownReentrancyError < RuntimeShutdownError; end
+
   # Raised by {Phronomy::GeneratorVerifier#invoke} when +raise_if_untrusted: true+
   # and the pipeline's combined confidence score falls below the configured threshold.
   #
@@ -118,8 +127,8 @@ module Phronomy
   # result is available. Extends {TimeoutError} for backwards compatibility.
   class ScopeTimeoutError < TimeoutError; end
 
-  # Raised when a Workflow entry/exit action task exceeds the +action_timeout:+
-  # configured for its state.  Extends {TimeoutError}.
+  # Deprecated compatibility constant. Workflow entry/exit actions are
+  # synchronous and the Workflow DSL no longer accepts +action_timeout:+.
   class ActionTimeoutError < TimeoutError; end
 
   # Raised when a {Phronomy::WorkflowContext} field is mutated from a thread
@@ -175,28 +184,26 @@ module Phronomy
       @configuration = original
     end
 
-    # Resets all Phronomy runtime state: configuration and the EventLoop
-    # singleton (if running).
+    # Shuts down and clears the process-wide default Runtime, then resets
+    # global configuration. Intended for test suites only.
     #
-    # **Intended for test suites only.**  Stops any running EventLoop thread,
-    # clears the EventLoop singleton, and resets configuration to defaults.
-    # Call once before/after each example to ensure test isolation.
+    # Runtime execution failure and resource cleanup are separate. The
+    # singleton is cleared when cleanup completed, even if execution failed.
     #
-    # @example
-    #   config.around { |ex| Phronomy.reset_runtime! ; ex.run ; Phronomy.reset_runtime! }
+    # @param timeout [Numeric] maximum graceful wait for Runtime tasks and
+    #   EventLoop shutdown
+    # @return [Phronomy::Runtime::ShutdownResult]
     # @api public
-    def reset_runtime!
-      # Do NOT stop the EventLoop here. Since Phase 2, all Agent#invoke calls
-      # go through FSMSession + EventLoop. Stopping and restarting the EventLoop
-      # on every after(:each) hook would add thread creation overhead per test.
-      # run_via_event_loop and _invoke_via_fsm restart it lazily if it was reset.
-      #
-      # Preserve event_loop_stop_grace_seconds from the current configuration
-      # so that test suites that set it to 0 (for fast teardown) keep that value
-      # across configuration resets.
-      prev_grace = @configuration&.event_loop_stop_grace_seconds
-      @configuration = Configuration.new
-      @configuration.event_loop_stop_grace_seconds = prev_grace if prev_grace
+    def reset_runtime!(timeout: configuration.event_loop_stop_grace_seconds)
+      previous_grace = @configuration&.event_loop_stop_grace_seconds
+      result = Runtime.reset_default!(timeout: timeout)
+
+      new_configuration = Configuration.new
+      if previous_grace
+        new_configuration.event_loop_stop_grace_seconds = previous_grace
+      end
+      @configuration = new_configuration
+      result
     end
   end
 end

data/scripts/check_readme_runnable.rb

@@ -29,11 +29,14 @@ PREAMBLE = <<~RUBY
   # Patch invoke methods to return canned responses instead of calling the LLM.
   module Phronomy
     module Agent
-      class Base
+      # Prepend overrides AsyncEventApi (which is also prepended) so invoke
+      # returns a canned response without triggering the EventLoop.
+      module CiInvokeStub
         def invoke(input = nil, **)
           {output: "ci-stub-output", messages: []}
         end
       end
+      Base.prepend(CiInvokeStub)
 
       class Runner
         def invoke(input = nil, **)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: phronomy
 version: !ruby/object:Gem::Version
-  version: 0.13.0
+  version: 0.15.0
 platform: ruby
 authors:
 - Raizo T.C.S
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-07-23 00:00:00.000000000 Z
+date: 2026-08-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ruby_llm
@@ -66,18 +66,58 @@ dependencies:
         version: '0.6'
 - !ruby/object:Gem::Dependency
   name: mcp
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3'
+- !ruby/object:Gem::Dependency
+  name: event_stream_parser
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0.3'
+        version: '1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '0.3'
+        version: '1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2'
 description: Phronomy is a Ruby AI agent framework that provides composable building
   blocks — Agents, Workflows, Tools, Filters, and Tracing — for building AI agents
   in Ruby. Powered by RubyLLM for LLM abstraction.
@@ -115,37 +155,44 @@ files:
 - docs/decisions/009-state-store-abstraction.md
 - docs/decisions/010-cooperative-first-concurrency.md
 - docs/decisions/011-build-context-as-single-llm-input-authority.md
+- docs/decisions/011-delegate-transport-policy-to-adapters.md
+- docs/mcp-client.md
+- examples/workflows/agent_event_mapping.rb
+- examples/workflows/generic_task_event_mapping.rb
+- gemfiles/mcp_1_0.gemfile
 - lib/phronomy.rb
 - lib/phronomy/agent.rb
+- lib/phronomy/agent/agent_invocation.rb
+- lib/phronomy/agent/agent_invocation_registry.rb
+- lib/phronomy/agent/agent_invocation_session_builder.rb
+- lib/phronomy/agent/approval_evaluation_request.rb
+- lib/phronomy/agent/async_event_api.rb
 - lib/phronomy/agent/base.rb
 - lib/phronomy/agent/before_completion_context.rb
 - lib/phronomy/agent/concerns/before_completion.rb
 - lib/phronomy/agent/concerns/error_translation.rb
 - lib/phronomy/agent/concerns/filterable.rb
-- lib/phronomy/agent/concerns/retryable.rb
 - lib/phronomy/agent/context/capability/base.rb
-- lib/phronomy/agent/context/capability/scope_policy.rb
 - lib/phronomy/agent/context/instruction/prompt_template.rb
 - lib/phronomy/agent/context/knowledge/base.rb
 - lib/phronomy/agent/context/knowledge/entity_knowledge.rb
 - lib/phronomy/agent/context/knowledge/static_knowledge.rb
-- lib/phronomy/agent/invocation_context.rb
-- lib/phronomy/agent/invocation_session.rb
+- lib/phronomy/agent/llm_operation_result.rb
 - lib/phronomy/agent/phase_machine_builder.rb
 - lib/phronomy/agent/runner.rb
 - lib/phronomy/agent/shared_state.rb
-- lib/phronomy/agent/suspended_session_registry.rb
+- lib/phronomy/agent/tool_approval_request.rb
 - lib/phronomy/agent/tool_call_intercepted.rb
 - lib/phronomy/agent/tool_executor.rb
+- lib/phronomy/agent/tool_invocation.rb
+- lib/phronomy/agent/tool_invocation_session_builder.rb
 - lib/phronomy/configuration.rb
 - lib/phronomy/diagnostics.rb
 - lib/phronomy/engine/concurrency/async_queue.rb
 - lib/phronomy/engine/concurrency/blocking_adapter_pool.rb
 - lib/phronomy/engine/concurrency/cancellation_scope.rb
 - lib/phronomy/engine/concurrency/cancellation_token.rb
-- lib/phronomy/engine/concurrency/concurrency_gate.rb
 - lib/phronomy/engine/concurrency/deadline.rb
-- lib/phronomy/engine/concurrency/gate_registry.rb
 - lib/phronomy/engine/concurrency/pool_registry.rb
 - lib/phronomy/engine/event_loop.rb
 - lib/phronomy/engine/fsm_session.rb
@@ -155,6 +202,7 @@ files:
 - lib/phronomy/engine/runtime/runtime_metrics.rb
 - lib/phronomy/engine/runtime/scheduler.rb
 - lib/phronomy/engine/runtime/scheduler_timer_adapter.rb
+- lib/phronomy/engine/runtime/shutdown_result.rb
 - lib/phronomy/engine/runtime/task_registry.rb
 - lib/phronomy/engine/runtime/thread_scheduler.rb
 - lib/phronomy/engine/runtime/timer_queue.rb
@@ -184,6 +232,9 @@ files:
 - lib/phronomy/filter/base.rb
 - lib/phronomy/filter/prompt_injection_filter.rb
 - lib/phronomy/generator_verifier.rb
+- lib/phronomy/invalid_async_entry_action_error.rb
+- lib/phronomy/invalid_async_transition_action_error.rb
+- lib/phronomy/invalid_async_workflow_action_error.rb
 - lib/phronomy/invocation_context.rb
 - lib/phronomy/knowledge_source.rb
 - lib/phronomy/llm_adapter.rb
@@ -206,6 +257,7 @@ files:
 - lib/phronomy/runnable.rb
 - lib/phronomy/state_store/base.rb
 - lib/phronomy/state_store/in_memory.rb
+- lib/phronomy/stream_callback_error.rb
 - lib/phronomy/testing.rb
 - lib/phronomy/testing/fake_clock.rb
 - lib/phronomy/testing/fake_scheduler.rb

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

@@ -1,103 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  module Agent
-    module Concerns
-      # Adds configurable retry behaviour to an agent.
-      #
-      # Included in {Phronomy::Agent::Base}. The retry loop wraps the full
-      # #invoke_once call; {Phronomy::FilterBlockError} is never retried.
-      # @api private
-      module Retryable
-        def self.included(base)
-          base.extend(ClassMethods)
-        end
-
-        # Class-level DSL methods mixed into the including agent class.
-        module ClassMethods
-          # Configures a retry policy that wraps the full #invoke call.
-          # FilterBlockError is never retried regardless of this setting.
-          #
-          # @param times [Integer] maximum retry attempts (default: 0)
-          # @param wait  [Symbol, Numeric] :exponential, :linear, or a fixed Float
-          # @param base  [Float]  base wait time in seconds (default: 1.0)
-          #
-          # @example
-          #   class MyAgent < Phronomy::Agent::Base
-          #     retry_policy times: 2, wait: :exponential, base: 1.0
-          #   end
-          # @api private
-          def retry_policy(times: 0, wait: 0, base: 1.0)
-            @_retry_policy = {times: times, wait: wait, base: base}
-          end
-
-          # Returns the configured retry policy, or nil when none is set.
-          # @return [Hash, nil]
-          attr_reader :_retry_policy
-
-          # Injectable sleep callable for testing.
-          # In the EventLoop-driven invoke path, actual delay is handled by
-          # timer_queue (non-blocking); _sleep_proc is called only as an
-          # instrumentation hook.  The default is a no-op; tests override it
-          # with a spy lambda to record sleep durations.
-          # @return [#call]
-          # @api private
-          def _sleep_proc
-            @_sleep_proc || method(:sleep)
-          end
-
-          # Overrides the sleep callable used between retries.
-          # @param proc [#call]
-          attr_writer :_sleep_proc
-        end
-
-        private
-
-        # Retry loop for #invoke.
-        def _invoke_impl(input, messages: [], thread_id: nil, config: {})
-          # Fail fast when the token is already cancelled before any LLM call.
-          if (token = config[:cancellation_token]) && token.cancelled?
-            raise Phronomy::CancellationError, "invocation cancelled"
-          end
-
-          policy = self.class._retry_policy
-          attempt = 0
-          begin
-            _invoke_via_fsm(input, messages: messages, thread_id: thread_id, config: config)
-          rescue Phronomy::FilterBlockError
-            raise
-          rescue Phronomy::CancellationError
-            raise # Never retry after cancellation.
-          rescue
-            if policy && attempt < policy[:times]
-              wait = compute_agent_retry_wait(policy[:wait], policy[:base], attempt)
-              self.class._sleep_proc.call(wait) if wait > 0
-              attempt += 1
-              retry
-            end
-            translate_and_reraise!($!)
-          end
-        end
-
-        # Computes the agent-level retry wait duration.
-        # @param strategy [Symbol, Numeric]
-        # @param base     [Float]
-        # @param attempt  [Integer]
-        # @return [Float]
-        # @api private
-        def compute_agent_retry_wait(strategy, base, attempt)
-          case strategy
-          when :exponential
-            (2**attempt) * base
-          when :linear
-            (attempt + 1) * base
-          when Numeric
-            strategy.to_f
-          else
-            base.to_f
-          end
-        end
-      end
-    end
-  end
-end

data/lib/phronomy/agent/context/capability/scope_policy.rb

@@ -1,54 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  module Agent
-    module Context
-      module Capability
-        # Evaluates whether a tool with a given scope may execute.
-        #
-        # A ScopePolicy is a callable that receives +(tool_class, scope, agent)+ and
-        # returns one of:
-        #   +:allow+   — proceed immediately without an approval gate.
-        #   +:reject+  — block execution; the tool returns a denial message.
-        #   +:approve+ — delegate to the agent's approval handler (if registered);
-        #                when no handler is registered the call is rejected.
-        #
-        # The {Default} instance is used automatically when no custom policy is
-        # configured on an agent.
-        #
-        # @example Custom policy that allows everything
-        #   agent.scope_policy = ->(_tool_class, _scope, _agent) { :allow }
-        #
-        # @example Strict policy that rejects all write scopes
-        #   agent.scope_policy = ->(_tc, scope, _agent) {
-        #     scope == :write ? :reject : :allow
-        #   }
-        class ScopePolicy
-          # Scopes that must go through an approval gate before execution.
-          APPROVAL_REQUIRED_SCOPES = %i[write admin external_network filesystem process external_process].freeze
-
-          # Scopes that are always permitted without approval.
-          ALWAYS_ALLOWED_SCOPES = %i[read_only].freeze
-
-          # Returns +:allow+ for always-allowed scopes, +:approve+ for high-risk
-          # scopes, and +:allow+ for anything else (including +nil+).
-          #
-          # @param _tool_class [Class]
-          # @param scope [Symbol, nil]
-          # @param _agent [Object]
-          # @return [:allow, :approve, :reject]
-          # @api private
-          def call(_tool_class, scope, _agent)
-            return :allow if scope.nil? || ALWAYS_ALLOWED_SCOPES.include?(scope)
-            return :approve if APPROVAL_REQUIRED_SCOPES.include?(scope)
-
-            :allow
-          end
-
-          # Shared singleton used when no custom policy is configured.
-          DEFAULT = new.freeze
-        end
-      end
-    end
-  end
-end

data/lib/phronomy/agent/invocation_context.rb

@@ -1,171 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  module Agent
-    # Holds the mutable state for a single Agent#invoke execution.
-    #
-    # An InvocationContext is created at the start of each invoke call and
-    # passed through every FSM state as the context object. It plays the same
-    # role as WorkflowContext does for Workflow executions.
-    #
-    # Fields:
-    #   input                  — the (possibly filter-transformed) user input
-    #   messages               — conversation history (Array of RubyLLM::Message)
-    #   chat                   — the RubyLLM::Chat object built during :building_context
-    #   output                 — the final LLM text response
-    #   usage                  — Phronomy::TokenUsage after completion
-    #   tool_call_pending      — whether the last LLM response contained a tool call
-    #   approval_required      — whether the pending tool requires human approval
-    #   input_blocked          — whether an input filter called block!
-    #   output_blocked         — whether an output filter called block!
-    #   block_error            — the FilterBlockError raised (for :blocked terminal)
-    #   pending_tool_call      — the intercepted tool_call object (name/arguments/id)
-    #   user_message_sent      — true after the first LLM call (continuation uses nil msg)
-    #   sync_approval_handler  — true when agent has an on_approval_required block
-    #   session_id             — FSM session id (set by set_graph_metadata)
-    #   phase                  — terminal FSM phase (set by set_graph_metadata)
-    #
-    # @api private
-    class InvocationContext
-      # @return [String, Hash] user input (may be transformed by input filters)
-      attr_accessor :input
-
-      # @return [Array] conversation history
-      attr_accessor :messages
-
-      # @return [Object, nil] RubyLLM::Chat instance
-      attr_accessor :chat
-
-      # @return [String, nil] final LLM output text
-      attr_accessor :output
-
-      # @return [Phronomy::TokenUsage, nil]
-      attr_accessor :usage
-
-      # @return [Boolean] true when calling_llm returned a tool call
-      attr_accessor :tool_call_pending
-
-      # @return [Boolean] true when the pending tool requires human approval
-      attr_accessor :approval_required
-
-      # @return [Boolean] true when an input filter called block!
-      attr_accessor :input_blocked
-
-      # @return [Boolean] true when an output filter called block!
-      attr_accessor :output_blocked
-
-      # @return [Phronomy::FilterBlockError, nil]
-      attr_accessor :block_error
-
-      # @return [Object, nil] intercepted RubyLLM tool_call (name/arguments/id)
-      attr_accessor :pending_tool_call
-
-      # @return [Boolean] true after the first LLM call (continuation passes nil msg)
-      attr_accessor :user_message_sent
-
-      # @return [Boolean] true when Agent.approve was called (signals executing_tool
-      #   to execute the pending tool rather than re-suspending)
-      attr_accessor :approved
-
-      # @return [Boolean] true when the pending tool call was rejected via
-      #   Agent.approve(session_id, approved: false)
-      attr_accessor :rejected
-
-      # @return [String, nil] FSM session id (set by set_graph_metadata)
-      attr_reader :session_id
-
-      # @return [Symbol, nil] terminal FSM phase (set by set_graph_metadata)
-      attr_reader :phase
-
-      # @return [Boolean] true when agent has a synchronous on_approval_required handler
-      attr_reader :sync_approval_handler
-
-      # @return [Phronomy::Agent::Base] the agent instance driving this invocation
-      attr_reader :agent
-
-      # @return [Hash] the config hash passed to invoke
-      attr_reader :config
-
-      # @return [String, nil] thread_id from config
-      attr_reader :thread_id
-
-      # @param agent    [Phronomy::Agent::Base]
-      # @param input    [String, Hash]
-      # @param messages [Array]
-      # @param config   [Hash]
-      # @api private
-      def initialize(agent:, input:, messages:, config:)
-        @agent = agent
-        @input = input
-        @messages = Array(messages)
-        @config = config
-        @thread_id = config[:thread_id]
-        @chat = nil
-        @output = nil
-        @usage = nil
-        @tool_call_pending = false
-        @approval_required = false
-        @input_blocked = false
-        @output_blocked = false
-        @block_error = nil
-        @pending_tool_call = nil
-        @user_message_sent = false
-        @approved = false
-        @rejected = false
-        @sync_approval_handler = !agent.instance_variable_get(:@approval_handler).nil?
-        @session_id = nil
-        @phase = nil
-      end
-
-      # Called by FSMSession#finish! and FSMSession#halt! to record the
-      # terminal/halted phase and the session id.
-      # Mirrors the WorkflowContext interface so FSMSession works with both.
-      # @param thread_id [String, nil]
-      # @param phase     [Symbol, nil]
-      # @return [void]
-      # @api private
-      def set_graph_metadata(thread_id: nil, phase: nil)
-        @session_id = thread_id if thread_id
-        @phase = phase
-      end
-
-      # Guard helpers used by PhaseMachineBuilder transitions.
-
-      # @return [Boolean]
-      # @api private
-      def input_passed?
-        !@input_blocked
-      end
-
-      # @return [Boolean]
-      # @api private
-      def input_blocked?
-        @input_blocked
-      end
-
-      # @return [Boolean]
-      # @api private
-      def output_passed?
-        !@output_blocked
-      end
-
-      # @return [Boolean]
-      # @api private
-      def output_blocked?
-        @output_blocked
-      end
-
-      # @return [Boolean]
-      # @api private
-      def tool_call_pending?
-        @tool_call_pending
-      end
-
-      # @return [Boolean]
-      # @api private
-      def approval_required?
-        @approval_required
-      end
-    end
-  end
-end