phronomy 0.15.0 → 0.16.0

data/scripts/migrate_spec_agent_definition.rb

@@ -0,0 +1,108 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Migrates spec files to add agent_definition to Agent::Base subclasses.
+# - Named classes: inserts after the class declaration line
+# - Anonymous blocks (do...end): inserts after the opening `do`
+# - Inline anonymous ({ ... }): expands to multi-line with agent_definition
+# Safe: skips classes that already have agent_definition
+
+require "fileutils"
+
+SPEC_DIR = File.expand_path("../spec", __dir__)
+AGENT_BASE_PATTERN = /Phronomy::Agent::Base/
+
+def snake_case(class_name)
+  # Remove trailing Agent/Tool suffixes, snake_case the name
+  name = class_name.split("::").last
+  name.gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+    .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+    .downcase
+end
+
+counter = 0
+files_modified = 0
+
+Dir.glob("#{SPEC_DIR}/**/*.rb").sort.each do |file|
+  lines = File.readlines(file, chomp: false)
+  new_lines = []
+  modified = false
+  i = 0
+
+  while i < lines.length
+    line = lines[i]
+
+    # ── Named class: class FooAgent < Phronomy::Agent::Base ──────────────────
+    if line =~ /^(\s*)class\s+(\w+)\s*<\s*(?:::)?Phronomy::Agent::Base\s*$/
+      indent = $1
+      class_name = $2
+      id = snake_case(class_name).sub(/_agent$/, "-agent").tr("_", "-")
+      id = "#{id}-agent" unless id.end_with?("-agent")
+      new_lines << line
+      i += 1
+      # Check if agent_definition already present in the class body
+      look_ahead = lines[i..]&.take(10) || []
+      unless look_ahead.any? { |l| l =~ /agent_definition/ }
+        new_lines << "#{indent}  agent_definition id: #{id.inspect}, version: 1\n"
+        counter += 1
+        modified = true
+      end
+      next
+    end
+
+    # ── Anonymous block (do...end): Class.new(Phronomy::Agent::Base) do ─────
+    if line =~ /^(\s*)([\w.]*\s*=\s*)?Class\.new\((?:::)?Phronomy::Agent::Base\)\s+do\s*(\|\w+\|)?\s*$/
+      indent = $1
+      # Check if agent_definition already present
+      look_ahead = lines[i + 1..]&.take(10) || []
+      new_lines << line
+      i += 1
+      unless look_ahead.any? { |l| l =~ /agent_definition/ }
+        # Derive indentation from the `do` block body (first non-blank line)
+        inner = lines[i..]&.take(5)&.find { |l| l.strip.length > 0 } || ""
+        inner_indent = inner.match(/^(\s*)/)[1]
+        inner_indent = "#{indent}  " if inner_indent.strip.length > 0 && inner_indent.length < indent.length + 2
+        new_lines << "#{inner_indent}agent_definition id: \"test-agent-#{counter += 1}\", version: 1\n"
+        modified = true
+      end
+      next
+    end
+
+    # ── Inline anonymous: Class.new(Phronomy::Agent::Base) { ... } ───────────
+    if line =~ /^(\s*)((?:[\w.]*\s*=\s*)?)Class\.new\((?:::)?Phronomy::Agent::Base\)\s*\{(.+)\}\s*$/
+      indent = $1
+      assignment = $2
+      body = $3
+      # Skip if agent_definition already present
+      if /agent_definition/.match?(body)
+        new_lines << line
+      else
+        id = counter += 1
+        definition_line = "agent_definition id: \"test-agent-#{id}\", version: 1;"
+        new_lines << "#{indent}#{assignment}Class.new(Phronomy::Agent::Base) do\n"
+        new_lines << "#{indent}  #{definition_line}\n"
+        # Rewrite the original body lines, stripping leading spaces
+        body.strip.split(";").each do |stmt|
+          stmt = stmt.strip
+          next if stmt.empty?
+          new_lines << "#{indent}  #{stmt}\n"
+        end
+        new_lines << "#{indent}end\n"
+        modified = true
+      end
+      i += 1
+      next
+    end
+
+    new_lines << line
+    i += 1
+  end
+
+  if modified
+    File.write(file, new_lines.join)
+    files_modified += 1
+    puts "  patched: #{file.sub("#{SPEC_DIR}/", "spec/")}"
+  end
+end
+
+puts "\nDone: #{counter} agent_definition insertions in #{files_modified} files."

data/scripts/migrate_spec_agent_definition_pass2.rb

@@ -0,0 +1,53 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Second pass: handles patterns missed by the first script
+#   - Class.new(Phronomy::Agent::Base) { ... }.new  (inline + .new suffix)
+#   - Class.new(Phronomy::Agent::Base).new           (no block + .new)
+#   - { Class.new(Phronomy::Agent::Base) }           (no block, inside outer { })
+
+require "fileutils"
+
+SPEC_DIR = File.expand_path("../spec", __dir__)
+counter = 200
+
+files_modified = 0
+
+Dir.glob("#{SPEC_DIR}/**/*.rb").sort.each do |file|
+  content = File.read(file)
+  new_content = content.dup
+
+  # Pattern A: Class.new(Phronomy::Agent::Base) { body }.new
+  new_content = new_content.gsub(
+    /Class\.new\(Phronomy::Agent::Base\) \{([^}]*)\}\.new/
+  ) do
+    body = $1
+    next $& if body.include?("agent_definition")
+    counter += 1
+    "Class.new(Phronomy::Agent::Base) { agent_definition id: \"test-agent-#{counter}\", version: 1;#{body}}.new"
+  end
+
+  # Pattern B: Class.new(Phronomy::Agent::Base).new  (no block, chained .new)
+  new_content = new_content.gsub(
+    /Class\.new\(Phronomy::Agent::Base\)\.new\b/
+  ) do
+    counter += 1
+    "Class.new(Phronomy::Agent::Base) { agent_definition id: \"test-agent-#{counter}\", version: 1 }.new"
+  end
+
+  # Pattern C: { Class.new(Phronomy::Agent::Base) }  (no block, inside outer block)
+  new_content = new_content.gsub(
+    "{ Class.new(Phronomy::Agent::Base) }"
+  ) do
+    counter += 1
+    "{ Class.new(Phronomy::Agent::Base) { agent_definition id: \"test-agent-#{counter}\", version: 1 } }"
+  end
+
+  if new_content != content
+    File.write(file, new_content)
+    files_modified += 1
+    puts "  patched: #{file.sub("#{SPEC_DIR}/", "spec/")}"
+  end
+end
+
+puts "\nSecond pass done: #{files_modified} files modified."

data/scripts/migrate_spec_inline_pass3.rb

@@ -0,0 +1,24 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Adds agent_definition to single-line inline anonymous blocks like:
+# Class.new(Phronomy::Agent::Base) { model "test-model" }
+
+counter = 300
+files = Dir.glob("spec/**/*.rb").sort
+
+files.each do |f|
+  content = File.read(f)
+  modified = content.gsub(
+    /Class\.new\(Phronomy::Agent::Base\) \{ ([^{}]+) \}/
+  ) do
+    body = $1
+    next $& if body.include?("agent_definition")
+    counter += 1
+    "Class.new(Phronomy::Agent::Base) { agent_definition id: \"test-agent-#{counter}\", version: 1; #{body} }"
+  end
+  if modified != content
+    File.write(f, modified)
+    puts "  patched: #{f}"
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: phronomy
 version: !ruby/object:Gem::Version
-  version: 0.15.0
+  version: 0.16.0
 platform: ruby
 authors:
 - Raizo T.C.S
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-08-02 00:00:00.000000000 Z
+date: 2026-08-08 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'
@@ -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.
@@ -156,20 +116,23 @@ 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/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
@@ -177,16 +140,51 @@ files:
 - 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/fsm_runtime_adapter.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
@@ -228,6 +226,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
@@ -235,6 +234,7 @@ 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
@@ -253,6 +253,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
@@ -291,11 +293,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