phronomy 0.17.0 → 0.19.0

data/lib/phronomy/agent/journal_projection.rb

@@ -10,9 +10,13 @@ module Phronomy
       ].freeze
       KNOWLEDGE_RESET_KINDS = %i[knowledge_cleared context_reset].freeze
 
-      def initialize(persistence:, agent_root:)
+      def initialize(agent_root:, persistence: nil, records: nil)
         @persistence = persistence
         @agent_root = agent_root
+        @records = records&.dup&.freeze
+        if @records.nil? && @persistence.nil?
+          raise ArgumentError, "JournalProjection requires persistence: or records:"
+        end
       end
 
       def transcript_records

data/lib/phronomy/agent/shared_state.rb

@@ -144,6 +144,7 @@ module Phronomy
           tool_name "read_store"
           description "Read all current findings from the shared knowledge store. " \
             "Call this to see what other researchers have discovered."
+          execution_mode :cooperative
 
           define_method(:execute) { store.read_all.to_json }
         end
@@ -152,6 +153,7 @@ module Phronomy
           tool_name "write_finding"
           description "Record a new finding into the shared knowledge store so " \
             "that other researchers can build on your discovery."
+          execution_mode :cooperative
           param :content, type: :string, desc: "The finding to record"
 
           define_method(:execute) do |content:|

data/lib/phronomy/agent/tool_executor.rb

@@ -2,90 +2,48 @@
 
 module Phronomy
   module Agent
-    # Centralises Tool execution routing based on execution_mode.
+    # Routes Tool work according to the Tool execution contract.
     #
-    # Tool-specific timeout and retry belong to the Tool implementation or its
-    # underlying client. This executor only chooses the Phronomy execution
-    # resource and propagates cooperative cancellation.
-    # @api private
+    # :cooperative Tool calls execute inline and must return quickly. call_async
+    # wraps their result in an already-settled Task and never consumes an
+    # OffloadPool worker.
+    #
+    # :offloaded Tool calls route synchronous work through OffloadPool. Phronomy
+    # does not distinguish whether the reason is blocking I/O, CPU-bound work, or
+    # another long synchronous operation.
     module ToolExecutor
-      WARNED_MODES = Set.new
-      WARNED_MODES_MUTEX = Mutex.new
-      private_constant :WARNED_MODES, :WARNED_MODES_MUTEX
-
-      # Agent-owned execution boundary. Only a ToolInvocation that has consumed
-      # authorization may enter this method.
-      def self.call_invocation_async(
-        tool_invocation:,
-        cancellation_token: nil,
-        config: {},
-        runtime: Phronomy::Runtime.instance
-      )
-        unless tool_invocation.dispatchable?
-          raise Phronomy::ToolError,
-            "ToolInvocation #{tool_invocation.id} is not authorized for dispatch"
-        end
-
-        call_async(
-          tool: tool_invocation.tool,
-          args: tool_invocation.arguments,
-          cancellation_token: cancellation_token,
-          config: config,
-          runtime: runtime
-        )
-      end
-
-      # Low-level Tool API used by direct Tool#call_async callers. Agent execution
-      # must use .call_invocation_async so authorization cannot be bypassed.
-      #
-      # +config+ remains available for invocation metadata, but Phronomy does not
-      # interpret it as a Tool timeout or retry policy.
       def self.call_async(
         tool:,
         args:,
         cancellation_token: nil,
         config: {},
-        runtime: Phronomy::Runtime.instance
+        runtime: nil,
+        on_full: :raise
       )
-        ct = cancellation_token
         mode = tool.class.execution_mode
 
-        if mode == :cpu_bound || mode == :external_process
-          warn_key = [tool.class.name, mode]
-          newly_warned = WARNED_MODES_MUTEX.synchronize { WARNED_MODES.add?(warn_key) }
-          if newly_warned
-            message = if mode == :cpu_bound
-              "[Phronomy] Tool #{tool.class.name} declares execution_mode :cpu_bound, " \
-                "which has no dedicated executor. Falling back to blocking_io " \
-                "(BlockingAdapterPool). Use :blocking_io explicitly to suppress this warning."
-            else
-              "[Phronomy] Tool #{tool.class.name} declares execution_mode :external_process, " \
-                "which has no dedicated process manager. Falling back to blocking_io " \
-                "(BlockingAdapterPool)."
-            end
-            if Phronomy.configuration.logger
-              Phronomy.configuration.logger.warn(message)
-            else
-              warn message
-            end
+        case mode
+        when :cooperative
+          task = Phronomy::Task.deferred(name: "tool-#{tool.name}")
+          begin
+            task.complete(
+              tool.call(args, cancellation_token: cancellation_token)
+            )
+          rescue => error
+            task.fail(error)
           end
-          mode = :blocking_io
-        end
-
-        pool = begin
-          runtime&.blocking_io
-        rescue
-          nil
-        end
-
-        if mode == :cooperative || pool.nil?
-          runtime.spawn(name: "tool-#{tool.class.name.to_s.split("::").last}") do
-            tool.call(args, cancellation_token: ct)
+          task
+        when :offloaded
+          runtime ||= Phronomy::Runtime.instance
+          runtime.offload.submit(
+            cancellation_token: cancellation_token,
+            on_full: on_full
+          ) do
+            tool.call(args, cancellation_token: cancellation_token)
           end
         else
-          pool.submit(cancellation_token: ct) do
-            tool.call(args, cancellation_token: ct)
-          end
+          raise Phronomy::ConfigurationError,
+            "unknown Tool execution_mode: #{mode.inspect}"
         end
       end
     end

data/lib/phronomy/agent/tool_invocation.rb

@@ -119,8 +119,7 @@ module Phronomy
         end
 
         if schema_error
-          if @tool.class.respond_to?(:on_schema_error) &&
-              @tool.class.on_schema_error == :raise
+          if @tool.class.respond_to?(:on_schema_error) && @tool.class.on_schema_error == :raise
             @error = Phronomy::ToolError.new(
               "#{@tool.class.name} schema error: #{schema_error}"
             )
@@ -141,64 +140,75 @@ module Phronomy
         self
       end
 
-      def authorization_task(runtime: Phronomy::Runtime.instance)
+      # Starts authorization and reports exactly one AuthorizationOutcome through
+      # the callback. No Task is created.
+      def start_authorization(runtime: Phronomy::Runtime.instance, &callback)
+        raise ArgumentError, "start_authorization requires a callback" unless callback
+
         pool = runtime.pool(
           :authorization,
           size: Phronomy.configuration.authorization_pool_size,
           queue_size: Phronomy.configuration.authorization_queue_size
         )
-        timeout = @config.fetch(:authorization_timeout, Phronomy.configuration.authorization_timeout)
-        pending = pool.submit(
+        timeout = @config.fetch(
+          :authorization_timeout,
+          Phronomy.configuration.authorization_timeout
+        )
+        operation = pool.submit(
           timeout: timeout,
           cancellation_token: @config[:cancellation_token],
           on_full: :raise
         ) { evaluate_authorization }
-
-        task = Phronomy::Task.deferred(name: "tool-authorization:#{@tool_name}")
-        pending.on_complete do |outcome, error|
-          resolved = error ? authorization_failure_outcome(error) : outcome
-          task.backend.unblock(resolved, nil)
-          task.transition!(:completed, value: resolved)
+        operation.on_complete do |outcome, error|
+          callback.call(error ? authorization_failure_outcome(error) : outcome)
         end
-        task
+        self
       rescue => error
-        task = Phronomy::Task.deferred(name: "tool-authorization:#{@tool_name}")
-        outcome = authorization_failure_outcome(error)
-        task.backend.unblock(outcome, nil)
-        task.transition!(:completed, value: outcome)
-        task
+        callback.call(authorization_failure_outcome(error))
+        self
       end
 
-      def execution_task(runtime: Phronomy::Runtime.instance)
-        pending = Phronomy::Agent::ToolExecutor.call_invocation_async(
-          tool_invocation: self,
-          cancellation_token: @config[:cancellation_token],
-          config: @config,
-          runtime: runtime
-        )
-        task = Phronomy::Task.deferred(name: "tool-execution:#{@tool_name}")
-        pending.on_complete do |result, error|
-          outcome = if error
-            ExecutionOutcome.new(
-              error: error,
-              cancelled: error.is_a?(Phronomy::CancellationError)
-            )
-          else
-            ExecutionOutcome.new(result: result)
+      # Starts Tool execution and reports completion through the callback.
+      #
+      # Both core execution paths use Tool#call_async:
+      #
+      # - :cooperative returns a Task without consuming an OffloadPool worker.
+      #   Ordinary cooperative Tools settle that Task inline; Agent-backed Tools
+      #   may start child EventLoop/FSM work and settle later.
+      # - :offloaded returns an OffloadPool PendingOperation for synchronous work
+      #   that must not occupy the EventLoop.
+      #
+      # In either case ToolInvocation remains in :running and resumes only from
+      # the explicit :execution_completed FSM event posted by the session builder.
+      def start_execution(runtime: Phronomy::Runtime.instance, &callback)
+        raise ArgumentError, "start_execution requires a callback" unless callback
+        unless dispatchable?
+          callback.call(ExecutionOutcome.new(error: Phronomy::ToolError.new(
+            "ToolInvocation #{@id} is not authorized for dispatch"
+          )))
+          return self
+        end
+
+        case @tool.class.execution_mode
+        when :cooperative, :offloaded
+          operation = start_async_tool_operation(runtime)
+          unless operation.respond_to?(:on_complete)
+            raise Phronomy::ToolError,
+              "Tool #{@tool.class.name}#call_async must return a completion handle"
           end
-          task.backend.unblock(outcome, nil)
-          task.transition!(:completed, value: outcome)
+
+          operation.on_complete do |result, error|
+            callback.call(execution_outcome(result, error))
+          end
+        else
+          callback.call(ExecutionOutcome.new(error: Phronomy::ConfigurationError.new(
+            "unknown Tool execution_mode: #{@tool.class.execution_mode.inspect}"
+          )))
         end
-        task
+        self
       rescue => error
-        task = Phronomy::Task.deferred(name: "tool-execution:#{@tool_name}")
-        outcome = ExecutionOutcome.new(
-          error: error,
-          cancelled: error.is_a?(Phronomy::CancellationError)
-        )
-        task.backend.unblock(outcome, nil)
-        task.transition!(:completed, value: outcome)
-        task
+        callback.call(execution_outcome(nil, error))
+        self
       end
 
       def mark_awaiting_approval! = (@status = :awaiting_approval
@@ -256,6 +266,48 @@ module Phronomy
 
       private
 
+      # Runtime is framework execution infrastructure, not part of the public
+      # Tool#call_async protocol.
+      #
+      # Tools using Capability::Base's default async implementation are routed
+      # directly through ToolExecutor so this ToolInvocation can supply its
+      # owning Runtime internally. Tools that override #call_async (for example
+      # Agent-backed Tools) receive only the public Tool async keywords.
+      def start_async_tool_operation(runtime)
+        if uses_default_call_async?
+          Phronomy::Agent::ToolExecutor.call_async(
+            tool: @tool,
+            args: @arguments,
+            cancellation_token: @config[:cancellation_token],
+            config: @config,
+            runtime: runtime,
+            on_full: :raise
+          )
+        else
+          @tool.call_async(
+            @arguments,
+            cancellation_token: @config[:cancellation_token],
+            config: @config
+          )
+        end
+      end
+
+      def uses_default_call_async?
+        @tool.method(:call_async).owner ==
+          Phronomy::Agent::Context::Capability::Base
+      end
+
+      def execution_outcome(result, error)
+        if error
+          ExecutionOutcome.new(
+            error: error,
+            cancelled: error.is_a?(Phronomy::CancellationError)
+          )
+        else
+          ExecutionOutcome.new(result: result)
+        end
+      end
+
       def evaluate_authorization
         request = build_request(facts: {}, default_decision: nil)
         facts = evaluate_facts
@@ -272,9 +324,7 @@ module Phronomy
         end
 
         reason = if decision == :require_approval
-          (@origin == :mcp) ?
-            "MCP Tool execution requires approval" :
-            "Tool execution requires approval"
+          (@origin == :mcp) ? "MCP Tool execution requires approval" : "Tool execution requires approval"
         end
         AuthorizationOutcome.new(decision: decision, facts: facts, reason: reason)
       end

data/lib/phronomy/agent/tool_invocation_session_builder.rb

@@ -5,18 +5,9 @@ require "state_machines"
 module Phronomy
   module Agent
     # Builds an FSMSession for one ToolInvocation.
-    #
-    # Authorization and execution Tasks are observed by ToolInvocation-specific
-    # callbacks that post explicit FSM events. The generated phase machine does
-    # not await Tasks.
-    #
-    # @api private
+    # Async completion is represented only by explicit FSM events.
     class ToolInvocationSessionBuilder
-      AUTO_STATE_SET = {
-        idle: true,
-        validating: true,
-        queued: true
-      }.freeze
+      AUTO_STATE_SET = {idle: true, validating: true, queued: true}.freeze
 
       DECLARED_STATES = %i[
         idle validating authorizing awaiting_approval authorized queued running
@@ -27,42 +18,20 @@ module Phronomy
 
       EXTERNAL_EVENTS = {
         authorization_completed: [
-          {from: :authorizing, to: :cancelled, guard: ->(ctx) {
-            ctx.cancelled?
-          }},
-          {from: :authorizing, to: :failed, guard: ->(ctx) {
-            ctx.failed?
-          }},
-          {from: :authorizing, to: :rejected, guard: ->(ctx) {
-            ctx.rejected?
-          }},
-          {from: :authorizing, to: :awaiting_approval, guard: ->(ctx) {
-            ctx.awaiting_approval?
-          }},
-          {from: :authorizing, to: :authorized, guard: ->(ctx) {
-            ctx.authorized?
-          }}
+          {from: :authorizing, to: :cancelled, guard: ->(ctx) { ctx.cancelled? }},
+          {from: :authorizing, to: :failed, guard: ->(ctx) { ctx.failed? }},
+          {from: :authorizing, to: :rejected, guard: ->(ctx) { ctx.rejected? }},
+          {from: :authorizing, to: :awaiting_approval, guard: ->(ctx) { ctx.awaiting_approval? }},
+          {from: :authorizing, to: :authorized, guard: ->(ctx) { ctx.authorized? }}
         ],
         execution_completed: [
-          {from: :running, to: :cancelled, guard: ->(ctx) {
-            ctx.cancelled?
-          }},
-          {from: :running, to: :failed, guard: ->(ctx) {
-            ctx.failed?
-          }},
-          {from: :running, to: :completed, guard: ->(ctx) {
-            ctx.execution_completed?
-          }}
-        ],
-        approve: [
-          {from: :awaiting_approval, to: :authorized, guard: nil}
-        ],
-        reject: [
-          {from: :awaiting_approval, to: :rejected, guard: nil}
-        ],
-        dispatch: [
-          {from: :authorized, to: :queued, guard: nil}
+          {from: :running, to: :cancelled, guard: ->(ctx) { ctx.cancelled? }},
+          {from: :running, to: :failed, guard: ->(ctx) { ctx.failed? }},
+          {from: :running, to: :completed, guard: ->(ctx) { ctx.execution_completed? }}
         ],
+        approve: [{from: :awaiting_approval, to: :authorized, guard: nil}],
+        reject: [{from: :awaiting_approval, to: :rejected, guard: nil}],
+        dispatch: [{from: :authorized, to: :queued, guard: nil}],
         cancel: [
           {from: :awaiting_approval, to: :cancelled, guard: nil},
           {from: :authorized, to: :cancelled, guard: nil},
@@ -71,14 +40,8 @@ module Phronomy
         ]
       }.freeze
 
-      def self.build(
-        tool_invocation:,
-        runtime: Phronomy::Runtime.instance
-      )
-        build_session(
-          tool_invocation: tool_invocation,
-          runtime: runtime
-        )
+      def self.build(tool_invocation:, runtime: Phronomy::Runtime.instance)
+        build_session(tool_invocation: tool_invocation, runtime: runtime)
       end
 
       def self.build_for_resume(
@@ -125,31 +88,15 @@ module Phronomy
       def self.build_entry_actions(runtime)
         {
           validating: [method(:validating_action)],
-          authorizing: [
-            method(:authorizing_action).curry.call(runtime)
-          ],
-          awaiting_approval: [
-            method(:awaiting_approval_action).curry.call(runtime)
-          ],
-          authorized: [
-            method(:authorized_action).curry.call(runtime)
-          ],
+          authorizing: [method(:authorizing_action).curry.call(runtime)],
+          awaiting_approval: [method(:awaiting_approval_action).curry.call(runtime)],
+          authorized: [method(:authorized_action).curry.call(runtime)],
           queued: [method(:queued_action)],
-          running: [
-            method(:running_action).curry.call(runtime)
-          ],
-          completed: [
-            method(:completed_action).curry.call(runtime)
-          ],
-          failed: [
-            method(:failed_action).curry.call(runtime)
-          ],
-          rejected: [
-            method(:rejected_action).curry.call(runtime)
-          ],
-          cancelled: [
-            method(:cancelled_action).curry.call(runtime)
-          ]
+          running: [method(:running_action).curry.call(runtime)],
+          completed: [method(:completed_action).curry.call(runtime)],
+          failed: [method(:failed_action).curry.call(runtime)],
+          rejected: [method(:rejected_action).curry.call(runtime)],
+          cancelled: [method(:cancelled_action).curry.call(runtime)]
         }
       end
       private_class_method :build_entry_actions
@@ -176,59 +123,29 @@ module Phronomy
 
             event :state_completed do
               transition idle: :validating
-
-              transition validating: :failed,
-                if: ->(machine) { machine.context&.failed? }
-              transition validating: :completed,
-                if: ->(machine) {
-                  machine.context&.validation_completed?
-                }
-              transition validating: :authorizing,
-                if: ->(machine) {
-                  machine.context&.validation_passed?
-                }
-
+              transition validating: :failed, if: ->(m) { m.context&.failed? }
+              transition validating: :completed, if: ->(m) { m.context&.validation_completed? }
+              transition validating: :authorizing, if: ->(m) { m.context&.validation_passed? }
               transition queued: :running
             end
 
             event :authorization_completed do
-              transition authorizing: :cancelled,
-                if: ->(machine) { machine.context&.cancelled? }
-              transition authorizing: :failed,
-                if: ->(machine) { machine.context&.failed? }
-              transition authorizing: :rejected,
-                if: ->(machine) { machine.context&.rejected? }
-              transition authorizing: :awaiting_approval,
-                if: ->(machine) {
-                  machine.context&.awaiting_approval?
-                }
-              transition authorizing: :authorized,
-                if: ->(machine) { machine.context&.authorized? }
+              transition authorizing: :cancelled, if: ->(m) { m.context&.cancelled? }
+              transition authorizing: :failed, if: ->(m) { m.context&.failed? }
+              transition authorizing: :rejected, if: ->(m) { m.context&.rejected? }
+              transition authorizing: :awaiting_approval, if: ->(m) { m.context&.awaiting_approval? }
+              transition authorizing: :authorized, if: ->(m) { m.context&.authorized? }
             end
 
             event :execution_completed do
-              transition running: :cancelled,
-                if: ->(machine) { machine.context&.cancelled? }
-              transition running: :failed,
-                if: ->(machine) { machine.context&.failed? }
-              transition running: :completed,
-                if: ->(machine) {
-                  machine.context&.execution_completed?
-                }
-            end
-
-            event :approve do
-              transition awaiting_approval: :authorized
-            end
-
-            event :reject do
-              transition awaiting_approval: :rejected
-            end
-
-            event :dispatch do
-              transition authorized: :queued
+              transition running: :cancelled, if: ->(m) { m.context&.cancelled? }
+              transition running: :failed, if: ->(m) { m.context&.failed? }
+              transition running: :completed, if: ->(m) { m.context&.execution_completed? }
             end
 
+            event(:approve) { transition awaiting_approval: :authorized }
+            event(:reject) { transition awaiting_approval: :rejected }
+            event(:dispatch) { transition authorized: :queued }
             event :cancel do
               transition awaiting_approval: :cancelled
               transition authorized: :cancelled
@@ -267,13 +184,9 @@ module Phronomy
       private_class_method :validating_action
 
       def self.authorizing_action(runtime, invocation)
-        task = invocation.authorization_task(runtime: runtime)
-        observe_task(
-          runtime,
-          invocation,
-          task,
-          event_type: :authorization_completed
-        )
+        invocation.start_authorization(runtime: runtime) do |outcome|
+          post_to_invocation(runtime, invocation.id, :authorization_completed, outcome)
+        end
         invocation
       end
       private_class_method :authorizing_action
@@ -298,45 +211,14 @@ module Phronomy
       private_class_method :queued_action
 
       def self.running_action(runtime, invocation)
-        # execution_task checks dispatchable? which requires :queued status;
-        # mark_running! is deferred until after the task is started.
-        task = invocation.execution_task(runtime: runtime)
+        invocation.start_execution(runtime: runtime) do |outcome|
+          post_to_invocation(runtime, invocation.id, :execution_completed, outcome)
+        end
         invocation.mark_running!
-        observe_task(
-          runtime,
-          invocation,
-          task,
-          event_type: :execution_completed
-        )
         invocation
       end
       private_class_method :running_action
 
-      def self.observe_task(
-        runtime,
-        invocation,
-        task,
-        event_type:
-      )
-        task.on_complete do |outcome, error|
-          payload = error || outcome
-          accepted = runtime.event_loop.post_to_session(
-            Phronomy::Event.new(
-              type: event_type,
-              target_id: invocation.id,
-              payload: payload
-            )
-          )
-          next if accepted
-
-          Phronomy.configuration.logger&.warn(
-            "[Phronomy] Dropped #{event_type.inspect} for " \
-            "ToolInvocation #{invocation.id}"
-          )
-        end
-      end
-      private_class_method :observe_task
-
       def self.completed_action(runtime, invocation)
         notify_parent(runtime, invocation, :tool_completed)
         invocation
@@ -363,6 +245,18 @@ module Phronomy
       end
       private_class_method :cancelled_action
 
+      def self.post_to_invocation(runtime, id, event_type, payload)
+        accepted = runtime.event_loop.post_to_session(
+          Phronomy::Event.new(type: event_type, target_id: id, payload: payload)
+        )
+        return if accepted
+
+        Phronomy.configuration.logger&.warn(
+          "[Phronomy] Dropped #{event_type.inspect} for ToolInvocation #{id}"
+        )
+      end
+      private_class_method :post_to_invocation
+
       def self.notify_parent(runtime, invocation, event_type)
         runtime.event_loop.post_to_session(
           Phronomy::Event.new(