phronomy 0.15.1 → 0.17.0

data/lib/phronomy/multi_agent/team_coordinator.rb

@@ -1,96 +1,37 @@
 # frozen_string_literal: true
 
+require "securerandom"
+
 module Phronomy
   module MultiAgent
-    # Implements the "Agent teams" coordination pattern (Anthropic blog, Pattern 3).
-    #
-    # @see https://claude.com/blog/multi-agent-coordination-patterns
-    #
-    # A coordinator LLM agent decomposes work into tasks and enqueues them
-    # dynamically via built-in tools. A fixed set of worker agents processes tasks
-    # sequentially — one task per worker per turn — carrying forward their
-    # conversation history across assignments to accumulate domain context over time.
-    #
-    # Workers are selected in sequence (the worker with the fewest accumulated
-    # messages is chosen by default). Task dispatch is synchronous; there is no
-    # concurrent or parallel execution.
-    #
-    # The coordinator is an {Agent::Base} subclass that has two built-in tools:
-    # - +enqueue_task+ — adds a task description to the queue
-    # - +finalize+     — signals that all tasks have been enqueued
-    #
-    # Worker persistence is implemented by passing each worker's accumulated
-    # +messages+ array back as a top-level +messages:+ argument on every subsequent
-    # +invoke+ call, so the LLM retains context across multiple task assignments.
-    #
-    # @example Basic usage
-    #   class MigrationTeam < Phronomy::MultiAgent::TeamCoordinator
-    #     coordinator_model        "claude-3-5-sonnet-20241022"
-    #     coordinator_instructions <<~INST
-    #       Analyze the request and enqueue one migration task per service.
-    #       Call enqueue_task for each service, then call finalize.
-    #     INST
-    #
-    #     pool size: 3, agent: MigrationAgent
-    #
-    #     aggregate do |assignments|
-    #       { reports: assignments.map { |a| { task: a[:task][:description], result: a[:result] } } }
-    #     end
-    #   end
-    #
-    #   result = MigrationTeam.new.invoke("Migrate all services to Rails 8")
+    # Coordinator/worker multi-agent pattern with persistent worker Agent state.
     class TeamCoordinator
-      # Holds per-worker context between task invocations.
-      # Worker persistence is implemented by carrying +messages+ forward on each
-      # successive +agent#invoke+ call as the top-level +messages:+ argument..
       WorkerState = Struct.new(
-        :index,    # Integer — 0-based worker index
-        :agent,    # Agent::Base instance
-        :messages, # Array  — accumulated conversation history
-        :status    # Symbol — :idle | :available | :done
+        :index,
+        :agent,
+        :transcript_size,
+        :status
       ) do
-        # Returns true when this worker is ready to accept the next task.
-        def available? = [:idle, :available].include?(status)
+        def available? = %i[idle available].include?(status)
       end
       private_constant :WorkerState
 
       class << self
-        # Sets the LLM model for the coordinator agent.
-        # Falls back to +Phronomy.configuration.default_model+ when not set.
-        #
-        # @param value [String, nil]
         # @api public
         def coordinator_model(value = nil)
           value ? @coordinator_model = value : @coordinator_model
         end
 
-        # Sets the system instructions for the coordinator agent.
-        # The prompt should direct the LLM to call +enqueue_task+ for each task
-        # and then call +finalize+ when all tasks are enqueued.
-        #
-        # @param value [String, nil]
         # @api public
         def coordinator_instructions(value = nil)
           value ? @coordinator_instructions = value : @coordinator_instructions
         end
 
-        # Sets the LLM provider for the coordinator agent.
-        # Required when using a custom +BASE_URL+ (e.g. LM Studio, Ollama, vLLM)
-        # so that RubyLLM does not attempt to resolve an unknown model name.
-        # Pass the same value as +LLMConfig::PROVIDER+ in your examples.
-        #
-        # @param value [Symbol, nil]
         # @api public
         def coordinator_provider(value = nil)
           value ? @coordinator_provider = value : @coordinator_provider
         end
 
-        # Configures the set of workers.
-        #
-        # @param size     [Integer] number of persistent worker instances (tasks are assigned sequentially)
-        # @param agent    [Class]   Agent::Base subclass used for all workers
-        # @param on_error [Symbol]  +:raise+ (default) propagates worker exceptions;
-        #                           +:skip+ records the failure and continues with remaining tasks
         # @api public
         def pool(size:, agent:, on_error: :raise)
           @pool_size = Integer(size)
@@ -98,57 +39,31 @@ module Phronomy
           @on_error = on_error
         end
 
-        # Customises the worker selection algorithm.
-        # The block receives an Array of available WorkerState objects and must
-        # return the one to assign the next task to.
-        # Default: worker with the fewest accumulated messages (round-robin-like).
-        #
-        # @yield [Array<WorkerState>] available workers
-        # @yieldreturn [WorkerState] the chosen worker
         # @api public
         def schedule(&block)
           @scheduler = block
         end
 
-        # Defines how task assignments are merged into the final return value.
-        # The block receives an Array of assignment Hashes:
-        #   { task: Hash, result: String|nil, worker: Integer, error: Exception|nil }
-        # When omitted, the raw assignments array is returned.
-        #
-        # @yield [Array<Hash>] all completed (and skipped) task assignments
         # @api public
         def aggregate(&block)
           @aggregator = block
         end
 
-        # @!visibility private
         def _coordinator_model = @coordinator_model
-        # @!visibility private
         def _coordinator_instructions = @coordinator_instructions
-        # @!visibility private
         def _coordinator_provider = @coordinator_provider
-        # @!visibility private
         def _pool_size = @pool_size || 1
-        # @!visibility private
         def _worker_agent = @worker_agent
-        # @!visibility private
         def _on_error = @on_error || :raise
-        # @!visibility private
         def _scheduler = @scheduler
-        # @!visibility private
         def _aggregator = @aggregator
       end
 
-      # Runs the full team coordination: coordinator generates tasks, workers
-      # process them sequentially, and the aggregate block merges the results.
-      #
-      # @param team_input [String, Hash] the high-level objective given to the coordinator
-      # @param config     [Hash]         reserved for future use
-      # @return [Object] the return value of the aggregate block, or the raw assignments Array
-      # @raise [ArgumentError] when +pool :agent+ has not been configured
       # @api public
       def invoke(team_input, config: {})
-        raise ArgumentError, "pool :agent must be configured before invoking" unless self.class._worker_agent
+        unless self.class._worker_agent
+          raise ArgumentError, "pool :agent must be configured before invoking"
+        end
 
         task_queue = []
         run_coordinator(team_input, task_queue)
@@ -156,26 +71,13 @@ module Phronomy
         finalize_result(assignments)
       end
 
-      # Streaming version of +invoke+. Yields a Hash event for each completed or
-      # failed task assignment.
-      #
-      # Yielded Hash keys:
-      #   :type   — +:task_completed+ or +:task_failed+
-      #   :worker — worker index (Integer)
-      #   :task   — the task Hash from the queue ({ id:, description:, metadata:, enqueued_at: })
-      #   :result — output string, or +nil+ on failure
-      #   :error  — Exception, or +nil+ on success
-      #
-      # @param team_input [String, Hash]
-      # @param config     [Hash]
-      # @yield [Hash] one event per completed/failed task
-      # @return [Object] same as +invoke+
-      # @raise [ArgumentError] when +pool :agent+ has not been configured
       # @api public
       def stream(team_input, config: {}, &block)
         return invoke(team_input, config: config) unless block
 
-        raise ArgumentError, "pool :agent must be configured before invoking" unless self.class._worker_agent
+        unless self.class._worker_agent
+          raise ArgumentError, "pool :agent must be configured before invoking"
+        end
 
         task_queue = []
         run_coordinator(team_input, task_queue)
@@ -185,23 +87,25 @@ module Phronomy
 
       private
 
-      # Phase 1: Run the coordinator LLM agent to populate task_queue.
       def run_coordinator(team_input, task_queue)
         coordinator = build_coordinator_agent(task_queue)
         input = team_input.is_a?(String) ? team_input : team_input.to_s
         coordinator.invoke(input)
       end
 
-      # Phase 2: Process tasks from the queue using the worker pool.
-      # Workers accumulate message history across assignments.
       def run_workers(task_queue, &event_block)
         pool_size = self.class._pool_size
         agent_class = self.class._worker_agent
         on_error = self.class._on_error
         scheduler = self.class._scheduler
 
-        workers = Array.new(pool_size) do |i|
-          WorkerState.new(index: i, agent: agent_class.new, messages: [], status: :idle)
+        workers = Array.new(pool_size) do |index|
+          WorkerState.new(
+            index: index,
+            agent: agent_class.new,
+            transcript_size: 0,
+            status: :idle
+          )
         end
 
         assignments = []
@@ -212,39 +116,45 @@ module Phronomy
           worker = scheduler ? scheduler.call(available) : default_scheduler(available)
 
           begin
-            result = worker.agent.invoke(task[:description], messages: worker.messages)
-            worker.messages = result[:messages]
+            result = worker.agent.invoke(task[:description])
+            worker.transcript_size = worker.agent.transcript.length
             worker.status = :available
-            entry = {task: task, result: result[:output], worker: worker.index, error: nil}
+            entry = {
+              task: task,
+              result: result[:output],
+              worker: worker.index,
+              error: nil
+            }
             assignments << entry
             event_block&.call(entry.merge(type: :task_completed))
-          rescue => e
+          rescue => error
             worker.status = :available
             raise unless on_error == :skip
 
-            entry = {task: task, result: nil, worker: worker.index, error: e}
+            entry = {
+              task: task,
+              result: nil,
+              worker: worker.index,
+              error: error
+            }
             assignments << entry
             event_block&.call(entry.merge(type: :task_failed))
           end
         end
 
-        workers.each { |w| w.status = :done }
+        workers.each { |worker| worker.status = :done }
         assignments
       end
 
-      # Phase 3: Apply the aggregate block (or return raw assignments).
       def finalize_result(assignments)
         aggregator = self.class._aggregator
         aggregator ? aggregator.call(assignments) : assignments
       end
 
-      # Default scheduler: assign to the worker with the fewest accumulated
-      # messages (promotes round-robin-like distribution across the pool).
       def default_scheduler(available_workers)
-        available_workers.min_by { |w| w.messages.size }
+        available_workers.min_by(&:transcript_size)
       end
 
-      # Build an anonymous coordinator Agent::Base with the two built-in tools.
       def build_coordinator_agent(task_queue)
         coordinator_model_val = self.class._coordinator_model
         coordinator_instructions_val = self.class._coordinator_instructions
@@ -253,16 +163,16 @@ module Phronomy
         finalize_tool = build_finalize_tool(task_queue)
 
         coordinator_class = Class.new(Phronomy::Agent::Base) do
+          agent_definition id: "team-coordinator-#{SecureRandom.hex(4)}", version: 1
           model coordinator_model_val
           provider coordinator_provider_val if coordinator_provider_val
           instructions coordinator_instructions_val
-          tools enqueue_tool, finalize_tool
+          tools(enqueue_tool => nil, finalize_tool => nil)
         end
 
         coordinator_class.new
       end
 
-      # Builds the +enqueue_task+ tool. Each call appends a task Hash to task_queue.
       def build_enqueue_tool(task_queue)
         Class.new(Phronomy::Agent::Context::Capability::Base) do
           tool_name "enqueue_task"
@@ -271,15 +181,18 @@ module Phronomy
           param :metadata, type: :string, desc: "Optional metadata", required: false
 
           define_method(:execute) do |description:, metadata: nil|
-            task = {id: task_queue.size + 1, description: description, metadata: metadata, enqueued_at: Time.now}
+            task = {
+              id: task_queue.size + 1,
+              description: description,
+              metadata: metadata,
+              enqueued_at: Time.now
+            }
             task_queue << task
             "Task ##{task[:id]} enqueued: #{description}"
           end
         end
       end
 
-      # Builds the +finalize+ tool. Signals to the coordinator LLM that all tasks
-      # have been enqueued; returns a confirmation string.
       def build_finalize_tool(task_queue)
         Class.new(Phronomy::Agent::Context::Capability::Base) do
           tool_name "finalize"

data/lib/phronomy/persistence/in_memory.rb

@@ -0,0 +1,247 @@
+# frozen_string_literal: true
+
+require "monitor"
+require "digest"
+
+module Phronomy
+  class Persistence
+    class InMemory < Persistence
+      class Contents < Phronomy::ContentStore::Base
+        def initialize(owner)
+          @owner = owner
+        end
+
+        def put(bytes, canonicalization_version:)
+          value = String(bytes).b.freeze
+          id = content_id_for(value)
+          @owner.synchronize do
+            current = @owner.state[:contents][id]
+            if current && current[:bytes] != value
+              raise Phronomy::ContentStore::IntegrityError, "digest collision for #{id}"
+            end
+            @owner.state[:contents][id] ||= {
+              bytes: value,
+              canonicalization_version: Integer(canonicalization_version)
+            }
+          end
+          id
+        end
+
+        def fetch(content_id)
+          @owner.synchronize do
+            record = @owner.state[:contents].fetch(content_id.to_s) do
+              raise NotFoundError, "content not found: #{content_id}"
+            end
+            bytes = record[:bytes]
+            unless content_id_for(bytes) == content_id.to_s
+              raise Phronomy::ContentStore::IntegrityError, "content digest mismatch: #{content_id}"
+            end
+            bytes.dup
+          end
+        end
+
+        def exist?(content_id)
+          @owner.synchronize { @owner.state[:contents].key?(content_id.to_s) }
+        end
+      end
+
+      class Agents
+        def initialize(owner) = @owner = owner
+
+        def create(root)
+          @owner.synchronize do
+            key = root.agent_id.to_s
+            raise ConflictError, "agent_id must not be empty" if key.empty?
+            raise ConflictError, "agent already exists: #{key}" if @owner.state[:agents].key?(key)
+            @owner.state[:agents][key] = root
+          end
+          root
+        end
+
+        def load(agent_id)
+          @owner.synchronize do
+            @owner.state[:agents].fetch(agent_id.to_s) { raise NotFoundError, "agent not found: #{agent_id}" }
+          end
+        end
+
+        def save(agent_id, expected_revision:, root:)
+          @owner.synchronize do
+            current = load(agent_id)
+            unless current.agent_revision == expected_revision
+              raise ConflictError,
+                "agent revision conflict: expected #{expected_revision}, actual #{current.agent_revision}"
+            end
+            unless root.agent_id.to_s == agent_id.to_s
+              raise ConflictError, "Agent root identity mismatch: #{root.agent_id} != #{agent_id}"
+            end
+            unless root.agent_revision == expected_revision + 1
+              raise ConflictError,
+                "agent save must advance revision exactly once: " \
+                "expected #{expected_revision + 1}, got #{root.agent_revision}"
+            end
+            @owner.state[:agents][agent_id.to_s] = root
+          end
+          root
+        end
+
+        def delete(agent_id)
+          @owner.synchronize { @owner.state[:agents].delete(agent_id.to_s) }
+        end
+      end
+
+      class Journals
+        def initialize(owner) = @owner = owner
+
+        def append(agent_id, expected_position:, records:)
+          @owner.synchronize do
+            target = (@owner.state[:journals][agent_id.to_s] ||= [])
+            unless target.length == expected_position
+              raise ConflictError,
+                "journal position conflict: expected #{expected_position}, actual #{target.length}"
+            end
+            existing_ids = target.to_h { |record| [record.record_id, true] }
+            incoming_ids = {}
+            appended = Array(records).each_with_index.map do |record, index|
+              unless record.agent_id.to_s == agent_id.to_s
+                raise ConflictError,
+                  "Journal record Agent mismatch: #{record.agent_id} != #{agent_id}"
+              end
+              if existing_ids[record.record_id] || incoming_ids[record.record_id]
+                raise ConflictError, "duplicate Journal record_id: #{record.record_id}"
+              end
+              incoming_ids[record.record_id] = true
+              record.with_sequence(expected_position + index + 1)
+            end
+            target.concat(appended)
+            appended.freeze
+          end
+        end
+
+        def read(agent_id, after: nil, limit: nil)
+          @owner.synchronize do
+            result = Array(@owner.state[:journals][agent_id.to_s])
+            result = result.drop(Integer(after)) if after
+            result = result.first(limit) if limit
+            result.dup.freeze
+          end
+        end
+
+        def head(agent_id)
+          @owner.synchronize { Array(@owner.state[:journals][agent_id.to_s]).length }
+        end
+
+        def delete(agent_id)
+          @owner.synchronize { @owner.state[:journals].delete(agent_id.to_s) }
+        end
+      end
+
+      class Executions
+        def initialize(owner) = @owner = owner
+
+        def create_active(execution)
+          @owner.synchronize do
+            if @owner.state[:executions].key?(execution.execution_id.to_s)
+              raise ConflictError, "execution already exists: #{execution.execution_id}"
+            end
+            active = @owner.state[:executions].values.find do |candidate|
+              candidate.agent_id == execution.agent_id && candidate.active?
+            end
+            raise Phronomy::AgentBusyError, "agent is busy: #{execution.agent_id}" if active
+            @owner.state[:executions][execution.execution_id] = execution
+          end
+          execution
+        end
+
+        def load(execution_id)
+          @owner.synchronize do
+            @owner.state[:executions].fetch(execution_id.to_s) do
+              raise NotFoundError, "execution not found: #{execution_id}"
+            end
+          end
+        end
+
+        def save(execution_id, expected_revision:, execution:)
+          @owner.synchronize do
+            current = load(execution_id)
+            unless current.execution_revision == expected_revision
+              raise ConflictError,
+                "execution revision conflict: expected #{expected_revision}, actual #{current.execution_revision}"
+            end
+            unless execution.execution_id.to_s == execution_id.to_s
+              raise ConflictError,
+                "Execution identity mismatch: #{execution.execution_id} != #{execution_id}"
+            end
+            unless execution.execution_revision == expected_revision + 1
+              raise ConflictError,
+                "execution save must advance revision exactly once: " \
+                "expected #{expected_revision + 1}, got #{execution.execution_revision}"
+            end
+            @owner.state[:executions][execution_id.to_s] = execution
+          end
+          execution
+        end
+
+        def list_active(agent_id)
+          @owner.synchronize do
+            @owner.state[:executions].values.select do |execution|
+              execution.agent_id == agent_id.to_s && execution.active?
+            end.freeze
+          end
+        end
+
+        def delete(execution_id)
+          @owner.synchronize { @owner.state[:executions].delete(execution_id.to_s) }
+        end
+
+        def delete_for_agent(agent_id)
+          @owner.synchronize do
+            @owner.state[:executions].delete_if { |_id, execution| execution.agent_id == agent_id.to_s }
+          end
+        end
+
+        # Raises AgentBusyError if there is an active execution for agent_id.
+        # Must be called from within a transaction (monitor already held).
+        def assert_idle!(agent_id)
+          active = @owner.state[:executions].values.find do |candidate|
+            candidate.agent_id == agent_id.to_s && candidate.active?
+          end
+          raise Phronomy::AgentBusyError, "agent has an active or suspended execution: #{agent_id}" if active
+        end
+      end
+
+      attr_reader :state
+
+      def initialize
+        @monitor = Monitor.new
+        @state = {contents: {}, agents: {}, journals: {}, executions: {}}
+        @contents = Contents.new(self)
+        @agents = Agents.new(self)
+        @journals = Journals.new(self)
+        @executions = Executions.new(self)
+        @activations = Phronomy::Agent::ActivationRegistry.new
+        super(contents: @contents, agents: @agents, journals: @journals,
+              executions: @executions, activations: @activations)
+      end
+
+      def capabilities
+        {atomic_all: true, atomic_admission: true, optimistic_revision: true}.freeze
+      end
+
+      def transaction
+        synchronize do
+          snapshot = Marshal.load(Marshal.dump(@state))
+          begin
+            yield self
+          rescue
+            @state = snapshot
+            raise
+          end
+        end
+      end
+
+      def synchronize(&block)
+        @monitor.synchronize(&block)
+      end
+    end
+  end
+end

data/lib/phronomy/persistence.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Phronomy
+  class Persistence
+    class ConflictError < Phronomy::Error; end
+    class NotFoundError < Phronomy::Error; end
+    class UnsupportedBackendError < Phronomy::Error; end
+
+    attr_reader :contents, :agents, :journals, :executions, :activations
+
+    def initialize(contents:, agents:, journals:, executions:, activations:)
+      @contents = contents
+      @agents = agents
+      @journals = journals
+      @executions = executions
+      @activations = activations
+      validate_capabilities!
+    end
+
+    def capabilities
+      {atomic_all: false, atomic_admission: false}.freeze
+    end
+
+    def transaction
+      raise UnsupportedBackendError, "#{self.class} does not provide atomic_all"
+    end
+
+    private
+
+    def validate_capabilities!
+      required = {atomic_all: true, atomic_admission: true}
+      missing = required.reject { |key, value| capabilities[key] == value }
+      return if missing.empty?
+
+      raise UnsupportedBackendError,
+        "Persistence backend lacks required capabilities: #{missing.keys.join(", ")}"
+    end
+  end
+end

data/lib/phronomy/tools/agent.rb

@@ -3,69 +3,47 @@
 module Phronomy
   module Tools
     # Wraps a Phronomy::Agent::Base subclass as a callable tool so that a parent
-    # agent can delegate sub-tasks to a fully-capable sub-agent.
-    #
-    # Use Agent.from_agent to generate a concrete tool class.  The generated
-    # class is anonymous; assign it to a constant when you need a stable name.
-    #
-    # @example Wrap an existing agent
-    #   SummarizerTool = Phronomy::Tools::Agent.from_agent(
-    #     SummarizerAgent,
-    #     tool_name:   "summarize",
-    #     description: "Summarizes a long text and returns a brief summary"
-    #   )
-    #
-    #   class OrchestratorAgent < Phronomy::Agent::Base
-    #     model "openai/gpt-4o-mini"
-    #     instructions "You are an orchestrator that delegates to specialist agents."
-    #     tools SummarizerTool
-    #   end
+    # agent can delegate a one-shot sub-task through the same stateful pipeline.
     class Agent < Phronomy::Agent::Context::Capability::Base
       description "Wraps an agent as a tool"
       param :input, type: :string, desc: "The input to forward to the wrapped agent"
 
       class << self
-        # Generates a Phronomy::Tools::Agent subclass that delegates #execute to
-        # an instance of +agent_class+.
-        #
-        # @param agent_class  [Class] a Phronomy::Agent::Base subclass
-        # @param tool_name    [String, nil] function name exposed to the LLM;
-        #   defaults to a snake_case derivation of the agent class name
-        # @param description  [String, nil] description exposed to the LLM;
-        #   defaults to "Delegates to <AgentClassName>"
-        # @return [Class] an anonymous Phronomy::Tools::Agent subclass
-        # @api public
         def from_agent(agent_class, tool_name: nil, description: nil)
           raise ArgumentError, "agent_class must be a Class" unless agent_class.is_a?(Class)
+          unless agent_class <= Phronomy::Agent::Base
+            raise ArgumentError,
+              "agent_class must inherit from Phronomy::Agent::Base"
+          end
 
-          klass = Class.new(self)
+          # Fail at Tool definition time rather than on the first Tool call.
+          agent_class.agent_definition
 
+          klass = Class.new(self)
           effective_name = tool_name || derive_name(agent_class)
           effective_desc = description || "Delegates to #{agent_class.name || "an agent"}"
 
           klass.tool_name(effective_name)
           klass.description(effective_desc)
-
           klass.define_method(:execute) do |input:|
-            result = agent_class.new.invoke(input)
+            result = Phronomy::Agent.run_once(
+              definition: agent_class,
+              input: input
+            )
             result[:output].to_s
           end
-
           klass
         end
 
         private
 
-        # Derives a snake_case tool name from the agent class name.
-        # e.g. "My::SummarizerAgent" → "summarizer"
-        #      "TranslatorAgent"     → "translator"
         def derive_name(agent_class)
           return "agent_tool" unless agent_class.name
 
           agent_class.name
             .split("::").last
-            .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
-            .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+            .gsub(/([A-Z]+)([A-Z][a-z])/, '\\1_\\2')
+            .gsub(/([a-z\\d])([A-Z])/, '\\1_\\2')
             .downcase
             .sub(/_agent$/, "")
             .sub(/_tool$/, "")