phronomy 0.11.0 → 0.11.1

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: phronomy
 version: !ruby/object:Gem::Version
-  version: 0.11.0
+  version: 0.11.1
 platform: ruby
 authors:
 - Raizo T.C.S
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-06-16 00:00:00.000000000 Z
+date: 2026-07-19 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: ruby_llm
@@ -105,34 +105,54 @@ files:
 - lib/phronomy/agent.rb
 - lib/phronomy/agent/base.rb
 - lib/phronomy/agent/before_completion_context.rb
-- lib/phronomy/agent/checkpoint.rb
-- lib/phronomy/agent/checkpoint_store.rb
 - lib/phronomy/agent/concerns/before_completion.rb
 - lib/phronomy/agent/concerns/error_translation.rb
 - lib/phronomy/agent/concerns/filterable.rb
 - lib/phronomy/agent/concerns/retryable.rb
-- lib/phronomy/agent/concerns/suspendable.rb
 - lib/phronomy/agent/context/capability/base.rb
 - lib/phronomy/agent/context/capability/scope_policy.rb
 - lib/phronomy/agent/context/instruction/prompt_template.rb
 - lib/phronomy/agent/context/knowledge/base.rb
 - lib/phronomy/agent/context/knowledge/entity_knowledge.rb
 - lib/phronomy/agent/context/knowledge/static_knowledge.rb
+- lib/phronomy/agent/invocation_context.rb
+- lib/phronomy/agent/invocation_session.rb
+- lib/phronomy/agent/phase_machine_builder.rb
 - lib/phronomy/agent/runner.rb
 - lib/phronomy/agent/shared_state.rb
-- lib/phronomy/agent/suspend_signal.rb
+- lib/phronomy/agent/suspended_session_registry.rb
+- lib/phronomy/agent/tool_call_intercepted.rb
 - lib/phronomy/agent/tool_executor.rb
-- lib/phronomy/concurrency/async_queue.rb
-- lib/phronomy/concurrency/blocking_adapter_pool.rb
-- lib/phronomy/concurrency/cancellation_scope.rb
-- lib/phronomy/concurrency/cancellation_token.rb
-- lib/phronomy/concurrency/concurrency_gate.rb
-- lib/phronomy/concurrency/deadline.rb
-- lib/phronomy/concurrency/gate_registry.rb
-- lib/phronomy/concurrency/pool_registry.rb
 - lib/phronomy/configuration.rb
-- lib/phronomy/context.rb
 - lib/phronomy/diagnostics.rb
+- lib/phronomy/engine/concurrency/async_queue.rb
+- lib/phronomy/engine/concurrency/blocking_adapter_pool.rb
+- lib/phronomy/engine/concurrency/cancellation_scope.rb
+- lib/phronomy/engine/concurrency/cancellation_token.rb
+- lib/phronomy/engine/concurrency/concurrency_gate.rb
+- lib/phronomy/engine/concurrency/deadline.rb
+- lib/phronomy/engine/concurrency/gate_registry.rb
+- lib/phronomy/engine/concurrency/pool_registry.rb
+- lib/phronomy/engine/event_loop.rb
+- lib/phronomy/engine/fsm_session.rb
+- lib/phronomy/engine/runtime.rb
+- lib/phronomy/engine/runtime/deterministic_scheduler.rb
+- lib/phronomy/engine/runtime/fake_scheduler.rb
+- lib/phronomy/engine/runtime/runtime_metrics.rb
+- lib/phronomy/engine/runtime/scheduler.rb
+- lib/phronomy/engine/runtime/scheduler_timer_adapter.rb
+- lib/phronomy/engine/runtime/task_registry.rb
+- lib/phronomy/engine/runtime/thread_scheduler.rb
+- lib/phronomy/engine/runtime/timer_queue.rb
+- lib/phronomy/engine/runtime/timer_service.rb
+- lib/phronomy/engine/task.rb
+- lib/phronomy/engine/task/backend.rb
+- lib/phronomy/engine/task/deferred_backend.rb
+- lib/phronomy/engine/task/fiber_backend.rb
+- lib/phronomy/engine/task/immediate_backend.rb
+- lib/phronomy/engine/task/mapped_backend.rb
+- lib/phronomy/engine/task/thread_backend.rb
+- lib/phronomy/engine/task_group.rb
 - lib/phronomy/eval.rb
 - lib/phronomy/eval/comparison.rb
 - lib/phronomy/eval/dataset.rb
@@ -146,7 +166,6 @@ files:
 - lib/phronomy/eval/scorer/includes_scorer.rb
 - lib/phronomy/eval/scorer/llm_judge.rb
 - lib/phronomy/event.rb
-- lib/phronomy/event_loop.rb
 - lib/phronomy/filter.rb
 - lib/phronomy/filter/base.rb
 - lib/phronomy/filter/prompt_injection_filter.rb
@@ -171,31 +190,13 @@ files:
 - lib/phronomy/output_parser/structured_parser.rb
 - lib/phronomy/ruby_llm_patches.rb
 - lib/phronomy/runnable.rb
-- lib/phronomy/runtime.rb
-- lib/phronomy/runtime/deterministic_scheduler.rb
-- lib/phronomy/runtime/fake_scheduler.rb
-- lib/phronomy/runtime/runtime_metrics.rb
-- lib/phronomy/runtime/scheduler.rb
-- lib/phronomy/runtime/scheduler_timer_adapter.rb
-- lib/phronomy/runtime/task_registry.rb
-- lib/phronomy/runtime/thread_scheduler.rb
-- lib/phronomy/runtime/timer_queue.rb
-- lib/phronomy/runtime/timer_service.rb
 - lib/phronomy/state_store/base.rb
 - lib/phronomy/state_store/in_memory.rb
-- lib/phronomy/task.rb
-- lib/phronomy/task/backend.rb
-- lib/phronomy/task/fiber_backend.rb
-- lib/phronomy/task/immediate_backend.rb
-- lib/phronomy/task/mapped_backend.rb
-- lib/phronomy/task/thread_backend.rb
-- lib/phronomy/task_group.rb
 - lib/phronomy/testing.rb
 - lib/phronomy/testing/fake_clock.rb
 - lib/phronomy/testing/fake_scheduler.rb
 - lib/phronomy/testing/scheduler_helpers.rb
 - lib/phronomy/token_usage.rb
-- lib/phronomy/tool.rb
 - lib/phronomy/tools/agent.rb
 - lib/phronomy/tools/mcp.rb
 - lib/phronomy/tools/vector_search.rb
@@ -221,7 +222,6 @@ files:
 - lib/phronomy/vector_store/splitter/recursive_splitter.rb
 - lib/phronomy/version.rb
 - lib/phronomy/workflow.rb
-- lib/phronomy/workflow/fsm_session.rb
 - lib/phronomy/workflow/phase_machine_builder.rb
 - lib/phronomy/workflow_context.rb
 - lib/phronomy/workflow_runner.rb

data/lib/phronomy/agent/checkpoint.rb

@@ -1,208 +0,0 @@
-# frozen_string_literal: true
-
-require "securerandom"
-
-module Phronomy
-  module Agent
-    # Encapsulates the suspended state of an agent invocation.
-    #
-    # A Checkpoint is returned as the +:checkpoint+ key of the result hash when
-    # an approval-required tool is encountered and no synchronous
-    # on_approval_required handler has been registered.
-    #
-    # Pass the checkpoint to Agent::Base#resume to continue execution after
-    # obtaining an approval decision from the user or an external system.
-    #
-    # @example Suspend and resume
-    #   result = agent.invoke("Do task X")
-    #   if result[:suspended]
-    #     approved = prompt_user(result[:checkpoint].pending_tool_name)
-    #     result   = agent.resume(result[:checkpoint], approved: approved)
-    #   end
-    #   puts result[:output]
-    class Checkpoint
-      # @return [String] a globally unique identifier for this checkpoint;
-      #   used as an idempotency key when guarding against duplicate resumes
-      attr_reader :checkpoint_id
-
-      # @return [String, nil] the fully-qualified name of the agent class that
-      #   created this checkpoint (e.g. +"MyApp::ReviewAgent"+); used by the
-      #   class-level +resume+ method to validate the correct agent is used
-      attr_reader :agent_class
-
-      # @return [Time] the UTC timestamp when this checkpoint was created
-      attr_reader :requested_at
-
-      # @return [String, nil] the thread_id from the invocation config
-      attr_reader :thread_id
-
-      # @return [String, Hash] the original input passed to #invoke; stored so
-      #   that #resume can re-apply dynamic system instructions (e.g. Proc or
-      #   PromptTemplate-based instructions that depend on the input value).
-      attr_reader :original_input
-
-      # @return [Array<RubyLLM::Message>] conversation messages up to and including
-      #   the assistant message that requested the pending tool call
-      attr_reader :messages
-
-      # @return [String] the name of the tool awaiting approval
-      attr_reader :pending_tool_name
-
-      # @return [Hash] the arguments the LLM passed to the pending tool
-      attr_reader :pending_tool_args
-
-      # @return [String] the tool_call_id from the LLM response (required to
-      #   inject the tool result message on resume)
-      attr_reader :pending_tool_call_id
-
-      # @param checkpoint_id        [String] unique identifier; defaults to a new UUID
-      # @param agent_class           [String, nil] fully-qualified agent class name
-      # @param requested_at          [Time] when the checkpoint was created; defaults to +Time.now.utc+
-      # @param thread_id            [String, nil]
-      # @param original_input       [String, Hash] the input passed to the original #invoke call
-      # @param messages             [Array<RubyLLM::Message>]
-      # @param pending_tool_name    [String]
-      # @param pending_tool_args    [Hash]
-      # @param pending_tool_call_id [String]
-      # @api public
-      def initialize(thread_id:, original_input:, messages:, pending_tool_name:, pending_tool_args:, pending_tool_call_id:,
-        checkpoint_id: SecureRandom.uuid, agent_class: nil, requested_at: Time.now.utc)
-        @checkpoint_id = checkpoint_id
-        @agent_class = agent_class
-        @requested_at = requested_at
-        @thread_id = thread_id
-        @original_input = original_input
-        @messages = messages.dup.freeze
-        @pending_tool_name = pending_tool_name
-        @pending_tool_args = pending_tool_args
-        @pending_tool_call_id = pending_tool_call_id
-      end
-
-      # Converts this checkpoint to a plain Hash suitable for JSON / Marshal serialization.
-      #
-      # All values are plain Ruby objects (String, Symbol, Hash, Array, Numeric,
-      # nil). +RubyLLM::Message+ objects in +:messages+ are deep-converted so that
-      # any embedded +RubyLLM::ToolCall+ objects are also serialized as plain hashes.
-      #
-      # @example Round-trip via JSON
-      #   json = JSON.generate(checkpoint.to_h)
-      #   checkpoint2 = Phronomy::Agent::Checkpoint.from_h(JSON.parse(json))
-      #
-      # @return [Hash]
-      # @api public
-      def to_h
-        {
-          checkpoint_id: @checkpoint_id,
-          agent_class: @agent_class,
-          requested_at: @requested_at&.iso8601,
-          thread_id: @thread_id,
-          original_input: @original_input,
-          messages: @messages.map { |m| serialize_message(m) },
-          pending_tool_name: @pending_tool_name,
-          pending_tool_args: @pending_tool_args,
-          pending_tool_call_id: @pending_tool_call_id
-        }
-      end
-
-      # Reconstructs a +Checkpoint+ from a plain Hash (e.g. produced by {#to_h}
-      # and deserialized from JSON or Marshal).
-      #
-      # Hash keys may be either Symbols or Strings; both are accepted.
-      # +RubyLLM::ToolCall+ objects inside message +:tool_calls+ arrays are
-      # reconstructed from their hash representations.
-      #
-      # @param h [Hash] a hash previously produced by {#to_h}
-      # @return [Checkpoint]
-      # @api public
-      def self.from_h(h)
-        h = h.transform_keys { |k|
-          begin
-            k.to_sym
-          rescue
-            k
-          end
-        }
-        messages = Array(h[:messages]).map { |m| deserialize_message(m) }
-        requested_at_raw = h[:requested_at]
-        requested_at = requested_at_raw ? Time.parse(requested_at_raw.to_s).utc : nil
-        new(
-          checkpoint_id: h[:checkpoint_id]&.to_s || SecureRandom.uuid,
-          agent_class: h[:agent_class]&.to_s,
-          requested_at: requested_at || Time.now.utc,
-          thread_id: h[:thread_id],
-          original_input: h[:original_input],
-          messages: messages,
-          pending_tool_name: h[:pending_tool_name]&.to_s,
-          pending_tool_args: h[:pending_tool_args] ? h[:pending_tool_args].transform_keys { |k|
-            begin
-              k.to_sym
-            rescue
-              k
-            end
-          } : {},
-          pending_tool_call_id: h[:pending_tool_call_id]&.to_s
-        )
-      end
-
-      private
-
-      # Converts a +RubyLLM::Message+ to a plain Hash, ensuring that any
-      # embedded +RubyLLM::ToolCall+ objects in +:tool_calls+ are also converted.
-      #
-      # @param msg [RubyLLM::Message]
-      # @return [Hash]
-      # @api private
-      def serialize_message(msg)
-        h = msg.to_h
-        return h unless h[:tool_calls]
-
-        h.merge(tool_calls: h[:tool_calls].map { |tc|
-          tc.respond_to?(:to_h) ? tc.to_h : tc
-        })
-      end
-
-      # Reconstructs a +RubyLLM::Message+ from a plain Hash.
-      # +RubyLLM::ToolCall+ entries in +:tool_calls+ are re-instantiated.
-      #
-      # @param h [Hash]
-      # @return [RubyLLM::Message]
-      # @api private
-      def self.deserialize_message(h)
-        h = h.transform_keys { |k|
-          begin
-            k.to_sym
-          rescue
-            k
-          end
-        }
-        if h[:tool_calls]
-          h = h.merge(tool_calls: Array(h[:tool_calls]).map { |tc|
-            next tc if tc.is_a?(RubyLLM::ToolCall)
-
-            tc = tc.transform_keys { |k|
-              begin
-                k.to_sym
-              rescue
-                k
-              end
-            }
-            RubyLLM::ToolCall.new(
-              id: tc[:id].to_s,
-              name: tc[:name].to_s,
-              arguments: (tc[:arguments] || {}).transform_keys { |k|
-                begin
-                  k.to_sym
-                rescue
-                  k
-                end
-              },
-              thought_signature: tc[:thought_signature]
-            )
-          })
-        end
-        RubyLLM::Message.new(h)
-      end
-      private_class_method :deserialize_message
-    end
-  end
-end

data/lib/phronomy/agent/checkpoint_store.rb

@@ -1,97 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  module Agent
-    # Default in-memory idempotency store for {Checkpoint} resume operations.
-    #
-    # Tracks consumed checkpoint IDs so that calling {Agent::Base#resume} twice
-    # with the same checkpoint raises {Phronomy::CheckpointAlreadyResumedError}
-    # instead of silently executing the approved tool a second time.
-    #
-    # This implementation is *not thread-safe*. It assumes a single agent instance
-    # is accessed from only one thread at a time, which is the expected usage pattern.
-    # Agent instances themselves are not thread-safe (state like +@messages+, +@config+
-    # is not protected), so concurrent calls to the same agent instance are unsupported.
-    #
-    # Each agent instance gets its own store by default, so no sharing occurs unless
-    # the caller explicitly assigns the same store object to multiple agents.
-    #
-    # For distributed environments (multiple processes or background jobs), swap this
-    # for a custom implementation backed by Redis, ActiveRecord, or another shared store.
-    # *Your custom store implementation is responsible for ensuring thread-safety* if
-    # your application shares the same store instance across multiple threads.
-    #
-    # @example Plugging in a custom store
-    #   agent = MyAgent.new
-    #   agent.checkpoint_store = MyRedis::CheckpointStore.new
-    #
-    # @example Duck-type contract required by any replacement
-    #   # consumed?(checkpoint_id) => Boolean
-    #   # consume!(checkpoint_id)  => void; raises CheckpointAlreadyResumedError if duplicate
-    #   # cleanup!(checkpoint_id)  => void (optional); removes tracking for the checkpoint
-    #   # clear!                   => void (optional); removes all tracked checkpoints
-    #
-    # @api public
-    class CheckpointStore
-      def initialize
-        @consumed = Set.new
-      end
-
-      # Returns +true+ if the given checkpoint ID has already been consumed.
-      #
-      # @param checkpoint_id [String]
-      # @return [Boolean]
-      # @api public
-      def consumed?(checkpoint_id)
-        @consumed.include?(checkpoint_id)
-      end
-
-      # Marks +checkpoint_id+ as consumed, or raises if it was already consumed.
-      #
-      # @param checkpoint_id [String]
-      # @raise [Phronomy::CheckpointAlreadyResumedError]
-      # @return [void]
-      # @api public
-      def consume!(checkpoint_id)
-        if @consumed.include?(checkpoint_id)
-          raise Phronomy::CheckpointAlreadyResumedError,
-            "checkpoint #{checkpoint_id} has already been resumed"
-        end
-        @consumed.add(checkpoint_id)
-        nil
-      end
-
-      # Removes tracking for a specific checkpoint ID.
-      #
-      # Use this to explicitly discard a checkpoint when the application
-      # determines it is no longer needed (e.g., user abandons an approval
-      # workflow).
-      #
-      # This method is optional in the duck-type contract. Custom store
-      # implementations may choose not to implement it.
-      #
-      # @param checkpoint_id [String]
-      # @return [void]
-      # @api public
-      def cleanup!(checkpoint_id)
-        @consumed.delete(checkpoint_id)
-        nil
-      end
-
-      # Removes all tracked checkpoint IDs.
-      #
-      # Use this for test cleanup, periodic maintenance, or application
-      # shutdown.
-      #
-      # This method is optional in the duck-type contract. Custom store
-      # implementations may choose not to implement it.
-      #
-      # @return [void]
-      # @api public
-      def clear!
-        @consumed.clear
-        nil
-      end
-    end
-  end
-end

data/lib/phronomy/agent/concerns/suspendable.rb

@@ -1,190 +0,0 @@
-# frozen_string_literal: true
-
-require "securerandom"
-
-module Phronomy
-  module Agent
-    module Concerns
-      # Adds suspend/resume and tool-approval support to an agent.
-      #
-      # Included in {Phronomy::Agent::Base}. When a tool decorated with
-      # +requires_approval true+ is called and no synchronous approval handler
-      # has been registered, the invocation is suspended and a
-      # @api private
-      # {Phronomy::Agent::Checkpoint} is returned so the caller can resume later.
-      module Suspendable
-        # Registers a callback that is invoked before executing any tool that has
-        # +requires_approval true+ set. The block receives the tool name (String)
-        # and the arguments Hash, and must return a truthy value to allow execution.
-        # Returning a falsy value causes the tool to return a denial message instead
-        # of executing.
-        #
-        # When no handler is registered and a tool with +requires_approval+ is
-        # called, #invoke returns a suspended result hash containing a
-        # {Phronomy::Agent::Checkpoint}. Call #resume to continue execution after
-        # obtaining an approval decision from the user or an external system.
-        #
-        # @example Synchronous handler
-        #   agent = MyAgent.new
-        #   agent.on_approval_required { |tool_name, args| prompt_user(tool_name, args) }
-        # @return [self]
-        # @api private
-        def on_approval_required(&block)
-          @approval_handler = block
-          self
-        end
-
-        # Registers a scope policy callable for this agent instance.
-        #
-        # The callable receives +(tool_class, scope, agent)+ and must return
-        # +:allow+, +:reject+, or +:approve+.
-        #
-        # @example Reject all write-scoped tools
-        #   agent.scope_policy = ->(_tc, scope, _agent) { scope == :write ? :reject : :allow }
-        #
-        # @param policy [#call]
-        # @return [void]
-        # @api public
-        def scope_policy=(policy)
-          @scope_policy = policy
-        end
-
-        # Sets the idempotency store used to guard against duplicate resumes.
-        #
-        # The store must respond to:
-        # - +consumed?(checkpoint_id)+ ⇒ Boolean
-        # - +consume!(checkpoint_id)+  ⇒ void; raises {Phronomy::CheckpointAlreadyResumedError} on duplicate
-        #
-        # Defaults to a per-instance {Phronomy::Agent::CheckpointStore} (in-memory, not thread-safe).
-        # Assign a shared persistent store when resuming across processes (e.g. Redis-backed).
-        # Custom stores are responsible for ensuring thread-safety if shared across threads.
-        #
-        # @param store [#consumed?, #consume!]
-        # @return [void]
-        # @api public
-        def checkpoint_store=(store)
-          @checkpoint_store = store
-        end
-
-        # Resumes a previously suspended invocation from a {Phronomy::Agent::Checkpoint}.
-        #
-        # This method reconstructs the conversation state captured at suspension
-        # time, injects the tool result (executed or denied), and continues the
-        # LLM loop until it produces a final answer.
-        #
-        # @param checkpoint [Phronomy::Agent::Checkpoint] the checkpoint returned by
-        #   the suspended #invoke call
-        # @param approved   [Boolean] +true+ to execute the pending tool; +false+
-        #   to inject a denial message and let the LLM handle it gracefully
-        # @param config     [Hash] same runtime options as #invoke
-        # @return [Hash] +{ output: String, suspended: false, messages: Array, usage: Phronomy::TokenUsage }+
-        #   or +{ output: nil, suspended: true, checkpoint: Phronomy::Agent::Checkpoint, messages: Array }+
-        #   when a second approval-required tool is encountered during continuation
-        # @raise [Phronomy::FilterBlockError] when an output filter rejects the value
-        # @raise [Phronomy::CheckpointAlreadyResumedError] when the checkpoint has already been consumed
-        # @api private
-        def resume(checkpoint, approved:, config: {})
-          # Guard against duplicate resumes using the idempotency store.
-          _checkpoint_store.consume!(checkpoint.checkpoint_id)
-          # Build a fresh chat with all tools registered.
-          chat = build_chat
-
-          # Re-apply system instructions and register tools so the LLM has the
-          # same persona/context as the original invocation. build_context
-          # includes all tool classes (static + handoff) via add_capability.
-          context = build_context(checkpoint.original_input, messages: [])
-          apply_instructions(chat, context[:system]) if context[:system]
-          (context[:tool_classes] || []).each { |tc| chat.with_tool(prepare_tool_class(tc)) }
-
-          # Restore the full conversation (history + user + assistant with tool call).
-          checkpoint.messages.each { |msg| chat.messages << msg }
-
-          # Determine the tool result: execute it or inject a denial string.
-          tool_result =
-            if approved
-              tool_instance = chat.tools[checkpoint.pending_tool_name.to_sym]
-              tool_instance ? tool_instance.call(checkpoint.pending_tool_args) : "Tool not found."
-            else
-              "Tool execution denied."
-            end
-
-          # Inject the tool result so the LLM can continue.
-          chat.add_message(
-            role: :tool,
-            content: tool_result.to_s,
-            tool_call_id: checkpoint.pending_tool_call_id
-          )
-
-          # Re-register the suspension hook so that any further requires_approval
-          # tools encountered during continuation are intercepted rather than
-          # executed without approval (cascading / chained approval scenario).
-          _register_suspension_hook!(chat)
-
-          # Continue the LLM loop. Rescue SuspendSignal so that a second
-          # approval-required tool produces a new checkpoint instead of running
-          # without consent.
-          begin
-            response = chat.complete
-          rescue SuspendSignal => signal
-            new_checkpoint = Checkpoint.new(
-              checkpoint_id: SecureRandom.uuid,
-              agent_class: self.class.name,
-              requested_at: Time.now.utc,
-              thread_id: checkpoint.thread_id,
-              original_input: checkpoint.original_input,
-              messages: chat.messages.dup,
-              pending_tool_name: signal.tool_name,
-              pending_tool_args: signal.args,
-              pending_tool_call_id: signal.tool_call_id
-            )
-            return {output: nil, suspended: true, checkpoint: new_checkpoint, messages: chat.messages}
-          end
-
-          output = response.content
-          usage = Phronomy::TokenUsage.from_tokens(response.tokens)
-
-          output = run_output_filters!(output)
-
-          {output: output, suspended: false, messages: chat.messages, usage: usage}
-        end
-
-        private
-
-        # Registers an on_tool_call hook on the chat object that raises SuspendSignal
-        # when an approval-required tool is about to be executed and no synchronous
-        # on_approval_required handler has been registered.
-        #
-        # Does nothing when:
-        #   - a synchronous handler is already registered (@approval_handler is set), or
-        #   - none of the agent's tools have requires_approval set.
-        #
-        # @param chat [RubyLLM::Chat]
-        # @api private
-        def _register_suspension_hook!(chat)
-          return if @approval_handler
-          return if self.class.tools.none? { |tc| tc.requires_approval }
-
-          chat.on_tool_call do |tool_call|
-            tool_instance = chat.tools[tool_call.name.to_sym]
-            if tool_instance&.requires_approval
-              raise SuspendSignal.new(
-                tool_name: tool_call.name,
-                args: tool_call.arguments,
-                tool_call_id: tool_call.id
-              )
-            end
-          end
-        end
-
-        # Returns the checkpoint idempotency store for this instance, lazily
-        # initialising a default in-memory {Phronomy::Agent::CheckpointStore}.
-        #
-        # @return [#consumed?, #consume!]
-        # @api private
-        def _checkpoint_store
-          @checkpoint_store ||= CheckpointStore.new
-        end
-      end
-    end
-  end
-end

data/lib/phronomy/agent/suspend_signal.rb

@@ -1,37 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  module Agent
-    # Raised internally inside the on_tool_call hook when an approval-required
-    # tool is encountered and no synchronous on_approval_required handler has
-    # been registered.  Caught by Agent::Base#invoke_once to produce a
-    # suspended result hash containing a Checkpoint.
-    #
-    # This class is intentionally NOT part of the public API.  Callers should
-    # @api private
-    # inspect the +:suspended+ key in the result hash returned by #invoke.
-    #
-    # @api private
-    class SuspendSignal < StandardError
-      # @return [String] the name of the tool that triggered the suspension
-      attr_reader :tool_name
-
-      # @return [Hash] the arguments the LLM passed to the tool
-      attr_reader :args
-
-      # @return [String] the tool_call_id from the LLM response
-      attr_reader :tool_call_id
-
-      # @param tool_name    [String]
-      # @param args         [Hash]
-      # @param tool_call_id [String]
-      # @api private
-      def initialize(tool_name:, args:, tool_call_id:)
-        super("Agent suspended waiting for approval of tool: #{tool_name}")
-        @tool_name = tool_name
-        @args = args
-        @tool_call_id = tool_call_id
-      end
-    end
-  end
-end

data/lib/phronomy/context.rb

@@ -1,12 +0,0 @@
-# frozen_string_literal: true
-
-module Phronomy
-  # Context management utilities: token estimation, budget calculation, and
-  # context assembly.
-  #
-  # Sub-modules are auto-loaded by Zeitwerk:
-  #   Phronomy::LlmContextWindow::TokenEstimator
-  #   Phronomy::LlmContextWindow::TokenBudget
-  module Context
-  end
-end

data/lib/phronomy/tool.rb

@@ -1,9 +0,0 @@
-# frozen_string_literal: true
-
-# This file is intentionally empty.
-# Tool definitions have moved to Phronomy::Agent::Context::Capability.
-# See lib/phronomy/agent/context/capability/.
-module Phronomy
-  module Tool
-  end
-end