phronomy 0.7.0 → 0.7.1

data/lib/phronomy/tool/mcp_tool.rb

@@ -5,7 +5,6 @@ require "net/http"
 require "open3"
 require "securerandom"
 require "shellwords"
-require "timeout"
 require "uri"
 
 module Phronomy
@@ -67,7 +66,7 @@ module Phronomy
 
         def build_tool_class(tool_name, server_uri, tool_def)
           klass = Class.new(McpTool)
-          klass.instance_variable_set(:@mcp_tool_name, tool_name)
+          klass.tool_name(tool_name)
           klass.instance_variable_set(:@mcp_server_uri, server_uri)
 
           # Register description and params from the MCP tool definition.
@@ -118,7 +117,9 @@ module Phronomy
         #   {HttpTransport}. Defaults to 30 seconds.
         # @param env             [Hash, nil] environment variable overrides for the subprocess.
         #   When provided, only these variables are added/overridden; the parent environment
-        #   is still inherited unless explicitly cleared via an empty string value.
+        #   is still inherited. Use +nil+ as a value to unset a variable in the child process
+        #   (e.g. +{ "SECRET" => nil }+). An empty string value (+""+ ) sets the variable to
+        #   an empty string — it does NOT unset it.
         # @param cwd             [String, nil] working directory for the subprocess.
         #   Defaults to the current process's working directory.
         # @param startup_timeout [Numeric, nil] seconds to wait for the server to
@@ -138,6 +139,7 @@ module Phronomy
           @stderr = nil
           @wait_thr = nil
           @stderr_thread = nil
+          @stderr_op = nil
         end
 
         # Shut down the child process and close its IO streams.
@@ -149,10 +151,17 @@ module Phronomy
           @stdout = nil
           @stderr = nil
           stderr_thread = @stderr_thread
+          stderr_op = @stderr_op
           wait_thr = @wait_thr
           @stderr_thread = nil
+          @stderr_op = nil
           @wait_thr = nil
           stderr_thread&.join(1)
+          begin
+            stderr_op&.await(timeout: 1.0)
+          rescue
+            nil
+          end
           wait_thr&.join(5)
         end
 
@@ -209,31 +218,53 @@ module Phronomy
           # Drain stderr asynchronously to prevent the pipe buffer from filling
           # and deadlocking the child process. Errors inside the drain thread are
           # silently ignored since stderr content is diagnostics-only.
-          @stderr_thread = Thread.new do
-            @stderr.read
-          rescue
-            nil
+          #
+          # Prefer BlockingAdapterPool when a Runtime is configured so that this
+          # file eventually needs no direct Thread.new (Issue #360). Fall back to
+          # Thread.new when no pool is available (no EventLoop / bare invocation).
+          pool = begin; Phronomy::Runtime.instance&.blocking_io; rescue; nil; end
+          if pool
+            @stderr_op = pool.submit {
+              begin
+                @stderr.read
+              rescue
+                nil
+              end
+            }
+            @stderr_thread = nil
+          else
+            @stderr_thread = Thread.new {
+              begin
+                @stderr.read
+              rescue
+                nil
+              end
+            }
+            @stderr_op = nil
           end
 
           if @startup_timeout
-            Timeout.timeout(@startup_timeout) { @stdout.gets.tap { |line| @stdout.ungetbyte(line) if line } }
+            unless IO.select([@stdout], nil, nil, @startup_timeout)
+              close
+              raise Phronomy::ToolError,
+                "MCP stdio server did not start within #{@startup_timeout} seconds"
+            end
+            line = @stdout.gets
+            @stdout.ungetbyte(line) if line
           end
-        rescue Timeout::Error
-          close
-          raise Phronomy::ToolError,
-            "MCP stdio server did not start within #{@startup_timeout} seconds"
         end
 
         def rpc_call(method, params)
           ensure_started!
           payload = JSON.generate(jsonrpc: "2.0", id: SecureRandom.uuid, method: method, params: params)
           @stdin.puts(payload)
-          raw = Timeout.timeout(@read_timeout) { @stdout.gets }
+          unless IO.select([@stdout], nil, nil, @read_timeout)
+            raise Phronomy::ToolError,
+              "MCP stdio server did not respond within #{@read_timeout} seconds"
+          end
+          raw = @stdout.gets
           raise Phronomy::ToolError, "MCP server closed the connection unexpectedly" if raw.nil?
           JSON.parse(raw)
-        rescue Timeout::Error
-          raise Phronomy::ToolError,
-            "MCP stdio server did not respond within #{@read_timeout} seconds"
         end
 
         def parse_schema_params(properties, required_names: [])

data/lib/phronomy/tool/scope_policy.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Tool
+    # 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

data/lib/phronomy/tool_executor.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+module Phronomy
+  # Centralises tool execution routing based on {Tool::Base.execution_mode}.
+  #
+  # This is the single place in the framework that decides *how* a tool call is
+  # dispatched:
+  #
+  # - +:cooperative+       — dispatched via +Runtime#spawn+ through the configured
+  #                          scheduler. Under the +:fiber+ backend this avoids an
+  #                          extra OS thread; under the +:thread+ backend it is
+  #                          backed by +ThreadScheduler+ (one thread per task).
+  # - +:blocking_io+       — submitted to +BlockingAdapterPool+ when the runtime
+  #                          provides a pool; falls back to +Runtime#spawn+ otherwise.
+  # - +:cpu_bound+         — emits a deprecation-style warning then falls back to
+  #                          +:blocking_io+ routing (no process pool available yet).
+  # - +:external_process+  — falls back to +:blocking_io+ routing (no process
+  #                          manager available yet).
+  #
+  # All paths return an object that responds to +#await+ (+Phronomy::Task+ or
+  # +BlockingAdapterPool::PendingOperation+), so callers can collect results
+  # uniformly.
+  #
+  # @note Non-goals
+  #   ToolExecutor deliberately does NOT provide:
+  #   - A CPU-bound process pool. CPU-intensive tool work must be handled at the
+  #     application layer (e.g., fork, Sidekiq, separate OS processes). The
+  #     framework will not add a +ProcessPoolExecutor+ equivalent.
+  #   - An external process manager. Spawning or supervising subprocesses is
+  #     out of scope for this module.
+  #   - Additional core execution routes beyond scheduler-backed cooperative
+  #     execution and BlockingAdapterPool-backed blocking I/O isolation.
+  #     The +:cpu_bound+ and +:external_process+ modes are accepted for
+  #     compatibility but both fall back to +:blocking_io+ routing with a
+  #     one-time warning. If a genuinely new core execution route is needed,
+  #     a new ADR is required.
+  #   These non-goals follow from the cooperative-first, non-preemptive
+  #   concurrency model (ADR-010): framework components must not assume the
+  #   caller's concurrency model, and CPU/process management belongs to the
+  #   application layer.
+  #
+  # @api private
+  module ToolExecutor
+    # Tracks tool classes that have already emitted an execution_mode warning so
+    # that the same warning is only logged once per process lifetime.
+    WARNED_MODES = Set.new
+    WARNED_MODES_MUTEX = Mutex.new
+    private_constant :WARNED_MODES, :WARNED_MODES_MUTEX
+
+    # Dispatches a single tool call asynchronously according to its
+    # +execution_mode+ and returns an awaitable.
+    #
+    # @param tool               [Phronomy::Tool::Base] the tool instance to invoke
+    # @param args               [Hash]                 argument hash to pass to {Tool::Base#call}
+    # @param cancellation_token [Phronomy::CancellationToken, nil]
+    # @param runtime            [Phronomy::Runtime]    runtime to use for spawning
+    #                           (defaults to {Runtime.instance}; injectable for tests)
+    # @return [#await] a {Phronomy::Task} or {BlockingAdapterPool::PendingOperation}
+    # @api private
+    def self.call_async(tool:, args:, cancellation_token: nil, runtime: Phronomy::Runtime.instance)
+      ct = cancellation_token
+      mode = tool.class.execution_mode
+
+      # Warn and normalise unsupported modes to :blocking_io.
+      # Each (tool class, mode) pair emits the warning at most once per process
+      # lifetime to avoid log flooding in high-throughput scenarios.
+      if mode == :cpu_bound || mode == :external_process
+        warn_key = [tool.class.name, mode]
+        newly_warned = WARNED_MODES_MUTEX.synchronize { WARNED_MODES.add?(warn_key) }
+        if newly_warned
+          msg = if mode == :cpu_bound
+            "[Phronomy] Tool #{tool.class.name} declares execution_mode :cpu_bound, " \
+            "which has no dedicated executor. " \
+            "Falling back to blocking_io (BlockingAdapterPool). " \
+            "Use :blocking_io explicitly to suppress this warning."
+          else
+            "[Phronomy] Tool #{tool.class.name} declares execution_mode :external_process, " \
+            "which has no dedicated process manager. " \
+            "Falling back to blocking_io (BlockingAdapterPool)."
+          end
+          if Phronomy.configuration.logger
+            Phronomy.configuration.logger.warn(msg)
+          else
+            warn msg
+          end
+        end
+        mode = :blocking_io
+      end
+
+      pool = begin
+        runtime&.blocking_io
+      rescue
+        nil
+      end
+
+      if mode == :cooperative || pool.nil?
+        runtime.spawn(name: "tool-#{tool.class.name.to_s.split("::").last}") do
+          tool.call(args, cancellation_token: ct)
+        end
+      else
+        # Submit directly to pool — no wrapping Task thread required.
+        pool.submit(cancellation_token: ct) { tool.call(args, cancellation_token: ct) }
+      end
+    end
+  end
+end

data/lib/phronomy/tracing/open_telemetry_tracer.rb

@@ -52,6 +52,40 @@ module Phronomy
         end
         span.finish
       end
+
+      # Overrides Base#trace to use OTel +in_span+, which pushes the span onto
+      # the OTel Context stack while the block runs.  Nested +trace+ calls
+      # automatically inherit the current span as their parent, establishing the
+      # correct parent/child hierarchy in the trace tree.
+      #
+      # @param name [String] span name
+      # @param input [Object, nil] input to record as a span attribute
+      # @param meta [Hash] additional metadata (e.g. task_id, user_id)
+      # @yield [span] the active OTel span
+      # @return [Object] the block's return value
+      # @api private
+      def trace(name, input: nil, **meta)
+        attrs = {}
+        attrs["phronomy.input"] = input.to_s if input
+        meta.each { |k, v| attrs["phronomy.#{k}"] = v.to_s unless v.nil? }
+
+        result = nil
+        @otel_tracer.in_span(name, attributes: attrs) do |span|
+          result, usage = yield span
+          span.set_attribute("phronomy.output", result.to_s) if result
+          if usage
+            span.set_attribute("llm.usage.input_tokens", usage.input)
+            span.set_attribute("llm.usage.output_tokens", usage.output)
+            total = (usage.input || 0) + (usage.output || 0)
+            span.set_attribute("llm.usage.total_tokens", total)
+          end
+        rescue => e
+          span.record_exception(e)
+          span.status = OpenTelemetry::Trace::Status.error(e.message)
+          raise
+        end
+        result
+      end
     end
   end
 end

data/lib/phronomy/vector_store/async_backend.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module VectorStore
+    # Mixin that defines the async interface for VectorStore backends.
+    #
+    # Mixing this module into a VectorStore class provides three choices:
+    #
+    # 1. **Do nothing** — inherits default implementations from {VectorStore::Base}
+    #    that route through {BlockingAdapterPool} (the previous behaviour).
+    #
+    # 2. **Override selectively** — override only the async methods where the
+    #    backend has a native async driver, while the remaining methods fall back
+    #    to the pool.
+    #
+    # 3. **Implement all natively** — override all async methods to avoid pool
+    #    allocation entirely.
+    #
+    # @example Native async search (no pool worker thread allocated)
+    #   class MyFastStore < Phronomy::VectorStore::Base
+    #     include Phronomy::VectorStore::AsyncBackend
+    #
+    #     def search_async(query_embedding:, k: 5, cancellation_token: nil, timeout: nil)
+    #       # Returns a PendingOperation backed by a native async driver.
+    #       native_async_search(query_embedding, k)
+    #     end
+    #   end
+    #
+    # @api public
+    module AsyncBackend
+      # Async variant of {VectorStore::Base#add}.
+      #
+      # Submits the add call to {BlockingAdapterPool} by default.
+      # Override to use a native async driver.
+      #
+      # @param id                 [String]
+      # @param embedding          [Array<Float>]
+      # @param metadata           [Hash]
+      # @param cancellation_token [Phronomy::CancellationToken, nil]
+      # @param timeout            [Numeric, nil]
+      # @return [BlockingAdapterPool::PendingOperation]
+      # @api public
+      def add_async(id:, embedding:, metadata: {}, cancellation_token: nil, timeout: nil)
+        Phronomy::Runtime.instance.blocking_io.submit(
+          timeout: timeout,
+          cancellation_token: cancellation_token
+        ) do
+          add(id: id, embedding: embedding, metadata: metadata, cancellation_token: cancellation_token)
+        end
+      end
+
+      # Async variant of {VectorStore::Base#search}.
+      #
+      # Submits the search call to {BlockingAdapterPool} by default.
+      # Override to use a native async driver.
+      #
+      # @param query_embedding    [Array<Float>]
+      # @param k                  [Integer]
+      # @param cancellation_token [Phronomy::CancellationToken, nil]
+      # @param timeout            [Numeric, nil]
+      # @return [BlockingAdapterPool::PendingOperation]
+      # @api public
+      def search_async(query_embedding:, k: 5, cancellation_token: nil, timeout: nil)
+        Phronomy::Runtime.instance.blocking_io.submit(
+          timeout: timeout,
+          cancellation_token: cancellation_token
+        ) do
+          search(query_embedding: query_embedding, k: k, cancellation_token: cancellation_token)
+        end
+      end
+
+      # Async variant of {VectorStore::Base#remove}.
+      #
+      # Submits the remove call to {BlockingAdapterPool} by default.
+      # Override to use a native async driver.
+      #
+      # @param id                 [String]
+      # @param cancellation_token [Phronomy::CancellationToken, nil]
+      # @param timeout            [Numeric, nil]
+      # @return [BlockingAdapterPool::PendingOperation]
+      # @api public
+      def remove_async(id:, cancellation_token: nil, timeout: nil)
+        Phronomy::Runtime.instance.blocking_io.submit(
+          timeout: timeout,
+          cancellation_token: cancellation_token
+        ) do
+          remove(id: id)
+        end
+      end
+
+      # Async variant of {VectorStore::Base#clear}.
+      #
+      # Submits the clear call to {BlockingAdapterPool} by default.
+      # Override to use a native async driver.
+      #
+      # @param cancellation_token [Phronomy::CancellationToken, nil]
+      # @param timeout            [Numeric, nil]
+      # @return [BlockingAdapterPool::PendingOperation]
+      # @api public
+      def clear_async(cancellation_token: nil, timeout: nil)
+        Phronomy::Runtime.instance.blocking_io.submit(
+          timeout: timeout,
+          cancellation_token: cancellation_token
+        ) do
+          clear
+        end
+      end
+    end
+  end
+end

data/lib/phronomy/vector_store/base.rb

@@ -6,7 +6,14 @@ module Phronomy
     #
     # Implementations manage a collection of (embedding, metadata) pairs and
     # support similarity search.
+    #
+    # Async methods (`search_async`, `add_async`, `remove_async`, `clear_async`)
+    # are provided by the {AsyncBackend} mixin which defaults to routing calls
+    # through {BlockingAdapterPool}.  Backends with native async drivers may
+    # override individual async methods without touching the pool at all.
     class Base
+      include AsyncBackend
+
       # Add a document with its vector embedding.
       #
       # @param id                 [String]                         unique document identifier

data/lib/phronomy/version.rb

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

data/lib/phronomy/workflow.rb

@@ -81,12 +81,35 @@ module Phronomy
     # Executes the workflow from the initial state.
     # @param input [Hash] initial context field values
     # @param config [Hash] { thread_id:, recursion_limit:, user_id:, session_id: }
+    # @param invocation_context [Phronomy::InvocationContext, nil] optional first-class context
+    #   object.  When present, +thread_id+, +cancellation_token+, and +deadline+ are
+    #   derived from it (existing +config:+ keys take precedence).  The object is also
+    #   stored in +config[:invocation_context]+ for downstream tracing.
     # @return [Object] final context
     # @api public
-    def invoke(input, config: {})
+    def invoke(input, config: {}, invocation_context: nil)
+      if invocation_context
+        config = _apply_invocation_context(config, invocation_context)
+      end
       @runner.invoke(input, config: config)
     end
 
+    # Invokes this workflow asynchronously and returns a {Phronomy::Task}.
+    #
+    # @param input  [Hash]
+    # @param config [Hash]
+    # @param invocation_context [Phronomy::InvocationContext, nil]
+    # @return [Phronomy::Task]
+    # @api public
+    def invoke_async(input, config: {}, invocation_context: nil)
+      if invocation_context
+        config = _apply_invocation_context(config, invocation_context)
+      end
+      Phronomy::Runtime.instance.spawn(name: "workflow-invoke-async") do
+        invoke(input, config: config)
+      end
+    end
+
     # Resumes a halted workflow. Generic resume that works for all halt types.
     # @param state [Object] halted context
     # @param input [Hash, nil] optional field updates to merge before resuming
@@ -116,6 +139,23 @@ module Phronomy
       @runner.stream(input, config: config, &block)
     end
 
+    private
+
+    # Merges an {InvocationContext} into the config hash.
+    # Existing +config+ keys take precedence (backward-compat).
+    def _apply_invocation_context(config, ic)
+      effective = config.merge(invocation_context: ic)
+      effective = effective.merge(thread_id: ic.thread_id) if effective[:thread_id].nil? && ic.thread_id
+      if effective[:cancellation_token].nil?
+        if (tok = ic.effective_timeout_token)
+          effective = effective.merge(cancellation_token: tok)
+        end
+      end
+      effective
+    end
+
+    public
+
     # ---------------------------------------------------------------------------
     # Internal DSL builder
     # ---------------------------------------------------------------------------
@@ -139,6 +179,8 @@ module Phronomy
         @transitions = []
         # Set of wait state names
         @wait_state_names = []
+        # { state_name => Numeric } — per-state action timeout in seconds
+        @action_timeouts = {}
       end
 
       # Declares the initial (entry) state.
@@ -151,13 +193,17 @@ module Phronomy
       # rubocop:enable Style/TrivialAccessors
 
       # Declares an action state.
-      # @param name   [Symbol]   state name
-      # @param action [#call, nil] optional entry action shorthand.
+      # @param name           [Symbol]        state name
+      # @param action         [#call, nil]    optional entry action shorthand.
       #   +state :generate, action: MY_PROC+ is equivalent to
       #   +state :generate; entry :generate, MY_PROC+.
+      # @param action_timeout [Numeric, nil]  seconds before an async (Task-returning)
+      #   entry action is cancelled and {Phronomy::ActionTimeoutError} is raised.
+      #   Only applies when the action returns a {Task} or {PendingOperation}.
       # @api public
-      def state(name, action: nil)
+      def state(name, action: nil, action_timeout: nil)
         @declared_states << name
+        @action_timeouts[name] = action_timeout if action_timeout
         entry(name, action) if action
       end
 
@@ -309,7 +355,8 @@ module Phronomy
           external_events: external_events,
           entry_point: @initial || @declared_states.first,
           wait_state_names: @wait_state_names,
-          state_store: @state_store
+          state_store: @state_store,
+          action_timeouts: @action_timeouts.dup
         )
 
         Workflow.new(runner)

data/lib/phronomy/workflow_context.rb

@@ -42,7 +42,16 @@ module Phronomy
         end
 
         @fields[name] = {type: type, default: default}
-        attr_accessor name
+
+        # Define getter.
+        attr_reader name
+
+        # Define write-guarded setter.  Mutation from outside the EventLoop
+        # dispatch thread raises WorkflowContextOwnershipError in EventLoop mode.
+        define_method(:"#{name}=") do |value|
+          _assert_write_permitted!
+          instance_variable_set(:"@#{name}", value)
+        end
       end
 
       def fields
@@ -88,7 +97,9 @@ module Phronomy
 
       self.class.fields.each do |name, config|
         default = config[:default].is_a?(Proc) ? config[:default].call : config[:default]
-        send(:"#{name}=", attrs.fetch(name, default))
+        # Bypass the write guard in initialize — ownership enforcement begins
+        # after construction is complete.
+        instance_variable_set(:"@#{name}", attrs.fetch(name, default))
       end
       @thread_id = nil
       @phase = :__end__
@@ -142,6 +153,22 @@ module Phronomy
 
     private
 
+    # Asserts that the calling thread is allowed to mutate this context.
+    # No-op when EventLoop mode is disabled.
+    # @raise [Phronomy::WorkflowContextOwnershipError] when called from a
+    #   non-EventLoop thread in EventLoop mode.
+    # @api private
+    def _assert_write_permitted!
+      return unless defined?(Phronomy::EventLoop) &&
+        Phronomy.configuration.event_loop
+      return if Phronomy::EventLoop.current?
+
+      raise Phronomy::WorkflowContextOwnershipError,
+        "WorkflowContext fields may only be mutated from the EventLoop dispatch " \
+        "thread. Use context.merge(...) to produce a new context, or deliver " \
+        "updates as event payloads."
+    end
+
     # Performs a deep copy of a value for immutable context propagation.
     # Arrays and Hashes are deep-duplicated recursively.
     # Immutable values (nil, Symbol, Integer, Float, true/false, frozen String) are returned as-is.