phronomy 0.14.0 → 0.15.0

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: phronomy
 version: !ruby/object:Gem::Version
-  version: 0.14.0
+  version: 0.15.0
 platform: ruby
 authors:
 - Raizo T.C.S
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-07-27 00:00:00.000000000 Z
+date: 2026-08-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ruby_llm
@@ -155,30 +155,37 @@ 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/decisions/011-delegate-transport-policy-to-adapters.md
 - docs/mcp-client.md
+- examples/workflows/agent_event_mapping.rb
+- examples/workflows/generic_task_event_mapping.rb
 - gemfiles/mcp_1_0.gemfile
 - lib/phronomy.rb
 - lib/phronomy/agent.rb
+- lib/phronomy/agent/agent_invocation.rb
+- lib/phronomy/agent/agent_invocation_registry.rb
+- lib/phronomy/agent/agent_invocation_session_builder.rb
+- lib/phronomy/agent/approval_evaluation_request.rb
+- lib/phronomy/agent/async_event_api.rb
 - lib/phronomy/agent/base.rb
 - lib/phronomy/agent/before_completion_context.rb
 - lib/phronomy/agent/concerns/before_completion.rb
 - lib/phronomy/agent/concerns/error_translation.rb
 - lib/phronomy/agent/concerns/filterable.rb
-- lib/phronomy/agent/concerns/retryable.rb
 - lib/phronomy/agent/context/capability/base.rb
-- lib/phronomy/agent/context/capability/scope_policy.rb
 - lib/phronomy/agent/context/instruction/prompt_template.rb
 - lib/phronomy/agent/context/knowledge/base.rb
 - lib/phronomy/agent/context/knowledge/entity_knowledge.rb
 - lib/phronomy/agent/context/knowledge/static_knowledge.rb
-- lib/phronomy/agent/invocation_context.rb
-- lib/phronomy/agent/invocation_session.rb
+- lib/phronomy/agent/llm_operation_result.rb
 - lib/phronomy/agent/phase_machine_builder.rb
 - lib/phronomy/agent/runner.rb
 - lib/phronomy/agent/shared_state.rb
-- lib/phronomy/agent/suspended_session_registry.rb
+- lib/phronomy/agent/tool_approval_request.rb
 - lib/phronomy/agent/tool_call_intercepted.rb
 - lib/phronomy/agent/tool_executor.rb
+- lib/phronomy/agent/tool_invocation.rb
+- lib/phronomy/agent/tool_invocation_session_builder.rb
 - lib/phronomy/configuration.rb
 - lib/phronomy/diagnostics.rb
 - lib/phronomy/engine/concurrency/async_queue.rb
@@ -225,6 +232,9 @@ files:
 - lib/phronomy/filter/base.rb
 - lib/phronomy/filter/prompt_injection_filter.rb
 - lib/phronomy/generator_verifier.rb
+- lib/phronomy/invalid_async_entry_action_error.rb
+- lib/phronomy/invalid_async_transition_action_error.rb
+- lib/phronomy/invalid_async_workflow_action_error.rb
 - lib/phronomy/invocation_context.rb
 - lib/phronomy/knowledge_source.rb
 - lib/phronomy/llm_adapter.rb
@@ -247,6 +257,7 @@ files:
 - lib/phronomy/runnable.rb
 - lib/phronomy/state_store/base.rb
 - lib/phronomy/state_store/in_memory.rb
+- lib/phronomy/stream_callback_error.rb
 - lib/phronomy/testing.rb
 - lib/phronomy/testing/fake_clock.rb
 - lib/phronomy/testing/fake_scheduler.rb

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

@@ -1,103 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  module Agent
-    module Concerns
-      # Adds configurable retry behaviour to an agent.
-      #
-      # Included in {Phronomy::Agent::Base}. The retry loop wraps the full
-      # #invoke_once call; {Phronomy::FilterBlockError} is never retried.
-      # @api private
-      module Retryable
-        def self.included(base)
-          base.extend(ClassMethods)
-        end
-
-        # Class-level DSL methods mixed into the including agent class.
-        module ClassMethods
-          # Configures a retry policy that wraps the full #invoke call.
-          # FilterBlockError is never retried regardless of this setting.
-          #
-          # @param times [Integer] maximum retry attempts (default: 0)
-          # @param wait  [Symbol, Numeric] :exponential, :linear, or a fixed Float
-          # @param base  [Float]  base wait time in seconds (default: 1.0)
-          #
-          # @example
-          #   class MyAgent < Phronomy::Agent::Base
-          #     retry_policy times: 2, wait: :exponential, base: 1.0
-          #   end
-          # @api private
-          def retry_policy(times: 0, wait: 0, base: 1.0)
-            @_retry_policy = {times: times, wait: wait, base: base}
-          end
-
-          # Returns the configured retry policy, or nil when none is set.
-          # @return [Hash, nil]
-          attr_reader :_retry_policy
-
-          # Injectable sleep callable for testing.
-          # In the EventLoop-driven invoke path, actual delay is handled by
-          # timer_queue (non-blocking); _sleep_proc is called only as an
-          # instrumentation hook.  The default is a no-op; tests override it
-          # with a spy lambda to record sleep durations.
-          # @return [#call]
-          # @api private
-          def _sleep_proc
-            @_sleep_proc || method(:sleep)
-          end
-
-          # Overrides the sleep callable used between retries.
-          # @param proc [#call]
-          attr_writer :_sleep_proc
-        end
-
-        private
-
-        # Retry loop for #invoke.
-        def _invoke_impl(input, messages: [], thread_id: nil, config: {})
-          # Fail fast when the token is already cancelled before any LLM call.
-          if (token = config[:cancellation_token]) && token.cancelled?
-            raise Phronomy::CancellationError, "invocation cancelled"
-          end
-
-          policy = self.class._retry_policy
-          attempt = 0
-          begin
-            _invoke_via_fsm(input, messages: messages, thread_id: thread_id, config: config)
-          rescue Phronomy::FilterBlockError
-            raise
-          rescue Phronomy::CancellationError
-            raise # Never retry after cancellation.
-          rescue
-            if policy && attempt < policy[:times]
-              wait = compute_agent_retry_wait(policy[:wait], policy[:base], attempt)
-              self.class._sleep_proc.call(wait) if wait > 0
-              attempt += 1
-              retry
-            end
-            translate_and_reraise!($!)
-          end
-        end
-
-        # Computes the agent-level retry wait duration.
-        # @param strategy [Symbol, Numeric]
-        # @param base     [Float]
-        # @param attempt  [Integer]
-        # @return [Float]
-        # @api private
-        def compute_agent_retry_wait(strategy, base, attempt)
-          case strategy
-          when :exponential
-            (2**attempt) * base
-          when :linear
-            (attempt + 1) * base
-          when Numeric
-            strategy.to_f
-          else
-            base.to_f
-          end
-        end
-      end
-    end
-  end
-end

data/lib/phronomy/agent/context/capability/scope_policy.rb

@@ -1,54 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  module Agent
-    module Context
-      module Capability
-        # 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
-  end
-end

data/lib/phronomy/agent/invocation_context.rb

@@ -1,171 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  module Agent
-    # Holds the mutable state for a single Agent#invoke execution.
-    #
-    # An InvocationContext is created at the start of each invoke call and
-    # passed through every FSM state as the context object. It plays the same
-    # role as WorkflowContext does for Workflow executions.
-    #
-    # Fields:
-    #   input                  — the (possibly filter-transformed) user input
-    #   messages               — conversation history (Array of RubyLLM::Message)
-    #   chat                   — the RubyLLM::Chat object built during :building_context
-    #   output                 — the final LLM text response
-    #   usage                  — Phronomy::TokenUsage after completion
-    #   tool_call_pending      — whether the last LLM response contained a tool call
-    #   approval_required      — whether the pending tool requires human approval
-    #   input_blocked          — whether an input filter called block!
-    #   output_blocked         — whether an output filter called block!
-    #   block_error            — the FilterBlockError raised (for :blocked terminal)
-    #   pending_tool_call      — the intercepted tool_call object (name/arguments/id)
-    #   user_message_sent      — true after the first LLM call (continuation uses nil msg)
-    #   sync_approval_handler  — true when agent has an on_approval_required block
-    #   session_id             — FSM session id (set by set_graph_metadata)
-    #   phase                  — terminal FSM phase (set by set_graph_metadata)
-    #
-    # @api private
-    class InvocationContext
-      # @return [String, Hash] user input (may be transformed by input filters)
-      attr_accessor :input
-
-      # @return [Array] conversation history
-      attr_accessor :messages
-
-      # @return [Object, nil] RubyLLM::Chat instance
-      attr_accessor :chat
-
-      # @return [String, nil] final LLM output text
-      attr_accessor :output
-
-      # @return [Phronomy::TokenUsage, nil]
-      attr_accessor :usage
-
-      # @return [Boolean] true when calling_llm returned a tool call
-      attr_accessor :tool_call_pending
-
-      # @return [Boolean] true when the pending tool requires human approval
-      attr_accessor :approval_required
-
-      # @return [Boolean] true when an input filter called block!
-      attr_accessor :input_blocked
-
-      # @return [Boolean] true when an output filter called block!
-      attr_accessor :output_blocked
-
-      # @return [Phronomy::FilterBlockError, nil]
-      attr_accessor :block_error
-
-      # @return [Object, nil] intercepted RubyLLM tool_call (name/arguments/id)
-      attr_accessor :pending_tool_call
-
-      # @return [Boolean] true after the first LLM call (continuation passes nil msg)
-      attr_accessor :user_message_sent
-
-      # @return [Boolean] true when Agent.approve was called (signals executing_tool
-      #   to execute the pending tool rather than re-suspending)
-      attr_accessor :approved
-
-      # @return [Boolean] true when the pending tool call was rejected via
-      #   Agent.approve(session_id, approved: false)
-      attr_accessor :rejected
-
-      # @return [String, nil] FSM session id (set by set_graph_metadata)
-      attr_reader :session_id
-
-      # @return [Symbol, nil] terminal FSM phase (set by set_graph_metadata)
-      attr_reader :phase
-
-      # @return [Boolean] true when agent has a synchronous on_approval_required handler
-      attr_reader :sync_approval_handler
-
-      # @return [Phronomy::Agent::Base] the agent instance driving this invocation
-      attr_reader :agent
-
-      # @return [Hash] the config hash passed to invoke
-      attr_reader :config
-
-      # @return [String, nil] thread_id from config
-      attr_reader :thread_id
-
-      # @param agent    [Phronomy::Agent::Base]
-      # @param input    [String, Hash]
-      # @param messages [Array]
-      # @param config   [Hash]
-      # @api private
-      def initialize(agent:, input:, messages:, config:)
-        @agent = agent
-        @input = input
-        @messages = Array(messages)
-        @config = config
-        @thread_id = config[:thread_id]
-        @chat = nil
-        @output = nil
-        @usage = nil
-        @tool_call_pending = false
-        @approval_required = false
-        @input_blocked = false
-        @output_blocked = false
-        @block_error = nil
-        @pending_tool_call = nil
-        @user_message_sent = false
-        @approved = false
-        @rejected = false
-        @sync_approval_handler = !agent.instance_variable_get(:@approval_handler).nil?
-        @session_id = nil
-        @phase = nil
-      end
-
-      # Called by FSMSession#finish! and FSMSession#halt! to record the
-      # terminal/halted phase and the session id.
-      # Mirrors the WorkflowContext interface so FSMSession works with both.
-      # @param thread_id [String, nil]
-      # @param phase     [Symbol, nil]
-      # @return [void]
-      # @api private
-      def set_graph_metadata(thread_id: nil, phase: nil)
-        @session_id = thread_id if thread_id
-        @phase = phase
-      end
-
-      # Guard helpers used by PhaseMachineBuilder transitions.
-
-      # @return [Boolean]
-      # @api private
-      def input_passed?
-        !@input_blocked
-      end
-
-      # @return [Boolean]
-      # @api private
-      def input_blocked?
-        @input_blocked
-      end
-
-      # @return [Boolean]
-      # @api private
-      def output_passed?
-        !@output_blocked
-      end
-
-      # @return [Boolean]
-      # @api private
-      def output_blocked?
-        @output_blocked
-      end
-
-      # @return [Boolean]
-      # @api private
-      def tool_call_pending?
-        @tool_call_pending
-      end
-
-      # @return [Boolean]
-      # @api private
-      def approval_required?
-        @approval_required
-      end
-    end
-  end
-end