phronomy 0.22.0 → 0.23.0

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: phronomy
 version: !ruby/object:Gem::Version
-  version: 0.22.0
+  version: 0.23.0
 platform: ruby
 authors:
 - Raizo T.C.S
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-08-17 00:00:00.000000000 Z
+date: 2026-08-28 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ruby_llm
@@ -95,6 +95,7 @@ files:
 - RELEASE_CHECKLIST.md
 - Rakefile
 - SECURITY.md
+- VERIFY.sh
 - benchmark/baseline.json
 - benchmark/bench_agent_invoke.rb
 - benchmark/bench_context_assembler.rb
@@ -104,6 +105,22 @@ files:
 - benchmark/bench_vector_store.rb
 - benchmark/bench_workflow.rb
 - benchmark/run_all.rb
+- docs/architecture.md
+- docs/architecture/agent-context.md
+- docs/architecture/before-llm-input.md
+- docs/architecture/context-management.md
+- docs/architecture/knowledge-and-rag.md
+- docs/architecture/multi-agent-handoff.md
+- docs/architecture/persistence.md
+- docs/architecture/removed/agent-context.md
+- docs/architecture/security-boundaries.md
+- docs/architecture/tracing.md
+- docs/archive/design/archived/04_api_design.md
+- docs/archive/design/archived/09_guardrails.md
+- docs/archive/design/archived/17_rails_integration.md
+- docs/archive/design/historical/00_design_philosophy.md
+- docs/archive/design/historical/01_rubyllm_evaluation.md
+- docs/archive/design/historical/06_design_decisions.md
 - docs/changelog/0.14-and-earlier.md
 - docs/decisions/001-rubyllm-as-provider-layer.md
 - docs/decisions/002-workflow-context-immutability.md
@@ -121,22 +138,33 @@ files:
 - docs/decisions/013-journal-backed-knowledge-as-context-candidates.md
 - docs/decisions/014-unified-persistence-durable-state.md
 - docs/decisions/015-tool-public-facade-and-rbs-boundary.md
+- docs/decisions/016-semantic-multi-agent-handoff.md
+- docs/decisions/017-design-authority-and-adr-governance.md
+- docs/decisions/018-durability-guarantees-and-failure-model.md
+- docs/decisions/019-filter-contract-and-security-boundaries.md
+- docs/decisions/020-canonical-workflow-instance-identity.md
+- docs/decisions/021-generic-agent-invocation-identity-removal.md
+- docs/decisions/022-agent-execution-parent-identity-and-runtime-routing-boundary.md
+- docs/decisions/023-fsm-session-incarnation-identity-and-routing.md
+- docs/decisions/024-event-loop-single-writer-agent-runtime.md
+- 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/README.md
 - docs/features.md
 - docs/getting-started.md
 - docs/mcp-client.md
 - docs/migrations/0.15.md
 - docs/migrations/0.16.md
 - docs/migrations/0.19.md
+- docs/migrations/0.22.md
 - docs/persistence-backends.md
 - docs/runtime-and-concurrency.md
-- examples/workflows/agent_event_mapping.rb
-- examples/workflows/generic_task_event_mapping.rb
+- examples/README.md
 - 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_session_builder.rb
 - lib/phronomy/agent/agent_root.rb
@@ -149,23 +177,15 @@ files:
 - lib/phronomy/agent/context/capability/base.rb
 - lib/phronomy/agent/context/instruction/prompt_template.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/context_policy_input.rb
+- lib/phronomy/agent/context_policy_input_builder.rb
 - lib/phronomy/agent/execution_coordinator.rb
 - lib/phronomy/agent/immutable.rb
 - lib/phronomy/agent/journal_projection.rb
@@ -177,8 +197,14 @@ files:
 - lib/phronomy/agent/llm_operation_result.rb
 - lib/phronomy/agent/phase_machine_builder.rb
 - lib/phronomy/agent/provider_call_outcome.rb
+- lib/phronomy/agent/recovery_coordinator.rb
+- lib/phronomy/agent/recovery_coordinator/continuation.rb
+- lib/phronomy/agent/recovery_coordinator/installation.rb
+- lib/phronomy/agent/recovery_coordinator/resolution.rb
+- lib/phronomy/agent/recovery_support.rb
 - lib/phronomy/agent/ruby_llm_materializer.rb
-- lib/phronomy/agent/runner.rb
+- lib/phronomy/agent/selection/candidate.rb
+- lib/phronomy/agent/selection/constraint.rb
 - lib/phronomy/agent/shared_state.rb
 - lib/phronomy/agent/token_budget_resolver.rb
 - lib/phronomy/agent/tool_approval_request.rb
@@ -187,7 +213,9 @@ files:
 - lib/phronomy/agent/tool_executor.rb
 - lib/phronomy/agent/tool_invocation.rb
 - lib/phronomy/agent/tool_invocation_session_builder.rb
+- lib/phronomy/agent_already_exists_error.rb
 - lib/phronomy/agent_busy_error.rb
+- lib/phronomy/agent_purged_error.rb
 - lib/phronomy/canonical_json.rb
 - lib/phronomy/configuration.rb
 - lib/phronomy/content_store/base.rb
@@ -198,10 +226,12 @@ files:
 - lib/phronomy/engine/concurrency/cancellation_token.rb
 - lib/phronomy/engine/concurrency/deadline.rb
 - lib/phronomy/engine/concurrency/offload_pool.rb
+- lib/phronomy/engine/concurrency/physical_completion_task.rb
 - lib/phronomy/engine/concurrency/pool_registry.rb
 - lib/phronomy/engine/event_loop.rb
 - lib/phronomy/engine/fsm_session.rb
 - lib/phronomy/engine/runtime.rb
+- lib/phronomy/engine/runtime/agent_ownership_registry.rb
 - lib/phronomy/engine/runtime/shutdown_result.rb
 - lib/phronomy/engine/runtime/timer_queue.rb
 - lib/phronomy/engine/runtime/timer_service.rb
@@ -223,18 +253,33 @@ files:
 - lib/phronomy/llm_context_window/token_budget.rb
 - 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/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/output_parser.rb
 - 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/durable_codec.rb
+- lib/phronomy/persistence/durable_record.rb
 - lib/phronomy/persistence/in_memory.rb
+- lib/phronomy/persistence/migration/initial_format_migration.rb
+- lib/phronomy/persistence/repository_facades.rb
+- lib/phronomy/recovery.rb
 - lib/phronomy/ruby_llm_patches.rb
 - lib/phronomy/runnable.rb
 - lib/phronomy/stream_callback_error.rb
@@ -266,6 +311,7 @@ files:
 - lib/phronomy/tools/mcp.rb
 - lib/phronomy/tools/vector_search.rb
 - lib/phronomy/tracing.rb
+- lib/phronomy/tracing/automatic.rb
 - lib/phronomy/tracing/base.rb
 - lib/phronomy/tracing/langfuse_tracer.rb
 - lib/phronomy/tracing/null_tracer.rb
@@ -289,6 +335,7 @@ files:
 - lib/phronomy/workflow.rb
 - lib/phronomy/workflow/phase_machine_builder.rb
 - lib/phronomy/workflow_context.rb
+- lib/phronomy/workflow_recovery.rb
 - lib/phronomy/workflow_runner.rb
 - scripts/add_to_h_to_token_doubles.rb
 - scripts/add_to_h_unnamed_doubles.rb
@@ -304,6 +351,7 @@ files:
 - sig/phronomy/agent.rbs
 - sig/phronomy/extensions.rbs
 - sig/phronomy/llm_adapter.rbs
+- sig/phronomy/multi_agent.rbs
 - sig/phronomy/persistence.rbs
 - sig/phronomy/runtime.rbs
 - sig/phronomy/tool.rbs

data/examples/workflows/agent_event_mapping.rb

@@ -1,101 +0,0 @@
-# frozen_string_literal: true
-
-require "phronomy"
-require "securerandom"
-
-class GenerationContext
-  include Phronomy::WorkflowContext
-
-  field :prompt
-  field :generation_request_id
-  field :answer
-  field :error_message
-
-  # This is application logic. Phronomy transports the event and payload but
-  # does not decide which Agent invocation is current or where the result lives.
-  def handle_fsm_event(event)
-    request_id = event.payload[:generation_request_id]
-    return :consume unless request_id == generation_request_id
-
-    case event.type
-    when :generation_completed
-      self.answer = event.payload[:agent_result][:output]
-    when :generation_failed
-      self.error_message = event.payload[:error].message
-    end
-    false
-  end
-end
-
-class AnswerAgent < Phronomy::Agent::Base
-  model "gpt-4o-mini"
-  instructions "Answer clearly and briefly."
-end
-
-agent = AnswerAgent.new
-workflow = nil
-
-workflow = Phronomy::Workflow.define(GenerationContext) do
-  initial :generating
-
-  state :generating, action: ->(context) {
-    request_id = context.generation_request_id
-
-    # The Agent Task is intentionally not returned from the entry action.
-    # The block is the application-level integration channel.
-    agent.invoke_async(context.prompt) do |agent_event|
-      workflow_event =
-        case agent_event.type
-        when :done
-          :generation_completed
-        when :error, :timeout, :cancelled, :approval_required
-          :generation_failed
-        end
-      next unless workflow_event
-
-      workflow.signal(
-        thread_id: context.thread_id,
-        event: workflow_event,
-        payload: {
-          generation_request_id: request_id,
-          agent_result: (
-            agent_event.payload if agent_event.type == :done
-          ),
-          error:
-            agent_event.payload[:error] ||
-            Phronomy::Error.new(
-              "Agent requested Tool approval"
-            )
-        }
-      )
-    end
-
-    context
-  }
-
-  state :succeeded
-  state :failed
-
-  transition(
-    from: :generating,
-    on: :generation_completed,
-    to: :succeeded
-  )
-  transition(
-    from: :generating,
-    on: :generation_failed,
-    to: :failed
-  )
-  transition from: :succeeded, to: :__finish__
-  transition from: :failed, to: :__finish__
-end
-
-result = workflow.invoke(
-  {
-    prompt: "What is Run-to-Completion?",
-    generation_request_id: SecureRandom.uuid
-  },
-  config: {thread_id: SecureRandom.uuid}
-)
-
-puts(result.answer || result.error_message)

data/examples/workflows/generic_task_event_mapping.rb

@@ -1,66 +0,0 @@
-# frozen_string_literal: true
-
-require "phronomy"
-
-class ImportContext
-  include Phronomy::WorkflowContext
-
-  field :record_count, default: 0
-  field :error_message
-
-  def handle_fsm_event(event)
-    case event.type
-    when :import_completed
-      self.record_count = event.payload[:record_count]
-    when :import_failed
-      self.error_message = event.payload[:error].message
-    end
-    false
-  end
-end
-
-# Example application service for synchronous work that must stay off EventLoop.
-# The worker Thread belongs to Phronomy's bounded OffloadPool; the Workflow
-# itself never blocks EventLoop waiting for the operation.
-def start_import_async
-  Phronomy::Runtime.instance.offload.submit(on_full: :raise) do
-    # Replace with blocking file/DB/network work or another long synchronous call.
-    100
-  end
-end
-
-workflow = nil
-
-workflow = Phronomy::Workflow.define(ImportContext) do
-  initial :importing
-
-  state :importing, action: ->(context) {
-    operation = start_import_async
-
-    operation.on_complete do |record_count, error|
-      workflow.signal(
-        thread_id: context.thread_id,
-        event: error ? :import_failed : :import_completed,
-        payload: {
-          record_count: record_count,
-          error: error
-        }
-      )
-    end
-
-    # Do not return the completion handle. The state remains active after this
-    # synchronous action returns, and later completion arrives as an FSM event.
-    context
-  }
-
-  state :completed
-  state :failed
-
-  transition from: :importing, on: :import_completed, to: :completed
-  transition from: :importing, on: :import_failed, to: :failed
-  transition from: :completed, to: :__finish__
-  transition from: :failed, to: :__finish__
-end
-
-result = workflow.invoke({})
-puts "Imported #{result.record_count} records"

data/lib/phronomy/agent/activation_registry.rb

@@ -1,28 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  module Agent
-    class ActivationRegistry
-      def initialize
-        @mutex = Mutex.new
-        @records = {}
-      end
-
-      def register(activation)
-        @mutex.synchronize do
-          raise ArgumentError, "activation already registered: #{activation.execution_id}" if @records.key?(activation.execution_id)
-          @records[activation.execution_id] = activation
-        end
-        activation
-      end
-
-      def fetch(execution_id)
-        @mutex.synchronize { @records[execution_id.to_s] }
-      end
-
-      def delete(execution_id)
-        @mutex.synchronize { @records.delete(execution_id.to_s) }
-      end
-    end
-  end
-end

data/lib/phronomy/agent/agent_execution_activation.rb

@@ -1,172 +0,0 @@
-# frozen_string_literal: true
-
-require "securerandom"
-require "time"
-
-module Phronomy
-  module Agent
-    class AgentExecutionActivation
-      attr_reader :execution_id, :agent, :application_listener, :coordinator,
-        :base_manifest
-      attr_accessor :invocation, :session
-
-      def initialize(
-        execution:,
-        agent:,
-        runtime_projection:,
-        coordinator:,
-        application_listener: nil
-      )
-        @execution_id = execution.execution_id
-        @execution = execution
-        @agent = agent
-        @runtime_projection = runtime_projection
-        @base_manifest = runtime_projection.manifest
-        @coordinator = coordinator
-        @application_listener = application_listener
-        @mutex = Mutex.new
-        @active_call = nil
-        @llm_results = []
-        @runtime_events = []
-        @callback_errors = []
-      end
-
-      def execution
-        @mutex.synchronize { @execution }
-      end
-
-      def replace_execution(value)
-        @mutex.synchronize { @execution = value }
-      end
-
-      def runtime_projection
-        @mutex.synchronize { @runtime_projection }
-      end
-
-      def replace_runtime_projection(value)
-        @mutex.synchronize { @runtime_projection = value }
-      end
-
-      # Allocates Provider Call identity before transport begins. This identity is
-      # provenance only; Context selection must not use it as a semantic boundary.
-      def begin_llm_call(projection)
-        call_context = {
-          llm_call_id: SecureRandom.uuid,
-          manifest_ref: projection.manifest_ref,
-          started_at: Time.now.utc.iso8601(6)
-        }.freeze
-        @mutex.synchronize do
-          if @active_call
-            raise Phronomy::Error,
-              "cannot start a Provider Call while another Provider Call is active"
-          end
-          @runtime_projection = projection
-          @active_call = call_context
-        end
-        call_context
-      end
-
-      def record_llm_result(response:, error:, streaming:)
-        @mutex.synchronize do
-          active_call = @active_call
-          unless active_call
-            raise Phronomy::Error, "LLM result arrived without an active Provider Call"
-          end
-          @llm_results << {
-            llm_call_id: active_call.fetch(:llm_call_id),
-            response: response,
-            error: error,
-            streaming: streaming,
-            manifest_ref: active_call.fetch(:manifest_ref),
-            started_at: active_call.fetch(:started_at)
-          }
-          @active_call = nil
-        end
-      end
-
-      def runtime_snapshot
-        @mutex.synchronize do
-          {
-            llm_results: @llm_results.dup,
-            runtime_events: @runtime_events.dup,
-            active_call: @active_call&.dup
-          }
-        end
-      end
-
-      def acknowledge_runtime_snapshot(snapshot)
-        @mutex.synchronize do
-          @llm_results.shift(snapshot.fetch(:llm_results).length)
-          @runtime_events.shift(snapshot.fetch(:runtime_events).length)
-          if snapshot[:active_call] && @active_call == snapshot[:active_call]
-            @active_call = nil
-          end
-        end
-      end
-
-      ApplicationCallbackFailure = Data.define(:event_type, :error) do
-        def to_stream_callback_error
-          wrapped = Phronomy::StreamCallbackError.new(
-            event_type: event_type, original_error: error, result: nil
-          )
-          begin
-            raise wrapped, cause: error
-          rescue Phronomy::StreamCallbackError => caught
-            caught.set_backtrace(error.backtrace)
-            caught
-          end
-        end
-      end
-
-      attr_reader :callback_failure
-
-      def callback_failed?
-        @mutex.synchronize { !@callback_failure.nil? }
-      end
-
-      # Canonical runtime recording is independent of Application callback health.
-      # Once an event is observed it is appended even after a listener has failed.
-      def record_event(event)
-        listener = @mutex.synchronize do
-          @runtime_events << event
-          @callback_failure ? nil : @application_listener
-        end
-        return unless listener
-
-        listener.call(event)
-      rescue => callback_error
-        failure = ApplicationCallbackFailure.new(
-          event_type: event.type, error: callback_error
-        )
-        @mutex.synchronize do
-          @callback_failure ||= failure
-          @application_listener = nil
-        end
-        notify_callback_failure(failure)
-      end
-
-      private
-
-      def notify_callback_failure(failure)
-        invocation = @mutex.synchronize { @invocation }
-        if invocation
-          accepted = Phronomy::Runtime.instance.event_loop.post_to_session(
-            Phronomy::Event.new(
-              type: :application_callback_failed,
-              target_id: invocation.id,
-              payload: {failure: failure}
-            )
-          )
-          unless accepted
-            Phronomy.configuration.logger&.warn(
-              "[Phronomy] Callback failure recorded but could not notify FSM: execution_id=#{@execution_id}"
-            )
-          end
-        end
-        Phronomy.configuration.logger&.warn(
-          "[Phronomy] Application event listener failed: #{failure.error.class}: #{failure.error.message}"
-        )
-      end
-    end
-  end
-end

data/lib/phronomy/agent/context_candidate.rb

@@ -1,47 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  module Agent
-    ContextCandidate = Data.define(
-      :candidate_id,
-      :source_kind,
-      :category,
-      :role,
-      :content_ref,
-      :record_id,
-      :agent_id,
-      :execution_id,
-      :llm_call_id,
-      :tool_call_id,
-      :sequence,
-      :requirement,
-      :priority,
-      :metadata
-    ) do
-      def initialize(**values)
-        normalized = values.merge(
-          candidate_id: values.fetch(:candidate_id).to_s.freeze,
-          source_kind: values.fetch(:source_kind).to_sym,
-          category: values.fetch(:category).to_sym,
-          role: values[:role]&.to_sym,
-          content_ref: values.fetch(:content_ref).to_s.freeze,
-          record_id: values[:record_id]&.to_s&.freeze,
-          agent_id: values[:agent_id]&.to_s&.freeze,
-          execution_id: values[:execution_id]&.to_s&.freeze,
-          llm_call_id: values[:llm_call_id]&.to_s&.freeze,
-          tool_call_id: values[:tool_call_id]&.to_s&.freeze,
-          sequence: values[:sequence] && Integer(values[:sequence]),
-          requirement: (values[:requirement] || :optional).to_sym,
-          priority: Integer(values[:priority] || 0),
-          metadata: Immutable.copy(values[:metadata] || {})
-        )
-        unless %i[protocol_required declared_required optional].include?(normalized[:requirement])
-          raise ArgumentError, "unknown ContextCandidate requirement: #{normalized[:requirement].inspect}"
-        end
-
-        super(**normalized)
-        freeze
-      end
-    end
-  end
-end

data/lib/phronomy/agent/context_parts/budget/token_budget_packer.rb

@@ -1,53 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  module Agent
-    module ContextParts
-      module Budget
-        class TokenBudgetPacker
-          def pack(request:, units:)
-            return Array(units).freeze unless request.token_budget
-
-            candidate_index = request.candidates.to_h { |candidate| [candidate.candidate_id, candidate] }
-            mandatory = Integer(request.metadata["mandatory_token_estimate"] || 0)
-            limit = request.token_budget.effective_input_limit
-            if mandatory > limit
-              raise Phronomy::ContextBudgetExceededError,
-                "Mandatory content (estimated #{mandatory} tokens) exceeds " \
-                "available input budget (#{limit} tokens)"
-            end
-
-            remaining = limit - mandatory
-            required, optional = Array(units).partition { |unit| unit.requirement != :optional }
-            required_cost = required.sum { |unit| unit_cost(unit, candidate_index) }
-            if required_cost > remaining
-              raise Phronomy::ContextBudgetExceededError,
-                "Required Context (estimated #{required_cost} tokens) exceeds " \
-                "remaining input budget (#{remaining} tokens after mandatory content)"
-            end
-
-            selected = required.dup
-            remaining -= required_cost
-            optional.each do |unit|
-              cost = unit_cost(unit, candidate_index)
-              next if cost > remaining
-
-              selected << unit
-              remaining -= cost
-            end
-            selected.freeze
-          end
-
-          private
-
-          def unit_cost(unit, candidate_index)
-            unit.candidate_ids.sum do |candidate_id|
-              candidate = candidate_index.fetch(candidate_id)
-              Integer(candidate.metadata["estimated_tokens"] || 0)
-            end
-          end
-        end
-      end
-    end
-  end
-end