phronomy 0.27.0 → 0.28.0

data/lib/phronomy/tool/operation.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Tool
+    # Tool operation protocol: execution modes, custom async dispatch, and
+    # completion-handle validation. Agent approval/progress are separate owners.
+    # @api public
+    module Operation
+      # Starts one Tool operation. The submitter implements Execution submission
+      # for the default offloaded path; custom call_async keeps its public protocol
+      # and owns its execution mechanism. Neither receives a concrete Runtime.
+      # @return [#on_complete] the original completion handle
+      # @api public
+      def self.call_async(tool:, args:, cancellation_token: nil, config: {},
+        submitter: Phronomy::Execution, on_full: :raise)
+        unless %i[cooperative offloaded].include?(tool.class.execution_mode)
+          raise Phronomy::ConfigurationError,
+            "unknown Tool execution_mode: #{tool.class.execution_mode.inspect}"
+        end
+        operation = if custom_async?(tool.method(:call_async))
+          tool.call_async(args, cancellation_token: cancellation_token, config: config)
+        else
+          ToolExecutor.call_async(tool: tool, args: args,
+            cancellation_token: cancellation_token, config: config,
+            submitter: submitter, on_full: on_full)
+        end
+        unless operation.respond_to?(:on_complete)
+          raise Phronomy::ToolError,
+            "Tool #{tool.class.name}#call_async must return a completion handle"
+        end
+        operation
+      end
+
+      # Decorates synchronous Tool results and custom async completions. A custom
+      # async operation is mapped through Execution's physical-completion-aware
+      # operation contract. The caller owns transformation meaning, ordering and
+      # multiplicity: repeated decorations remain distinct stages. Base's internal
+      # async-to-sync delegation skips only the synchronous counterpart of these
+      # async stages. Explicit application calls retain their own transformations.
+      # @return [Class<Phronomy::Tool::Base>] a derived Tool class
+      # @api public
+      def self.with_result_transform(tool_class, &transform)
+        raise ArgumentError, "a result transformation is required" unless transform
+        effective_name = tool_class.new.name
+        custom_async_call = custom_async?(tool_class.instance_method(:call_async))
+        decorated = Class.new(tool_class) do
+          tool_name effective_name
+          define_method(:call) do |args, **kwargs|
+            result = super(args, **kwargs)
+            transform.call(result, name, args)
+          end
+          if custom_async_call
+            define_method(:call_async) do |args, **kwargs|
+              source = super(args, **kwargs)
+              Phronomy::AsyncOperation.map(source, name: "tool-filter-#{name}") do |value|
+                transform.call(value, name, args)
+              end
+            end
+          end
+        end
+        if custom_async_call
+          decorated.instance_variable_set(:@phronomy_async_transform_call,
+            decorated.instance_method(:call))
+        end
+        decorated
+      end
+
+      # Base's async bridge uses this bound callable on the original receiver,
+      # including after offload. Skip only framework-generated call wrappers whose
+      # async counterpart applies the same stage on completion. Stop at application
+      # methods and sync-only stages; do not infer application intent or use ambient
+      # flags, mutable receiver state, result identity, or filter deduplication.
+      # @api private
+      def self.synchronous_delegate(tool)
+        callable = tool.method(:call)
+        while callable.owner.instance_variable_get(:@phronomy_async_transform_call) == callable.unbind
+          callable = callable.super_method
+        end
+        callable
+      end
+
+      def self.custom_async?(method)
+        method.owner != Base
+      end
+      private_class_method :custom_async?
+    end
+  end
+end

data/lib/phronomy/tool/schema.rb

@@ -0,0 +1,214 @@
+# frozen_string_literal: true
+
+require "json_schemer"
+require "schematist"
+require_relative "../common/values/immutable"
+
+module Phronomy
+  module Tool
+    # One schema defines both the advertised arguments and runtime validation.
+    # Schema evaluation is local: remote references and custom vocabularies are
+    # not supported. Provider request rendering does not belong to this class.
+    # @api public
+    class Schema
+      KEYWORDS = %w[
+        $schema $ref $defs $comment definitions
+        type enum const title description default examples deprecated readOnly writeOnly
+        properties patternProperties additionalProperties required propertyNames
+        minProperties maxProperties dependentRequired dependentSchemas
+        items prefixItems contains minContains maxContains
+        minItems maxItems uniqueItems minimum maximum exclusiveMinimum exclusiveMaximum multipleOf
+        minLength maxLength pattern format allOf anyOf oneOf not if then else
+        unevaluatedProperties unevaluatedItems strict
+      ].freeze
+      FORMATS = %w[date-time date time duration email idn-email hostname idn-hostname ipv4 ipv6 uri uri-reference iri iri-reference uuid uri-template json-pointer relative-json-pointer regex].freeze
+      SCHEMA_MAPS = %w[properties patternProperties $defs definitions dependentSchemas].freeze
+      SCHEMA_LISTS = %w[allOf anyOf oneOf prefixItems].freeze
+      SCHEMA_VALUES = %w[additionalProperties propertyNames items contains not if then else unevaluatedProperties unevaluatedItems].freeze
+
+      # @api public
+      def initialize(schema = nil, &block)
+        source = if block
+          raise ArgumentError, "pass either a schema or a block" unless schema.nil?
+          Schematist::Schema.create(&block).new.to_json_schema
+        elsif schema.is_a?(Class) && schema.method_defined?(:to_json_schema)
+          schema.new.to_json_schema
+        elsif schema.respond_to?(:to_json_schema)
+          schema.to_json_schema
+        else
+          schema
+        end
+        source = source[:schema] || source["schema"] || source if source.is_a?(Hash)
+        @json_schema = self.class.json_value(source)
+        unless @json_schema.is_a?(Hash) && @json_schema["type"] == "object"
+          raise ArgumentError, "Tool schema must declare an object"
+        end
+        @references = []
+        validate_keywords!(@json_schema)
+        options = {ref_resolver: ->(uri) { raise ArgumentError, "external Tool schema reference: #{uri}" }}
+        unless JSONSchemer.valid_schema?(@json_schema, **options)
+          raise ArgumentError, "invalid Tool JSON Schema"
+        end
+        @json_schema = Phronomy::Values::Immutable.copy(@json_schema)
+        @validator = JSONSchemer.schema(@json_schema, **options)
+        @references.each { |reference| @validator.ref(reference) }
+        @references = nil
+        freeze
+      rescue JSONSchemer::InvalidRefPointer, JSONSchemer::InvalidRefResolution => error
+        raise ArgumentError, "invalid local Tool schema reference: #{error.message}"
+      end
+
+      # @api public
+      attr_reader :json_schema
+
+      # Return validated keyword arguments without modifying the caller's values.
+      # Coercion is limited to explicit property/item types; combinators and
+      # references are validated without guessing a branch or resolving a cast.
+      # @api public
+      def validate(arguments, coerce: false)
+        return [nil, "arguments must be an object (Hash)"] unless arguments.is_a?(Hash)
+        data = self.class.json_value(arguments)
+        data = self.class.json_value(coerce_value(data, @json_schema)) if coerce
+        error = @validator.validate(data).first
+        return [nil, error_message(error)] if error
+        [restore_keys(arguments, data).transform_keys(&:to_sym), nil]
+      rescue ArgumentError, TypeError => error
+        [nil, error.message]
+      end
+
+      # JSON values, with duplicate normalized keys rejected instead of lost.
+      # @api private
+      def self.json_value(value)
+        case value
+        when Hash
+          value.each_with_object({}) do |(key, child), result|
+            unless key.is_a?(String) || key.is_a?(Symbol)
+              raise ArgumentError, "Tool object keys must be Strings or Symbols"
+            end
+            name = key.to_s
+            raise ArgumentError, "duplicate Tool object key: #{name}" if result.key?(name)
+            result[name] = json_value(child)
+          end
+        when Array then value.map { |child| json_value(child) }
+        when String, Integer, TrueClass, FalseClass, NilClass then value
+        when Float
+          raise ArgumentError, "Tool numbers must be finite" unless value.finite?
+          value
+        else
+          raise ArgumentError, "unsupported Tool value: #{value.class}"
+        end
+      end
+
+      private
+
+      def error_message(error)
+        path = error.fetch("data_pointer", "").split("/").drop(1)
+        field = path.join(".")
+        type = error["type"]
+        type = "additionalProperties" if error["schema"] == false && error["schema_pointer"].end_with?("/additionalProperties")
+        case type
+        when "required"
+          key = Array(error.dig("details", "missing_keys")).first
+          path.empty? ? "required parameter '#{key}' is missing" : "nested required field '#{field}.#{key}' is missing"
+        when "additionalProperties"
+          (path.size > 1) ? "nested field '#{path[0...-1].join(".")}' contains undeclared key(s): #{path.last.inspect}" : "unknown parameter(s): #{path.last.inspect}"
+        when "enum"
+          "parameter '#{field}' must be one of: #{Array(error.dig("schema", "enum")).join(", ")} (got: #{error["data"].inspect})"
+        when "string", "integer", "number", "boolean", "object", "array", "null"
+          prefix = (path.size > 1) ? "nested field '#{field}'" : "parameter '#{field}'"
+          "#{prefix} expected type #{type} (got: #{error["data"].inspect})"
+        else
+          error.fetch("error", "invalid Tool arguments")
+        end
+      end
+
+      def validate_keywords!(schema)
+        return if schema == true || schema == false
+        raise ArgumentError, "invalid Tool schema node" unless schema.is_a?(Hash)
+        unknown = schema.keys - KEYWORDS
+        raise ArgumentError, "unsupported Tool schema keywords: #{unknown.join(", ")}" unless unknown.empty?
+        if schema.key?("$schema") && schema["$schema"] != "https://json-schema.org/draft/2020-12/schema"
+          raise ArgumentError, "Tool schemas require JSON Schema 2020-12"
+        end
+        if schema.key?("format") && !FORMATS.include?(schema["format"])
+          raise ArgumentError, "unsupported Tool schema format: #{schema["format"]}"
+        end
+        if schema.key?("$ref")
+          reference = schema["$ref"]
+          if !(reference.is_a?(String) && (reference == "#" || reference.start_with?("#/")))
+            raise ArgumentError, "Tool schemas support local JSON Pointer references only"
+          end
+          @references << reference
+        end
+        SCHEMA_MAPS.each do |key|
+          next unless schema.key?(key)
+          raise ArgumentError, "#{key} must be an object" unless schema[key].is_a?(Hash)
+          schema[key].each_value { |child| validate_keywords!(child) }
+        end
+        SCHEMA_LISTS.each do |key|
+          next unless schema.key?(key)
+          raise ArgumentError, "#{key} must be an array" unless schema[key].is_a?(Array)
+          schema[key].each { |child| validate_keywords!(child) }
+        end
+        SCHEMA_VALUES.each { |key| validate_keywords!(schema[key]) if schema.key?(key) }
+      end
+
+      def coerce_value(value, schema)
+        return value unless schema.is_a?(Hash)
+        return value if (schema.keys & %w[$ref anyOf oneOf allOf not if]).any?
+        type = schema["type"]
+        if type.is_a?(Array)
+          alternatives = type - ["null"]
+          type = alternatives.first if alternatives.length == 1
+        end
+        case type
+        when "object"
+          return value unless value.is_a?(Hash)
+          value.to_h { |key, child| [key, coerce_value(child, schema.fetch("properties", {}).fetch(key, {}))] }
+        when "array"
+          return value unless value.is_a?(Array)
+          value.map { |child| coerce_value(child, schema.fetch("items", {})) }
+        when "string" then value.nil? ? value : value.to_s
+        when "integer"
+          return value if value.nil? || value.is_a?(Integer)
+          raise ArgumentError, "fractional Tool value cannot be coerced to integer" if value.is_a?(Numeric) && value != value.to_i
+          begin
+            Integer(value)
+          rescue ArgumentError, TypeError
+            raise ArgumentError, "parameter cannot be coerced to integer: #{value.inspect}"
+          end
+        when "number"
+          begin
+            value.nil? ? value : Float(value)
+          rescue ArgumentError, TypeError
+            raise ArgumentError, "parameter cannot be coerced to number: #{value.inspect}"
+          end
+        when "boolean"
+          case value
+          when true, false, nil then value
+          else
+            case value.to_s.downcase
+            when "true" then true
+            when "false" then false
+            else raise ArgumentError, "parameter cannot be coerced to boolean: #{value.inspect}"
+            end
+          end
+        else value
+        end
+      end
+
+      def restore_keys(original, value)
+        case value
+        when Hash
+          value.to_h do |key, child|
+            old_key = (original.is_a?(Hash) && original.key?(key.to_sym)) ? key.to_sym : key
+            [old_key, restore_keys(original.is_a?(Hash) ? original[old_key] : nil, child)]
+          end
+        when Array
+          value.each_with_index.map { |child, index| restore_keys(original.is_a?(Array) ? original[index] : nil, child) }
+        else value
+        end
+      end
+    end
+  end
+end

data/lib/phronomy/tool/settings.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require_relative "../common/configuration_error"
+
+module Phronomy
+  module Tool
+    # Tool-owned defaults. Composition supplies values; result processing reads
+    # them at its existing boundary, after execution or asynchronous completion.
+    # @api private
+    class Settings
+      def self.install_provider(&provider)
+        raise ArgumentError, "Tool settings provider requires a block" unless provider
+
+        @provider = provider
+        nil
+      end
+
+      # Resolve the current value container without caching or notifications.
+      def self.current
+        settings = @provider&.call
+        unless settings.is_a?(Settings)
+          raise ConfigurationError, "Tool settings provider must return Tool::Settings"
+        end
+
+        settings
+      end
+
+      attr_accessor :max_result_size
+    end
+  end
+end

data/lib/phronomy/tool/tool_error.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+require_relative "../common/error"
+
+module Phronomy
+  class ToolError < Error; end
+end

data/lib/phronomy/tool/tool_executor.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Tool
+    # Routes Tool work according to the Tool execution contract.
+    #
+    # Both execution modes return {Phronomy::TaskResult}; only the execution mechanism
+    # differs.
+    #
+    # :cooperative Tool calls execute inline and must return quickly. call_async
+    # wraps their result in an already-settled TaskResult and never consumes an
+    # OffloadPool worker.
+    #
+    # :offloaded Tool calls route synchronous work through OffloadPool, whose
+    # caller-facing completion handle is also a TaskResult. Phronomy does not distinguish
+    # whether the reason is blocking I/O, CPU-bound work, or another long
+    # synchronous operation.
+    #
+    # @api private
+    module ToolExecutor
+      # @api private
+      def self.call_async(
+        tool:,
+        args:,
+        cancellation_token: nil,
+        config: {},
+        submitter: Phronomy::Execution,
+        on_full: :raise,
+        synchronous_call: tool.method(:call)
+      )
+        mode = tool.class.execution_mode
+
+        case mode
+        when :cooperative
+          task = Phronomy::TaskResult.deferred(name: "tool-#{tool.name}")
+          begin
+            task.complete(
+              synchronous_call.call(args, cancellation_token: cancellation_token)
+            )
+          rescue => error
+            task.fail(error)
+          end
+          task
+        when :offloaded
+          submitter.submit(
+            cancellation_token: cancellation_token,
+            on_full: on_full
+          ) do
+            synchronous_call.call(args, cancellation_token: cancellation_token)
+          end
+        else
+          raise Phronomy::ConfigurationError,
+            "unknown Tool execution_mode: #{mode.inspect}"
+        end
+      end
+    end
+  end
+end

data/lib/phronomy/tools/agent.rb

@@ -9,7 +9,7 @@ module Phronomy
     # 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.
-    class Agent < Phronomy::Agent::Context::Capability::Base
+    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"
@@ -39,11 +39,16 @@ module Phronomy
             if cancellation_token
               invoke_options[:config] = {cancellation_token: cancellation_token}
             end
-            result = Phronomy::Agent.run_once(
-              definition: agent_class,
-              input: input,
-              **invoke_options
+            # 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
           end
 
@@ -51,7 +56,7 @@ module Phronomy
           # The child Agent owns its own FSMSession/EventLoop lifecycle; this
           # method only returns its completion handle and performs a short map.
           klass.define_method(:execute_async) do |input:, cancellation_token: nil, config: {}|
-            persistence = Phronomy::Persistence.in_memory
+            persistence = Phronomy::Agent::DefaultPersistence.build
             agent = agent_class.create(persistence: persistence)
             task_config = (config || {}).dup
             if cancellation_token && !task_config[:cancellation_token]
@@ -83,106 +88,33 @@ module Phronomy
 
       # Agent-backed Tools have an asynchronous implementation that does not use
       # ToolExecutor/OffloadPool. Validation and Tool error policy still match
-      # Capability::Base#call.
+      # Tool::Base#call.
       def call_async(
         args,
         cancellation_token: nil,
         config: {}
       )
-        cancellation_token&.raise_if_cancelled!
-        validated_args, schema_error = send(:validate_and_coerce, args)
-
-        if schema_error
-          return schema_error_task(schema_error)
-        end
-
-        source = execute_async(
-          **(validated_args || {}),
-          cancellation_token: cancellation_token,
-          config: config || {}
-        )
-        unless source.respond_to?(:on_complete)
-          raise Phronomy::ToolError,
-            "#{self.class.name} asynchronous execution must return a completion handle"
+        call_async_operation(args, cancellation_token: cancellation_token,
+          operation_name: "agent-tool-#{name}") do |validated_args|
+          execute_async(**validated_args, cancellation_token: cancellation_token, config: config || {})
         end
-
-        result_task = Phronomy::TaskResult.deferred(name: "agent-tool-#{name}")
-        source.on_complete do |result, error|
-          if error
-            settle_async_error(result_task, error)
-            next
-          end
-
-          begin
-            result_task.complete(send(:truncate_result_if_needed, result))
-          rescue => result_error
-            settle_async_error(result_task, result_error)
-          end
-        end
-        result_task
-      rescue Phronomy::ToolError, Phronomy::CancellationError => error
-        failed_task(error)
-      rescue => error
-        result_task = Phronomy::TaskResult.deferred(name: "agent-tool-#{name}")
-        settle_async_error(result_task, error)
-        result_task
       end
 
       private
 
-      # Subclasses created by .from_agent and Orchestrator override this method.
+      # 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: {})
-        task = Phronomy::TaskResult.deferred(name: "agent-tool-#{name}-fallback")
-        begin
-          task.complete(execute(input: input, cancellation_token: cancellation_token))
-        rescue => error
-          task.fail(error)
+        Phronomy::AsyncOperation.capture(name: "agent-tool-#{name}-fallback") do
+          execute(input: input, cancellation_token: cancellation_token)
         end
-        task
       end
 
-      def schema_error_task(schema_error)
-        task = Phronomy::TaskResult.deferred(name: "agent-tool-#{name}-schema")
-        if self.class.on_schema_error == :raise
-          task.fail(Phronomy::ToolError.new(
-            "#{self.class.name} schema error: #{schema_error}"
-          ))
-        else
-          task.complete("Schema validation failed: #{schema_error}")
-        end
-        task
-      end
-
-      def failed_task(error)
-        Phronomy::TaskResult.deferred(name: "agent-tool-#{name}-failed").tap do |task|
-          task.fail(error)
-        end
-      end
+      # Agent recovery is an Agent operation outcome, not a generic Tool error.
+      def async_error_value(error)
+        raise error if error.is_a?(Phronomy::ExecutionRehydrationRequiredError)
 
-      def settle_async_error(task, error)
-        if error.is_a?(Phronomy::ToolError) || error.is_a?(Phronomy::CancellationError) || error.is_a?(Phronomy::ExecutionRehydrationRequiredError)
-          task.fail(error)
-          return task
-        end
-
-        if self.class.on_error == :suppress
-          message = "[Phronomy] Tool #{self.class.name} suppressed error: " \
-            "#{error.class}: #{error.message}"
-          if Phronomy.configuration.logger
-            Phronomy.configuration.logger.warn(message)
-          else
-            warn message
-          end
-          task.complete("Tool error suppressed: #{error.message}")
-        else
-          wrapped = Phronomy::ToolError.new(
-            "#{self.class.name} execution failed: #{error.message}"
-          )
-          wrapped.set_backtrace(error.backtrace)
-          task.fail(wrapped)
-        end
-        task
+        super
       end
     end
   end

data/lib/phronomy/tools/mcp.rb

@@ -7,7 +7,7 @@ require "uri"
 
 module Phronomy
   module Tools
-    # A Phronomy::Agent::Context::Capability::Base subclass that wraps a tool exposed by an external
+    # A Phronomy::Tool::Base subclass that wraps a tool exposed by an external
     # MCP (Model Context Protocol) server.
     #
     # Uses the official MCP Ruby SDK v1.x for transport handling, which provides
@@ -27,7 +27,7 @@ module Phronomy
     #     tool_name: "search_web"
     #   )
     #   agent_class.tools(web_search)
-    class Mcp < Phronomy::Agent::Context::Capability::Base
+    class Mcp < Phronomy::Tool::Base
       SUPPORTED_SCHEMA_DIALECTS = [
         "https://json-schema.org/draft/2020-12/schema",
         "https://json-schema.org/draft/2020-12/schema#"
@@ -273,8 +273,9 @@ module Phronomy
         end
 
         def warn_mcp(message)
-          if Phronomy.configuration.logger
-            Phronomy.configuration.logger.warn(message)
+          logger = Phronomy::RuntimeSettings.current.logger
+          if logger
+            logger.warn(message)
           else
             Kernel.warn(message)
           end
@@ -344,7 +345,8 @@ module Phronomy
       private
 
       def perform_mcp_call(cancellation_token:, args:)
-        mcp_cancellation = build_mcp_cancellation(cancellation_token)
+        subscriptions = Phronomy::Concurrency::ResultSubscriptions.new
+        mcp_cancellation = build_mcp_cancellation(cancellation_token, subscriptions: subscriptions)
         response = begin
           @mcp_client.call_tool(
             name: self.class.tool_name,
@@ -376,13 +378,17 @@ module Phronomy
 
         result = validate_call_tool_response!(response)
         format_tool_result(result)
+      ensure
+        # A caller-facing timeout can settle before this SDK call returns.
+        # Keep its bridge alive until this invocation actually leaves the SDK.
+        subscriptions&.close
       end
 
-      def build_mcp_cancellation(cancellation_token)
+      def build_mcp_cancellation(cancellation_token, subscriptions:)
         return nil unless cancellation_token
 
         mcp_cancellation = MCP::Cancellation.new
-        cancellation_token.on_cancel do
+        subscriptions.explicit_cancellation(cancellation_token) do
           mcp_cancellation.cancel(reason: "phronomy_cancelled")
         end
         mcp_cancellation
@@ -478,17 +484,18 @@ module Phronomy
       end
 
       def schedule_transport_cleanup(transport)
-        cleanup_pool = Phronomy::Runtime.instance.pool(
-          :mcp_cleanup,
+        Phronomy::Execution.submit(
+          pool_name: :mcp_cleanup,
           size: MCP_CLEANUP_POOL_SIZE,
-          queue_size: MCP_CLEANUP_QUEUE_SIZE
-        )
-        cleanup_pool.submit(on_full: :raise) do
+          queue_size: MCP_CLEANUP_QUEUE_SIZE,
+          on_full: :raise
+        ) do
           self.class.send(:close_transport_safely, transport)
         end
-      rescue Phronomy::BackpressureError, Phronomy::PoolShutdownError
+      rescue Phronomy::BackpressureError, Phronomy::PoolShutdownError, Phronomy::RuntimeShutdownError
         # During shutdown or an exceptional cleanup burst, prefer a bounded
-        # synchronous fallback over leaking the child process/socket.
+        # synchronous fallback over leaking the child process/socket. Runtime
+        # can reject acquisition before the cleanup pool itself is consulted.
         self.class.send(:close_transport_safely, transport)
       end
     end

data/lib/phronomy/tools/vector_search.rb

@@ -3,7 +3,7 @@
 module Phronomy
   module Tools
     # A Capability::Base subclass that wraps a {Phronomy::VectorStore::Base} and
-    # a {Phronomy::VectorStore::Embeddings::Base} adapter so that an agent can
+    # a {Phronomy::Embeddings::Base} adapter so that an agent can
     # perform semantic search as a tool call.
     #
     # Do not instantiate this class directly.  Use the factory method
@@ -11,7 +11,7 @@ module Phronomy
     #
     # @example
     #   store = Phronomy::VectorStore::InMemory.new
-    #   emb   = Phronomy::VectorStore::Embeddings::RubyLLMEmbeddings.new(model: "...")
+    #   emb   = Phronomy::Embeddings::RubyLLMEmbeddings.new(model: "...")
     #   tool  = Phronomy::Tools::VectorSearch.from_store(store, embeddings: emb,
     #             k: 3, tool_name: "search_docs",
     #             description: "Search the company knowledge base.")
@@ -19,7 +19,7 @@ module Phronomy
     #   agent.tools tool
     #
     # @api public
-    class VectorSearch < Phronomy::Agent::Context::Capability::Base
+    class VectorSearch < Phronomy::Tool::Base
       description "Search for relevant documents using semantic similarity."
       param :query, type: :string, desc: "The natural-language search query"
 
@@ -27,7 +27,7 @@ module Phronomy
         # Build a VectorSearch tool backed by the given store and embeddings adapter.
         #
         # @param store       [Phronomy::VectorStore::Base]
-        # @param embeddings  [Phronomy::VectorStore::Embeddings::Base]
+        # @param embeddings  [Phronomy::Embeddings::Base]
         # @param k           [Integer]       number of results to return (default 5)
         # @param tool_name   [String]        name exposed to the LLM
         # @param description [String, nil]   optional description override