phronomy 0.7.0 → 0.7.1

data/lib/phronomy/workflow_runner.rb

@@ -45,7 +45,7 @@ module Phronomy
     # Sentinel value for the terminal state of a workflow.
     FINISH = :__end__
 
-    def initialize(state_class:, entry_actions:, declared_states:, auto_transitions:, external_events:, entry_point:, exit_actions: {}, wait_state_names: [], state_store: nil)
+    def initialize(state_class:, entry_actions:, declared_states:, auto_transitions:, external_events:, entry_point:, exit_actions: {}, wait_state_names: [], state_store: nil, action_timeouts: {})
       @state_class = state_class
       @entry_actions = entry_actions   # { state_name => [callable, ...] }
       @declared_states = declared_states
@@ -55,6 +55,7 @@ module Phronomy
       @entry_point = entry_point
       @wait_state_names = wait_state_names
       @state_store = state_store
+      @action_timeouts = action_timeouts   # { state_name => seconds }
       @phase_machine_class = build_phase_machine_class(auto_transitions, exit_actions)
     end
 
@@ -170,6 +171,7 @@ module Phronomy
         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
       )
@@ -211,7 +213,20 @@ module Phronomy
         # The entry point has no prior transition, so we invoke its entry actions directly.
         @entry_actions[current_state]&.each do |c|
           result = c.call(ctx)
-          ctx = result if result.is_a?(Phronomy::WorkflowContext)
+          if result.is_a?(Phronomy::Task)
+            timeout_secs = @action_timeouts[current_state]
+            if timeout_secs
+              if result.join(timeout_secs).nil?
+                result.cancel!
+                raise Phronomy::ActionTimeoutError,
+                  "Action in state #{current_state.inspect} timed out after #{timeout_secs}s"
+              end
+            end
+            task_result = result.await
+            ctx = task_result if task_result.is_a?(Phronomy::WorkflowContext)
+          elsif result.is_a?(Phronomy::WorkflowContext)
+            ctx = result
+          end
         end
         tracker.context = ctx
       end
@@ -302,11 +317,17 @@ module Phronomy
       ext_events = @external_events
       entry_acts = @entry_actions
       exit_acts = exit_actions
+      act_timeouts = @action_timeouts  # { state_name => seconds }
 
       Class.new do
         # Holds the current WorkflowContext so guards and callbacks can read it.
         attr_accessor :context
 
+        # Set to true by an entry action that returned an awaitable Task.
+        # When true, FSMSession skips the automatic advance_or_halt step and
+        # waits for the async worker thread to post a state_completed event back.
+        attr_accessor :async_pending
+
         state_machine :phase, initial: entry do
           all_states.each { |s| state s }
 
@@ -345,9 +366,59 @@ module Phronomy
           #    the returned context replaces the current one on the tracker.
           entry_acts.each do |state_name, callables|
             callables.each do |callable|
+              timeout_secs = act_timeouts[state_name]
               after_transition to: state_name do |machine|
                 result = callable.call(machine.context)
-                machine.context = result if result.is_a?(Phronomy::WorkflowContext)
+                if result.is_a?(Phronomy::Task)
+                  if Phronomy.configuration.event_loop
+                    # EventLoop mode: await in a background task so the EventLoop
+                    # thread is not blocked. Signal async_pending so FSMSession
+                    # skips the automatic advance_or_halt step.
+                    machine.async_pending = true
+                    ctx_ref = machine.context
+                    thread_id = ctx_ref.thread_id
+                    Phronomy::Runtime.instance.spawn(name: "wf-await-#{thread_id}") do
+                      if timeout_secs
+                        if result.join(timeout_secs).nil?
+                          result.cancel!
+                          raise Phronomy::ActionTimeoutError,
+                            "Action in state #{state_name.inspect} timed out after #{timeout_secs}s"
+                        end
+                      end
+                      task_result = result.await
+                      if task_result.is_a?(Phronomy::WorkflowContext)
+                        Phronomy::EventLoop.instance.post(
+                          Phronomy::Event.new(
+                            type: :action_completed,
+                            target_id: thread_id,
+                            payload: task_result
+                          )
+                        )
+                      else
+                        Phronomy::EventLoop.instance.post(
+                          Phronomy::Event.new(type: :state_completed, target_id: thread_id, payload: nil)
+                        )
+                      end
+                    rescue => e
+                      Phronomy::EventLoop.instance.post(
+                        Phronomy::Event.new(type: :error, target_id: thread_id, payload: e)
+                      )
+                    end
+                  else
+                    # Non-EventLoop mode: block synchronously on the task result.
+                    if timeout_secs
+                      if result.join(timeout_secs).nil?
+                        result.cancel!
+                        raise Phronomy::ActionTimeoutError,
+                          "Action in state #{state_name.inspect} timed out after #{timeout_secs}s"
+                      end
+                    end
+                    task_result = result.await
+                    machine.context = task_result if task_result.is_a?(Phronomy::WorkflowContext)
+                  end
+                elsif result.is_a?(Phronomy::WorkflowContext)
+                  machine.context = result
+                end
               end
             end
           end

data/lib/phronomy.rb

@@ -12,6 +12,10 @@ loader.inflector.inflect("ruby_llm_embeddings" => "RubyLLMEmbeddings")
 loader.inflector.inflect("fsm_session" => "FSMSession")
 # AgentFSM: Zeitwerk would infer "Fsm" — override to "FSM".
 loader.inflector.inflect("fsm" => "FSM")
+# LLMAdapter: Zeitwerk would infer "LlmAdapter" — override to "LLMAdapter".
+loader.inflector.inflect("llm_adapter" => "LLMAdapter")
+# LLMAdapter::RubyLLM: "ruby_llm" maps to "RubyLLM" (not "RubyLlm").
+loader.inflector.inflect("ruby_llm" => "RubyLLM")
 loader.setup
 
 require_relative "phronomy/version"
@@ -50,6 +54,22 @@ module Phronomy
   # Separate from TimeoutError (deadline exceeded) — this is an intentional stop.
   class CancellationError < Error; end
 
+  # Raised when {Agent#invoke} (a synchronous, blocking call) is attempted from
+  # inside an active scheduler task and +strict_runtime_guards+ is enabled.
+  #
+  # Calling a blocking invocation from within a scheduler task stalls the
+  # scheduler until the inner invocation completes, preventing other tasks from
+  # making progress (hidden deadlock risk).  Use {Agent#invoke_async} followed by
+  # +#await+ inside scheduler tasks instead.
+  #
+  # This error is only raised when:
+  #   Phronomy.configure { |c| c.strict_runtime_guards = true }
+  #
+  # By default a warning is logged and execution continues.
+  #
+  # @see Phronomy::Runtime.in_scheduler_context?
+  class SchedulerReentrancyError < Error; end
+
   # Raised by {Phronomy::GeneratorVerifier#invoke} when +raise_if_untrusted: true+
   # and the pipeline's combined confidence score falls below the configured threshold.
   #
@@ -76,6 +96,28 @@ module Phronomy
     end
   end
 
+  # Raised when an operation is submitted to a {BlockingAdapterPool} that has
+  # already been shut down via {BlockingAdapterPool#shutdown}.
+  class PoolShutdownError < Error; end
+
+  # Raised when a concurrency limit is exceeded and the configured backpressure
+  # strategy is +:raise+. The caller should back off and retry.
+  class BackpressureError < Error; end
+
+  # Raised by {CancellationScope#pop_queue} when the deadline expires before a
+  # 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}.
+  class ActionTimeoutError < TimeoutError; end
+
+  # Raised when a {Phronomy::WorkflowContext} field is mutated from a thread
+  # that does not own the context (i.e. not the EventLoop dispatch thread).
+  # Only raised in EventLoop mode.  Use +context.merge(...)+ to produce a new
+  # context, or deliver updates as +:child_completed+ event payloads.
+  class WorkflowContextOwnershipError < Error; end
+
   class << self
     def configuration
       @configuration ||= Configuration.new

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: phronomy
 version: !ruby/object:Gem::Version
-  version: 0.7.0
+  version: 0.7.1
 platform: ruby
 authors:
 - Raizo T.C.S
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-05-23 00:00:00.000000000 Z
+date: 2026-05-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ruby_llm
@@ -98,6 +98,7 @@ files:
 - docs/decisions/007-mcp-is-beta-stability.md
 - docs/decisions/008-orchestrator-uses-os-threads.md
 - docs/decisions/009-state-store-abstraction.md
+- docs/decisions/010-cooperative-first-concurrency.md
 - lib/phronomy.rb
 - lib/phronomy/agent.rb
 - lib/phronomy/agent/base.rb
@@ -117,7 +118,11 @@ files:
 - lib/phronomy/agent/shared_state.rb
 - lib/phronomy/agent/suspend_signal.rb
 - lib/phronomy/agent/team_coordinator.rb
+- lib/phronomy/async_queue.rb
+- lib/phronomy/blocking_adapter_pool.rb
+- lib/phronomy/cancellation_scope.rb
 - lib/phronomy/cancellation_token.rb
+- lib/phronomy/concurrency_gate.rb
 - lib/phronomy/configuration.rb
 - lib/phronomy/context.rb
 - lib/phronomy/context/assembler.rb
@@ -127,6 +132,8 @@ files:
 - lib/phronomy/context/token_estimator.rb
 - lib/phronomy/context/trigger_context.rb
 - lib/phronomy/context/trim_context.rb
+- lib/phronomy/deadline.rb
+- lib/phronomy/diagnostics.rb
 - lib/phronomy/embeddings.rb
 - lib/phronomy/embeddings/base.rb
 - lib/phronomy/embeddings/ruby_llm_embeddings.rb
@@ -150,16 +157,22 @@ files:
 - lib/phronomy/guardrail/base.rb
 - lib/phronomy/guardrail/input_guardrail.rb
 - lib/phronomy/guardrail/output_guardrail.rb
+- lib/phronomy/guardrail/prompt_injection_guardrail.rb
+- lib/phronomy/invocation_context.rb
 - lib/phronomy/knowledge_source.rb
 - lib/phronomy/knowledge_source/base.rb
 - lib/phronomy/knowledge_source/entity_knowledge.rb
 - lib/phronomy/knowledge_source/rag_knowledge.rb
 - lib/phronomy/knowledge_source/static_knowledge.rb
+- lib/phronomy/llm_adapter.rb
+- lib/phronomy/llm_adapter/base.rb
+- lib/phronomy/llm_adapter/ruby_llm.rb
 - lib/phronomy/loader.rb
 - lib/phronomy/loader/base.rb
 - lib/phronomy/loader/csv_loader.rb
 - lib/phronomy/loader/markdown_loader.rb
 - lib/phronomy/loader/plain_text_loader.rb
+- lib/phronomy/metrics.rb
 - lib/phronomy/output_parser.rb
 - lib/phronomy/output_parser/base.rb
 - lib/phronomy/output_parser/json_parser.rb
@@ -167,23 +180,48 @@ files:
 - lib/phronomy/prompt_template.rb
 - lib/phronomy/ruby_llm_patches.rb
 - lib/phronomy/runnable.rb
+- lib/phronomy/runtime.rb
+- lib/phronomy/runtime/deterministic_scheduler.rb
+- lib/phronomy/runtime/fake_scheduler.rb
+- lib/phronomy/runtime/gate_registry.rb
+- lib/phronomy/runtime/pool_registry.rb
+- lib/phronomy/runtime/runtime_metrics.rb
+- lib/phronomy/runtime/scheduler.rb
+- lib/phronomy/runtime/scheduler_timer_adapter.rb
+- lib/phronomy/runtime/task_registry.rb
+- lib/phronomy/runtime/thread_scheduler.rb
+- lib/phronomy/runtime/timer_queue.rb
+- lib/phronomy/runtime/timer_service.rb
 - lib/phronomy/splitter.rb
 - lib/phronomy/splitter/base.rb
 - lib/phronomy/splitter/fixed_size_splitter.rb
 - lib/phronomy/splitter/recursive_splitter.rb
 - lib/phronomy/state_store/base.rb
 - lib/phronomy/state_store/in_memory.rb
+- lib/phronomy/task.rb
+- lib/phronomy/task/backend.rb
+- lib/phronomy/task/fiber_backend.rb
+- lib/phronomy/task/immediate_backend.rb
+- lib/phronomy/task/thread_backend.rb
+- lib/phronomy/task_group.rb
+- lib/phronomy/testing.rb
+- lib/phronomy/testing/fake_clock.rb
+- lib/phronomy/testing/fake_scheduler.rb
+- lib/phronomy/testing/scheduler_helpers.rb
 - lib/phronomy/token_usage.rb
 - lib/phronomy/tool.rb
 - lib/phronomy/tool/agent_tool.rb
 - lib/phronomy/tool/base.rb
 - lib/phronomy/tool/mcp_tool.rb
+- lib/phronomy/tool/scope_policy.rb
+- lib/phronomy/tool_executor.rb
 - lib/phronomy/tracing.rb
 - lib/phronomy/tracing/base.rb
 - lib/phronomy/tracing/langfuse_tracer.rb
 - lib/phronomy/tracing/null_tracer.rb
 - lib/phronomy/tracing/open_telemetry_tracer.rb
 - lib/phronomy/vector_store.rb
+- lib/phronomy/vector_store/async_backend.rb
 - lib/phronomy/vector_store/base.rb
 - lib/phronomy/vector_store/in_memory.rb
 - lib/phronomy/vector_store/pgvector.rb