phronomy 0.25.0 → 0.27.0

data/lib/phronomy/multi_agent/orchestrator.rb

@@ -6,6 +6,9 @@ module Phronomy
     class Orchestrator < Agent::Base
       agent_definition id: "orchestrator", version: 1
 
+      ParallelChild = Data.define(:index, :agent, :input, :config)
+      private_constant :ParallelChild
+
       # Own one live cancellation token shared with this invocation's static
       # children, including when Recovery reconstructs the invocation.
       # @api private
@@ -20,7 +23,7 @@ module Phronomy
           raise Phronomy::EventLoopReentrancyError, "Orchestrator#resume cannot block EventLoop"
         end
         execution = persistence.executions.load(execution_id)
-        raise Phronomy::Persistence::ConflictError, "Parent execution owner mismatch" unless execution.agent_id == agent_id
+        raise Phronomy::Storage::ConflictError, "Parent execution owner mismatch" unless execution.agent_id == agent_id
         input = persistence.contents.fetch_text(execution.metadata.fetch("current_input_ref"))
         result = Phronomy::Agent::ExactExecution.start(agent: self, execution_id: execution_id, input: input, config: config).wait_result
         raise Phronomy::Agent::RecoverySupport.error_from_failure(result[:error]) if result[:error]
@@ -29,7 +32,7 @@ module Phronomy
 
       def self.subagent(name, agent_class, on_error: :raise, inherit_knowledge: true)
         # A subagent Tool is logically asynchronous: ToolInvocation starts the
-        # child Agent and resumes when its completion Task settles. It must not
+        # child Agent and resumes when its completion TaskResult settles. It must not
         # occupy an OffloadPool worker while waiting for the child.
         tool_class = Class.new(Phronomy::Tools::Agent) do
           def self.__framework_owned_operation? = true
@@ -57,7 +60,7 @@ module Phronomy
               super(args, cancellation_token: cancellation_token, config: config)
             end
           rescue => error
-            Phronomy::Task.deferred(name: "subagent-dispatch-failed").tap { |task| task.fail(error) }
+            Phronomy::TaskResult.deferred(name: "subagent-dispatch-failed").tap { |task| task.fail(error) }
           end
 
           define_method(:execute_async) do |input:, cancellation_token: nil, config: {}|
@@ -87,7 +90,7 @@ module Phronomy
               end
             end
             source = agent.invoke_async(input, config: task_config)
-            result_task = Phronomy::Task.deferred(
+            result_task = Phronomy::TaskResult.deferred(
               name: "subagent-tool-#{name}"
             )
             source.on_complete do |result, error|
@@ -99,7 +102,7 @@ module Phronomy
             end
             result_task
           rescue => error
-            result_task ||= Phronomy::Task.deferred(
+            result_task ||= Phronomy::TaskResult.deferred(
               name: "subagent-tool-#{name}"
             )
             (on_error == :raise) ? result_task.fail(error) : result_task.complete(nil)
@@ -160,73 +163,38 @@ module Phronomy
         inherit_knowledge: true
       )
         validate_parallel_options!(tasks, max_concurrency, on_error)
-        return Phronomy::Task.deferred(name: "fan-out-empty").tap { |task| task.complete([]) } if tasks.empty?
-
         children = build_fan_out_children(
           tasks,
-          cancellation_token: cancellation_token,
-          invocation_context: invocation_context,
-          inherit_knowledge: inherit_knowledge
-        )
-        invocation = FanOutInvocation.new(
-          children: children,
-          max_concurrency: max_concurrency || children.length,
-          on_error: on_error
-        )
-        effective_token = cancellation_token || invocation_context&.cancellation_token
-        FanOutSessionBuilder.start(
-          invocation: invocation,
-          timeout: timeout,
-          cancellation_token: effective_token
-        )
-      end
-
-      def fan_out(
-        agent:,
-        inputs:,
-        config: {},
-        max_concurrency: nil,
-        on_error: :raise,
-        timeout: nil,
-        cancellation_token: nil,
-        invocation_context: nil,
-        inherit_knowledge: true
-      )
-        dispatch_parallel(
-          *inputs.map do |input|
-            {agent: agent, input: input, config: config}
-          end,
-          max_concurrency: max_concurrency,
-          on_error: on_error,
-          timeout: timeout,
-          cancellation_token: cancellation_token,
-          invocation_context: invocation_context,
+          cancellation_token: nil,
+          invocation_context: nil,
           inherit_knowledge: inherit_knowledge
         )
-      end
+        Phronomy::Execution.send(:__run_async, children,
+          timeout: timeout, cancellation_token: cancellation_token,
+          invocation_context: invocation_context, concurrency_limit: max_concurrency) do |child, execution|
+          # Preserve a child-specific context as well as this dispatch's controls.
+          # Agent admission adds that context's constraints to the supplied token.
+          binding = Phronomy::Concurrency::OperationBinding.new(
+            invocation_context: execution.invocation_context,
+            cancellation_token: child.config[:cancellation_token]
+          )
+          child_context = child.config[:invocation_context] ||
+            execution.invocation_context.merge(parent_task_id: invocation_context&.task_id)
+          begin
+            source = child.agent.invoke_async(child.input,
+              config: child.config.merge(cancellation_token: binding.token),
+              invocation_context: child_context)
+            binding.track(source)
+          rescue
+            binding.close
+            raise
+          end
+        end.map do |outcomes|
+          failure = outcomes.find { |outcome| outcome.status != :completed }
+          raise failure.error if failure && on_error == :raise
 
-      def fan_out_async(
-        agent:,
-        inputs:,
-        config: {},
-        max_concurrency: nil,
-        on_error: :raise,
-        timeout: nil,
-        cancellation_token: nil,
-        invocation_context: nil,
-        inherit_knowledge: true
-      )
-        dispatch_parallel_async(
-          *inputs.map do |input|
-            {agent: agent, input: input, config: config}
-          end,
-          max_concurrency: max_concurrency,
-          on_error: on_error,
-          timeout: timeout,
-          cancellation_token: cancellation_token,
-          invocation_context: invocation_context,
-          inherit_knowledge: inherit_knowledge
-        )
+          outcomes.map { |outcome| (outcome.status == :completed) ? outcome.value : nil }
+        end
       end
 
       def subagent(
@@ -366,7 +334,7 @@ module Phronomy
             knowledge_snapshot: knowledge_snapshot
           )
 
-          FanOutInvocation::Child.new(
+          ParallelChild.new(
             index: index,
             agent: child_agent,
             input: task.fetch(:input),

data/lib/phronomy/multi_agent/persistence/codec.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module MultiAgent
+    module Persistence
+      # Current-format record schemas and conversion for this domain.
+      # @api private
+      module Codec
+        extend Phronomy::Storage::RecordCodec
+
+        module_function
+
+        def encode_team_root(value)
+          payload = value.to_h
+          Phronomy::MultiAgent::TeamRoot.from_h(payload)
+          build_record("phronomy.team_root", "0.1", payload)
+        rescue Phronomy::Storage::SerializationError
+          raise
+        rescue => error
+          serialization_error("cannot encode TeamRoot", error)
+        end
+
+        def decode_team_root(record)
+          payload = current_payload!(record, record_type: "phronomy.team_root",
+            format_version: "0.1", keys: Phronomy::MultiAgent::TeamRoot::ATTRIBUTES, label: "TeamRoot")
+          Phronomy::MultiAgent::TeamRoot.from_h(payload)
+        rescue Phronomy::Storage::SerializationError
+          raise
+        rescue => error
+          serialization_error("cannot decode TeamRoot", error)
+        end
+
+        def encode_team_execution(value)
+          payload = value.to_h
+          Phronomy::MultiAgent::TeamExecution.from_h(payload)
+          build_record("phronomy.team_execution", "0.1", payload)
+        rescue Phronomy::Storage::SerializationError
+          raise
+        rescue => error
+          serialization_error("cannot encode TeamExecution", error)
+        end
+
+        def decode_team_execution(record)
+          payload = current_payload!(record, record_type: "phronomy.team_execution",
+            format_version: "0.1", keys: Phronomy::MultiAgent::TeamExecution::ATTRIBUTES, label: "TeamExecution")
+          Phronomy::MultiAgent::TeamExecution.from_h(payload)
+        rescue Phronomy::Storage::SerializationError
+          raise
+        rescue => error
+          serialization_error("cannot decode TeamExecution", error)
+        end
+      end
+    end
+  end
+end

data/lib/phronomy/multi_agent/persistence/queries.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module MultiAgent
+    module Persistence
+      # Read and assemble domain results; the public entry point owns the execution-thread guard.
+      # @api private
+      class Queries
+        def initialize(repositories)
+          @repositories = repositories
+        end
+
+        def team_execution_result(team_execution_id)
+          execution = @repositories.team_executions.load(team_execution_id)
+          {
+            team_execution_id: execution.team_execution_id, team_id: execution.team_id,
+            status: execution.status, phase: execution.phase,
+            result_ref: execution.result_ref, error_ref: execution.error_ref,
+            result: execution.result_ref && @repositories.contents.fetch_json(execution.result_ref),
+            error: execution.error_ref && @repositories.contents.fetch_json(execution.error_ref)
+          }.then { |value| Phronomy::Values::Immutable.copy(value) }
+        end
+
+        def list_team_executions(team_id, after: nil, limit: 100)
+          @repositories.team_executions.list(team_id, after: after, limit: limit)
+        end
+      end
+    end
+  end
+end

data/lib/phronomy/multi_agent/persistence/team_execution_repository.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module MultiAgent
+    module Persistence
+      # Owns execution activity, ownership, admission and durable record encoding.
+      # @api private
+      class TeamExecutionRepository
+        def initialize(view) = @view = view
+
+        def create_active(execution)
+          raise Phronomy::Storage::SerializationError, "create_active requires an active TeamExecution" unless execution.active?
+          record = Codec.encode_team_execution(execution)
+          admission do
+            @view.atomic do |bound|
+              entry = bound.records(Phronomy::TeamStorageSchema::EXECUTIONS).insert(key: execution.team_execution_id.to_s,
+                revision: Integer(execution.execution_revision), attributes: attributes(execution), record: record)
+              decode(entry, execution.team_execution_id, owner: execution.team_id,
+                revision: execution.execution_revision, active: true)
+            end
+          end
+        end
+
+        def load(team_execution_id)
+          value = @view.atomic do |bound|
+            entry = bound.records(Phronomy::TeamStorageSchema::EXECUTIONS).read(team_execution_id.to_s)
+            entry && decode(entry, team_execution_id)
+          end
+          value || raise(Phronomy::Storage::NotFoundError, "TeamExecution not found: #{team_execution_id}")
+        end
+
+        def save(team_execution_id, expected_revision:, execution:)
+          expected = Integer(expected_revision)
+          revision = Integer(execution.execution_revision)
+          raise Phronomy::Storage::ConflictError, "execution save must advance revision exactly once" unless revision == expected + 1
+          unless execution.team_execution_id.to_s == team_execution_id.to_s
+            raise Phronomy::Storage::SerializationError, "Execution identity mismatch"
+          end
+          record = Codec.encode_team_execution(execution)
+          admission do
+            @view.atomic do |bound|
+              entry = bound.records(Phronomy::TeamStorageSchema::EXECUTIONS).replace(key: team_execution_id.to_s,
+                expected_revision: expected, next_revision: revision, attributes: attributes(execution),
+                expected_attributes: execution.active? ? {active: true} : {}, record: record)
+              decode(entry, team_execution_id, owner: execution.team_id, revision: revision, active: execution.active?)
+            end
+          end
+        end
+
+        def list_active(team_id)
+          @view.atomic do |bound|
+            bound.records(Phronomy::TeamStorageSchema::EXECUTIONS).scan(index: :owner_active,
+              equals: {owner: team_id.to_s, active: true}).map { |entry| decode(entry, entry.key, owner: team_id, active: true) }.freeze
+          end
+        end
+
+        def list(team_id, after: nil, limit: 100)
+          raise ArgumentError, "limit must be a positive Integer" unless limit.is_a?(Integer) && limit.positive?
+          @view.atomic do |bound|
+            bound.records(Phronomy::TeamStorageSchema::EXECUTIONS).scan(index: :owner, equals: {owner: team_id.to_s},
+              after: after&.to_s, limit: limit).map { |entry| decode(entry, entry.key, owner: team_id) }.freeze
+          end
+        end
+
+        def delete(team_execution_id)
+          @view.records(Phronomy::TeamStorageSchema::EXECUTIONS).delete(key: team_execution_id.to_s)
+        end
+
+        def delete_for_team(team_id)
+          @view.records(Phronomy::TeamStorageSchema::EXECUTIONS).delete_matching(index: :owner, equals: {owner: team_id.to_s})
+        end
+
+        def assert_idle!(team_id)
+          condition = Phronomy::Storage::Condition::NoRows.new(resource: Phronomy::TeamStorageSchema::EXECUTIONS,
+            index: :owner_active, equals: {owner: team_id.to_s, active: true})
+          @view.check!(guards: [Phronomy::Storage::GuardRef.new(resource: Phronomy::TeamStorageSchema::ROOTS, key: team_id.to_s)],
+            conditions: [condition])
+        rescue Phronomy::Storage::ConditionFailedError => error
+          raise unless error.condition.equal?(condition)
+          raise Phronomy::AgentBusyError, error.message
+        end
+
+        private
+
+        def attributes(execution) = {owner: execution.team_id.to_s, active: execution.active?}
+
+        def admission
+          yield
+        rescue Phronomy::Storage::UniqueConstraintError => error
+          raise unless error.resource == Phronomy::TeamStorageSchema::EXECUTIONS.id && error.constraint == :one_active_owner
+          raise Phronomy::AgentBusyError, error.message
+        end
+
+        def decode(entry, team_execution_id, owner: nil, revision: nil, active: nil)
+          execution = Codec.decode_team_execution(entry.record)
+          valid = entry.key == team_execution_id.to_s && execution.team_execution_id == entry.key &&
+            execution.execution_revision == entry.revision && attributes(execution) == entry.attributes &&
+            (!owner || execution.team_id == owner.to_s) && (!revision || execution.execution_revision == revision) &&
+            (active.nil? || execution.active? == active)
+          unless valid
+            raise Phronomy::Storage::SerializationError, "backend returned another Team Execution identity/metadata"
+          end
+          execution
+        end
+      end
+    end
+  end
+end

data/lib/phronomy/multi_agent/persistence/team_repository.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module MultiAgent
+    module Persistence
+      # Owns Team root encoding and validates returned storage metadata.
+      # @api private
+      class TeamRepository
+        def initialize(view) = @view = view
+
+        def create(root)
+          record = Codec.encode_team_root(root)
+          @view.atomic do |bound|
+            entry = bound.records(Phronomy::TeamStorageSchema::ROOTS).insert(key: root.team_id.to_s,
+              revision: Integer(root.team_revision), attributes: {}, record: record)
+            decode(entry, root.team_id, revision: root.team_revision)
+          end
+        end
+
+        def load(team_id)
+          value = @view.atomic do |bound|
+            entry = bound.records(Phronomy::TeamStorageSchema::ROOTS).read(team_id.to_s)
+            entry && decode(entry, team_id)
+          end
+          value || raise(Phronomy::Storage::NotFoundError, "Team not found: #{team_id}")
+        end
+
+        def save(team_id, expected_revision:, root:)
+          expected = Integer(expected_revision)
+          revision = Integer(root.team_revision)
+          raise Phronomy::Storage::ConflictError, "root save must advance revision exactly once" unless revision == expected + 1
+          unless root.team_id.to_s == team_id.to_s
+            raise Phronomy::Storage::SerializationError, "Team root identity mismatch"
+          end
+          record = Codec.encode_team_root(root)
+          @view.atomic do |bound|
+            entry = bound.records(Phronomy::TeamStorageSchema::ROOTS).replace(key: team_id.to_s,
+              expected_revision: expected, next_revision: revision, attributes: {}, record: record)
+            decode(entry, team_id, revision: revision)
+          end
+        end
+
+        def delete(team_id)
+          @view.records(Phronomy::TeamStorageSchema::ROOTS).delete(key: team_id.to_s)
+        end
+
+        private
+
+        def decode(entry, team_id, revision: nil)
+          root = Codec.decode_team_root(entry.record)
+          valid = entry.key == team_id.to_s && root.team_id == entry.key &&
+            root.team_revision == entry.revision && (!revision || revision == entry.revision)
+          unless valid
+            raise Phronomy::Storage::SerializationError, "backend returned another Team identity/revision"
+          end
+          root
+        end
+      end
+    end
+  end
+end

data/lib/phronomy/{agent → multi_agent}/shared_state.rb

@@ -1,8 +1,9 @@
 # frozen_string_literal: true
 
 module Phronomy
-  module Agent
-    # Implements peer coordination through a shared KnowledgeStore.
+  module MultiAgent
+    # Implements peer coordination through an invocation-local KnowledgeStore.
+    # @api public
     class SharedState
       # Semantic revision of the framework-owned SharedState instrumentation
       # applied on top of one specific researcher definition revision.
@@ -13,6 +14,8 @@ module Phronomy
       INSTRUMENTATION_DEFINITION_VERSION = 1
       private_constant :INSTRUMENTATION_DEFINITION_VERSION
 
+      # Findings shared by the sequential members of one invocation.
+      # @api public
       class KnowledgeStore
         def initialize
           @findings = []
@@ -78,8 +81,15 @@ module Phronomy
       # @api public
       def invoke(input, config: {})
         validate_termination!
-
         store = KnowledgeStore.new
+        cycles, terminated_by = coordinate_members(input, store)
+
+        {output: aggregate_findings(store), cycles: cycles, terminated_by: terminated_by}
+      end
+
+      private
+
+      def coordinate_members(input, store)
         max_cycles = self.class._max_cycles
         deadline = self.class._timeout ? Time.now + self.class._timeout : nil
         terminated_by = :max_cycles
@@ -87,15 +97,7 @@ module Phronomy
         cycle_limit = max_cycles || Float::INFINITY
 
         (1..cycle_limit).each do |cycle|
-          self.class._members.each do |member_config|
-            invoke_researcher(
-              member_config[:klass],
-              store,
-              cycle,
-              input,
-              member_config[:instruction]
-            )
-          end
+          invoke_members(input, store, cycle)
           completed_cycles = cycle
 
           if self.class._terminate_when&.call(store)
@@ -109,17 +111,25 @@ module Phronomy
           end
         end
 
-        output = if self.class._aggregator
+        [completed_cycles, terminated_by]
+      end
+
+      def invoke_members(input, store, cycle)
+        self.class._members.each do |member_config|
+          invoke_researcher(
+            member_config[:klass], store, cycle, input, member_config[:instruction]
+          )
+        end
+      end
+
+      def aggregate_findings(store)
+        if self.class._aggregator
           self.class._aggregator.call(store)
         else
           store.read_all
         end
-
-        {output: output, cycles: completed_cycles, terminated_by: terminated_by}
       end
 
-      private
-
       def validate_termination!
         return if self.class._max_cycles || self.class._timeout
 
@@ -148,28 +158,8 @@ module Phronomy
 
       def build_instrumented_researcher(researcher_class, store, cycle)
         agent_key = researcher_class.name&.to_sym || researcher_class.object_id.to_s.to_sym
-
-        read_tool = Class.new(Phronomy::Agent::Context::Capability::Base) do
-          tool_name "read_store"
-          description "Read all current findings from the shared knowledge store. " \
-            "Call this to see what other researchers have discovered."
-          execution_mode :cooperative
-
-          define_method(:execute) { store.read_all.to_json }
-        end
-
-        write_tool = Class.new(Phronomy::Agent::Context::Capability::Base) do
-          tool_name "write_finding"
-          description "Record a new finding into the shared knowledge store so " \
-            "that other researchers can build on your discovery."
-          execution_mode :cooperative
-          param :content, type: :string, desc: "The finding to record"
-
-          define_method(:execute) do |content:|
-            store.write(agent: agent_key, content: content, cycle: cycle)
-            "Finding recorded."
-          end
-        end
+        read_tool = build_read_tool(store)
+        write_tool = build_write_tool(store, cycle, agent_key)
 
         definitions = researcher_class.tools.to_h do |tool_class|
           [tool_class, researcher_class.tool_aliases[tool_class]]
@@ -197,12 +187,39 @@ module Phronomy
         end
       end
 
+      def build_read_tool(store)
+        Class.new(Phronomy::Agent::Context::Capability::Base) do
+          tool_name "read_store"
+          description "Read all current findings from the shared knowledge store. " \
+            "Call this to see what other researchers have discovered."
+          execution_mode :cooperative
+
+          define_method(:execute) { store.read_all.to_json }
+        end
+      end
+
+      def build_write_tool(store, cycle, agent_key)
+        Class.new(Phronomy::Agent::Context::Capability::Base) do
+          tool_name "write_finding"
+          description "Record a new finding into the shared knowledge store so " \
+            "that other researchers can build on your discovery."
+          execution_mode :cooperative
+          param :content, type: :string, desc: "The finding to record"
+
+          define_method(:execute) do |content:|
+            store.write(agent: agent_key, content: content, cycle: cycle)
+            "Finding recorded."
+          end
+        end
+      end
+
       def instrumented_definition_for(researcher_class)
         parent_def = researcher_class.agent_definition
         parent_id = parent_def.fetch(:id)
         parent_version = parent_def.fetch(:version)
 
         {
+          # Keep the existing semantic ID across the Ruby namespace migration.
           id: "Phronomy::Agent::SharedState::Instrumented/#{parent_id}@#{parent_version}".freeze,
           version: INSTRUMENTATION_DEFINITION_VERSION
         }.freeze

data/lib/phronomy/multi_agent/storage_contract/team_storage_schema.rb

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+module Phronomy
+  # Domain-owned Team metadata, independent of coordination runtime loading.
+  # @api private
+  module TeamStorageSchema
+    ROOTS = Phronomy::Storage::Resource.new(id: "team.roots", kind: :records,
+      guard: {resource: "team.roots", via: :key})
+    EXECUTIONS = Phronomy::Storage::Resource.new(id: "team.executions", kind: :records,
+      attributes: {owner: :string, active: :boolean}, immutable_attributes: [:owner],
+      indexes: {owner: [:owner], owner_active: [:owner, :active]},
+      unique: [{name: :one_active_owner, fields: [:owner], where: {active: true}}],
+      guard: {resource: ROOTS.id, via: :owner})
+  end
+end