phronomy 0.15.1 → 0.17.0

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: phronomy
 version: !ruby/object:Gem::Version
-  version: 0.15.1
+  version: 0.17.0
 platform: ruby
 authors:
 - Raizo T.C.S
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-08-03 00:00:00.000000000 Z
+date: 2026-08-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ruby_llm
@@ -16,7 +16,7 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '1.3'
+        version: '1.15'
     - - "<"
       - !ruby/object:Gem::Version
         version: '2'
@@ -26,7 +26,7 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: '1.3'
+        version: '1.15'
     - - "<"
       - !ruby/object:Gem::Version
         version: '2'
@@ -116,37 +116,72 @@ files:
 - 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/decisions/012-canonical-execution-log-and-context-policy.md
+- docs/decisions/013-journal-backed-knowledge-as-context-candidates.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/activation_registry.rb
+- lib/phronomy/agent/agent_execution.rb
+- lib/phronomy/agent/agent_execution_activation.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/agent_root.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/before_llm_input.rb
 - lib/phronomy/agent/concerns/error_translation.rb
 - lib/phronomy/agent/concerns/filterable.rb
 - lib/phronomy/agent/context/capability/base.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/context_assembler.rb
+- lib/phronomy/agent/context_candidate.rb
+- lib/phronomy/agent/context_candidate_resolver.rb
+- lib/phronomy/agent/context_importer.rb
+- lib/phronomy/agent/context_parts/budget/token_budget_packer.rb
+- lib/phronomy/agent/context_parts/requirements/required_context_resolver.rb
+- lib/phronomy/agent/context_parts/selectors/recent_first_selector.rb
+- lib/phronomy/agent/context_parts/unit_builders/dependency_aware_unit_builder.rb
+- lib/phronomy/agent/context_parts/validators/final_budget_validator.rb
+- lib/phronomy/agent/context_plan.rb
+- lib/phronomy/agent/context_plan_validator.rb
+- lib/phronomy/agent/context_policies/default.rb
+- lib/phronomy/agent/context_policy.rb
+- lib/phronomy/agent/context_policy_descriptor.rb
+- lib/phronomy/agent/context_policy_registry.rb
+- lib/phronomy/agent/context_request.rb
+- lib/phronomy/agent/context_selection_unit.rb
+- lib/phronomy/agent/derived_content_spec.rb
+- lib/phronomy/agent/execution_coordinator.rb
+- lib/phronomy/agent/immutable.rb
+- lib/phronomy/agent/journal_projection.rb
+- lib/phronomy/agent/journal_record.rb
+- lib/phronomy/agent/llm_call_record.rb
+- lib/phronomy/agent/llm_input_build_context.rb
+- lib/phronomy/agent/llm_input_manifest.rb
+- lib/phronomy/agent/llm_input_patch.rb
 - lib/phronomy/agent/llm_operation_result.rb
 - lib/phronomy/agent/phase_machine_builder.rb
+- lib/phronomy/agent/provider_call_outcome.rb
+- lib/phronomy/agent/ruby_llm_materializer.rb
 - lib/phronomy/agent/runner.rb
 - lib/phronomy/agent/shared_state.rb
+- lib/phronomy/agent/token_budget_resolver.rb
 - lib/phronomy/agent/tool_approval_request.rb
 - lib/phronomy/agent/tool_call_intercepted.rb
+- lib/phronomy/agent/tool_definition_set.rb
 - lib/phronomy/agent/tool_executor.rb
 - lib/phronomy/agent/tool_invocation.rb
 - lib/phronomy/agent/tool_invocation_session_builder.rb
+- lib/phronomy/agent_busy_error.rb
+- lib/phronomy/canonical_json.rb
 - lib/phronomy/configuration.rb
+- lib/phronomy/content_store/base.rb
+- lib/phronomy/context_budget_exceeded_error.rb
 - lib/phronomy/diagnostics.rb
 - lib/phronomy/engine/concurrency/async_queue.rb
 - lib/phronomy/engine/concurrency/blocking_adapter_pool.rb
@@ -188,6 +223,7 @@ files:
 - lib/phronomy/eval/scorer/includes_scorer.rb
 - lib/phronomy/eval/scorer/llm_judge.rb
 - lib/phronomy/event.rb
+- lib/phronomy/execution_rehydration_required_error.rb
 - lib/phronomy/filter.rb
 - lib/phronomy/filter/base.rb
 - lib/phronomy/filter/prompt_injection_filter.rb
@@ -195,13 +231,11 @@ files:
 - 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/invalid_context_budget_configuration_error.rb
 - lib/phronomy/invocation_context.rb
-- lib/phronomy/knowledge_source.rb
 - lib/phronomy/llm_adapter.rb
 - lib/phronomy/llm_adapter/base.rb
 - lib/phronomy/llm_adapter/ruby_llm.rb
-- lib/phronomy/llm_context_window/assembler.rb
-- lib/phronomy/llm_context_window/context_version_cache.rb
 - lib/phronomy/llm_context_window/token_budget.rb
 - lib/phronomy/llm_context_window/token_estimator.rb
 - lib/phronomy/metrics.rb
@@ -213,6 +247,8 @@ files:
 - lib/phronomy/output_parser/base.rb
 - lib/phronomy/output_parser/json_parser.rb
 - lib/phronomy/output_parser/structured_parser.rb
+- lib/phronomy/persistence.rb
+- lib/phronomy/persistence/in_memory.rb
 - lib/phronomy/ruby_llm_patches.rb
 - lib/phronomy/runnable.rb
 - lib/phronomy/state_store/base.rb
@@ -251,11 +287,16 @@ files:
 - lib/phronomy/workflow/phase_machine_builder.rb
 - lib/phronomy/workflow_context.rb
 - lib/phronomy/workflow_runner.rb
+- scripts/add_to_h_to_token_doubles.rb
+- scripts/add_to_h_unnamed_doubles.rb
 - scripts/api_snapshot.rb
 - scripts/check_api_annotations.rb
 - scripts/check_private_enforcement.rb
 - scripts/check_readme_ruby.rb
 - scripts/check_readme_runnable.rb
+- scripts/migrate_spec_agent_definition.rb
+- scripts/migrate_spec_agent_definition_pass2.rb
+- scripts/migrate_spec_inline_pass3.rb
 - scripts/run_mutation.sh
 - sig/phronomy.rbs
 homepage: https://github.com/Raizo-TCS/phronomy

data/lib/phronomy/agent/agent_invocation_registry.rb

@@ -1,75 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  module Agent
-    # In-process registry for suspended AgentInvocation aggregates.
-    #
-    # The registry is the single in-process source for pending Human approval.
-    # Cross-process persistence remains outside the scope of this implementation.
-    #
-    # @api private
-    module AgentInvocationRegistry
-      Entry = Struct.new(:invocation, :approval_request)
-
-      @entries = {}
-      @approval_index = {}
-      @mutex = Mutex.new
-
-      def self.store_suspended(invocation, approval_request)
-        @mutex.synchronize do
-          invocation_id = invocation.id
-          request_id = approval_request.id
-          if @entries.key?(invocation_id) || @approval_index.key?(request_id)
-            raise Phronomy::Error,
-              "Suspended AgentInvocation is already registered: #{invocation_id}"
-          end
-
-          @entries[invocation_id] = Entry.new(
-            invocation: invocation,
-            approval_request: approval_request
-          )
-          @approval_index[request_id] = invocation_id
-        end
-        approval_request
-      end
-
-      # Atomically removes and returns one pending approval aggregate.
-      # Duplicate approval commands therefore cannot execute the Tool twice.
-      def self.consume_approval(agent_invocation_id, approval_request_id)
-        @mutex.synchronize do
-          indexed_invocation_id = @approval_index[approval_request_id.to_s]
-          return nil unless indexed_invocation_id == agent_invocation_id.to_s
-
-          entry = @entries.delete(indexed_invocation_id)
-          return nil unless entry
-
-          @approval_index.delete(entry.approval_request.id)
-          entry
-        end
-      end
-
-      def self.lookup(agent_invocation_id)
-        @mutex.synchronize { @entries[agent_invocation_id.to_s] }
-      end
-
-      def self.exists?(agent_invocation_id)
-        @mutex.synchronize { @entries.key?(agent_invocation_id.to_s) }
-      end
-
-      def self.remove_terminal(agent_invocation_id)
-        @mutex.synchronize do
-          entry = @entries.delete(agent_invocation_id.to_s)
-          @approval_index.delete(entry.approval_request.id) if entry
-          entry
-        end
-      end
-
-      def self.clear!
-        @mutex.synchronize do
-          @entries.clear
-          @approval_index.clear
-        end
-      end
-    end
-  end
-end

data/lib/phronomy/agent/before_completion_context.rb

@@ -1,47 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  module Agent
-    # Passed to every before_completion hook callable.
-    # Provides read access to the agent, assembled messages, and invocation config.
-    # Hooks may inspect these and return a Hash of params to merge into the LLM request.
-    #
-    # @example Reading context inside a hook
-    #   Phronomy.configure do |cfg|
-    #     cfg.before_completion = lambda do |ctx|
-    #       Rails.logger.info "LLM request: model=#{ctx.params[:model]}"
-    #       { temperature: 0.2 }
-    #     end
-    #   end
-    class BeforeCompletionContext
-      # The agent instance making the LLM call.
-      # @return [Phronomy::Agent::Base]
-      attr_reader :agent
-
-      # Messages currently assembled for this invocation (read-only snapshot).
-      # @return [Array]
-      attr_reader :messages
-
-      # Runtime config hash passed to invoke/stream (e.g. thread_id, memory).
-      # @return [Hash]
-      attr_reader :config
-
-      # Current LLM params being built (model, temperature, etc.).
-      # Read-only; return a Hash from the hook to merge overrides.
-      # @return [Hash]
-      attr_reader :params
-
-      # @param agent    [Phronomy::Agent::Base]
-      # @param messages [Array]
-      # @param config   [Hash]
-      # @param params   [Hash] initial params (model, temperature already set on chat)
-      # @api public
-      def initialize(agent:, messages:, config:, params: {})
-        @agent = agent
-        @messages = messages.dup.freeze
-        @config = config
-        @params = params.dup.freeze
-      end
-    end
-  end
-end

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

@@ -1,111 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  module Agent
-    module Concerns
-      # Adds before_completion hook support to an agent.
-      #
-      # Included in {Phronomy::Agent::Base}. Hooks are executed just before every
-      # LLM call (global → class → instance order) and may inject or override
-      # LLM parameters such as temperature or model.
-      # @api private
-      module BeforeCompletion
-        def self.included(base)
-          base.extend(ClassMethods)
-        end
-
-        # Class-level DSL methods mixed into the including agent class.
-        module ClassMethods
-          # Sets or reads the class-level before_completion hook.
-          # The hook is called before every LLM request for instances of this class.
-          # Receives a {Phronomy::Agent::BeforeCompletionContext}; must return a Hash
-          # of params to merge into the LLM call, or nil to pass through unchanged.
-          #
-          # @param callable [#call, nil] lambda/proc to register, or nil to clear
-          # @return [#call, nil]
-          # @example
-          #   class MyAgent < Phronomy::Agent::Base
-          #     before_completion ->(ctx) { { temperature: 0.2 } }
-          #   end
-          # @api private
-          def before_completion(callable = nil)
-            if callable.nil? && !block_given?
-              @before_completion
-            else
-              @before_completion = callable
-            end
-          end
-
-          # @return [#call, nil]
-          # @api private
-          def _before_completion
-            @before_completion
-          end
-        end
-
-        # Instance-level before_completion hook. When set, takes precedence over
-        # the class-level hook for this specific agent instance only.
-        # @return [#call, nil]
-        attr_accessor :before_completion
-
-        private
-
-        # Collects and runs all registered before_completion hooks in order
-        # (global → class → instance) and applies the merged params to the chat.
-        #
-        # @param chat   [RubyLLM::Chat] the assembled chat object
-        # @param config [Hash] the invocation config hash
-        # @return [Hash] the merged params applied to the chat
-        # @api private
-        def run_before_completion_hooks!(chat, config)
-          hooks = [
-            Phronomy.configuration.before_completion,
-            self.class._before_completion,
-            @before_completion
-          ].compact
-
-          return {} if hooks.empty?
-
-          ctx = BeforeCompletionContext.new(
-            agent: self,
-            messages: chat.messages,
-            config: config,
-            params: {}
-          )
-
-          merged = {}
-          hooks.each do |hook|
-            result = hook.call(ctx)
-            check_cancellation!(config, "invocation cancelled during before_completion hook")
-            merged.merge!(result) if result.is_a?(Hash)
-          end
-
-          apply_before_completion_params!(chat, merged)
-          merged
-        end
-
-        # Applies a merged param hash returned by before_completion hooks to
-        # the chat object using the appropriate RubyLLM::Chat API methods.
-        # When overriding the model, reuses the agent's configured provider and
-        # assume_exists setting so that local/namespaced models continue to work.
-        #
-        # @param chat   [RubyLLM::Chat]
-        # @param params [Hash]
-        # @api private
-        def apply_before_completion_params!(chat, params)
-          params.each do |key, value|
-            case key
-            when :model
-              prov = self.class.provider
-              chat.with_model(value, provider: prov, assume_exists: !prov.nil?)
-            when :temperature
-              chat.with_temperature(value)
-            else
-              chat.with_params(key => value)
-            end
-          end
-        end
-      end
-    end
-  end
-end

data/lib/phronomy/agent/context/knowledge/base.rb

@@ -1,58 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  module Agent
-    module Context
-      module Knowledge
-        # Abstract base class for all KnowledgeSource implementations.
-        #
-        # Subclasses must implement #fetch(query:) and return an Array of chunk Hashes.
-        # Each chunk Hash must contain:
-        #   :content [String]  the text to inject into the context
-        #   :type    [Symbol]  semantic tag (e.g. :static, :rag, :entity)
-        class Base
-          # Retrieve knowledge chunks relevant to the given query.
-          #
-          # @param query              [String, nil]                    the current user input used to select relevant chunks
-          # @param cancellation_token [Phronomy::Concurrency::CancellationToken, nil] optional token; raises CancellationError when cancelled
-          # @return [Array<Hash>] array of { content: String, type: Symbol }
-          # @api public
-          def fetch(query: nil, cancellation_token: nil)
-            cancellation_token&.raise_if_cancelled!
-            raise NotImplementedError, "#{self.class}#fetch is not implemented"
-          end
-
-          # Submits a {#fetch} call to {BlockingAdapterPool} and returns a
-          # {BlockingAdapterPool::PendingOperation}.
-          # Callers can fan out multiple fetches in parallel and await them all.
-          #
-          # @param query              [String, nil]
-          # @param cancellation_token [Phronomy::Concurrency::CancellationToken, nil]
-          # @param timeout            [Numeric, nil] seconds before the operation is abandoned
-          # @return [BlockingAdapterPool::PendingOperation]
-          # @api public
-          def fetch_async(query: nil, cancellation_token: nil, timeout: nil)
-            Phronomy::Runtime.instance.blocking_io.submit(
-              timeout: timeout,
-              cancellation_token: cancellation_token
-            ) do
-              fetch(query: query, cancellation_token: cancellation_token)
-            end
-          end
-
-          # Returns true when this source's content is considered static (i.e. does
-          # not change between agent invocations). Static sources are eligible for
-          # fingerprint-based caching in ContextVersionCache.
-          #
-          # Override in subclasses that return fixed content.
-          #
-          # @return [Boolean]
-          # @api public
-          def static?
-            false
-          end
-        end
-      end
-    end
-  end
-end

data/lib/phronomy/agent/context/knowledge/entity_knowledge.rb

@@ -1,102 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  module Agent
-    module Context
-      module Knowledge
-        # A KnowledgeSource that extracts named-entity facts from conversation history.
-        #
-        # This is the knowledge-injection counterpart of the old EntityMemory.
-        # It scans saved user messages with a regex heuristic (no LLM call) and
-        # returns the discovered facts as a single knowledge chunk tagged :entity.
-        #
-        # EntityKnowledge is stateful: it accumulates extracted facts via #update(messages:)
-        # which should be called each time new messages are saved.
-        #
-        # Supported extraction patterns (case-insensitive):
-        #   "my name is Alice"          → { name: "Alice" }
-        #   "I am Alice"                → { identity: "Alice" }
-        #   "I'm a software engineer"   → { occupation: "software engineer" }
-        #   "I work at / for Acme"      → { workplace: "Acme" }
-        #   "I live in Tokyo"           → { location: "Tokyo" }
-        #   "I'm from Tokyo"            → { location: "Tokyo" }
-        #   "I like / love Ruby"        → { preference: "Ruby" }
-        #
-        # @example
-        #   ks = Phronomy::Agent::Context::Knowledge::EntityKnowledge.new
-        #   ks.update(messages: chat_messages)
-        #   agent = MyAgent.new
-        #   agent.add_knowledge_source(ks)
-        #   agent.invoke("What is my name?")
-        class EntityKnowledge < Base
-          PATTERNS = [
-            [:name, /\bmy name is\s+([A-Za-z][A-Za-z0-9 \-']*)/i],
-            [:identity, /\bI\s+am\s+([A-Z][A-Za-z0-9 \-']+)/],
-            [:occupation, /\bI(?:'m| am) a(?:n)?\s+([A-Za-z][A-Za-z0-9 \-']*)/i],
-            [:workplace, /\bI (?:work|worked) (?:at|for|in)\s+([A-Za-z0-9][A-Za-z0-9 \-'.&,]*)/i],
-            [:location, /\bI live in\s+([A-Za-z][A-Za-z0-9 \-']*)/i],
-            [:location, /\bI(?:'m| am) from\s+([A-Za-z][A-Za-z0-9 \-']*)/i],
-            [:preference, /\bI (?:like|love|enjoy)\s+([A-Za-z][A-Za-z0-9 \-']*)/i]
-          ].freeze
-
-          def initialize
-            @entities = {}
-          end
-
-          # Scan messages and accumulate entity facts.
-          # Call this after saving a new set of messages (e.g. from a ConversationManager save hook).
-          #
-          # @param messages [Array] message objects responding to #role and #content
-          # @api public
-          def update(messages:)
-            messages.each do |msg|
-              next unless msg.role.to_sym == :user
-
-              extract(msg.content.to_s).each { |key, value| @entities[key] = value }
-            end
-          end
-
-          # Returns a single chunk containing all known entity facts in XML context format.
-          # Returns an empty array when no entities have been discovered.
-          #
-          # @param query              [String, nil]                    unused — entity knowledge is always fully injected
-          # @param cancellation_token [Phronomy::Concurrency::CancellationToken, nil] optional; raises CancellationError when cancelled
-          # @return [Array<Hash>]
-          # @api public
-          def fetch(query: nil, cancellation_token: nil)
-            cancellation_token&.raise_if_cancelled!
-            return [] if @entities.empty?
-
-            lines = @entities.map { |key, value| "- #{key}: #{value}" }.join("\n")
-            content = <<~CONTENT.chomp
-              Known facts about the user:
-              #{lines}
-            CONTENT
-            [{content: content, type: :entity}]
-          end
-
-          # Returns the current entity store (primarily for testing).
-          #
-          # @return [Hash]
-          # @api public
-          def entities
-            @entities.dup
-          end
-
-          private
-
-          def extract(text)
-            found = {}
-            PATTERNS.each do |key, pattern|
-              if (match = text.match(pattern))
-                value = match[1].strip.sub(/[.!?]\s+.*$/, "").gsub(/[.,;!?]+$/, "")
-                found[key] = value unless value.empty?
-              end
-            end
-            found
-          end
-        end
-      end
-    end
-  end
-end

data/lib/phronomy/agent/context/knowledge/static_knowledge.rb

@@ -1,58 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  module Agent
-    module Context
-      module Knowledge
-        # A KnowledgeSource backed by fixed text provided at construction time.
-        #
-        # Useful for injecting static documents, policy files, or configuration
-        # knowledge that does not change per request.
-        #
-        # @example
-        #   ks = Phronomy::Agent::Context::Knowledge::StaticKnowledge.new(
-        #     "Our refund policy: ...",
-        #     type: :policy
-        #   )
-        #   agent = MyAgent.new
-        #   agent.add_knowledge_source(ks)
-        #   agent.invoke("What is the refund policy?")
-        class StaticKnowledge < Base
-          # @param text   [String] the static knowledge text to inject
-          # @param type   [Symbol] semantic tag for the chunk (default :static)
-          # @param source [String, nil] label identifying where this knowledge came from
-          #   (e.g. a filename). Included in the context XML tag and exposed to the LLM
-          #   so that agents can produce grounded citations.
-          # @api public
-          def initialize(text, type: :static, source: nil)
-            @text = text.to_s
-            @type = type
-            @source = source
-          end
-
-          # Returns the fixed text as a single chunk, regardless of query.
-          #
-          # @param query              [String, nil]                    ignored for static knowledge
-          # @param cancellation_token [Phronomy::Concurrency::CancellationToken, nil] optional; raises CancellationError when cancelled
-          # @return [Array<Hash>]
-          # @api public
-          def fetch(query: nil, cancellation_token: nil)
-            cancellation_token&.raise_if_cancelled!
-            return [] if @text.empty?
-
-            chunk = {content: @text, type: @type}
-            chunk[:source] = @source if @source
-            [chunk]
-          end
-
-          # Static knowledge content never changes between invocations.
-          # @return [true]
-          # @api public
-          def static?
-            true
-          end
-        end
-      end
-    end
-  end
-end

data/lib/phronomy/knowledge_source.rb

@@ -1,12 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  # KnowledgeSource provides the interface for supplying context region 3 (Knowledge)
-  # to the Context::Assembler.
-  #
-  # Each implementation returns an array of knowledge chunks via #fetch(query:).
-  # Each chunk is a Hash with :content (String) and :type (Symbol) keys.
-  # The Assembler wraps each chunk in an XML context tag before injecting it.
-  module KnowledgeSource
-  end
-end