phronomy 0.7.0 → 0.7.1

data/lib/phronomy/agent/base.rb

@@ -2,7 +2,6 @@
 
 require "digest"
 require "securerandom"
-require "timeout"
 require_relative "concerns/retryable"
 require_relative "concerns/guardrailable"
 require_relative "concerns/before_completion"
@@ -226,13 +225,10 @@ module Phronomy
         # Defaults to +nil+ (no timeout).
         # Inherited by subclasses; the most-specific definition wins.
         #
-        # **Note**: +invoke_timeout+ is a *wait timeout*, not a cancellation.
-        # When the timeout fires, +Phronomy::TimeoutError+ is raised to the
-        # caller, but the background agent thread and any in-flight LLM or tool
-        # calls are **not** interrupted — they continue running until they
-        # complete naturally.  The agent therefore keeps consuming threads,
-        # memory, and external API credits after the caller has already received
-        # the error.  True cancellation is not yet supported.
+        # When the timeout fires, a {Phronomy::CancellationScope} is cancelled
+        # and its token is propagated to the FSM config so that in-flight LLM,
+        # tool, and RAG calls observe cancellation via their +cancellation_token:+
+        # keyword argument.  +Phronomy::TimeoutError+ is raised to the caller.
         #
         # @param val [Numeric, nil]
         # @return [Numeric, nil]
@@ -489,6 +485,11 @@ module Phronomy
       #   +:knowledge_sources+ (Array) — dynamic knowledge sources for this turn
       #   +:user_id+    (+String+, optional) — caller identity forwarded to the tracer
       #   +:session_id+ (+String+, optional) — session identity forwarded to the tracer
+      # @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 as backward-compat
+      #   aliases).  The object is also stored in +config[:invocation_context]+ so that
+      #   +task_id+ / +parent_task_id+ appear in trace spans automatically.
       # @return [Hash] +{ output: String, messages: Array, usage: Phronomy::TokenUsage }+,
       #   or +{ output: nil, suspended: true, checkpoint: Phronomy::Agent::Checkpoint,
       #   messages: Array }+ when the invocation was suspended awaiting tool approval.
@@ -505,29 +506,49 @@ module Phronomy
       #     result = agent.resume(result[:checkpoint], approved: true)
       #   end
       #   puts result[:output]
+      # @example With InvocationContext (deadline-based timeout)
+      #   ctx = Phronomy::InvocationContext.new(
+      #     thread_id: "conv-123",
+      #     deadline: Phronomy::Deadline.in(30),
+      #     task_id: SecureRandom.uuid
+      #   )
+      #   result = MyAgent.new.invoke("Hello", invocation_context: ctx)
       # @api public
-      def invoke(input, messages: [], thread_id: nil, config: {})
+      def invoke(input, messages: [], thread_id: nil, config: {}, invocation_context: nil)
+        if invocation_context
+          thread_id, config = _apply_invocation_context(thread_id, config, invocation_context)
+        end
         if Phronomy.configuration.event_loop
           # Protect against blocking the EventLoop thread itself.
-          if Thread.current[:phronomy_event_loop_thread]
+          if Phronomy::EventLoop.current?
             raise Phronomy::Error,
               "Cannot call Agent#invoke (EventLoop mode) from within an EventLoop " \
               "entry action. Use agent.run_as_child(input, ctx: ctx) instead."
           end
 
+          # Build an effective config that includes the invoke_timeout scope's
+          # CancellationToken before constructing the FSM.  This ensures that
+          # every LLM, tool, and RAG call made inside _invoke_impl observes
+          # cancellation when the deadline fires.
+          timeout_sec = self.class.invoke_timeout
+          effective_config, scope = if timeout_sec
+            s = Phronomy::CancellationScope.new(parent_token: config[:cancellation_token])
+            s.deadline_in(timeout_sec)
+            [config.merge(cancellation_token: s.token), s]
+          else
+            [config, nil]
+          end
+
           fsm = Agent::FSM.new(
             agent: self,
             input: input,
             messages: messages,
             thread_id: thread_id || SecureRandom.uuid,
-            config: config
+            config: effective_config
           )
           completion_queue = Phronomy::EventLoop.instance.register(fsm)
-          timeout_sec = self.class.invoke_timeout
-          result = if timeout_sec
-            begin
-              Timeout.timeout(timeout_sec) { completion_queue.pop }
-            rescue Timeout::Error
+          result = if scope
+            scope.pop_queue(completion_queue) do
               raise Phronomy::TimeoutError,
                 "Agent #{self.class.name} invoke timed out after #{timeout_sec}s"
             end
@@ -537,13 +558,60 @@ module Phronomy
           raise result if result.is_a?(Exception)
           result
         else
-          _invoke_impl(input, messages: messages, thread_id: thread_id, config: config)
+          # Guard: calling invoke from inside a scheduler task would block the task
+          # against itself when using a cooperative backend.  Use invoke_async
+          # instead to compose agents without introducing a blocking wait.
+          if Phronomy::Task.current
+            msg = "#{self.class.name}#invoke called from inside a scheduler task. " \
+              "This blocks the scheduler until the inner invocation completes, preventing " \
+              "other tasks from making progress. Use invoke_async + await instead."
+            if Phronomy.configuration.strict_runtime_guards
+              raise Phronomy::SchedulerReentrancyError, msg
+            elsif Phronomy.configuration.logger
+              Phronomy.configuration.logger.warn(msg)
+            else
+              Kernel.warn("[phronomy] WARNING: #{msg}")
+            end
+          end
+          invoke_async(input, messages: messages, thread_id: thread_id, config: config).await
+        end
+      end
+
+      # Invokes this agent asynchronously and returns a {Phronomy::Task}.
+      #
+      # This is the primary async entry point.  {#invoke} is a synchronous wrapper
+      # that calls this method and blocks the caller until the task completes.
+      # Calling {#invoke} from inside an active scheduler task raises
+      # {Phronomy::SchedulerReentrancyError}; use +invoke_async+ directly in that
+      # context.
+      #
+      # The task is registered with the Runtime task registry so {Runtime#shutdown}
+      # drains in-flight invocations before process exit.
+      #
+      # @example
+      #   task = agent.invoke_async("Hello!")
+      #   result = task.await   # => { output: "...", messages: [...], usage: ... }
+      #
+      # @param input    [String, Hash]
+      # @param messages [Array]
+      # @param thread_id [String, nil]
+      # @param config   [Hash]
+      # @param invocation_context [Phronomy::InvocationContext, nil]
+      # @return [Phronomy::Task]
+      # @api public
+      def invoke_async(input, messages: [], thread_id: nil, config: {}, invocation_context: nil)
+        if invocation_context
+          thread_id, config = _apply_invocation_context(thread_id, config, invocation_context)
+        end
+        bp = Phronomy.configuration.backpressure
+        on_full = (bp == :raise) ? :reject : (bp || :wait)
+        bp_timeout = Phronomy.configuration.backpressure_timeout
+        gate = Phronomy::Runtime.instance.gate(:agent)
+        Phronomy::Runtime.instance.spawn(name: "agent-#{(self.class.name || "anonymous").downcase}-async") do
+          gate.acquire(on_full: on_full, timeout: bp_timeout) do
+            _invoke_impl(input, messages: messages, thread_id: thread_id, config: config)
+          end
         end
-      ensure
-        # Remove this agent's context cache entry from the current thread to
-        # prevent unbounded growth of the thread-local hash in long-lived
-        # processes (e.g. Rails servers).
-        Thread.current[:phronomy_context_version_caches]&.delete(object_id)
       end
 
       # Registers this agent as a child {AgentFSM} inside the given Workflow context.
@@ -557,31 +625,24 @@ module Phronomy
       # result hash +{ output:, messages:, usage: }+.  Declare an +on: :child_completed+
       # transition in your Workflow to advance to the next state.
       #
-      # An optional block may be provided to write the result back into the parent
-      # WorkflowContext <b>before</b> the +:child_completed+ event is dispatched.
-      # +Thread::Queue+ provides the happens-before guarantee \u2014 no Mutex is needed.
+      # The result is delivered exclusively as the +:child_completed+ event payload.
+      # The parent Workflow task is the sole owner of the parent +WorkflowContext+ and
+      # applies the result after receiving the event — no background thread writes to
+      # the parent context directly.
       #
-      # @example Without block (result available only as event payload)
+      # @example
       #   entry :run_agent, ->(ctx) { MyAgent.new.run_as_child(ctx.query, ctx: ctx) }
       #   transition from: :run_agent, on: :child_completed, to: :process_result
       #
-      # @example With block (writes result into context)
-      #   entry :run_agent, ->(ctx) {
-      #     MyAgent.new.run_as_child(ctx.query, ctx: ctx) { |r| ctx.answer = r[:output] }
-      #   }
-      #   transition from: :run_agent, on: :child_completed, to: :process_result
-      #
       # @param input     [String, Hash]  user input passed to the agent
       # @param ctx       [Object]        a WorkflowContext that responds to +#thread_id+
       # @param messages  [Array]         prior conversation history
       # @param config    [Hash]          invocation config (forwarded to +_invoke_impl+)
-      # @yield [Hash]  result hash +{ output:, messages:, usage: }+ — called from the
-      #                agent IO thread before +:child_completed+ is posted
       # @return [nil]  the caller must not wait on any return value;
       #                the result arrives as a +:child_completed+ event
       # @raise [Phronomy::Error] when EventLoop mode is not enabled
       # @api public
-      def run_as_child(input, ctx:, messages: [], config: {}, &result_writer)
+      def run_as_child(input, ctx:, messages: [], config: {})
         unless Phronomy.configuration.event_loop
           raise Phronomy::Error,
             "run_as_child requires EventLoop mode. " \
@@ -594,8 +655,7 @@ module Phronomy
           messages: messages,
           thread_id: "#{ctx.thread_id}_agent_#{SecureRandom.uuid}",
           config: config,
-          parent_id: ctx.thread_id,
-          result_writer: result_writer
+          parent_id: ctx.thread_id
         )
         Phronomy::EventLoop.instance.enqueue_child(fsm)
         nil
@@ -644,11 +704,33 @@ module Phronomy
 
       private
 
+      # Merges an {InvocationContext} into the +thread_id+ / +config+ pair.
+      # Returns +[effective_thread_id, effective_config]+.
+      #
+      # Precedence rules (existing explicit values always win):
+      # - +thread_id+ argument > +ic.thread_id+
+      # - +config[:cancellation_token]+ > +ic.cancellation_token+ > token derived from +ic.deadline+
+      # - +ic+ is stored in +config[:invocation_context]+ (overwriting any previous value)
+      def _apply_invocation_context(thread_id, config, ic)
+        effective_thread_id = thread_id || ic.thread_id
+        effective_config = config.merge(invocation_context: ic)
+        if effective_config[:cancellation_token].nil?
+          if (tok = ic.effective_timeout_token)
+            effective_config = effective_config.merge(cancellation_token: tok)
+          end
+        end
+        [effective_thread_id, effective_config]
+      end
+
       # Streaming implementation for #stream.
       def _stream_impl(input, messages: [], thread_id: nil, config: {}, &block)
         caller_meta = {}
         caller_meta[:user_id] = config[:user_id] if config[:user_id]
         caller_meta[:session_id] = config[:session_id] if config[:session_id]
+        if (ic = config[:invocation_context])
+          caller_meta[:task_id] = ic.task_id if ic.task_id
+          caller_meta[:parent_task_id] = ic.parent_task_id if ic.parent_task_id
+        end
 
         trace("agent.invoke", input: input, **caller_meta) do |_span|
           run_input_guardrails!(input)
@@ -679,11 +761,26 @@ module Phronomy
           # Run before_completion hooks (global → class → instance) before the LLM call.
           run_before_completion_hooks!(chat, config)
 
-          response = chat.ask(user_message) do |chunk|
+          # Route the LLM streaming call through the configured LLMAdapter.
+          # Chunks are pushed into a token queue by the pool worker thread and
+          # drained here (on the caller's side) so that the user block is never
+          # executed on a BlockingAdapterPool worker thread.
+          # The queue capacity is bounded by Configuration#stream_queue_max_size
+          # (nil = unbounded) to provide backpressure against a fast LLM producer.
+          adapter = Phronomy.configuration.llm_adapter
+          chunk_queue = Phronomy::AsyncQueue.new(max_size: Phronomy.configuration.stream_queue_max_size)
+          pending = adapter.stream_async(chat, user_message, config: config, enqueue_to: chunk_queue)
+
+          # Drain the chunk queue on this side (scheduler task / caller thread).
+          loop do
+            chunk = chunk_queue.pop
+            break if chunk.nil? # queue closed — LLM streaming complete
             block.call(StreamEvent.new(type: :token, payload: {content: chunk.content}))
             check_cancellation!(config, "invocation cancelled during streaming")
           end
 
+          response = pending.await
+
           output = response.content
           usage = Phronomy::TokenUsage.from_tokens(response.tokens)
 
@@ -715,10 +812,49 @@ module Phronomy
         assembler = Context::Assembler.new(budget: budget)
         assembler.add_instruction(system_text) if system_text
 
-        Array(config[:knowledge_sources]).each do |ks|
-          check_cancellation!(config, "invocation cancelled during RAG fetch")
-          ks.fetch(query: user_message, cancellation_token: config[:cancellation_token]).each do |chunk|
-            assembler.add_knowledge(chunk[:content], type: chunk[:type], source: chunk[:source])
+        sources = Array(config[:knowledge_sources])
+        unless sources.empty?
+          check_cancellation!(config, "invocation cancelled before RAG fetch")
+          # Determine TaskGroup failure policy: :skip (default) ignores per-source
+          # failures so the agent can still answer with partial context; :fail
+          # surfaces the first error immediately via :fail_fast.
+          failure_policy =
+            case config[:rag_failure_policy]
+            when :fail then :fail_fast
+            else :skip_failed
+            end
+
+          group = Phronomy::Runtime.instance.task_group(failure_policy: failure_policy)
+
+          bp = Phronomy.configuration.backpressure
+          rag_on_full = (bp == :raise) ? :reject : (bp || :wait)
+          rag_bp_timeout = Phronomy.configuration.backpressure_timeout
+
+          # Spawn all fetches concurrently. Results are returned in spawn order
+          # (i.e. registration order of knowledge sources) by TaskGroup#await_all.
+          sources.each do |ks|
+            group.spawn do
+              Phronomy::Runtime.instance.gate(:rag).acquire(on_full: rag_on_full, timeout: rag_bp_timeout) do
+                t0 = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+                result = ks.fetch_async(
+                  query: user_message,
+                  cancellation_token: config[:cancellation_token],
+                  timeout: config[:rag_timeout]
+                ).await
+                elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - t0
+                Phronomy.configuration.logger&.debug { "RAG fetch from #{ks.class.name} completed in #{(elapsed * 1000).round}ms" }
+                result
+              end
+            end
+          end
+
+          # await_all returns results in spawn order; nil entries indicate
+          # skipped failures when using :skip_failed.
+          per_source_chunks = group.await_all
+          per_source_chunks.each do |chunks|
+            Array(chunks).each do |chunk|
+              assembler.add_knowledge(chunk[:content], type: chunk[:type], source: chunk[:source])
+            end
           end
         end
 
@@ -774,6 +910,10 @@ module Phronomy
         caller_meta = {}
         caller_meta[:user_id] = config[:user_id] if config[:user_id]
         caller_meta[:session_id] = config[:session_id] if config[:session_id]
+        if (ic = config[:invocation_context])
+          caller_meta[:task_id] = ic.task_id if ic.task_id
+          caller_meta[:parent_task_id] = ic.parent_task_id if ic.parent_task_id
+        end
 
         trace("agent.invoke", input: input, **caller_meta) do |_span|
           # Run input guardrails before touching the LLM.
@@ -798,14 +938,17 @@ module Phronomy
           # Check for cancellation immediately before the LLM call.
           check_cancellation!(config, "invocation cancelled before LLM call")
 
-          # Forward the cancellation token to ParallelToolChat via a thread-local
-          # so that tool dispatch batches can observe cancellation without needing
-          # direct access to config.
-          prev_ct = Thread.current[:phronomy_cancellation_token]
-          Thread.current[:phronomy_cancellation_token] = config[:cancellation_token]
+          # Forward the cancellation token to ParallelToolChat explicitly
+          # via the chat instance so that tool dispatch batches can observe
+          # cancellation without needing Thread.current.
+          chat.cancellation_token = config[:cancellation_token] if chat.respond_to?(:cancellation_token=)
 
           begin
-            response = chat.ask(user_message)
+            # Route the LLM call through the configured LLMAdapter so that the
+            # blocking HTTP request runs inside BlockingAdapterPool and the
+            # adapter can be swapped without changing agent code.
+            adapter = Phronomy.configuration.llm_adapter
+            response = adapter.complete_async(chat, user_message, config: config).await
           rescue SuspendSignal => signal
             checkpoint = Checkpoint.new(
               thread_id: thread_id,
@@ -818,7 +961,8 @@ module Phronomy
             suspended_result = {output: nil, suspended: true, checkpoint: checkpoint, messages: chat.messages}
             next [suspended_result, nil]
           ensure
-            Thread.current[:phronomy_cancellation_token] = prev_ct
+            # Clear the chat's cancellation token reference after each LLM call.
+            chat.cancellation_token = nil if chat.respond_to?(:cancellation_token=)
           end
 
           output = response.content
@@ -890,9 +1034,7 @@ module Phronomy
           [instruction.to_s, *static_chunks.map { |c| c[:content] }].join("\0")
         )
 
-        agent_id = object_id
-        cache = (Thread.current[:phronomy_context_version_caches] ||= {})[agent_id] ||=
-          Context::ContextVersionCache.new
+        cache = (@context_version_cache ||= Context::ContextVersionCache.new)
         unless cache.valid?(fingerprint)
           parts = [instruction]
           static_chunks.each do |chunk|
@@ -902,22 +1044,19 @@ module Phronomy
         end
 
         # Persist a reference on the instance so that context_version_cache
-        # remains accessible after invoke's ensure block cleans up the
-        # thread-local entry.
+        # remains accessible after invoke completes.
         @last_context_version_cache = cache
 
         cache.system_text.empty? ? nil : cache.system_text
       end
 
-      # Load messages from a ConversationManager.
-      #
       # Returns the chat class to instantiate for this invocation.
-      # When the +:phronomy_agent_parallel_tools+ thread-local flag is set
-      # (i.e. inside an {AgentFSM} IO thread), returns {ParallelToolChat} so
-      # that concurrent tool dispatch is enabled.  Falls back to +nil+ otherwise,
-      # signalling {#build_chat} to use the standard +RubyLLM.chat+ factory.
+      # When EventLoop mode is enabled ({Phronomy.configuration.event_loop}),
+      # returns {ParallelToolChat} so that concurrent tool dispatch is enabled.
+      # Falls back to +nil+ otherwise, signalling {#build_chat} to use the
+      # standard +RubyLLM.chat+ factory.
       def build_chat_class
-        Thread.current[:phronomy_agent_parallel_tools] ? Agent::ParallelToolChat : nil
+        Phronomy.configuration.event_loop ? Agent::ParallelToolChat : nil
       end
 
       def build_chat
@@ -931,7 +1070,11 @@ module Phronomy
         end
         t = self.class.temperature
         parallel_class = build_chat_class
-        chat = parallel_class ? parallel_class.new(**opts) : RubyLLM.chat(**opts)
+        chat = if parallel_class
+          parallel_class.new(max_parallel_tools: self.class.max_parallel_tools, **opts)
+        else
+          RubyLLM.chat(**opts)
+        end
         chat.with_temperature(t) if t
         self.class.tools.each do |tool_class|
           chat.with_tool(prepare_tool_class(tool_class))
@@ -995,15 +1138,30 @@ module Phronomy
 
       # Builds the final tool class to register with the chat.
       #
-      # Two transformations are applied in order:
+      # When an already-instantiated tool object is passed (e.g. a
+      # {Phronomy::Tool::McpTool} returned by +McpTool.from_server+), it is
+      # returned as-is.  RubyLLM's +with_tool+ accepts both classes and
+      # instances, so no wrapping is needed.
+      #
+      # For tool classes, three transformations are applied in order:
       #   1. Alias override — when the Hash form of .tools maps this class to an
       #      explicit name, an anonymous subclass with that tool_name is returned.
-      #   2. Approval gate  — when the tool class has +requires_approval+ set AND
+      #   2. Scope policy   — when a scope is declared on the tool, the configured
+      #      {Phronomy::Tool::ScopePolicy} (or the default) is evaluated.
+      #      +:reject+ wraps the tool to return a denial message without executing.
+      #      +:approve+ behaves like requiring approval (same as step 3 when the
+      #      tool does not already have +requires_approval+).
+      #   3. Approval gate  — when the tool class has +requires_approval+ set AND
       #      an approval handler has been registered via #on_approval_required,
       #      the tool's #call method is wrapped: the handler is invoked with
       #      (tool_name, args) and, if it returns falsy, the tool returns a denial
       #      message instead of executing.
       def prepare_tool_class(tool_class)
+        # When an instantiated tool object is passed (e.g. McpTool.from_server
+        # returns an instance, not a class), skip class-level processing and
+        # return it directly. RubyLLM#with_tool handles both forms.
+        return tool_class unless tool_class.is_a?(Class)
+
         # Step 1: apply alias if needed.
         resolved = if (alias_name = self.class.tool_aliases[tool_class])
           parent_description = tool_class.description
@@ -1015,7 +1173,34 @@ module Phronomy
           tool_class
         end
 
-        # Step 2: wrap with approval gate when handler is registered.
+        # Step 2: evaluate scope policy.
+        scope = resolved.scope
+        if scope
+          policy = @scope_policy || Phronomy::Tool::ScopePolicy::DEFAULT
+          decision = policy.call(resolved, scope, self)
+          case decision
+          when :reject
+            effective_name = resolved.new.name
+            rejected_class = Class.new(resolved) do
+              tool_name effective_name
+              define_method(:call) do |_args|
+                "Tool execution denied: scope :#{scope} is not permitted."
+              end
+            end
+            return rejected_class
+          when :approve
+            # Treat as requires_approval unless the tool already has that flag.
+            unless resolved.requires_approval
+              effective_name = resolved.new.name
+              resolved = Class.new(resolved) do
+                tool_name effective_name
+                requires_approval true
+              end
+            end
+          end
+        end
+
+        # Step 3: wrap with approval gate when handler is registered.
         return resolved unless resolved.requires_approval && @approval_handler
 
         handler = @approval_handler

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

@@ -32,6 +32,21 @@ module Phronomy
           self
         end
 
+        # Registers a scope policy callable for this agent instance.
+        #
+        # The callable receives +(tool_class, scope, agent)+ and must return
+        # +:allow+, +:reject+, or +:approve+.
+        #
+        # @example Reject all write-scoped tools
+        #   agent.scope_policy = ->(_tc, scope, _agent) { scope == :write ? :reject : :allow }
+        #
+        # @param policy [#call]
+        # @return [void]
+        # @api public
+        def scope_policy=(policy)
+          @scope_policy = policy
+        end
+
         # Resumes a previously suspended invocation from a {Phronomy::Agent::Checkpoint}.
         #
         # This method reconstructs the conversation state captured at suspension