phronomy 0.6.0 → 0.7.1

data/lib/phronomy/tool/mcp_tool.rb

@@ -36,6 +36,7 @@ module Phronomy
         #   - "http://<url>" / "https://<url>" — connect to an HTTP/SSE server
         # @param tool_name [String] the tool name as registered in the MCP server
         # @return [McpTool] a configured subclass instance ready for use with an Agent
+        # @api public
         def from_server(server_uri, tool_name:)
           # Use a short-lived transport only to query the tool definition,
           # then close it.  Each McpTool instance creates its own transport
@@ -65,13 +66,16 @@ module Phronomy
 
         def build_tool_class(tool_name, server_uri, tool_def)
           klass = Class.new(McpTool)
-          klass.instance_variable_set(:@mcp_tool_name, tool_name)
+          klass.tool_name(tool_name)
           klass.instance_variable_set(:@mcp_server_uri, server_uri)
 
           # Register description and params from the MCP tool definition.
           klass.description(tool_def[:description] || tool_name)
           (tool_def[:parameters] || []).each do |p|
-            klass.param(p[:name].to_sym, type: p[:type]&.to_sym || :string, desc: p[:description].to_s)
+            opts = {type: p[:type]&.to_sym || :string, desc: p[:description].to_s}
+            opts[:required] = p[:required] if p.key?(:required)
+            opts[:enum] = p[:enum] if p.key?(:enum)
+            klass.param(p[:name].to_sym, **opts)
           end
 
           # Each instance creates its own transport so concurrent agent threads
@@ -107,15 +111,35 @@ module Phronomy
       # so that session state (registered resources, tool context, etc.) is preserved
       # across multiple calls.
       class StdioTransport
-        def initialize(command)
+        # @param command         [String]  shell command to spawn the MCP server process
+        # @param read_timeout    [Integer] seconds to wait for the server's JSON-RPC response
+        #   before raising {Phronomy::ToolError}. Mirrors the +read_timeout+ option on
+        #   {HttpTransport}. Defaults to 30 seconds.
+        # @param env             [Hash, nil] environment variable overrides for the subprocess.
+        #   When provided, only these variables are added/overridden; the parent environment
+        #   is still inherited. Use +nil+ as a value to unset a variable in the child process
+        #   (e.g. +{ "SECRET" => nil }+). An empty string value (+""+ ) sets the variable to
+        #   an empty string — it does NOT unset it.
+        # @param cwd             [String, nil] working directory for the subprocess.
+        #   Defaults to the current process's working directory.
+        # @param startup_timeout [Numeric, nil] seconds to wait for the server to
+        #   emit its first line on stdout before raising {Phronomy::ToolError}.
+        #   When nil (default), no startup check is performed.
+        # @api public
+        def initialize(command, read_timeout: 30, env: nil, cwd: nil, startup_timeout: nil)
           # Split the command string into an argv array so that Open3 executes
           # it directly without going through the shell, preventing injection.
           @command = Shellwords.split(command)
+          @read_timeout = read_timeout
+          @env = env
+          @cwd = cwd
+          @startup_timeout = startup_timeout
           @stdin = nil
           @stdout = nil
           @stderr = nil
           @wait_thr = nil
           @stderr_thread = nil
+          @stderr_op = nil
         end
 
         # Shut down the child process and close its IO streams.
@@ -127,25 +151,34 @@ module Phronomy
           @stdout = nil
           @stderr = nil
           stderr_thread = @stderr_thread
+          stderr_op = @stderr_op
           wait_thr = @wait_thr
           @stderr_thread = nil
+          @stderr_op = nil
           @wait_thr = nil
           stderr_thread&.join(1)
+          begin
+            stderr_op&.await(timeout: 1.0)
+          rescue
+            nil
+          end
           wait_thr&.join(5)
         end
 
         # Retrieve the tool definition from the server using the MCP `tools/list` method.
         # @param tool_name [String]
         # @return [Hash] { description:, parameters: }
+        # @api public
         def fetch_tool(tool_name)
           response = rpc_call("tools/list", {})
           tools = response.dig("result", "tools") || []
           defn = tools.find { |t| t["name"] == tool_name }
           raise ArgumentError, "Tool #{tool_name.inspect} not found on MCP server #{@command.inspect}" unless defn
 
+          required_names = defn.dig("inputSchema", "required") || []
           {
             description: defn["description"],
-            parameters: parse_schema_params(defn.dig("inputSchema", "properties") || {})
+            parameters: parse_schema_params(defn.dig("inputSchema", "properties") || {}, required_names: required_names)
           }
         end
 
@@ -153,6 +186,7 @@ module Phronomy
         # @param tool_name [String]
         # @param args [Hash]
         # @return [Object] the tool result
+        # @api public
         def call_tool(tool_name, args)
           response = rpc_call("tools/call", {name: tool_name, arguments: args})
           if response["error"]
@@ -176,14 +210,47 @@ module Phronomy
         def ensure_started!
           return if @stdin && !@stdin.closed?
 
-          @stdin, @stdout, @stderr, @wait_thr = Open3.popen3(*@command)
+          popen3_opts = {}
+          popen3_opts[:chdir] = @cwd if @cwd
+
+          argv = @env ? [@env, *@command] : @command
+          @stdin, @stdout, @stderr, @wait_thr = Open3.popen3(*argv, **popen3_opts)
           # Drain stderr asynchronously to prevent the pipe buffer from filling
           # and deadlocking the child process. Errors inside the drain thread are
           # silently ignored since stderr content is diagnostics-only.
-          @stderr_thread = Thread.new do
-            @stderr.read
-          rescue
-            nil
+          #
+          # Prefer BlockingAdapterPool when a Runtime is configured so that this
+          # file eventually needs no direct Thread.new (Issue #360). Fall back to
+          # Thread.new when no pool is available (no EventLoop / bare invocation).
+          pool = begin; Phronomy::Runtime.instance&.blocking_io; rescue; nil; end
+          if pool
+            @stderr_op = pool.submit {
+              begin
+                @stderr.read
+              rescue
+                nil
+              end
+            }
+            @stderr_thread = nil
+          else
+            @stderr_thread = Thread.new {
+              begin
+                @stderr.read
+              rescue
+                nil
+              end
+            }
+            @stderr_op = nil
+          end
+
+          if @startup_timeout
+            unless IO.select([@stdout], nil, nil, @startup_timeout)
+              close
+              raise Phronomy::ToolError,
+                "MCP stdio server did not start within #{@startup_timeout} seconds"
+            end
+            line = @stdout.gets
+            @stdout.ungetbyte(line) if line
           end
         end
 
@@ -191,18 +258,25 @@ module Phronomy
           ensure_started!
           payload = JSON.generate(jsonrpc: "2.0", id: SecureRandom.uuid, method: method, params: params)
           @stdin.puts(payload)
+          unless IO.select([@stdout], nil, nil, @read_timeout)
+            raise Phronomy::ToolError,
+              "MCP stdio server did not respond within #{@read_timeout} seconds"
+          end
           raw = @stdout.gets
           raise Phronomy::ToolError, "MCP server closed the connection unexpectedly" if raw.nil?
           JSON.parse(raw)
         end
 
-        def parse_schema_params(properties)
+        def parse_schema_params(properties, required_names: [])
           properties.map do |name, schema|
-            {
+            param = {
               name: name.to_s,
               type: schema["type"] || "string",
-              description: schema["description"].to_s
+              description: schema["description"].to_s,
+              required: required_names.include?(name.to_s)
             }
+            param[:enum] = schema["enum"] if schema["enum"]
+            param
           end
         end
       end
@@ -223,10 +297,15 @@ module Phronomy
         # @param base_url     [String]  full URL of the MCP endpoint, e.g. "http://localhost:8080/mcp"
         # @param open_timeout [Integer] TCP connection timeout in seconds (default: 5)
         # @param read_timeout [Integer] HTTP read timeout in seconds (default: 30)
-        def initialize(base_url, open_timeout: 5, read_timeout: 30)
+        # @param headers      [Hash]    additional HTTP request headers (e.g. Authorization).
+        #   Merged on top of the default Content-Type and Accept headers; caller-supplied
+        #   values override defaults when keys collide.
+        # @api public
+        def initialize(base_url, open_timeout: 5, read_timeout: 30, headers: {})
           @uri = URI.parse(base_url)
           @open_timeout = open_timeout
           @read_timeout = read_timeout
+          @extra_headers = headers
         end
 
         # HTTP connections are stateless; close is a no-op, defined so that
@@ -237,15 +316,17 @@ module Phronomy
         # Retrieve the tool definition from the server using MCP `tools/list`.
         # @param tool_name [String]
         # @return [Hash] { description:, parameters: }
+        # @api public
         def fetch_tool(tool_name)
           response = rpc_call("tools/list", {})
           tools = response.dig("result", "tools") || []
           defn = tools.find { |t| t["name"] == tool_name }
           raise ArgumentError, "Tool #{tool_name.inspect} not found on MCP server #{@uri}" unless defn
 
+          required_names = defn.dig("inputSchema", "required") || []
           {
             description: defn["description"],
-            parameters: parse_schema_params(defn.dig("inputSchema", "properties") || {})
+            parameters: parse_schema_params(defn.dig("inputSchema", "properties") || {}, required_names: required_names)
           }
         end
 
@@ -253,6 +334,7 @@ module Phronomy
         # @param tool_name [String]
         # @param args [Hash]
         # @return [Object] the tool result
+        # @api public
         def call_tool(tool_name, args)
           response = rpc_call("tools/call", {name: tool_name, arguments: args})
           if response["error"]
@@ -285,6 +367,7 @@ module Phronomy
           request = Net::HTTP::Post.new(path)
           request["Content-Type"] = "application/json"
           request["Accept"] = "application/json, text/event-stream"
+          @extra_headers.each { |k, v| request[k.to_s] = v.to_s }
           request.body = payload
 
           http_response = http.request(request)
@@ -323,13 +406,16 @@ module Phronomy
           result || raise(Phronomy::ToolError, "No valid JSON-RPC response found in SSE stream")
         end
 
-        def parse_schema_params(properties)
+        def parse_schema_params(properties, required_names: [])
           properties.map do |name, schema|
-            {
+            param = {
               name: name.to_s,
               type: schema["type"] || "string",
-              description: schema["description"].to_s
+              description: schema["description"].to_s,
+              required: required_names.include?(name.to_s)
             }
+            param[:enum] = schema["enum"] if schema["enum"]
+            param
           end
         end
       end

data/lib/phronomy/tool/scope_policy.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module Tool
+    # Evaluates whether a tool with a given scope may execute.
+    #
+    # A ScopePolicy is a callable that receives +(tool_class, scope, agent)+ and
+    # returns one of:
+    #   +:allow+   — proceed immediately without an approval gate.
+    #   +:reject+  — block execution; the tool returns a denial message.
+    #   +:approve+ — delegate to the agent's approval handler (if registered);
+    #                when no handler is registered the call is rejected.
+    #
+    # The {Default} instance is used automatically when no custom policy is
+    # configured on an agent.
+    #
+    # @example Custom policy that allows everything
+    #   agent.scope_policy = ->(_tool_class, _scope, _agent) { :allow }
+    #
+    # @example Strict policy that rejects all write scopes
+    #   agent.scope_policy = ->(_tc, scope, _agent) {
+    #     scope == :write ? :reject : :allow
+    #   }
+    class ScopePolicy
+      # Scopes that must go through an approval gate before execution.
+      APPROVAL_REQUIRED_SCOPES = %i[write admin external_network filesystem process external_process].freeze
+
+      # Scopes that are always permitted without approval.
+      ALWAYS_ALLOWED_SCOPES = %i[read_only].freeze
+
+      # Returns +:allow+ for always-allowed scopes, +:approve+ for high-risk
+      # scopes, and +:allow+ for anything else (including +nil+).
+      #
+      # @param _tool_class [Class]
+      # @param scope [Symbol, nil]
+      # @param _agent [Object]
+      # @return [:allow, :approve, :reject]
+      # @api private
+      def call(_tool_class, scope, _agent)
+        return :allow if scope.nil? || ALWAYS_ALLOWED_SCOPES.include?(scope)
+        return :approve if APPROVAL_REQUIRED_SCOPES.include?(scope)
+
+        :allow
+      end
+
+      # Shared singleton used when no custom policy is configured.
+      DEFAULT = new.freeze
+    end
+  end
+end

data/lib/phronomy/tool_executor.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+module Phronomy
+  # Centralises tool execution routing based on {Tool::Base.execution_mode}.
+  #
+  # This is the single place in the framework that decides *how* a tool call is
+  # dispatched:
+  #
+  # - +:cooperative+       — dispatched via +Runtime#spawn+ through the configured
+  #                          scheduler. Under the +:fiber+ backend this avoids an
+  #                          extra OS thread; under the +:thread+ backend it is
+  #                          backed by +ThreadScheduler+ (one thread per task).
+  # - +:blocking_io+       — submitted to +BlockingAdapterPool+ when the runtime
+  #                          provides a pool; falls back to +Runtime#spawn+ otherwise.
+  # - +:cpu_bound+         — emits a deprecation-style warning then falls back to
+  #                          +:blocking_io+ routing (no process pool available yet).
+  # - +:external_process+  — falls back to +:blocking_io+ routing (no process
+  #                          manager available yet).
+  #
+  # All paths return an object that responds to +#await+ (+Phronomy::Task+ or
+  # +BlockingAdapterPool::PendingOperation+), so callers can collect results
+  # uniformly.
+  #
+  # @note Non-goals
+  #   ToolExecutor deliberately does NOT provide:
+  #   - A CPU-bound process pool. CPU-intensive tool work must be handled at the
+  #     application layer (e.g., fork, Sidekiq, separate OS processes). The
+  #     framework will not add a +ProcessPoolExecutor+ equivalent.
+  #   - An external process manager. Spawning or supervising subprocesses is
+  #     out of scope for this module.
+  #   - Additional core execution routes beyond scheduler-backed cooperative
+  #     execution and BlockingAdapterPool-backed blocking I/O isolation.
+  #     The +:cpu_bound+ and +:external_process+ modes are accepted for
+  #     compatibility but both fall back to +:blocking_io+ routing with a
+  #     one-time warning. If a genuinely new core execution route is needed,
+  #     a new ADR is required.
+  #   These non-goals follow from the cooperative-first, non-preemptive
+  #   concurrency model (ADR-010): framework components must not assume the
+  #   caller's concurrency model, and CPU/process management belongs to the
+  #   application layer.
+  #
+  # @api private
+  module ToolExecutor
+    # Tracks tool classes that have already emitted an execution_mode warning so
+    # that the same warning is only logged once per process lifetime.
+    WARNED_MODES = Set.new
+    WARNED_MODES_MUTEX = Mutex.new
+    private_constant :WARNED_MODES, :WARNED_MODES_MUTEX
+
+    # Dispatches a single tool call asynchronously according to its
+    # +execution_mode+ and returns an awaitable.
+    #
+    # @param tool               [Phronomy::Tool::Base] the tool instance to invoke
+    # @param args               [Hash]                 argument hash to pass to {Tool::Base#call}
+    # @param cancellation_token [Phronomy::CancellationToken, nil]
+    # @param runtime            [Phronomy::Runtime]    runtime to use for spawning
+    #                           (defaults to {Runtime.instance}; injectable for tests)
+    # @return [#await] a {Phronomy::Task} or {BlockingAdapterPool::PendingOperation}
+    # @api private
+    def self.call_async(tool:, args:, cancellation_token: nil, runtime: Phronomy::Runtime.instance)
+      ct = cancellation_token
+      mode = tool.class.execution_mode
+
+      # Warn and normalise unsupported modes to :blocking_io.
+      # Each (tool class, mode) pair emits the warning at most once per process
+      # lifetime to avoid log flooding in high-throughput scenarios.
+      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
+          msg = 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(msg)
+          else
+            warn msg
+          end
+        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)
+        end
+      else
+        # Submit directly to pool — no wrapping Task thread required.
+        pool.submit(cancellation_token: ct) { tool.call(args, cancellation_token: ct) }
+      end
+    end
+  end
+end

data/lib/phronomy/tracing/base.rb

@@ -23,6 +23,7 @@ module Phronomy
       # @param meta [Hash] additional metadata attached to the span
       # @yield [span] the active span object
       # @return [Object] the block's return value
+      # @api public
       def trace(name, input: nil, **meta)
         span = start_span(name, input: input, **meta)
         result, usage = yield span
@@ -38,6 +39,7 @@ module Phronomy
       # @param name [String]
       # @param attributes [Hash]
       # @return [Object] an opaque span handle
+      # @api public
       def start_span(name, **attributes)
         raise NotImplementedError, "#{self.class}#start_span is not implemented"
       end
@@ -48,6 +50,7 @@ module Phronomy
       # @param output [Object, nil] successful output value
       # @param usage [Phronomy::TokenUsage, nil] token usage for this span
       # @param error [Exception, nil] exception if the block raised
+      # @api public
       def finish_span(span, output: nil, usage: nil, error: nil)
         raise NotImplementedError, "#{self.class}#finish_span is not implemented"
       end

data/lib/phronomy/tracing/langfuse_tracer.rb

@@ -31,6 +31,7 @@ module Phronomy
       # @param public_key [String] Langfuse project public key
       # @param secret_key [String] Langfuse project secret key
       # @param host [String] Langfuse host URL (override for self-hosted instances)
+      # @api public
       def initialize(public_key:, secret_key:, host: DEFAULT_HOST)
         @public_key = public_key
         @secret_key = secret_key
@@ -41,6 +42,7 @@ module Phronomy
       # Returns a plain Hash that records the span start state.
       #
       # @return [Hash] an opaque span handle used by {#finish_span}
+      # @api public
       def start_span(name, input: nil, **meta)
         {
           id: SecureRandom.uuid,

data/lib/phronomy/tracing/open_telemetry_tracer.rb

@@ -17,6 +17,7 @@ module Phronomy
     #   end
     class OpenTelemetryTracer < Base
       # @param tracer_name [String] name passed to the OTel TracerProvider
+      # @api public
       def initialize(tracer_name: "phronomy")
         require "opentelemetry"
         @otel_tracer = OpenTelemetry.tracer_provider.tracer(tracer_name, Phronomy::VERSION)
@@ -27,6 +28,7 @@ module Phronomy
       # +phronomy.+.
       #
       # @return [OpenTelemetry::Trace::Span]
+      # @api public
       def start_span(name, input: nil, **attributes)
         attrs = {}
         attrs["phronomy.input"] = input.to_s if input
@@ -50,6 +52,40 @@ module Phronomy
         end
         span.finish
       end
+
+      # Overrides Base#trace to use OTel +in_span+, which pushes the span onto
+      # the OTel Context stack while the block runs.  Nested +trace+ calls
+      # automatically inherit the current span as their parent, establishing the
+      # correct parent/child hierarchy in the trace tree.
+      #
+      # @param name [String] span name
+      # @param input [Object, nil] input to record as a span attribute
+      # @param meta [Hash] additional metadata (e.g. task_id, user_id)
+      # @yield [span] the active OTel span
+      # @return [Object] the block's return value
+      # @api private
+      def trace(name, input: nil, **meta)
+        attrs = {}
+        attrs["phronomy.input"] = input.to_s if input
+        meta.each { |k, v| attrs["phronomy.#{k}"] = v.to_s unless v.nil? }
+
+        result = nil
+        @otel_tracer.in_span(name, attributes: attrs) do |span|
+          result, usage = yield span
+          span.set_attribute("phronomy.output", result.to_s) if result
+          if usage
+            span.set_attribute("llm.usage.input_tokens", usage.input)
+            span.set_attribute("llm.usage.output_tokens", usage.output)
+            total = (usage.input || 0) + (usage.output || 0)
+            span.set_attribute("llm.usage.total_tokens", total)
+          end
+        rescue => e
+          span.record_exception(e)
+          span.status = OpenTelemetry::Trace::Status.error(e.message)
+          raise
+        end
+        result
+      end
     end
   end
 end

data/lib/phronomy/vector_store/async_backend.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+module Phronomy
+  module VectorStore
+    # Mixin that defines the async interface for VectorStore backends.
+    #
+    # Mixing this module into a VectorStore class provides three choices:
+    #
+    # 1. **Do nothing** — inherits default implementations from {VectorStore::Base}
+    #    that route through {BlockingAdapterPool} (the previous behaviour).
+    #
+    # 2. **Override selectively** — override only the async methods where the
+    #    backend has a native async driver, while the remaining methods fall back
+    #    to the pool.
+    #
+    # 3. **Implement all natively** — override all async methods to avoid pool
+    #    allocation entirely.
+    #
+    # @example Native async search (no pool worker thread allocated)
+    #   class MyFastStore < Phronomy::VectorStore::Base
+    #     include Phronomy::VectorStore::AsyncBackend
+    #
+    #     def search_async(query_embedding:, k: 5, cancellation_token: nil, timeout: nil)
+    #       # Returns a PendingOperation backed by a native async driver.
+    #       native_async_search(query_embedding, k)
+    #     end
+    #   end
+    #
+    # @api public
+    module AsyncBackend
+      # Async variant of {VectorStore::Base#add}.
+      #
+      # Submits the add call to {BlockingAdapterPool} by default.
+      # Override to use a native async driver.
+      #
+      # @param id                 [String]
+      # @param embedding          [Array<Float>]
+      # @param metadata           [Hash]
+      # @param cancellation_token [Phronomy::CancellationToken, nil]
+      # @param timeout            [Numeric, nil]
+      # @return [BlockingAdapterPool::PendingOperation]
+      # @api public
+      def add_async(id:, embedding:, metadata: {}, cancellation_token: nil, timeout: nil)
+        Phronomy::Runtime.instance.blocking_io.submit(
+          timeout: timeout,
+          cancellation_token: cancellation_token
+        ) do
+          add(id: id, embedding: embedding, metadata: metadata, cancellation_token: cancellation_token)
+        end
+      end
+
+      # Async variant of {VectorStore::Base#search}.
+      #
+      # Submits the search call to {BlockingAdapterPool} by default.
+      # Override to use a native async driver.
+      #
+      # @param query_embedding    [Array<Float>]
+      # @param k                  [Integer]
+      # @param cancellation_token [Phronomy::CancellationToken, nil]
+      # @param timeout            [Numeric, nil]
+      # @return [BlockingAdapterPool::PendingOperation]
+      # @api public
+      def search_async(query_embedding:, k: 5, cancellation_token: nil, timeout: nil)
+        Phronomy::Runtime.instance.blocking_io.submit(
+          timeout: timeout,
+          cancellation_token: cancellation_token
+        ) do
+          search(query_embedding: query_embedding, k: k, cancellation_token: cancellation_token)
+        end
+      end
+
+      # Async variant of {VectorStore::Base#remove}.
+      #
+      # Submits the remove call to {BlockingAdapterPool} by default.
+      # Override to use a native async driver.
+      #
+      # @param id                 [String]
+      # @param cancellation_token [Phronomy::CancellationToken, nil]
+      # @param timeout            [Numeric, nil]
+      # @return [BlockingAdapterPool::PendingOperation]
+      # @api public
+      def remove_async(id:, cancellation_token: nil, timeout: nil)
+        Phronomy::Runtime.instance.blocking_io.submit(
+          timeout: timeout,
+          cancellation_token: cancellation_token
+        ) do
+          remove(id: id)
+        end
+      end
+
+      # Async variant of {VectorStore::Base#clear}.
+      #
+      # Submits the clear call to {BlockingAdapterPool} by default.
+      # Override to use a native async driver.
+      #
+      # @param cancellation_token [Phronomy::CancellationToken, nil]
+      # @param timeout            [Numeric, nil]
+      # @return [BlockingAdapterPool::PendingOperation]
+      # @api public
+      def clear_async(cancellation_token: nil, timeout: nil)
+        Phronomy::Runtime.instance.blocking_io.submit(
+          timeout: timeout,
+          cancellation_token: cancellation_token
+        ) do
+          clear
+        end
+      end
+    end
+  end
+end