phronomy 0.17.0 → 0.19.0

data/lib/phronomy/agent/base.rb

@@ -252,24 +252,22 @@ module Phronomy
           new(agent_id: agent_id, persistence: persistence, load_existing: true)
         end
 
-        def approve(execution_id, approval_request_id:, persistence:, approved: true, config: {})
-          approve_async(
-            execution_id,
-            approval_request_id: approval_request_id,
-            approved: approved,
-            config: config,
-            persistence: persistence
-          ).wait_result
-        end
-
-        def approve_async(execution_id, approval_request_id:, persistence:, approved: true, config: {})
-          execution = persistence.executions.load(execution_id)
-          load(execution.agent_id, persistence: persistence).approve_async(
-            execution_id,
-            approval_request_id: approval_request_id,
-            approved: approved,
-            config: config
-          )
+        # Resolves the live Agent instance that currently owns execution_id in
+        # this process. This is a Runtime-local lookup, not durable rehydration.
+        def live_for_execution(execution_id)
+          activation = Phronomy::Runtime.instance.__agent_activations.fetch(execution_id)
+          unless activation
+            raise Phronomy::ExecutionRehydrationRequiredError,
+              "no live activation for #{execution_id}; durable rehydration is required"
+          end
+
+          agent = activation.agent
+          unless agent.is_a?(self)
+            raise ArgumentError,
+              "live activation #{execution_id} belongs to #{agent.class}, not #{self}"
+          end
+
+          agent
         end
       end
 
@@ -283,21 +281,33 @@ module Phronomy
         metadata: {},
         load_existing: false
       )
-        @persistence = persistence || Phronomy::Persistence::InMemory.new
+        @persistence = persistence ||
+          Phronomy.configuration.persistence ||
+          Phronomy::Persistence::InMemory.new
         @agent_id = agent_id.to_s.freeze
-        @root = if load_existing
-          loaded = @persistence.agents.load(@agent_id)
-          definition = self.class.agent_definition
-          unless loaded.agent_definition_id == definition.fetch(:id) &&
-              loaded.definition_version == definition.fetch(:version)
-            raise Phronomy::ConfigurationError,
-              "Agent definition mismatch for #{@agent_id}: stored " \
-              "#{loaded.agent_definition_id}@#{loaded.definition_version}, runtime " \
-              "#{definition.fetch(:id)}@#{definition.fetch(:version)}"
+
+        if load_existing
+          root = records = nil
+          @persistence.transaction do |tx|
+            root = tx.agents.load(@agent_id)
+            records = tx.journals.read(
+              @agent_id,
+              limit: root.journal_position
+            )
           end
-          loaded
+          validate_loaded_definition!(root)
+          @root = root
+          @_phronomy_journal_records = Array(records).dup.freeze
         else
-          create_agent_root!(context: context, knowledge: knowledge, metadata: metadata)
+          @root = create_agent_root!(
+            context: context,
+            knowledge: knowledge,
+            metadata: metadata
+          )
+          @_phronomy_journal_records = @persistence.journals.read(
+            @agent_id,
+            limit: @root.journal_position
+          ).dup.freeze
         end
       end
 
@@ -306,7 +316,10 @@ module Phronomy
       end
 
       def journal_projection
-        Agent::JournalProjection.new(persistence: persistence, agent_root: @root)
+        Agent::JournalProjection.new(
+          agent_root: @root,
+          records: _journal_records_snapshot
+        )
       end
 
       def transcript
@@ -334,13 +347,14 @@ module Phronomy
         end
       end
 
-      # Appends persistent Knowledge to the Agent Journal.
-      # Knowledge is an optional Context candidate; it is not part of #transcript.
+      # Appends persistent Knowledge to the Agent Journal. The live Agent owns the
+      # current logical root/Journal view; Persistence is advanced optimistically.
       def add_knowledge(content, metadata: {})
+        current = agent_root
         next_root = nil
+        appended = nil
         persistence.transaction do |tx|
           tx.executions.assert_idle!(agent_id)
-          current = tx.agents.load(agent_id)
           record = build_knowledge_record(
             tx: tx,
             root: current,
@@ -363,6 +377,7 @@ module Phronomy
             root: next_root
           )
         end
+        _append_journal_records(appended)
         @root = next_root
         self
       end
@@ -394,6 +409,7 @@ module Phronomy
           tx.agents.delete(agent_id)
         end
         @root = nil
+        @_phronomy_journal_records = [].freeze
         true
       end
 
@@ -404,6 +420,17 @@ module Phronomy
 
       private
 
+      def validate_loaded_definition!(loaded)
+        definition = self.class.agent_definition
+        return if loaded.agent_definition_id == definition.fetch(:id) &&
+          loaded.definition_version == definition.fetch(:version)
+
+        raise Phronomy::ConfigurationError,
+          "Agent definition mismatch for #{@agent_id}: stored " \
+          "#{loaded.agent_definition_id}@#{loaded.definition_version}, runtime " \
+          "#{definition.fetch(:id)}@#{definition.fetch(:version)}"
+      end
+
       def create_agent_root!(context:, knowledge:, metadata:)
         definition = self.class.agent_definition
         root = Agent::AgentRoot.create(
@@ -480,10 +507,11 @@ module Phronomy
       end
 
       def mutate_context!(kind, context_affecting: true)
+        current = agent_root
         next_root = nil
+        appended = nil
         persistence.transaction do |tx|
           tx.executions.assert_idle!(agent_id)
-          current = tx.agents.load(agent_id)
           record = Agent::JournalRecord.new(
             agent_id: agent_id,
             kind: kind,
@@ -502,8 +530,13 @@ module Phronomy
             context_revision: context_affecting ?
               yield_context_revision(current, proposed) : current.context_revision
           )
-          tx.agents.save(agent_id, expected_revision: current.agent_revision, root: next_root)
+          tx.agents.save(
+            agent_id,
+            expected_revision: current.agent_revision,
+            root: next_root
+          )
         end
+        _append_journal_records(appended)
         @root = next_root
       end
 
@@ -511,6 +544,18 @@ module Phronomy
         (proposed.context_revision == current.context_revision) ? current.context_revision + 1 : proposed.context_revision
       end
 
+      def _journal_records_snapshot
+        @_phronomy_journal_records || [].freeze
+      end
+
+      def _append_journal_records(records)
+        incoming = Array(records)
+        return _journal_records_snapshot if incoming.empty?
+
+        @_phronomy_journal_records =
+          (_journal_records_snapshot + incoming).freeze
+      end
+
       public
 
       def _add_handoff_tool(tool_class)
@@ -553,35 +598,20 @@ module Phronomy
         [effective_thread_id, effective_config]
       end
 
-      def _check_scheduler_reentrancy(sync_method, async_method)
+      def _check_event_loop_reentrancy(sync_method, async_method)
         if Phronomy::Runtime.instance.event_loop.current?
-          raise Phronomy::SchedulerReentrancyError,
+          raise Phronomy::EventLoopReentrancyError,
             "#{self.class.name}##{sync_method} cannot run on the EventLoop thread. " \
             "Use #{async_method} and return immediately."
         end
-
-        return unless Phronomy::Task.current
-
-        msg = "#{self.class.name}##{sync_method} called from inside a scheduler task. " \
-          "This blocks the scheduler until the inner invocation completes, preventing " \
-          "other tasks from making progress. Use #{async_method} + await instead."
-        if Phronomy.configuration.strict_runtime_guards
-          raise Phronomy::SchedulerReentrancyError, msg
-        elsif Phronomy.configuration.logger
-          Phronomy.configuration.logger.warn(msg)
-        else
-          Kernel.warn("[phronomy] WARNING: #{msg}")
-        end
       end
 
       def _complete_result_task(task, result)
-        task.backend.unblock(result, nil)
-        task.transition!(:completed, value: result)
+        task.complete(result)
       end
 
       def _fail_result_task(task, error)
-        task.backend.unblock(nil, error)
-        task.transition!(:failed, error: error)
+        task.fail(error)
       end
 
       def _translated_error(error)
@@ -782,6 +812,10 @@ module Phronomy
         return resolved if result_filters.empty?
 
         effective_name = resolved.new.name
+        custom_async_call =
+          resolved.instance_method(:call_async).owner !=
+          Phronomy::Agent::Context::Capability::Base
+
         Class.new(resolved) do
           tool_name effective_name
           define_method(:call) do |args, **kwargs|
@@ -790,6 +824,33 @@ module Phronomy
               filter.call(val, tool_name: name, args: args)
             }
           end
+
+          # Base#call_async ultimately executes #call, so the synchronous wrapper
+          # above already applies filters for ordinary Tools. Agent-backed Tools
+          # override #call_async and bypass #call; only those custom async Tools
+          # need an asynchronous result-filter wrapper here.
+          if custom_async_call
+            define_method(:call_async) do |args, **kwargs|
+              source = super(args, **kwargs)
+              filtered = Phronomy::Task.deferred(name: "tool-filter-#{name}")
+              source.on_complete do |value, error|
+                if error
+                  filtered.fail(error)
+                  next
+                end
+
+                begin
+                  result = result_filters.inject(value) { |val, filter|
+                    filter.call(val, tool_name: name, args: args)
+                  }
+                  filtered.complete(result)
+                rescue => filter_error
+                  filtered.fail(filter_error)
+                end
+              end
+              filtered
+            end
+          end
         end
       end
     end

data/lib/phronomy/agent/context/capability/base.rb

@@ -113,16 +113,22 @@ module Phronomy
 
             public
 
+            # Declares whether Tool work is safe to run cooperatively on the EventLoop
+            # or must be offloaded to a bounded worker pool.
+            #
+            # Phronomy does not classify the reason for offloading. Blocking I/O,
+            # CPU-bound synchronous work, and other long synchronous calls all use
+            # +:offloaded+. The application owns that workload classification.
             # @api public
             def execution_mode(value = nil)
               if value.nil?
                 return @execution_mode if instance_variable_defined?(:@execution_mode)
                 return superclass.execution_mode if superclass.respond_to?(:execution_mode)
 
-                return :blocking_io
+                return :offloaded
               end
 
-              valid = %i[cooperative blocking_io cpu_bound external_process]
+              valid = %i[cooperative offloaded]
               unless valid.include?(value)
                 raise ArgumentError,
                   "execution_mode must be one of #{valid.inspect}, got #{value.inspect}"
@@ -296,7 +302,11 @@ module Phronomy
           end
 
           # @api public
-          def call_async(args, cancellation_token: nil, config: {})
+          def call_async(
+            args,
+            cancellation_token: nil,
+            config: {}
+          )
             Phronomy::Agent::ToolExecutor.call_async(
               tool: self,
               args: args,

data/lib/phronomy/agent/context_assembler.rb

@@ -14,18 +14,20 @@ module Phronomy
         agent:,
         persistence:,
         policy: ContextPolicies::Default.new,
-        candidate_resolver: nil
+        candidate_resolver: nil,
+        journal_records: nil
       )
         @agent = agent
         @persistence = persistence
         @policy = policy
+        @journal_records = journal_records
         @candidate_resolver = candidate_resolver || ContextCandidateResolver.new(
           content_loader: method(:fetch_content)
         )
       end
 
       def build_initial(input:, agent_root:, execution:, config: {}, patch: LLMInputPatch.empty)
-        projection = JournalProjection.new(persistence: @persistence, agent_root: agent_root)
+        projection = journal_projection(agent_root)
         model_cfg = effective_model_config(config, patch)
         tool_set = ToolDefinitionSet.build(@agent)
         system_text = build_system_text(input)
@@ -65,7 +67,7 @@ module Phronomy
         config: {},
         patch: LLMInputPatch.empty
       )
-        projection = JournalProjection.new(persistence: @persistence, agent_root: agent_root)
+        projection = journal_projection(agent_root)
         model_cfg = effective_model_config(config, patch)
         hook_candidates = normalize_candidates(patch.segment_candidates)
         system_segments = base_manifest.segments.select do |segment|
@@ -96,6 +98,14 @@ module Phronomy
 
       private
 
+      def journal_projection(agent_root)
+        if @journal_records
+          JournalProjection.new(agent_root: agent_root, records: @journal_records)
+        else
+          JournalProjection.new(persistence: @persistence, agent_root: agent_root)
+        end
+      end
+
       def assemble(
         agent_root:,
         execution:,