phronomy 0.31.0 → 0.32.0

data/lib/phronomy/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Phronomy
-  VERSION = "0.31.0"
+  VERSION = "0.32.0"
 end

data/lib/phronomy/workflow/execution/workflow.rb

@@ -45,6 +45,15 @@ module Phronomy
       @runner.send_event(state: state, event: event, input: input)
     end
 
+    # Applies an explicitly named event to one revision of a saved wait.
+    # The host holds its exclusive claim for this Workflow across the call.
+    # @return [WorkflowContext] the next halted or completed context
+    # @api public
+    def send_saved_event(workflow_instance_id:, expected_revision:, event:, input: nil)
+      @runner.send_saved_event(workflow_instance_id: workflow_instance_id,
+        expected_revision: expected_revision, event: event, input: input)
+    end
+
     # Sends an event to an active Workflow execution without blocking.
     #
     # +workflow_instance_id+ is the logical/durable Workflow identity. EventLoop resolves it

data/lib/phronomy/workflow/execution/workflow_runner.rb

@@ -54,6 +54,7 @@ module Phronomy
       :input,
       :event_name,
       :current_phase,
+      :expected_revision,
       :result_task,
       :workflow_instance_id,
       :owner_token
@@ -141,13 +142,28 @@ module Phronomy
       end
 
       start_resume_execution(
-        state,
+        workflow_instance_id,
+        state: state,
         input: input,
         event_name: event_name,
         current_phase: current_phase
       ).wait_result
     end
 
+    def send_saved_event(workflow_instance_id:, expected_revision:, event:, input: nil)
+      if Phronomy::WaitPolicy.blocking_forbidden?
+        raise Phronomy::EventLoopReentrancyError, "send_saved_event requires a host thread"
+      end
+      unless workflow_instance_id.is_a?(String) && !workflow_instance_id.empty?
+        raise ArgumentError, "workflow_instance_id must be a nonempty String"
+      end
+      unless expected_revision.is_a?(Integer) && expected_revision.positive?
+        raise ArgumentError, "expected_revision must be a positive Integer"
+      end
+      start_resume_execution(workflow_instance_id.dup, expected_revision: expected_revision,
+        input: input, event_name: event).wait_result
+    end
+
     # Posts an application-defined event to the currently live Workflow owner.
     # WorkflowExecutionRegistry resolves workflow_instance_id to the current concrete
     # fsm_session_id. The opaque admission owner token is deliberately not a
@@ -256,8 +272,8 @@ module Phronomy
       result_task || failed_task("workflow:preparation", error)
     end
 
-    def start_resume_execution(state, input:, event_name:, current_phase:)
-      workflow_instance_id = state.workflow_instance_id.to_s.freeze
+    def start_resume_execution(workflow_instance_id, input:, event_name:, state: nil, current_phase: nil, expected_revision: nil)
+      workflow_instance_id = workflow_instance_id.to_s.freeze
       result_task = Phronomy::TaskResult.deferred(name: "workflow-resume:#{workflow_instance_id}")
       Phronomy::Tracing::Automatic.observe_task(
         result_task,
@@ -272,7 +288,8 @@ module Phronomy
         state: state,
         input: input,
         event_name: event_name.to_sym,
-        current_phase: current_phase.to_sym,
+        current_phase: current_phase,
+        expected_revision: expected_revision,
         result_task: result_task,
         workflow_instance_id: workflow_instance_id,
         owner_token: Object.new.freeze
@@ -345,6 +362,7 @@ module Phronomy
 
       repository = configured_repository
       unless repository
+        raise Phronomy::ConfigurationError, "send_saved_event requires Workflow persistence" if request.expected_revision
         context = request.input ? request.state.merge(request.input) : request.state
         execution = Execution.new(
           context: context,
@@ -445,12 +463,9 @@ module Phronomy
         return
       end
 
-      expected_revision = validate_resume_snapshot!(
-        request.state,
-        ready.result.snapshot,
-        ready.result.revision
-      )
-      context = request.input ? request.state.merge(request.input) : request.state
+      state = request.state || restore_saved_wait!(request, ready.result)
+      expected_revision = validate_resume_snapshot!(state, ready.result.snapshot, ready.result.revision)
+      context = request.input ? state.merge(request.input) : state
       execution = Execution.new(
         context: context,
         workflow_instance_id: request.workflow_instance_id,
@@ -465,12 +480,28 @@ module Phronomy
         execution,
         request.result_task,
         resume_event: request.event_name,
-        resume_phase: request.current_phase
+        resume_phase: request.current_phase || state.phase,
+        require_resume_transition: !request.expected_revision.nil?
       )
     rescue => error
       release_and_fail(request, error)
     end
 
+    def restore_saved_wait!(request, loaded)
+      unless loaded.snapshot && loaded.revision == request.expected_revision
+        raise Phronomy::Persistence::StateConflictError,
+          "No saved Workflow at revision #{request.expected_revision} for #{request.workflow_instance_id.inspect}"
+      end
+      phase = record_value(loaded.snapshot, :phase)&.to_sym
+      unless @wait_state_names.include?(phase) && @external_events.fetch(request.event_name, []).any? { |edge| edge[:from] == phase }
+        raise ArgumentError, "No saved wait at #{phase.inspect} accepting #{request.event_name.inspect}"
+      end
+      fields = record_value(loaded.snapshot, :fields)
+      @state_class.new(**restore_context_fields(fields)).set_graph_metadata(
+        workflow_instance_id: request.workflow_instance_id, phase: phase
+      )
+    end
+
     def build_new_execution(
       input,
       workflow_instance_id:,
@@ -487,9 +518,7 @@ module Phronomy
       stored_fields = loaded_snapshot &&
         (loaded_snapshot[:fields] || loaded_snapshot["fields"])
       initial_fields = if stored_fields
-        stored_fields
-          .transform_keys(&:to_sym)
-          .merge(input.transform_keys(&:to_sym))
+        restore_context_fields(stored_fields).merge(input.transform_keys(&:to_sym))
       else
         input
       end
@@ -509,6 +538,21 @@ module Phronomy
       )
     end
 
+    # The repository and the load message own immutable snapshots. Actions receive
+    # their own mutable field values, including strings nested in arrays or hashes.
+    def restore_context_fields(fields)
+      fields.to_h { |name, value| [name.to_sym, mutable_field_value(value)] }
+    end
+
+    def mutable_field_value(value)
+      case value
+      when Hash then value.transform_values { |child| mutable_field_value(child) }
+      when Array then value.map { |child| mutable_field_value(child) }
+      when String then value.dup
+      else value
+      end
+    end
+
     def validate_resume_snapshot!(state, durable_snapshot, durable_revision)
       return nil unless durable_snapshot
 
@@ -576,6 +620,7 @@ module Phronomy
       result_task,
       resume_event: nil,
       resume_phase: nil,
+      require_resume_transition: false,
       stable_observer: nil
     )
       assert_execution_owner!
@@ -588,6 +633,7 @@ module Phronomy
         execution: execution,
         resume_event: resume_event,
         resume_phase: resume_phase,
+        require_resume_transition: require_resume_transition,
         stable_observer: stable_observer,
         task_execution: task_execution
       )
@@ -769,6 +815,7 @@ module Phronomy
       execution:,
       resume_event: nil,
       resume_phase: nil,
+      require_resume_transition: false,
       stable_observer: nil,
       task_execution: nil
     )
@@ -787,6 +834,7 @@ module Phronomy
         recursion_limit: execution.recursion_limit,
         resume_event: resume_event,
         resume_phase: resume_phase,
+        require_resume_transition: require_resume_transition,
         stable_observer: stable_observer,
         persist: terminal_persistence_callback(execution),
         task_execution: task_execution

data/scripts/api_snapshot.rb

@@ -30,6 +30,8 @@ PUBLIC_API_ENTRIES = [
   Phronomy::Embeddings::AuthenticationError,
   Phronomy::Embeddings::RateLimitError,
   Phronomy::Agent::Base,
+  Phronomy::Agent::HostedInvocation,
+  Phronomy::Agent::ApprovalWait,
   Phronomy::Agent::ReservedExecution,
   Phronomy::Agent::ExecutionObservation,
   Phronomy::Agent::KnowledgeItem,

data/sig/phronomy/agent/execution_contract.rbs

@@ -4,6 +4,19 @@ module Phronomy
     type execution_wiring = { ?phronomy_execution_participant: _ExecutionParticipant, ?phronomy_control_bindings: Array[_ControlCapability], ?phronomy_transfer_context: TransferContext, ?phronomy_admission: _AdmissionOwner, ?phronomy_reservation: Hash[String, json_value] }
     type execution_result = { agent_id: String, execution_id: String, status: Symbol, result: json_value, output: json_value, ?raw_output: String?, error: Hash[String, json_value]? }
 
+    class ApprovalWait < Data
+      attr_reader execution_id: String
+      attr_reader approval_request_id: String
+      attr_reader execution_revision: Integer
+      def self.new: (execution_id: String, approval_request_id: String, execution_revision: Integer) -> instance
+    end
+
+    class HostedInvocation
+      def on_complete: () { (untyped, StandardError?) -> untyped } -> self
+      def detach!: (approval_request_id: String, ?execution_id: String) -> ApprovalWait
+      def wait_result: (?timeout: Numeric?) -> (execution_result | ApprovalWait)
+    end
+
     class ReservedExecution < Data
       attr_reader agent_id: String
       attr_reader execution_id: String

data/sig/phronomy/agent/store.rbs

@@ -54,6 +54,7 @@ module Phronomy
       def authorized_operations: (::Phronomy::Persistence::Transaction scope, agent_id: String, execution_id: String, invocation_id: String, name: String, arguments: Hash[String, untyped], names: Array[String]) -> Array[AuthorizedOperation]
       def result: (String execution_id) -> Hash[Symbol, untyped]
       def runs: (String owner_id, ?after: String?, ?limit: Integer) -> Array[untyped]
+      def standalone_approval_wait: (agent_id: String, execution_id: String, ?scope: ::Phronomy::Persistence::Transaction?) -> ApprovalWait?
       def observe_execution: (agent_id: String, execution_id: String, ?scope: ::Phronomy::Persistence::Transaction?) -> ExecutionObservation
       def active_executions: (agent_id: String, ?scope: ::Phronomy::Persistence::Transaction?) -> Array[ExecutionObservation]
       def definition: (agent_id: String, ?scope: ::Phronomy::Persistence::Transaction?) -> { id: String, version: Integer }

data/sig/phronomy/agent.rbs

@@ -108,6 +108,7 @@ module Phronomy
       attr_reader persistence: Store
       def knowledge_snapshot: () -> Array[KnowledgeItem]
       def event_listener: () -> (^(Object) -> void)?
+      def start_hosted: (reservation: ReservedExecution, input: String, ?config: Hash[Symbol, Object], ?output_schema: Hash[String | Symbol, untyped]?, ?schema_delivery: (:native | :none)?) -> HostedInvocation
       def start_reserved_async: (reservation: ReservedExecution, input: String, ?config: Hash[Symbol, Object], ?output_schema: Hash[String | Symbol, untyped]?, ?schema_delivery: (:native | :none)?) -> TaskResult[execution_result]
       def resume_async: (String execution_id, ?config: Hash[Symbol, Object]) -> TaskResult[execution_result]
       def resume: (String execution_id, ?config: Hash[Symbol, Object]) -> execution_result

data/sig/phronomy/multi_agent.rbs

@@ -23,6 +23,8 @@ module Phronomy
       def self.create: (?coordination_store: Store?, **Object options) ?{ (Object) -> void } -> instance
       def self.load: (String agent_id, persistence: Agent::Store, coordination_store: Store, **Object options) ?{ (Object) -> void } -> instance
       def self.subagent: (Symbol | String name, singleton(::Phronomy::Agent::Base) agent_class, ?on_error: Symbol, ?inherit_knowledge: bool) -> untyped
+      def unload_with_completed_child!: (String parent_execution_id, execution_id: String) -> bool
+      def approve_hosted_child: (String parent_execution_id, execution_id: String, approval_request_id: String, ?approved: bool, ?config: Hash[Symbol, untyped]) -> ::Phronomy::Agent::HostedInvocation
       def self.registered_subagents: () -> Hash[Symbol | String, untyped]
       def resume: (String execution_id, ?config: Hash[Symbol, untyped]) -> Hash[Symbol, untyped]
       def dispatch_parallel: (*Hash[Symbol, untyped] tasks, ?max_concurrency: Integer?, ?on_error: Symbol, ?timeout: Numeric?, ?cancellation_token: untyped, ?invocation_context: untyped, ?inherit_knowledge: bool) -> Array[untyped]

data/sig/phronomy/workflow.rbs

@@ -18,6 +18,7 @@ module Phronomy
     def stream: (untyped input, ?config: Hash[untyped, untyped], ?invocation_context: untyped) { (untyped) -> void } -> untyped
     def resume: (state: untyped, ?input: untyped) -> untyped
     def send_event: (state: untyped, event: Symbol, ?input: untyped) -> untyped
+    def send_saved_event: (workflow_instance_id: String, expected_revision: Integer, event: Symbol, ?input: untyped) -> untyped
     def signal: (workflow_instance_id: String, event: Symbol, ?payload: untyped) -> bool
 
     class Builder

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: phronomy
 version: !ruby/object:Gem::Version
-  version: 0.31.0
+  version: 0.32.0
 platform: ruby
 authors:
 - Raizo T.C.S
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-10-25 00:00:00.000000000 Z
+date: 2026-11-03 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ruby_llm
@@ -389,6 +389,7 @@ files:
 - lib/phronomy/agent/agent_unloaded_error.rb
 - lib/phronomy/agent/api/agent.rb
 - lib/phronomy/agent/api/execution_rehydration_required_error.rb
+- lib/phronomy/agent/approval_wait.rb
 - lib/phronomy/agent/async_event_api.rb
 - lib/phronomy/agent/base.rb
 - lib/phronomy/agent/before_llm_input.rb
@@ -429,6 +430,7 @@ files:
 - lib/phronomy/agent/knowledge_item.rb
 - lib/phronomy/agent/lifecycle/agent_root.rb
 - lib/phronomy/agent/lifecycle/default_persistence.rb
+- lib/phronomy/agent/lifecycle/hosted_invocation.rb
 - lib/phronomy/agent/lifecycle/lifetime_api.rb
 - lib/phronomy/agent/lifecycle/operation_lease.rb
 - lib/phronomy/agent/lifecycle/operation_result.rb