phronomy 0.12.0 → 0.14.0

data/lib/phronomy/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Phronomy
-  VERSION = "0.12.0"
+  VERSION = "0.14.0"
 end

data/lib/phronomy/workflow/phase_machine_builder.rb

@@ -76,6 +76,10 @@ module Phronomy
           # waits for the async worker thread to post a state_completed event back.
           attr_accessor :async_pending
 
+          # Invocation-local routing. FSMSession sets these on each machine
+          # instance; the compiled Class captures no Runtime-specific object.
+          attr_accessor :event_loop, :timer_queue_provider, :session_id
+
           state_machine :phase, initial: entry do
             all_states.each { |s| state s }
 
@@ -190,16 +194,16 @@ module Phronomy
       # @api private
       def dispatch_task_in_event_loop(machine, result, state_name, timeout_secs)
         machine.async_pending = true
-        thread_id = machine.context.thread_id
+        session_id = machine.session_id || machine.context.thread_id
         if timeout_secs
-          Phronomy::Runtime.instance.timer_queue.schedule(seconds: timeout_secs) do
+          machine.timer_queue_provider.call.schedule(seconds: timeout_secs) do
             next if result.done?
 
-            Phronomy::EventLoop.instance.post(
+            machine.event_loop.post(
               Phronomy::Event.new(
                 type: :error,
                 target_id: Phronomy::EventLoop::SYSTEM_CHANNEL_ID,
-                payload: {session_id: thread_id, result: Phronomy::ActionTimeoutError.new(
+                payload: {session_id: session_id, result: Phronomy::ActionTimeoutError.new(
                   "Action in state #{state_name.inspect} timed out after #{timeout_secs}s"
                 )}
               )
@@ -208,17 +212,17 @@ module Phronomy
         end
         result.on_complete do |task_result, error|
           if error
-            Phronomy::EventLoop.instance.post(
-              Phronomy::Event.new(type: :error, target_id: Phronomy::EventLoop::SYSTEM_CHANNEL_ID, payload: {session_id: thread_id, result: error})
+            machine.event_loop.post(
+              Phronomy::Event.new(type: :error, target_id: Phronomy::EventLoop::SYSTEM_CHANNEL_ID, payload: {session_id: session_id, result: error})
             )
             next
           end
           ev = if task_result.is_a?(Phronomy::WorkflowContext)
-            Phronomy::Event.new(type: :action_completed, target_id: thread_id, payload: task_result)
+            Phronomy::Event.new(type: :action_completed, target_id: session_id, payload: task_result)
           else
-            Phronomy::Event.new(type: :state_completed, target_id: thread_id, payload: nil)
+            Phronomy::Event.new(type: :state_completed, target_id: session_id, payload: nil)
           end
-          Phronomy::EventLoop.instance.post(ev)
+          machine.event_loop.post(ev)
         end
       end
 

data/lib/phronomy/workflow_context.rb

@@ -167,10 +167,9 @@ module Phronomy
     # @api private
     # mutant:disable - multiple genuine equivalent mutations: defined?(Phronomy::EventLoop)&& removal is genuine because EventLoop is always loaded in the killfork environment; true&& is genuine (truthy guard); EventLoop.current? resolves to Phronomy::EventLoop.current? within the Phronomy module; WorkflowContextOwnershipError resolves to Phronomy::WorkflowContextOwnershipError within the module; raise without message or with nil message is genuine (spec checks exception class, not message text)
     def _assert_write_permitted!
-      return unless defined?(Phronomy::EventLoop)
       # Allow mutations when executing synchronously (e.g. Workflow#stream via run_workflow).
       return if Thread.current[:phronomy_sync_execution]
-      return if Phronomy::EventLoop.current?
+      return if Phronomy::Runtime.in_event_loop_context?
 
       raise Phronomy::WorkflowContextOwnershipError,
         "WorkflowContext fields may only be mutated from the EventLoop dispatch " \

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.12.0
+  version: 0.14.0
 platform: ruby
 authors:
 - Raizo T.C.S
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-07-19 00:00:00.000000000 Z
+date: 2026-07-27 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ruby_llm
@@ -64,6 +64,60 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         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: '1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        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.
@@ -101,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
@@ -129,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
@@ -141,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