phronomy 0.23.0 → 0.24.1

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: phronomy
 version: !ruby/object:Gem::Version
-  version: 0.23.0
+  version: 0.24.1
 platform: ruby
 authors:
 - Raizo T.C.S
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-08-28 00:00:00.000000000 Z
+date: 2026-09-07 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ruby_llm
@@ -78,6 +78,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '1.0'
+- !ruby/object:Gem::Dependency
+  name: json
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3'
 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.
@@ -150,7 +164,17 @@ files:
 - docs/decisions/025-process-local-agent-ownership-and-runtime-admission.md
 - docs/decisions/026-workflow-runtime-admission-and-durable-terminal-barrier.md
 - docs/decisions/027-llm-adapter-provider-boundary.md
+- docs/decisions/028-preparing-recovery-replay-contract.md
+- docs/decisions/029-semantic-completion-and-application-effect-boundary.md
+- docs/decisions/030-agent-handoff-domain-and-durable-responsibility.md
+- docs/decisions/031-durable-multi-agent-coordination.md
 - docs/decisions/README.md
+- docs/design/durable-semantic-coordination/CHANGELOG_V2_REVISION_2.md
+- docs/design/durable-semantic-coordination/CONTINUATION_DECISION_REFACTOR.md
+- docs/design/durable-semantic-coordination/IMPLEMENTATION_DESIGN_V2.md
+- docs/design/durable-semantic-coordination/IMPLEMENTATION_REPORT.md
+- docs/design/durable-semantic-coordination/RECOVERY_CONTRACT_CLARIFICATIONS.md
+- docs/design/durable-semantic-coordination/RESPONSIBILITY_BOUNDARY_REVIEW.md
 - docs/features.md
 - docs/getting-started.md
 - docs/mcp-client.md
@@ -158,6 +182,7 @@ files:
 - docs/migrations/0.16.md
 - docs/migrations/0.19.md
 - docs/migrations/0.22.md
+- docs/migrations/durable-semantic-coordination-v2.md
 - docs/persistence-backends.md
 - docs/runtime-and-concurrency.md
 - examples/README.md
@@ -186,7 +211,18 @@ files:
 - lib/phronomy/agent/context_policy.rb
 - lib/phronomy/agent/context_policy_input.rb
 - lib/phronomy/agent/context_policy_input_builder.rb
+- lib/phronomy/agent/exact_execution.rb
+- lib/phronomy/agent/execution_cancellation.rb
 - lib/phronomy/agent/execution_coordinator.rb
+- lib/phronomy/agent/handoff.rb
+- lib/phronomy/agent/handoff_capability_factory.rb
+- lib/phronomy/agent/handoff_context.rb
+- lib/phronomy/agent/handoff_execution_coordinator.rb
+- lib/phronomy/agent/handoff_policy.rb
+- lib/phronomy/agent/handoff_projection.rb
+- lib/phronomy/agent/handoff_request.rb
+- lib/phronomy/agent/handoff_runner.rb
+- lib/phronomy/agent/handoff_state.rb
 - lib/phronomy/agent/immutable.rb
 - lib/phronomy/agent/journal_projection.rb
 - lib/phronomy/agent/journal_record.rb
@@ -233,6 +269,7 @@ files:
 - lib/phronomy/engine/runtime.rb
 - lib/phronomy/engine/runtime/agent_ownership_registry.rb
 - lib/phronomy/engine/runtime/shutdown_result.rb
+- lib/phronomy/engine/runtime/team_ownership_registry.rb
 - lib/phronomy/engine/runtime/timer_queue.rb
 - lib/phronomy/engine/runtime/timer_service.rb
 - lib/phronomy/engine/task.rb
@@ -254,21 +291,14 @@ files:
 - lib/phronomy/llm_context_window/token_estimator.rb
 - lib/phronomy/metrics.rb
 - lib/phronomy/multi_agent/admission_registry.rb
-- lib/phronomy/multi_agent/coordination_state.rb
-- lib/phronomy/multi_agent/coordinator.rb
-- lib/phronomy/multi_agent/execution_coordinator.rb
+- lib/phronomy/multi_agent/durable_subagent_coordinator.rb
 - lib/phronomy/multi_agent/fan_out_invocation.rb
 - lib/phronomy/multi_agent/fan_out_session_builder.rb
-- lib/phronomy/multi_agent/handoff.rb
-- lib/phronomy/multi_agent/handoff_capability_factory.rb
-- lib/phronomy/multi_agent/handoff_context.rb
-- lib/phronomy/multi_agent/handoff_policy.rb
-- lib/phronomy/multi_agent/handoff_projection.rb
-- lib/phronomy/multi_agent/handoff_request.rb
 - lib/phronomy/multi_agent/orchestrator.rb
 - lib/phronomy/multi_agent/parallel_tool_chat.rb
-- lib/phronomy/multi_agent/runner.rb
 - lib/phronomy/multi_agent/team_coordinator.rb
+- lib/phronomy/multi_agent/team_execution.rb
+- lib/phronomy/multi_agent/team_root.rb
 - lib/phronomy/output_parser.rb
 - lib/phronomy/output_parser/base.rb
 - lib/phronomy/output_parser/json_parser.rb
@@ -304,6 +334,7 @@ files:
 - lib/phronomy/testing/persistence_contract/a_workflow_state_repository.rb
 - lib/phronomy/testing/persistence_contract/an_agent_repository.rb
 - lib/phronomy/testing/persistence_contract/an_execution_repository.rb
+- lib/phronomy/testing/persistence_contract/coordination_repositories.rb
 - lib/phronomy/token_usage.rb
 - lib/phronomy/tool.rb
 - lib/phronomy/tool/base.rb
@@ -350,6 +381,7 @@ files:
 - sig/phronomy.rbs
 - sig/phronomy/agent.rbs
 - sig/phronomy/extensions.rbs
+- sig/phronomy/handoff.rbs
 - sig/phronomy/llm_adapter.rbs
 - sig/phronomy/multi_agent.rbs
 - sig/phronomy/persistence.rbs

data/lib/phronomy/multi_agent/coordination_state.rb

@@ -1,18 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  module MultiAgent
-    CoordinationState = Data.define(:active_agent, :active_handoff_context) do
-      def initialize(active_agent:, active_handoff_context: nil)
-        unless active_agent.is_a?(Phronomy::Agent::Base)
-          raise ArgumentError, "active_agent must be a Phronomy::Agent::Base"
-        end
-        if active_handoff_context && !active_handoff_context.is_a?(HandoffContext)
-          raise ArgumentError, "active_handoff_context must be a HandoffContext"
-        end
-        super
-        freeze
-      end
-    end
-  end
-end

data/lib/phronomy/multi_agent/coordinator.rb

@@ -1,154 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  module MultiAgent
-    class Coordinator
-      ATTACH_MUTEX = Mutex.new
-      private_constant :ATTACH_MUTEX
-
-      ApplyHandoffCommand = Data.define(:coordinator, :request, :context, :completion)
-
-      attr_reader :main_agent, :handoffs
-
-      def self.attach(main_agent:, handoffs:)
-        unless main_agent.is_a?(Phronomy::Agent::Base)
-          raise ArgumentError, "main_agent must be a Phronomy::Agent::Base"
-        end
-        normalized = Array(handoffs).freeze
-
-        ATTACH_MUTEX.synchronize do
-          existing = main_agent.instance_variable_get(:@_phronomy_multi_agent_coordinator)
-          if existing&.runtime_current?
-            existing.assert_compatible!(normalized)
-            return existing
-          end
-
-          created = new(main_agent: main_agent, handoffs: normalized)
-          main_agent.instance_variable_set(:@_phronomy_multi_agent_coordinator, created)
-          created
-        end
-      end
-
-      def initialize(main_agent:, handoffs:)
-        @main_agent = main_agent
-        @handoffs = Array(handoffs).freeze
-        @runtime = Phronomy::Runtime.instance
-        validate_graph!
-        @bindings_by_source = build_bindings
-        @state_mutex = Mutex.new
-        @state = CoordinationState.new(active_agent: main_agent)
-      end
-
-      def runtime_current?
-        Phronomy::Runtime.instance.equal?(@runtime)
-      end
-
-      def snapshot
-        unless runtime_current?
-          raise Phronomy::RuntimeShutdownError,
-            "Multi-Agent coordination state belongs to a previous Runtime"
-        end
-        @state_mutex.synchronize { @state }
-      end
-
-      def outgoing_bindings(agent)
-        @bindings_by_source.fetch(agent.object_id, []).freeze
-      end
-
-      def transition!(request, context)
-        completion = Phronomy::Task.deferred(name: "multi-agent-handoff")
-        command = ApplyHandoffCommand.new(
-          coordinator: self,
-          request: request,
-          context: context,
-          completion: completion
-        )
-        posted = Phronomy::Runtime.instance.event_loop.post(
-          Phronomy::Event.new(
-            type: :agent_terminal_ready,
-            target_id: Phronomy::EventLoop::SYSTEM_CHANNEL_ID,
-            payload: {command: command}
-          )
-        )
-        unless posted
-          completion.fail(
-            Phronomy::RuntimeShutdownError.new(
-              "EventLoop is not accepting Multi-Agent Handoff transitions"
-            )
-          )
-        end
-        completion.wait_result
-      end
-
-      # @api private
-      def deliver_on_event_loop(command)
-        runtime = Phronomy::Runtime.instance
-        unless runtime.event_loop.current?
-          raise Phronomy::Error,
-            "Multi-Agent coordination state may only be mutated on EventLoop"
-        end
-
-        request = command.request
-        context = command.context
-        current = snapshot
-        unless request.handoff.source_agent.equal?(current.active_agent)
-          raise Phronomy::HandoffError,
-            "Handoff source is no longer the active Agent"
-        end
-
-        next_state = CoordinationState.new(
-          active_agent: request.handoff.target_agent,
-          active_handoff_context: context
-        )
-        @state_mutex.synchronize { @state = next_state }
-        command.completion.complete(next_state)
-      rescue => error
-        command.completion.fail(error)
-      end
-
-      def assert_compatible!(handoffs)
-        incoming = graph_signature(handoffs)
-        current = graph_signature(@handoffs)
-        return true if incoming == current
-
-        raise Phronomy::ConfigurationError,
-          "a MultiAgent::Runner for this main Agent already exists with a different Handoff graph"
-      end
-
-      private
-
-      def validate_graph!
-        unless @handoffs.all? { |handoff| handoff.is_a?(Handoff) }
-          raise ArgumentError, "handoffs must contain only MultiAgent::Handoff values"
-        end
-
-        duplicates = @handoffs.group_by do |handoff|
-          [handoff.source_agent.object_id, handoff.target_agent.object_id]
-        end.select { |_key, values| values.length > 1 }
-        unless duplicates.empty?
-          raise ArgumentError, "duplicate Source → Target Handoff edges are not allowed"
-        end
-      end
-
-      def build_bindings
-        @handoffs.group_by(&:source_agent).to_h do |source, edges|
-          [
-            source.object_id,
-            edges.map { |handoff| HandoffCapabilityFactory.build(handoff) }.freeze
-          ]
-        end.freeze
-      end
-
-      def graph_signature(handoffs)
-        Array(handoffs).map do |handoff|
-          [
-            handoff.source_agent.object_id,
-            handoff.target_agent.object_id,
-            handoff.policy.to_h,
-            handoff.description
-          ]
-        end.sort_by { |row| [row[0], row[1], row[3]] }
-      end
-    end
-  end
-end

data/lib/phronomy/multi_agent/runner.rb

@@ -1,98 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  module MultiAgent
-    class Runner
-      MAX_HANDOFFS = 20
-
-      attr_reader :main_agent, :handoffs
-
-      # @api public
-      def initialize(main_agent:, handoffs: [])
-        @main_agent = main_agent
-        @handoffs = Array(handoffs).freeze
-        @coordinator = Coordinator.attach(
-          main_agent: main_agent,
-          handoffs: @handoffs
-        )
-      end
-
-      # @api public
-      def invoke(input, config: {})
-        trace_handle = Phronomy::Tracing::Automatic.start(
-          "multi_agent.turn",
-          input: input,
-          main_agent_id: @main_agent.agent_id,
-          **@main_agent.send(:_build_caller_meta, config)
-        )
-        result = nil
-        operation_error = nil
-
-        @coordinator = Coordinator.attach(
-          main_agent: @main_agent,
-          handoffs: @handoffs
-        )
-        runtime = Phronomy::Runtime.instance
-        runtime.__admit_multi_agent(@coordinator)
-        handoffs_taken = 0
-        current_input = input
-
-        result = loop do
-          state = @coordinator.snapshot
-          active_agent = state.active_agent
-          bindings = @coordinator.outgoing_bindings(active_agent)
-          agent_result = active_agent.invoke(
-            current_input,
-            config: config.merge(
-              phronomy_handoff_bindings: bindings,
-              phronomy_handoff_context: state.active_handoff_context
-            )
-          )
-
-          request = agent_result[:handoff_request]
-          break public_result(agent_result, active_agent) unless request
-
-          if handoffs_taken >= MAX_HANDOFFS
-            raise Phronomy::HandoffError,
-              "Exceeded maximum Handoffs (#{MAX_HANDOFFS}) in one user turn"
-          end
-
-          manifest = agent_result.fetch(:_phronomy_handoff_manifest)
-          context = HandoffProjection.new.build(
-            request: request,
-            manifest: manifest,
-            persistence: active_agent.persistence,
-            source_agent: active_agent
-          )
-          @coordinator.transition!(request, context)
-          current_input = request.responsibility
-          handoffs_taken += 1
-        end
-        result
-      rescue => error
-        operation_error = error
-        raise
-      ensure
-        runtime&.__release_multi_agent(@coordinator) if defined?(@coordinator)
-        trace_output = if result.is_a?(Hash)
-          result[:output] || result["output"]
-        else
-          result
-        end
-        Phronomy::Tracing::Automatic.finish(
-          trace_handle,
-          output: trace_output,
-          error: operation_error
-        )
-      end
-
-      private
-
-      def public_result(result, agent)
-        result.reject { |key, _| key.to_s.start_with?("_phronomy_") }
-          .except(:handoff_request)
-          .merge(agent: agent)
-      end
-    end
-  end
-end