phronomy 0.30.1 → 0.31.0

data/lib/phronomy/tools/agent.rb

@@ -7,13 +7,30 @@ module Phronomy
     # Agent-backed Tools are logically asynchronous rather than offloaded
     # synchronous operations. Their ToolInvocation starts the child Agent and then
     # returns to EventLoop immediately; the Tool completion handle settles when the
-    # child Agent FSMSession finishes. An OffloadPool worker is therefore never
-    # consumed merely to wait for another Agent.
+    # child Agent's physical work and release finish. An OffloadPool worker is
+    # therefore never consumed merely to wait for another Agent.
     class Agent < Phronomy::Tool::Base
       execution_mode :cooperative
       description "Wraps a Phronomy::Agent as a Tool"
       param :input, type: :string, desc: "The input to forward to the wrapped Agent"
 
+      # A private child's operation ended, but its safe release failed. The live
+      # reference supports retrying unload_async without repeating business work.
+      # This error and its child reference are process-local, not durable state.
+      # @api public
+      class CleanupError < Phronomy::ToolError
+        attr_reader :child_agent, :agent_id, :result, :primary_error, :cleanup_error
+
+        def initialize(child_agent:, result:, primary_error:, cleanup_error:)
+          @child_agent = child_agent
+          @agent_id = child_agent.agent_id
+          @result = result
+          @primary_error = primary_error
+          @cleanup_error = cleanup_error
+          super("Agent Tool cleanup failed for #{@agent_id.inspect}", code: "tool.agent_cleanup_failed")
+        end
+      end
+
       class << self
         def from_agent(agent_class, tool_name: nil, description: nil)
           raise ArgumentError, "agent_class must be a Class" unless agent_class.is_a?(Class)
@@ -35,36 +52,34 @@ module Phronomy
           # Preserve the synchronous Tool API for top-level callers. ToolInvocation
           # never uses this path for Agent-backed Tools; it calls #call_async.
           klass.define_method(:execute) do |input:, cancellation_token: nil|
-            invoke_options = {}
-            if cancellation_token
-              invoke_options[:config] = {cancellation_token: cancellation_token}
+            if Phronomy::WaitPolicy.blocking_forbidden?
+              raise Phronomy::EventLoopReentrancyError,
+                "Agent Tool execute cannot block EventLoop; use call_async"
             end
-            # Use the same supplied store factory as the asynchronous path.
-            # Preserve the creation arguments previously supplied by run_once.
-            persistence = Phronomy::Agent::DefaultPersistence.build
-            agent = agent_class.create(
-              context: nil,
-              knowledge: [],
-              persistence: persistence,
-              on_event: nil
-            )
-            result = agent.invoke(input, **invoke_options)
-            result[:output].to_s
+            execute_async(input: input, cancellation_token: cancellation_token).wait_result
           end
 
           # Internal asynchronous execution protocol used by Agent#call_async.
-          # The child Agent owns its own FSMSession/EventLoop lifecycle; this
-          # method only returns its completion handle and performs a short map.
+          # C04 decides whether release is safe; C13 composes completion. The
+          # concrete Tool supplies only creation, output and cleanup policies.
           klass.define_method(:execute_async) do |input:, cancellation_token: nil, config: {}|
-            persistence = Phronomy::Agent::DefaultPersistence.build
-            agent = agent_class.create(persistence: persistence)
+            unless config.nil? || config.is_a?(Hash)
+              raise ArgumentError, "Agent Tool config must be a Hash"
+            end
             task_config = (config || {}).dup
             if cancellation_token && !task_config[:cancellation_token]
               task_config[:cancellation_token] = cancellation_token
             end
 
-            agent.invoke_async(input, config: task_config).map do |result|
-              result[:output].to_s
+            persistence = Phronomy::Agent::DefaultPersistence.build
+            agent = agent_class.create(persistence: persistence)
+            Phronomy::AsyncOperation.finalize(name: "agent-tool-#{name}-release",
+              cleanup: -> { agent.unload_async },
+              on_cleanup_error: ->(value, primary, cleanup) { child_cleanup_failed(agent, value, primary, cleanup) }) do
+              Phronomy::AsyncOperation.call(name: "agent-tool-#{name}-invoke",
+                transform: ->(result) { result[:output].to_s }) do
+                agent.invoke_async(input, config: task_config)
+              end
             end
           end
           klass.send(:private, :execute_async)
@@ -102,6 +117,27 @@ module Phronomy
 
       private
 
+      def child_cleanup_failed(agent, result, primary_error, cleanup_error)
+        failure = CleanupError.new(child_agent: agent, result: result,
+          primary_error: primary_error, cleanup_error: cleanup_error)
+        # Always report cleanup failures: an outer observer may already have
+        # cancelled its handle, so returning an error alone is not sufficient.
+        report_child_cleanup_failure(failure)
+        raise failure, cause: primary_error || cleanup_error
+      end
+
+      def report_child_cleanup_failure(failure)
+        details = {"agent_id" => failure.agent_id, "code" => failure.code,
+                   "cleanup_error" => Phronomy::Error.diagnostic(failure.cleanup_error)}
+        details["primary_error"] = Phronomy::Error.diagnostic(failure.primary_error) if failure.primary_error
+        message = "[Phronomy] Agent Tool cleanup failed: #{details.inspect}"
+        logger = Phronomy::RuntimeSettings.current.logger
+        logger ? logger.error(message) : warn(message)
+      rescue
+        # Diagnostics cannot change the combined error or repeat the operation.
+        nil
+      end
+
       # Subclasses created by .from_agent override this method.
       # It deliberately remains private so it is not part of the public Tool API.
       def execute_async(input:, cancellation_token: nil, config: {})

data/lib/phronomy/version.rb

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

data/sig/phronomy/agent.rbs

@@ -108,7 +108,7 @@ module Phronomy
       attr_reader persistence: Store
       def knowledge_snapshot: () -> Array[KnowledgeItem]
       def event_listener: () -> (^(Object) -> void)?
-      def start_reserved_async: (reservation: ReservedExecution, input: String, ?config: Hash[Symbol, Object], ?output_schema: Hash[String | Symbol, untyped]?) -> TaskResult[execution_result]
+      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
       def cancel_async: (String execution_id) -> TaskResult[ExecutionObservation]
@@ -116,10 +116,10 @@ module Phronomy
 
       # Public operation methods no longer accept per-invocation event listeners
       # or event-listener blocks.
-      def invoke: (untyped input, ?config: Hash[untyped, untyped], ?invocation_context: untyped, ?output_schema: Hash[String | Symbol, untyped]?) -> Hash[Symbol, untyped]
-      def invoke_async: (untyped input, ?config: Hash[untyped, untyped], ?invocation_context: untyped, ?output_schema: Hash[String | Symbol, untyped]?) -> TaskResult[Hash[Symbol, untyped]]
-      def stream: (untyped input, ?config: Hash[untyped, untyped], ?invocation_context: untyped, ?output_schema: Hash[String | Symbol, untyped]?) -> Hash[Symbol, untyped]
-      def stream_async: (untyped input, ?config: Hash[untyped, untyped], ?invocation_context: untyped, ?output_schema: Hash[String | Symbol, untyped]?) -> TaskResult[Hash[Symbol, untyped]]
+      def invoke: (untyped input, ?config: Hash[untyped, untyped], ?invocation_context: untyped, ?output_schema: Hash[String | Symbol, untyped]?, ?schema_delivery: (:native | :none)?) -> Hash[Symbol, untyped]
+      def invoke_async: (untyped input, ?config: Hash[untyped, untyped], ?invocation_context: untyped, ?output_schema: Hash[String | Symbol, untyped]?, ?schema_delivery: (:native | :none)?) -> TaskResult[Hash[Symbol, untyped]]
+      def stream: (untyped input, ?config: Hash[untyped, untyped], ?invocation_context: untyped, ?output_schema: Hash[String | Symbol, untyped]?, ?schema_delivery: (:native | :none)?) -> Hash[Symbol, untyped]
+      def stream_async: (untyped input, ?config: Hash[untyped, untyped], ?invocation_context: untyped, ?output_schema: Hash[String | Symbol, untyped]?, ?schema_delivery: (:native | :none)?) -> TaskResult[Hash[Symbol, untyped]]
 
       def approve: (String execution_id, approval_request_id: String, ?approved: bool, ?config: Hash[untyped, untyped]) -> untyped
       def approve_async: (String execution_id, approval_request_id: String, ?approved: bool, ?config: Hash[untyped, untyped]) -> TaskResult[untyped]
@@ -131,6 +131,8 @@ module Phronomy
       def resolve_async: (String execution_id, expected_execution_revision: Integer, subject: Hash[Symbol, untyped], outcome: Symbol, ?result: untyped, ?error: Exception) -> TaskResult[untyped]
 
       def transcript: () -> Array[untyped]
+      def transcript_messages: () -> Array[LLMAdapter::Message]
+      def transcript_messages_async: () -> TaskResult[Array[LLMAdapter::Message]]
       def add_knowledge: (untyped content, ?metadata: Hash[untyped, untyped]) -> self
       def clear_transcript!: () -> untyped
       def clear_knowledge!: () -> untyped

data/sig/phronomy/execution/async_operation.rbs

@@ -3,5 +3,6 @@ module Phronomy
     def self.map: [A, B] (_CompletionHandle[A] source, name: String, ?on_error: (^(Exception) -> B)?) { (A) -> B } -> TaskResult[B]
     def self.call: [A, B] (name: String, ?on_error: (^(Exception) -> B)?, ?transform: ^(A) -> B) { () -> _CompletionHandle[A] } -> TaskResult[B]
     def self.capture: [V] (name: String, ?on_error: (^(Exception) -> V)?) { () -> V } -> TaskResult[V]
+    def self.finalize: [V] (name: String, cleanup: ^() -> TaskResult[untyped], on_cleanup_error: ^(V?, Exception?, Exception) -> Exception) { () -> TaskResult[V] } -> TaskResult[V]
   end
 end

data/sig/phronomy/generation/generator_verifier.rbs

@@ -10,7 +10,7 @@ module Phronomy
     def self.open: [R] (**untyped options) { (GeneratorVerifier pipeline) -> (R | TaskResult[R]) } -> R
     def initialize: (draft_agent: singleton(Agent::Base), review_agent: singleton(Agent::Base),
       draft_prompt_builder: untyped, review_prompt_builder: untyped,
-      ?citation_schema: Hash[String | Symbol, untyped],
+      ?citation_schema: Hash[String | Symbol, untyped], ?schema_delivery: (:native | :none),
       ?confidence_threshold: Numeric, ?max_iterations: Integer,
       ?raise_if_unaccepted: bool, ?on_approval: _ApprovalListener?) -> void
     def invoke: (untyped input, ?config: Hash[Symbol, untyped]) -> Result

data/sig/phronomy/tools/agent.rbs

@@ -0,0 +1,14 @@
+module Phronomy
+  module Tools
+    class Agent < Phronomy::Tool::Base
+      class CleanupError < Phronomy::ToolError
+        attr_reader child_agent: Phronomy::Agent::Base
+        attr_reader agent_id: String
+        attr_reader result: untyped
+        attr_reader primary_error: Exception?
+        attr_reader cleanup_error: Exception
+        def initialize: (child_agent: Phronomy::Agent::Base, result: untyped, primary_error: Exception?, cleanup_error: Exception) -> void
+      end
+    end
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: phronomy
 version: !ruby/object:Gem::Version
-  version: 0.30.1
+  version: 0.31.0
 platform: ruby
 authors:
 - Raizo T.C.S
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-10-24 00:00:00.000000000 Z
+date: 2026-10-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ruby_llm
@@ -193,6 +193,7 @@ files:
 - docs/architecture/agent-configuration-and-tool-binding.md
 - docs/architecture/agent-context.md
 - docs/architecture/agent-iteration-budget.md
+- docs/architecture/agent-tool-child-lifetime.md
 - docs/architecture/agent-transition-ownership.md
 - docs/architecture/backend-groups.md
 - docs/architecture/before-llm-input.md
@@ -341,6 +342,7 @@ files:
 - docs/migrations/0.16.md
 - docs/migrations/0.19.md
 - docs/migrations/0.22.md
+- docs/migrations/0.31.md
 - docs/migrations/durable-semantic-coordination-v2.md
 - docs/migrations/handoff-runner-multi-agent.md
 - docs/migrations/neutral-storage-spi.md
@@ -534,6 +536,7 @@ files:
 - lib/phronomy/execution/concurrency/physical_completion_task.rb
 - lib/phronomy/execution/concurrency/result_collector.rb
 - lib/phronomy/execution/concurrency/result_composition.rb
+- lib/phronomy/execution/concurrency/result_finalization.rb
 - lib/phronomy/execution/concurrency/result_subscriptions.rb
 - lib/phronomy/execution/concurrency/subscriptions.rb
 - lib/phronomy/execution/concurrency/worker_input_restricted.rb
@@ -818,6 +821,7 @@ files:
 - sig/phronomy/storage/backends/in_memory.rbs
 - sig/phronomy/storage/contracts.rbs
 - sig/phronomy/tool.rbs
+- sig/phronomy/tools/agent.rbs
 - sig/phronomy/tracing/observation.rbs
 - sig/phronomy/vector_store/async/async_client.rbs
 - sig/phronomy/vector_store/base.rbs