phronomy 0.15.0 → 0.15.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b0ea2e317999f3202e06d5afac0b46509fa22a813531919447040d1e048a087f
-  data.tar.gz: ae5740df9899b7463b35b54b885948ca1e0e42e01b8b85b1a93fd6437022c90b
+  metadata.gz: 98b90b892fcd752aa84d1a00d033bb627df70d143145502f044e5288c7b124a4
+  data.tar.gz: c1e37fa68d782d5f506a83e019594e2f77efeb7d37e8f46c8b57286d8b8c9eaa
 SHA512:
-  metadata.gz: 123b0998a7a299f97ce981a3561c68990c41e05decb534b4c4664e441abd6cf368e04ecf6cea61df6a1ea2c4016850b093e0c208aa034fc02b1fa498e0078263
-  data.tar.gz: f1ba3ee6163b1a746bd99f00241daf286ac5eb3d8d1e30f7caa739de1de5dd900f3b19b90a063c4a9f19f494a1e9ac1dca59b4d32ade41deabe71f849803ac62
+  metadata.gz: e8a62f9eb2d0971a0faa91d822a9ecff39b495242514dd5144f442c8bcfba85edd84a3e22738df17447604f8c6201169df1f0b308035ad8a5e50603ad379da5b
+  data.tar.gz: bcb09d22cf850b447e49e13d022cf760c6b4628fe3df6ea744f91738e1085fea6218bee4ce96c4caf0b6f8a8c07f2900bc7f243ed374cc71c940869f64856ea1

data/CHANGELOG.md

@@ -9,6 +9,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Changed
+
+- Refactor: `Agent::AsyncEventApi` is now the single implementation of
+  `invoke`, `invoke_async`, `stream`, `stream_async`, and their session
+  lifecycle helpers (`_start_invocation`, `_handle_agent_completion`,
+  `_register_tool_invocation_session`, `_start_approval_resume`). The
+  duplicate definitions in `Agent::Base` have been removed. No public
+  behavior change is intended.
+- Remove `faraday` and `event_stream_parser` from gemspec declared
+  dependencies; both are transitive dependencies of `ruby_llm` and are
+  not used directly by phronomy.
+
 ### Added
 
 - `Workflow#signal(thread_id:, event:, payload:)` for FIFO delivery to a live

data/lib/phronomy/agent/async_event_api.rb

@@ -10,6 +10,22 @@ module Phronomy
     #
     # @api private
     module AsyncEventApi
+      # Invokes the agent synchronously and returns the terminal result.
+      #
+      # Provider errors are translated after the configured LLM adapter returns
+      # its final result. Phronomy does not replay the Agent invocation.
+      #
+      # @param input [String, Hash] user input for this invocation
+      # @param messages [Array<RubyLLM::Message>] conversation history
+      # @param thread_id [String, nil] conversation thread identifier
+      # @param config [Hash] additional runtime options
+      # @param invocation_context [Phronomy::InvocationContext, nil]
+      #   first-class invocation context
+      # @param on_event [Proc, nil] listener for lifecycle and Tool events
+      # @return [Hash] terminal invocation result
+      # @raise [Phronomy::SchedulerReentrancyError] when called from the
+      #   EventLoop thread or a guarded scheduler context
+      # @api public
       def invoke(
         input,
         messages: [],
@@ -43,6 +59,23 @@ module Phronomy
         end
       end
 
+      # Invokes the agent asynchronously.
+      #
+      # The returned Task settles after the terminal event listener returns.
+      # Lifecycle and Tool events are delivered from the Runtime-owned
+      # EventLoop thread.
+      #
+      # @param input [String, Hash] user input for this invocation
+      # @param messages [Array<RubyLLM::Message>] conversation history
+      # @param thread_id [String, nil] conversation thread identifier
+      # @param config [Hash] additional runtime options
+      # @param invocation_context [Phronomy::InvocationContext, nil]
+      #   first-class invocation context
+      # @param on_tool_approval_required [Proc, nil] per-invocation approval
+      #   notification listener
+      # @param on_event [Proc, nil] listener for lifecycle and Tool events
+      # @return [Phronomy::Task] Task resolving to the terminal result
+      # @api public
       def invoke_async(
         input,
         messages: [],
@@ -80,6 +113,26 @@ module Phronomy
         result_task
       end
 
+      # Invokes the agent asynchronously and emits streaming events.
+      #
+      # Accepts either +on_event:+ or a block. Supplying both is rejected.
+      # Token events are emitted only by streaming invocations; lifecycle and
+      # Tool events use the same contract as {#invoke_async}.
+      #
+      # @param input [String, Hash] user input for this invocation
+      # @param messages [Array<RubyLLM::Message>] conversation history
+      # @param thread_id [String, nil] conversation thread identifier
+      # @param config [Hash] additional runtime options
+      # @param invocation_context [Phronomy::InvocationContext, nil]
+      #   first-class invocation context
+      # @param on_tool_approval_required [Proc, nil] per-invocation approval
+      #   notification listener
+      # @param on_event [Proc, nil] event listener
+      # @yieldparam event [Phronomy::Agent::StreamEvent]
+      # @return [Phronomy::Task] Task resolving to the terminal result
+      # @raise [ArgumentError] when no listener is supplied or both listener
+      #   forms are supplied
+      # @api public
       def stream_async(
         input,
         messages: [],
@@ -125,6 +178,28 @@ module Phronomy
         result_task
       end
 
+      # Invokes the agent synchronously and emits streaming events.
+      #
+      # Accepts either +on_event:+ or a block. Event callbacks run on the
+      # Runtime-owned EventLoop thread; the calling thread waits for the final
+      # Task result.
+      #
+      # @param input [String, Hash] user input for this invocation
+      # @param messages [Array<RubyLLM::Message>] conversation history
+      # @param thread_id [String, nil] conversation thread identifier
+      # @param config [Hash] additional runtime options
+      # @param invocation_context [Phronomy::InvocationContext, nil]
+      #   first-class invocation context
+      # @param on_tool_approval_required [Proc, nil] per-invocation approval
+      #   notification listener
+      # @param on_event [Proc, nil] event listener
+      # @yieldparam event [Phronomy::Agent::StreamEvent]
+      # @return [Hash] terminal invocation result
+      # @raise [ArgumentError] when no listener is supplied or both listener
+      #   forms are supplied
+      # @raise [Phronomy::SchedulerReentrancyError] when called from the
+      #   EventLoop thread or a guarded scheduler context
+      # @api public
       def stream(
         input,
         messages: [],
@@ -182,6 +257,7 @@ module Phronomy
       # Cancellation is checked by the first Agent entry action on the EventLoop
       # thread so even pre-cancelled invocations produce a terminal event before
       # the returned Task settles.
+      # @api private
       def _start_invocation(
         result_task,
         input,
@@ -396,6 +472,12 @@ module Phronomy
         event_loop.register(session, completion: completion)
       end
 
+      # Resumes a suspended AgentInvocation and its pending Tool sessions.
+      #
+      # Parent completion handling is installed before EventLoop registration,
+      # and the parent session is registered before child sessions so immediate
+      # child events cannot be lost.
+      # @api private
       def _start_approval_resume(
         result_task,
         invocation,

data/lib/phronomy/agent/base.rb

@@ -386,166 +386,6 @@ module Phronomy
         self
       end
 
-      # Invokes the agent with the given input and returns a result Hash.
-      # Provider errors are translated after the configured LLM adapter returns
-      # its final result. Phronomy does not replay the Agent invocation.
-      #
-      # @param input     [String, Hash] the user message; a Hash may supply
-      #   +:message+, +:query+, or +:user+ as the text key, plus any template
-      #   variables consumed by the configured instructions template.
-      # @param messages  [Array<RubyLLM::Message>] conversation history from a
-      #   previous invocation. The application owns and persists this array;
-      #   pass it on every turn to maintain multi-turn context.
-      # @param thread_id [String, nil] conversation thread identifier, forwarded
-      #   to the compaction context when on_compact is configured.
-      # @param config    [Hash] additional runtime options:
-      #   +: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.
-      # @raise [Phronomy::FilterBlockError] when an input or output filter rejects the value
-      # @example Normal invocation
-      #   result = MyAgent.new.invoke("What is Ruby?")
-      #   puts result[:output]
-      # @example Multi-turn conversation
-      #   result1 = agent.invoke("Hi, I'm Alice.")
-      #   result2 = agent.invoke("What's my name?", messages: result1[:messages])
-      # @example Suspend / resume flow
-      #   result = agent.invoke("Perform task X")
-      #   if result[:suspended]
-      #     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::Concurrency::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: {}, invocation_context: nil)
-        if invocation_context
-          thread_id, config = _apply_invocation_context(thread_id, config, invocation_context)
-        end
-        _check_scheduler_reentrancy(:invoke, :invoke_async)
-
-        trace("agent.invoke", input: input, **_build_caller_meta(config)) do |_span|
-          result = invoke_async(
-            input,
-            messages: messages,
-            thread_id: thread_id,
-            config: config
-          ).wait_result
-          [result, result[:usage]]
-        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.wait_result   # => { 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, on_tool_approval_required: nil)
-        if invocation_context
-          thread_id, config = _apply_invocation_context(thread_id, config, invocation_context)
-        end
-        result_task = Phronomy::Task.deferred(name: "agent-#{(self.class.name || "anonymous").downcase}-async")
-        approval_snapshot = _approval_configuration_snapshot(on_tool_approval_required)
-        _start_invocation(
-          result_task, input,
-          messages: messages, thread_id: thread_id, config: config,
-          approval_snapshot: approval_snapshot
-        )
-        result_task
-      end
-
-      # Invokes this agent asynchronously and delivers stream events from the
-      # Runtime-owned EventLoop thread.
-      #
-      # The callback must return quickly. Blocking I/O, synchronous Agent calls,
-      # sleep, and heavy CPU work must be delegated by the Application.
-      #
-      # @return [Phronomy::Task] final invocation result
-      # @api public
-      def stream_async(input, messages: [], thread_id: nil, config: {},
-        invocation_context: nil, on_tool_approval_required: nil, &block)
-        raise ArgumentError, "stream_async requires a block" unless block
-
-        if invocation_context
-          thread_id, config = _apply_invocation_context(thread_id, config, invocation_context)
-        end
-
-        result_task = Phronomy::Task.deferred(
-          name: "agent-#{(self.class.name || "anonymous").downcase}-stream-async"
-        )
-        approval_snapshot = _approval_configuration_snapshot(on_tool_approval_required)
-        _start_invocation(
-          result_task,
-          input,
-          messages: messages,
-          thread_id: thread_id,
-          config: config,
-          approval_snapshot: approval_snapshot,
-          mode: :stream,
-          on_event: block
-        )
-        result_task
-      end
-
-      # Synchronous wrapper around {#stream_async}.
-      #
-      # Stream callbacks execute on the EventLoop thread, not on the thread that
-      # calls this method. This method only blocks while waiting for the final Task.
-      # @yield [Phronomy::Agent::StreamEvent]
-      # @return [Hash] same result shape as #invoke
-      # @api public
-      def stream(input, messages: [], thread_id: nil, config: {},
-        invocation_context: nil, on_tool_approval_required: nil, &block)
-        raise ArgumentError, "stream requires a block" unless block
-
-        if invocation_context
-          thread_id, config = _apply_invocation_context(thread_id, config, invocation_context)
-        end
-        _check_scheduler_reentrancy(:stream, :stream_async)
-
-        trace("agent.stream", input: input, **_build_caller_meta(config)) do |_span|
-          result = stream_async(
-            input,
-            messages: messages,
-            thread_id: thread_id,
-            config: config,
-            on_tool_approval_required: on_tool_approval_required,
-            &block
-          ).wait_result
-          [result, result[:usage]]
-        end
-      end
-
       # @deprecated The context version cache has been removed. Returns nil.
       #   Retained for backward compatibility with callers using safe navigation (+&.reset+).
       # @api private
@@ -761,50 +601,6 @@ module Phronomy
       end
       protected :instance_knowledge_chunks
 
-      # Starts one AgentInvocation and resolves +result_task+ from that session.
-      # Phronomy translates the adapter's final error but never starts another
-      # AgentInvocation automatically.
-      # @api private
-      def _start_invocation(result_task, input, messages:, thread_id:, config:,
-        approval_snapshot:, mode: :invoke, on_event: nil)
-        effective_config = thread_id ? config.merge(thread_id: thread_id) : config
-        check_cancellation!(effective_config, "invocation cancelled")
-        runtime = Phronomy::Runtime.instance
-        event_loop = runtime.event_loop
-        session = Agent::AgentInvocationSessionBuilder.build(
-          agent: self,
-          input: input,
-          messages: messages,
-          config: effective_config,
-          approval_policy: approval_snapshot[:policy],
-          approval_listener: approval_snapshot[:listener],
-          mode: mode,
-          on_event: on_event,
-          runtime: runtime
-        )
-        callback_error_policy =
-          Phronomy.configuration.stream_callback_error_policy
-        source_task = Phronomy::Task.deferred(name: "#{result_task.name}-source")
-        source_task.on_complete do |invocation, error|
-          _handle_agent_completion(
-            result_task: result_task,
-            invocation: invocation,
-            error: error,
-            mode: mode,
-            listener: on_event,
-            event_loop: event_loop,
-            callback_error_policy: callback_error_policy
-          )
-        end
-
-        # Register completion handling before EventLoop admission. Otherwise an
-        # immediately finishing session can complete source_task before the
-        # callback is installed, causing Task#on_complete to run on this thread.
-        event_loop.register(session, completion: source_task)
-      rescue => e
-        _fail_result_task(result_task, e)
-      end
-
       def _complete_result_task(task, result)
         task.backend.unblock(result, nil)
         task.transition!(:completed, value: result)
@@ -821,83 +617,6 @@ module Phronomy
         translated
       end
 
-      # Completes one Agent execution interval. Execution failures and
-      # Application callback failures are deliberately handled in separate
-      # exception domains.
-      def _handle_agent_completion(result_task:, invocation:, error:, mode:, listener:,
-        event_loop:, callback_error_policy:)
-        if mode == :stream && !event_loop.current?
-          completion_error = error || Phronomy::Error.new(
-            "Stream completion occurred outside the EventLoop"
-          )
-          _fail_result_task(result_task, _translated_error(completion_error))
-          return
-        end
-
-        result = nil
-        execution_error = nil
-        begin
-          raise error if error
-
-          result = _extract_invoke_result(invocation)
-        rescue => e
-          execution_error = _translated_error(e)
-        end
-
-        if execution_error
-          if mode == :stream
-            event = StreamEvent.new(
-              type: :error,
-              payload: {error: execution_error}
-            )
-            callback_error = _deliver_stream_event(listener, event)
-            if callback_error
-              _report_stream_callback_error(
-                callback_error,
-                event: event,
-                invocation_id: invocation&.id,
-                callback_error_policy: callback_error_policy
-              )
-            end
-          end
-
-          # An Application failure while consuming :error never replaces the
-          # original Agent/LLM/Tool/Runtime failure.
-          _fail_result_task(result_task, execution_error)
-          return
-        end
-
-        unless mode == :stream
-          _complete_result_task(result_task, result)
-          return
-        end
-
-        event = _build_stream_terminal_event(result)
-        callback_error = _deliver_stream_event(listener, event)
-        unless callback_error
-          _complete_result_task(result_task, result)
-          return
-        end
-
-        _report_stream_callback_error(
-          callback_error,
-          event: event,
-          invocation_id: invocation&.id,
-          callback_error_policy: callback_error_policy
-        )
-
-        if callback_error_policy == :fail_task
-          wrapped = _build_stream_callback_error(
-            event_type: event.type,
-            callback_error: callback_error,
-            result: result
-          )
-          _fail_result_task(result_task, wrapped)
-        else
-          _complete_result_task(result_task, result)
-        end
-      end
-
       def _build_stream_terminal_event(result)
         if result[:suspended]
           StreamEvent.new(
@@ -1026,64 +745,6 @@ module Phronomy
       end
       public :approve_async
 
-      # Parent completion handling is installed before EventLoop registration,
-      # and the parent session is registered before child sessions so immediate
-      # child events cannot be lost.
-      # @api private
-      def _start_approval_resume(result_task, invocation, approved:, config:)
-        invocation.merge_config!(config)
-        invocation.begin_approval_resume!(approved: approved)
-        runtime = Phronomy::Runtime.instance
-        event_loop = runtime.event_loop
-        source_task = Phronomy::Task.deferred(
-          name: "#{result_task.name}-source"
-        )
-        parent_session = Agent::AgentInvocationSessionBuilder.build_for_resume(
-          agent_invocation: invocation,
-          resume_event: :resume,
-          resume_phase: :suspended,
-          runtime: runtime
-        )
-        stream_listener = invocation.stream_listener
-        mode = stream_listener ? :stream : :invoke
-        callback_error_policy =
-          Phronomy.configuration.stream_callback_error_policy
-
-        source_task.on_complete do |completed_invocation, error|
-          _handle_agent_completion(
-            result_task: result_task,
-            invocation: completed_invocation,
-            error: error,
-            mode: mode,
-            listener: stream_listener,
-            event_loop: event_loop,
-            callback_error_policy: callback_error_policy
-          )
-        end
-
-        # The parent must exist before any child can post an immediate result.
-        event_loop.register(parent_session, completion: source_task)
-
-        invocation.tool_invocations.each do |child|
-          child_session = if child.awaiting_approval?
-            Agent::ToolInvocationSessionBuilder.build_for_resume(
-              tool_invocation: child,
-              resume_event: approved ? :approve : :reject,
-              resume_phase: :awaiting_approval,
-              runtime: runtime
-            )
-          elsif !approved && child.authorized?
-            Agent::ToolInvocationSessionBuilder.build_for_resume(
-              tool_invocation: child,
-              resume_event: :cancel,
-              resume_phase: :authorized,
-              runtime: runtime
-            )
-          end
-          _register_tool_invocation_session(event_loop, runtime, child, child_session) if child_session
-        end
-      end
-
       def _extract_invoke_result(invocation)
         if invocation.phase == :suspended
           request = invocation.approval_request
@@ -1106,23 +767,6 @@ module Phronomy
         end
       end
 
-      def _register_tool_invocation_session(event_loop, runtime, child, session)
-        completion = Phronomy::Task.deferred(name: "tool-session:#{child.id}")
-        completion.on_complete do |_result, error|
-          next unless error
-
-          child.mark_framework_failed!(error)
-          runtime.event_loop.post(
-            Phronomy::Event.new(
-              type: :tool_failed,
-              target_id: child.parent_agent_invocation_id,
-              payload: {tool_invocation_id: child.id}
-            )
-          )
-        end
-        event_loop.register(session, completion: completion)
-      end
-
       def _dispatch_tool_approval_notification(invocation, request)
         listener = invocation.approval_listener
         return unless listener

data/lib/phronomy/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: phronomy
 version: !ruby/object:Gem::Version
-  version: 0.15.0
+  version: 0.15.1
 platform: ruby
 authors:
 - Raizo T.C.S
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-08-02 00:00:00.000000000 Z
+date: 2026-08-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ruby_llm
@@ -78,46 +78,6 @@ dependencies:
     - - "~>"
       - !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.