phronomy 0.13.0 → 0.14.0

data/lib/phronomy/workflow_runner.rb

@@ -99,14 +99,19 @@ module Phronomy
     # @return [Phronomy::Task]
     # @api private
     def invoke_deferred(input, config: {})
+      runtime = Phronomy::Runtime.instance
+      event_loop = runtime.event_loop
       state, thread_id, recursion_limit, store = _build_initial_context(input, config)
       result_task = Phronomy::Task.deferred(name: "workflow-async:#{thread_id}")
-      Phronomy::EventLoop.instance.start
-      session = build_session_for(context: state, recursion_limit: recursion_limit)
+      session = build_session_for(
+        context: state,
+        recursion_limit: recursion_limit,
+        runtime: runtime
+      )
       if store && config[:thread_id]
         # Wrap so that state is persisted when the task resolves.
         persist_task = Phronomy::Task.deferred(name: "workflow-async-persist:#{thread_id}")
-        Phronomy::EventLoop.instance.register(session, completion: persist_task)
+        event_loop.register(session, completion: persist_task)
         persist_task.on_complete do |result, error|
           store.save(thread_id, {fields: result.to_h, phase: result.phase.to_s}) unless error
           if error
@@ -118,7 +123,7 @@ module Phronomy
           end
         end
       else
-        Phronomy::EventLoop.instance.register(session, completion: result_task)
+        event_loop.register(session, completion: result_task)
       end
       result_task
     end
@@ -202,7 +207,8 @@ module Phronomy
     end
 
     # Builds an FSMSession for the given context. Used in EventLoop mode.
-    def build_session_for(context:, recursion_limit:, resume_event: nil, resume_phase: nil)
+    def build_session_for(context:, recursion_limit:, runtime: Phronomy::Runtime.instance,
+      resume_event: nil, resume_phase: nil)
       Phronomy::FSMSession.new(
         id: context.thread_id,
         context: context,
@@ -214,24 +220,28 @@ module Phronomy
         external_events: @external_events,
         phase_machine_class: @phase_machine_class,
         recursion_limit: recursion_limit,
+        event_loop: runtime.event_loop,
+        timer_queue_provider: -> { runtime.timer_queue },
         action_timeouts: @action_timeouts,
         resume_event: resume_event,
         resume_phase: resume_phase
       )
     end
 
-    # Executes the workflow via the singleton EventLoop.
+    # Executes the workflow via the default Runtime-owned EventLoop.
     # Blocks the calling thread on a completion queue until the workflow
     # finishes, halts at a wait state, or raises an error.
     def run_via_event_loop(context, recursion_limit:, resume_event: nil, resume_phase: nil)
-      # Ensure EventLoop is running. In tests, reset_runtime! resets the
-      # singleton without restarting it; start is idempotent when already alive.
-      Phronomy::EventLoop.instance.start
+      runtime = Phronomy::Runtime.instance
+      event_loop = runtime.event_loop
       session = build_session_for(
-        context: context, recursion_limit: recursion_limit,
-        resume_event: resume_event, resume_phase: resume_phase
+        context: context,
+        recursion_limit: recursion_limit,
+        runtime: runtime,
+        resume_event: resume_event,
+        resume_phase: resume_phase
       )
-      completion_queue = Phronomy::EventLoop.instance.register(session)
+      completion_queue = event_loop.register(session)
       result = completion_queue.pop
       raise result if result.is_a?(Exception)
       result

data/lib/phronomy.rb

@@ -77,6 +77,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.
   #
@@ -175,28 +182,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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: phronomy
 version: !ruby/object:Gem::Version
-  version: 0.13.0
+  version: 0.14.0
 platform: ruby
 authors:
 - Raizo T.C.S
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-07-23 00:00:00.000000000 Z
+date: 2026-07-27 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,6 +155,8 @@ 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/mcp-client.md
+- gemfiles/mcp_1_0.gemfile
 - lib/phronomy.rb
 - lib/phronomy/agent.rb
 - lib/phronomy/agent/base.rb
@@ -143,9 +185,7 @@ files:
 - 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 +195,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

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