phronomy 0.15.1 → 0.17.0

data/lib/phronomy/agent/base.rb

@@ -2,7 +2,7 @@
 
 require "securerandom"
 require_relative "concerns/filterable"
-require_relative "concerns/before_completion"
+require_relative "concerns/before_llm_input"
 require_relative "concerns/error_translation"
 
 module Phronomy
@@ -10,11 +10,12 @@ module Phronomy
     # Base class for all Phronomy agents.
     #
     # Subclass this to create a conversational agent powered by an LLM.
-    # DSL class methods configure the model, instructions, tools, memory,
+    # DSL class methods configure the model, instructions, tools,
     # and execution hooks. Instance methods handle invocation.
     #
     # @example Minimal agent
     #   class GreetingAgent < Phronomy::Agent::Base
+    #     agent_definition id: "greeting-agent", version: 1
     #     model "gpt-4o-mini"
     #     instructions "You are a friendly greeter."
     #   end
@@ -23,15 +24,16 @@ module Phronomy
     #
     # @example Agent with tools
     #   class ResearchAgent < Phronomy::Agent::Base
+    #     agent_definition id: "research-agent", version: 1
     #     model "gpt-4o"
     #     instructions "You are a research assistant."
-    #     tools WebSearchTool, CalculatorTool
+    #     tools(WebSearchTool => nil, CalculatorTool => nil)
     #     max_iterations 15
     #   end
     class Base
       include Phronomy::Runnable
       include Concerns::Filterable
-      include Concerns::BeforeCompletion
+      include Concerns::BeforeLLMInput
       include Concerns::ErrorTranslation
 
       APPROVAL_CONFIGURATION_INIT_MUTEX = Mutex.new
@@ -84,40 +86,34 @@ module Phronomy
 
         # Registers tool classes for this agent.
         #
-        # Accepts either a splat of classes (backward-compatible) or a Hash mapping
-        # each class to an explicit alias name (String) or nil (use tool's own name).
-        # The alias form is useful when two tools share the same auto-generated name
-        # (e.g. two SearchTool classes from different modules).
+        # The setter accepts one Hash mapping each Tool class to an explicit alias
+        # name (String) or nil (use the Tool's own name). Calling without an
+        # argument returns the registered Tool classes.
         #
-        # @example Splat form (no alias)
-        #   tools WeatherTool, TimeTool
-        #
-        # @example Hash form (with optional per-tool alias)
+        # @example
         #   tools(
         #     Weather::SearchTool => "weather_search",
         #     Places::SearchTool  => "places_search",
         #     CurrentTimeTool     => nil
         #   )
         # @api public
-        def tools(*args)
-          if args.empty?
-            if instance_variable_defined?(:@tools)
-              return @tools
-            end
+        def tools(definitions = nil)
+          if definitions.nil?
+            return @tools if instance_variable_defined?(:@tools)
             return superclass.respond_to?(:tools) ? superclass.tools : []
           end
 
-          if args.length == 1 && args.first.is_a?(Hash)
-            hash = args.first
-            @tools = hash.keys
-            @tool_aliases = hash.transform_values { |v| v&.to_s }.reject { |_, v| v.nil? }
-          else
-            @tools = args
-            @tool_aliases = {}
+          unless definitions.is_a?(Hash)
+            raise ArgumentError,
+              "tools expects a Hash of ToolClass => alias_or_nil"
           end
+
+          @tools = definitions.keys
+          @tool_aliases = definitions.transform_values { |value| value&.to_s }
+            .reject { |_, value| value.nil? }
         end
 
-        # Returns the alias map registered via the hash form of .tools.
+        # Returns the alias map registered via .tools.
         # Merges parent class aliases so subclasses inherit their parent's mappings.
         # Subclass-specific aliases take precedence over parent aliases.
         # @return [Hash{Class => String}]
@@ -188,73 +184,9 @@ module Phronomy
           end
         end
 
-        # Registers one or more static knowledge sources on the agent class.
-        # Static source content is fetched and memoized at the **class** level
-        # the first time +invoke+ is called. The cache persists for the lifetime
-        # of the process; call {.static_knowledge_refresh!} to force a reload.
-        #
-        # @param sources [Array<Phronomy::Agent::Context::Knowledge::Base>]
-        # @example
-        #   class PolicyAgent < Phronomy::Agent::Base
-        #     static_knowledge Phronomy::Agent::Context::Knowledge::StaticKnowledge.new(POLICY_TEXT)
-        #   end
-        # @api public
-        def static_knowledge(*sources)
-          @static_knowledge_sources = sources.flatten
-          # Invalidate the cached chunks so the new sources are fetched on
-          # the next call to static_knowledge_chunks.
-          @static_knowledge_chunks = nil
-        end
-
-        # Returns the registered static knowledge sources.
-        # @return [Array<Phronomy::Agent::Context::Knowledge::Base>]
-        # @api public
-        def static_knowledge_sources
-          @static_knowledge_sources || []
-        end
-
-        # Returns the fetched content from all static knowledge sources.
-        # Results are cached at the class level so that each source is fetched
-        # only once regardless of how many times the agent is invoked.
-        # @return [Array<Hash>]
-        # @api public
-        def static_knowledge_chunks
-          @static_knowledge_chunks ||= static_knowledge_sources.flat_map { |ks|
-            ks.fetch(query: nil)
-          }
-        end
-
-        # Clears the class-level knowledge cache so that the next +invoke+ call
-        # re-fetches content from all registered static knowledge sources.
-        #
-        # Call this method when the underlying knowledge source has been updated
-        # at runtime (e.g. a file was rewritten, a DB record changed) and you
-        # want the agent to pick up the new content without restarting the
-        # process.
-        #
-        # @return [nil]
-        # @example Refresh after updating a knowledge file
-        #   MyAgent.static_knowledge_refresh!
-        # @api public
-        def static_knowledge_refresh!
-          @static_knowledge_chunks = nil
-        end
-
         # When enabled, attaches Anthropic prompt-cache markers to the system
         # message so that the fixed instructions are served from cache on
         # subsequent turns, reducing input-token costs.
-        #
-        # Only has an effect when the agent also declares `provider :anthropic`.
-        # The cache_control field is provider-specific (the format differs
-        # between Anthropic direct, Bedrock, etc.), so the agent must explicitly
-        # declare its provider via the DSL rather than having it inferred from
-        # the model name.
-        #
-        # @example
-        #   class MyAgent < Phronomy::Agent::Base
-        #     provider :anthropic
-        #     cache_instructions true
-        #   end
         # @api public
         def cache_instructions(enabled = nil)
           if enabled.nil?
@@ -266,11 +198,6 @@ module Phronomy
 
         # Tokens to reserve for the model's output.
         # When nil, the model's max_output_tokens from the registry is used.
-        #
-        # @example
-        #   class MyAgent < Phronomy::Agent::Base
-        #     max_output_tokens 4096
-        #   end
         # @api public
         def max_output_tokens(val = nil)
           if val.nil?
@@ -281,14 +208,6 @@ module Phronomy
         end
 
         # Overrides the context window size used for token budget calculations.
-        # When set, this value takes precedence over the RubyLLM model registry,
-        # which is useful for locally-hosted models (e.g. LM Studio) where the
-        # actually-loaded context length may differ from the catalogue value.
-        #
-        # @example
-        #   class MyAgent < Phronomy::Agent::Base
-        #     context_window 4096
-        #   end
         # @api public
         def context_window(val = nil)
           if val.nil?
@@ -298,47 +217,55 @@ module Phronomy
           end
         end
 
-        # Tokens reserved for the system prompt + tool definitions overhead.
-        # Subtract this from the context window before computing the memory budget.
-        #
-        # @example
-        #   class MyAgent < Phronomy::Agent::Base
-        #     context_overhead 500
-        #   end
-        # @api public
-        def context_overhead(val = nil)
-          if val.nil?
-            @context_overhead || 0
-          else
-            @context_overhead = val.to_i
+        # Defines or reads the stable Agent definition identity.
+        # Subclass with no explicit declaration inherits the parent's definition.
+        def agent_definition(id: nil, version: nil)
+          if id || version
+            raise ArgumentError, "agent_definition requires id: and version:" unless id && version
+            @agent_definition = {id: id.to_s.freeze, version: Integer(version)}.freeze
+          end
+          return @agent_definition if @agent_definition
+
+          klass = superclass
+          while klass.respond_to?(:agent_definition, true) &&
+              klass < Phronomy::Agent::Base
+            defn = klass.instance_variable_get(:@agent_definition)
+            return defn if defn
+            klass = klass.superclass
           end
+
+          raise Phronomy::ConfigurationError,
+            "#{name || self} must declare agent_definition id: ..., version: ..."
         end
 
-        # Continues a suspended AgentInvocation.
-        # @param agent_invocation_id [String]
-        # @param approval_request_id [String]
-        # @param approved [Boolean]
-        # @param config [Hash]
-        # @api public
-        def approve(agent_invocation_id, approval_request_id:, approved: true, config: {})
-          new.approve(
-            agent_invocation_id,
+        def create(agent_id: SecureRandom.uuid, context: nil, knowledge: [], persistence: nil, metadata: {})
+          new(
+            agent_id: agent_id,
+            context: context,
+            knowledge: knowledge,
+            persistence: persistence,
+            metadata: metadata
+          )
+        end
+
+        def load(agent_id, persistence:)
+          new(agent_id: agent_id, persistence: persistence, load_existing: true)
+        end
+
+        def approve(execution_id, approval_request_id:, persistence:, approved: true, config: {})
+          approve_async(
+            execution_id,
             approval_request_id: approval_request_id,
             approved: approved,
-            config: config
-          )
+            config: config,
+            persistence: persistence
+          ).wait_result
         end
 
-        # Continues a suspended AgentInvocation without blocking the caller.
-        # @param agent_invocation_id [String]
-        # @param approval_request_id [String]
-        # @param approved [Boolean]
-        # @param config [Hash]
-        # @return [Phronomy::Task]
-        # @api public
-        def approve_async(agent_invocation_id, approval_request_id:, approved: true, config: {})
-          new.approve_async(
-            agent_invocation_id,
+        def approve_async(execution_id, approval_request_id:, persistence:, approved: true, config: {})
+          execution = persistence.executions.load(execution_id)
+          load(execution.agent_id, persistence: persistence).approve_async(
+            execution_id,
             approval_request_id: approval_request_id,
             approved: approved,
             config: config
@@ -346,29 +273,256 @@ module Phronomy
         end
       end
 
-      # Registers an anonymous handoff tool class on this agent instance.
-      # Called by Runner during construction when routes are configured.
-      # @param tool_class [Class<Phronomy::Agent::Context::Capability::Base>]
-      # @return [self]
-      # @api private
+      attr_reader :agent_id, :persistence
+
+      def initialize(
+        agent_id: SecureRandom.uuid,
+        context: nil,
+        knowledge: [],
+        persistence: nil,
+        metadata: {},
+        load_existing: false
+      )
+        @persistence = persistence || Phronomy::Persistence::InMemory.new
+        @agent_id = agent_id.to_s.freeze
+        @root = if load_existing
+          loaded = @persistence.agents.load(@agent_id)
+          definition = self.class.agent_definition
+          unless loaded.agent_definition_id == definition.fetch(:id) &&
+              loaded.definition_version == definition.fetch(:version)
+            raise Phronomy::ConfigurationError,
+              "Agent definition mismatch for #{@agent_id}: stored " \
+              "#{loaded.agent_definition_id}@#{loaded.definition_version}, runtime " \
+              "#{definition.fetch(:id)}@#{definition.fetch(:version)}"
+          end
+          loaded
+        else
+          create_agent_root!(context: context, knowledge: knowledge, metadata: metadata)
+        end
+      end
+
+      def agent_root
+        @root
+      end
+
+      def journal_projection
+        Agent::JournalProjection.new(persistence: persistence, agent_root: @root)
+      end
+
+      def transcript
+        journal_projection.transcript_records
+      end
+
+      def clear_transcript!
+        mutate_context!(:transcript_cleared) do |root|
+          root.with(
+            agent_revision: root.agent_revision + 1,
+            context_revision: root.context_revision + 1,
+            transcript_generation: root.transcript_generation + 1
+          )
+        end
+      end
+
+      # Logically clears all persistent Knowledge registered before this point.
+      # Raw Journal records remain append-only and are not deleted.
+      def clear_knowledge!
+        mutate_context!(:knowledge_cleared) do |root|
+          root.with(
+            agent_revision: root.agent_revision + 1,
+            context_revision: root.context_revision + 1
+          )
+        end
+      end
+
+      # Appends persistent Knowledge to the Agent Journal.
+      # Knowledge is an optional Context candidate; it is not part of #transcript.
+      def add_knowledge(content, metadata: {})
+        next_root = nil
+        persistence.transaction do |tx|
+          tx.executions.assert_idle!(agent_id)
+          current = tx.agents.load(agent_id)
+          record = build_knowledge_record(
+            tx: tx,
+            root: current,
+            content: content,
+            metadata: metadata
+          )
+          appended = tx.journals.append(
+            agent_id,
+            expected_position: current.journal_position,
+            records: [record]
+          )
+          next_root = current.with(
+            agent_revision: current.agent_revision + 1,
+            context_revision: current.context_revision + 1,
+            journal_position: current.journal_position + appended.length
+          )
+          tx.agents.save(
+            agent_id,
+            expected_revision: current.agent_revision,
+            root: next_root
+          )
+        end
+        @root = next_root
+        self
+      end
+
+      def reset_context!
+        mutate_context!(:context_reset) do |root|
+          root.with(
+            agent_revision: root.agent_revision + 1,
+            context_revision: root.context_revision + 1,
+            transcript_generation: root.transcript_generation + 1
+          )
+        end
+      end
+
+      def close!
+        mutate_context!(:agent_closed, context_affecting: false) do |root|
+          root.with(
+            agent_revision: root.agent_revision + 1,
+            lifecycle_status: :closed
+          )
+        end
+      end
+
+      def purge!
+        persistence.transaction do |tx|
+          tx.executions.assert_idle!(agent_id)
+          tx.journals.delete(agent_id)
+          tx.executions.delete_for_agent(agent_id)
+          tx.agents.delete(agent_id)
+        end
+        @root = nil
+        true
+      end
+
+      # Internal hook used after a successful Persistence transaction.
+      def __replace_root(root)
+        @root = root
+      end
+
+      private
+
+      def create_agent_root!(context:, knowledge:, metadata:)
+        definition = self.class.agent_definition
+        root = Agent::AgentRoot.create(
+          agent_id: agent_id,
+          agent_definition_id: definition.fetch(:id),
+          definition_version: definition.fetch(:version),
+          metadata: metadata
+        )
+        persistence.transaction do |tx|
+          tx.agents.create(root)
+          records = initial_context_records(tx: tx, root: root, context: context)
+          records.concat(initial_knowledge_records(tx: tx, root: root, knowledge: knowledge))
+          unless records.empty?
+            appended = tx.journals.append(agent_id, expected_position: 0, records: records)
+            root = root.with(
+              agent_revision: 1,
+              context_revision: 1,
+              journal_position: appended.length
+            )
+            tx.agents.save(agent_id, expected_revision: 0, root: root)
+          end
+        end
+        root
+      end
+
+      def initial_context_records(tx:, root:, context:)
+        return [] unless context
+
+        imported = context.respond_to?(:records) ? context :
+          Agent::ContextImporter.import_messages(context)
+        imported.records.map do |record|
+          content_ref = case record.content_format
+          when :text then tx.contents.put_text(record.content)
+          when :json then tx.contents.put_json(record.content)
+          else
+            raise ArgumentError,
+              "unsupported imported content format: #{record.content_format.inspect}"
+          end
+          Agent::JournalRecord.new(
+            agent_id: agent_id,
+            kind: record.kind,
+            channel: record.channel,
+            role: record.role,
+            content_ref: content_ref,
+            context_generation: root.transcript_generation,
+            context_candidate: true,
+            metadata: record.metadata
+          )
+        end
+      end
+
+      def initial_knowledge_records(tx:, root:, knowledge:)
+        Array(knowledge).map do |content|
+          build_knowledge_record(
+            tx: tx,
+            root: root,
+            content: content,
+            metadata: {}
+          )
+        end
+      end
+
+      def build_knowledge_record(tx:, root:, content:, metadata:)
+        Agent::JournalRecord.new(
+          agent_id: agent_id,
+          kind: :knowledge,
+          channel: :context,
+          role: :user,
+          content_ref: tx.contents.put_text(String(content)),
+          context_generation: root.transcript_generation,
+          context_candidate: true,
+          metadata: metadata || {}
+        )
+      end
+
+      def mutate_context!(kind, context_affecting: true)
+        next_root = nil
+        persistence.transaction do |tx|
+          tx.executions.assert_idle!(agent_id)
+          current = tx.agents.load(agent_id)
+          record = Agent::JournalRecord.new(
+            agent_id: agent_id,
+            kind: kind,
+            channel: :state,
+            context_generation: current.transcript_generation,
+            context_candidate: false
+          )
+          appended = tx.journals.append(
+            agent_id,
+            expected_position: current.journal_position,
+            records: [record]
+          )
+          proposed = yield(current)
+          next_root = proposed.with(
+            journal_position: current.journal_position + appended.length,
+            context_revision: context_affecting ?
+              yield_context_revision(current, proposed) : current.context_revision
+          )
+          tx.agents.save(agent_id, expected_revision: current.agent_revision, root: next_root)
+        end
+        @root = next_root
+      end
+
+      def yield_context_revision(current, proposed)
+        (proposed.context_revision == current.context_revision) ? current.context_revision + 1 : proposed.context_revision
+      end
+
+      public
+
       def _add_handoff_tool(tool_class)
         @_handoff_tools ||= []
         @_handoff_tools << tool_class
         self
       end
 
-      # Returns handoff tool classes registered on this instance by Runner.
-      # @return [Array<Class>]
-      # @api private
       def _handoff_tools
         @_handoff_tools || []
       end
 
-      # Registers the final Agent/Application authorization policy.
-      # The block runs on the Runtime authorization pool and must return
-      # :allow, :require_approval, or :reject.
-      # @return [self]
-      # @api public
       def tool_approval_policy(&block)
         raise ArgumentError, "tool_approval_policy requires a block" unless block
 
@@ -376,9 +530,6 @@ module Phronomy
         self
       end
 
-      # Registers a non-blocking Application notification listener.
-      # @return [self]
-      # @api public
       def on_tool_approval_required(&block)
         raise ArgumentError, "on_tool_approval_required requires a block" unless block
 
@@ -386,28 +537,17 @@ module Phronomy
         self
       end
 
-      # @deprecated The context version cache has been removed. Returns nil.
-      #   Retained for backward compatibility with callers using safe navigation (+&.reset+).
-      # @api private
-      def context_version_cache
-        nil
-      end
-
       private
 
-      # Merges an {InvocationContext} into the +thread_id+ / +config+ pair.
-      # Returns +[effective_thread_id, effective_config]+.
-      #
-      # Precedence rules (existing explicit values always win):
-      # - +thread_id+ argument > +ic.thread_id+
-      # - +config[:cancellation_token]+ > +ic.cancellation_token+ > token derived from +ic.deadline+
-      # - +ic+ is stored in +config[:invocation_context]+ (overwriting any previous value)
       def _apply_invocation_context(thread_id, config, ic)
         effective_thread_id = thread_id || ic.thread_id
         effective_config = config.merge(invocation_context: ic)
         if effective_config[:cancellation_token].nil?
           if (tok = ic.effective_timeout_token)
-            effective_config = effective_config.merge(cancellation_token: tok)
+            effective_config = effective_config.merge(
+              cancellation_token: tok,
+              phronomy_timeout_deadline: ic.deadline
+            )
           end
         end
         [effective_thread_id, effective_config]
@@ -434,173 +574,6 @@ module Phronomy
         end
       end
 
-      # Assembles the LLM context (system prompt + conversation messages)
-      # for a single invocation. Subclasses may override this method to
-      # inject custom context editing logic without having to override
-      # the full #invoke_once pipeline.
-      #
-      # The keyword arguments +budget+, +instruction+, +tools+, and +knowledge+
-      # carry pre-computed values. Override them in a subclass call to +super+
-      # to inject custom context without recomputing the defaults.
-      #
-      # @param input       [String, Hash] the user's input for this turn
-      # @param messages    [Array<RubyLLM::Message>] raw conversation history
-      # @param thread_id   [String, nil] conversation thread identifier
-      # @param config      [Hash] the invocation config (see #invoke)
-      # @param budget      [LlmContextWindow::TokenBudget, nil] pre-computed token budget
-      # @param instruction [String, nil] pre-computed system instruction
-      # @param tools       [Array<Class>] tool classes to expose
-      # @param knowledge   [Array<Hash>] knowledge chunks ({ content:, type:, source: })
-      # @return [Hash] { system: String|nil, messages: Array, tool_classes: Array }
-      # @api public
-      def build_context(
-        input,
-        messages: [],
-        thread_id: nil,
-        config: {},
-        budget: build_token_budget,
-        instruction: build_instructions(input),
-        tools: self.class.tools + _handoff_tools,
-        knowledge: self.class.static_knowledge_chunks + instance_knowledge_chunks
-      )
-        assembler = LlmContextWindow::Assembler.new(budget: budget)
-        assembler.add_instruction(instruction) if instruction
-        assembler.add_capability(tools)
-        knowledge.each { |chunk| assembler.add_knowledge(chunk[:content], type: chunk[:type] || :static, trusted: true, source: chunk[:source]) }
-
-        msgs = Array(messages)
-
-        if budget && budget_exceeded?(msgs)
-          # Default strategy when the token budget is tight:
-          # 1. Compact: keep the most recent half of the messages verbatim and
-          #    replace the older half with a brief omission marker.
-          # 2. Trim: if the compacted history still exceeds the budget, call
-          #    trim_to_budget with the :safe strategy, which discards the oldest
-          #    message one at a time until the history fits.
-          # Subclasses can override build_context to apply a different strategy
-          # (e.g. LLM-based summarisation) before calling super.
-          keep = [msgs.size / 2, 2].max
-          msgs = compact_messages(msgs, keep_tail: keep) do |dropped|
-            "[#{dropped.size} earlier messages omitted]"
-          end
-          remaining = assembler.available_for_messages
-          msgs = trim_to_budget(msgs, remaining: remaining, strategy: :safe)
-        end
-
-        assembler.add_messages(msgs)
-        @last_context = assembler.build
-      end
-      protected :build_context
-
-      # Keeps the last +keep+ messages from +messages+, discarding older ones.
-      # Use this inside a +build_context+ override to trim conversation history.
-      #
-      # @param messages [Array<RubyLLM::Message>] conversation history
-      # @param keep     [Integer] number of messages to retain (from the tail)
-      # @return [Array<RubyLLM::Message>]
-      # @api public
-      def trim_messages(messages, keep:)
-        Array(messages).last(keep)
-      end
-      protected :trim_messages
-
-      # Removes the oldest messages one at a time until the count is within +limit+.
-      #
-      # @param messages [Array<RubyLLM::Message>] conversation history
-      # @param limit    [Integer] maximum number of messages to retain
-      # @return [Array<RubyLLM::Message>]
-      # @api public
-      def drop_messages_over(messages, limit:)
-        msgs = Array(messages).dup
-        msgs.shift while msgs.size > limit
-        msgs
-      end
-      protected :drop_messages_over
-
-      # Replaces all but the last +keep_tail+ messages with a single system summary.
-      # The block receives the dropped messages and must return a summary String.
-      #
-      # @param messages  [Array<RubyLLM::Message>] conversation history
-      # @param keep_tail [Integer] number of recent messages to preserve verbatim
-      # @yield  [Array<RubyLLM::Message>] the messages being summarised
-      # @yieldreturn [String] summary text
-      # @return [Array<RubyLLM::Message>]
-      # @api public
-      def compact_messages(messages, keep_tail:, &summariser)
-        msgs = Array(messages)
-        return msgs if msgs.size <= keep_tail
-        tail = msgs.last(keep_tail)
-        dropped = msgs.first(msgs.size - keep_tail)
-        summary_text = summariser.call(dropped)
-        [RubyLLM::Message.new(role: :system, content: summary_text)] + tail
-      end
-      protected :compact_messages
-
-      # Trims +messages+ to fit within +remaining+ tokens using the given
-      # +strategy+. Returns the trimmed message array without touching the
-      # assembler. The caller is responsible for passing the result to
-      # +assembler.add_messages+ and calling +assembler.build+.
-      #
-      # Supported strategies:
-      #   +:safe+ — discard the oldest message one at a time (default)
-      #
-      # @param messages  [Array<RubyLLM::Message>] conversation history
-      # @param remaining [Integer, nil] token allowance for messages; when +nil+
-      #   the messages are returned unchanged
-      # @param strategy  [Symbol] trim strategy (default +:safe+)
-      # @return [Array<RubyLLM::Message>]
-      # @api public
-      def trim_to_budget(messages, remaining:, strategy: :safe)
-        return Array(messages) unless remaining
-        msgs = Array(messages)
-        loop do
-          used = msgs.sum { |m| LlmContextWindow::TokenEstimator.estimate(m.content.to_s) }
-          return msgs if used <= remaining
-          break if msgs.empty?
-          msgs = trim_messages(msgs, keep: msgs.size - 1)
-        end
-        msgs
-      end
-      protected :trim_to_budget
-
-      # Returns +true+ when the estimated token usage of +messages+ exceeds
-      # +threshold+ times the available context budget.
-      # Always returns +false+ when no token budget is available.
-      #
-      # @param messages  [Array<RubyLLM::Message>] conversation history
-      # @param threshold [Float] fraction of the available budget (default 0.8)
-      # @return [Boolean]
-      # @api public
-      def budget_exceeded?(messages, threshold: 0.8)
-        return false unless (b = build_token_budget)
-        total = Array(messages).sum { |m| LlmContextWindow::TokenEstimator.estimate(m.content.to_s) }
-        limit = b.available(used: 0)
-        total > limit * threshold
-      end
-      protected :budget_exceeded?
-
-      # Registers a per-instance knowledge source. Knowledge chunks from all
-      # registered sources are included in every LLM call via +build_context+.
-      #
-      # @param source [#fetch] any object responding to +fetch(query:)+
-      # @return [void]
-      # @api public
-      def add_knowledge_source(source)
-        @instance_knowledge_sources ||= []
-        @instance_knowledge_sources << source
-      end
-      protected :add_knowledge_source
-
-      # Returns knowledge chunks fetched from all instance-level knowledge sources.
-      #
-      # @return [Array<Hash>]
-      # @api private
-      def instance_knowledge_chunks
-        return [] unless @instance_knowledge_sources
-        @instance_knowledge_sources.flat_map { |ks| ks.fetch(query: nil) }
-      end
-      protected :instance_knowledge_chunks
-
       def _complete_result_task(task, result)
         task.backend.unblock(result, nil)
         task.transition!(:completed, value: result)
@@ -617,20 +590,6 @@ module Phronomy
         translated
       end
 
-      def _build_stream_terminal_event(result)
-        if result[:suspended]
-          StreamEvent.new(
-            type: :approval_required,
-            payload: {request: result[:approval_request]}
-          )
-        else
-          StreamEvent.new(type: :done, payload: result)
-        end
-      end
-
-      # Returns the Application exception instead of allowing it to escape the
-      # shared EventLoop. A nil return means delivery succeeded or no listener
-      # was registered.
       def _deliver_stream_event(listener, event)
         return unless listener
 
@@ -695,94 +654,6 @@ module Phronomy
         nil
       end
 
-      # Continues a suspended AgentInvocation. The parent session is registered
-      # asynchronously; this method is only the synchronous wrapper.
-      # @return [Hash]
-      # @api public
-      def approve(agent_invocation_id, approval_request_id:, approved: true, config: {})
-        _check_scheduler_reentrancy(:approve, :approve_async)
-        approve_async(
-          agent_invocation_id,
-          approval_request_id: approval_request_id,
-          approved: approved,
-          config: config
-        ).wait_result
-      end
-      public :approve
-
-      # Continues a suspended AgentInvocation without blocking the caller.
-      #
-      # This method is safe to call from an EventLoop stream callback. The
-      # returned Task completes when the resumed AgentInvocation finishes,
-      # suspends again, or fails.
-      # @return [Phronomy::Task]
-      # @api public
-      def approve_async(agent_invocation_id, approval_request_id:, approved: true, config: {})
-        result_task = Phronomy::Task.deferred(
-          name: "agent-approval-resume:#{agent_invocation_id}"
-        )
-
-        begin
-          entry = Agent::AgentInvocationRegistry.consume_approval(
-            agent_invocation_id, approval_request_id
-          )
-          unless entry
-            raise ArgumentError,
-              "No pending approval found for AgentInvocation #{agent_invocation_id}"
-          end
-
-          _start_approval_resume(
-            result_task,
-            entry.invocation,
-            approved: approved,
-            config: config
-          )
-        rescue => e
-          _fail_result_task(result_task, e)
-        end
-
-        result_task
-      end
-      public :approve_async
-
-      def _extract_invoke_result(invocation)
-        if invocation.phase == :suspended
-          request = invocation.approval_request
-          Agent::AgentInvocationRegistry.store_suspended(invocation, request)
-          _dispatch_tool_approval_notification(invocation, request)
-          {
-            suspended: true,
-            agent_invocation_id: invocation.id,
-            approval_request: request,
-            messages: invocation.messages
-          }
-        elsif invocation.input_blocked? || invocation.output_blocked?
-          raise invocation.block_error
-        elsif invocation.error
-          raise invocation.error
-        elsif invocation.rejected
-          {rejected: true, messages: invocation.messages}
-        else
-          {output: invocation.output, messages: invocation.messages, usage: invocation.usage}
-        end
-      end
-
-      def _dispatch_tool_approval_notification(invocation, request)
-        listener = invocation.approval_listener
-        return unless listener
-
-        Phronomy::Runtime.instance.blocking_io.submit(on_full: :raise) do
-          listener.call(request)
-        end
-      rescue => e
-        message = "[Phronomy] Tool approval notification failed: #{e.class}: #{e.message}"
-        if Phronomy.configuration.logger
-          Phronomy.configuration.logger.warn(message)
-        else
-          Kernel.warn(message)
-        end
-      end
-
       def _approval_configuration_mutex
         return @approval_configuration_mutex if @approval_configuration_mutex
 
@@ -811,64 +682,45 @@ module Phronomy
         meta
       end
 
-      def _apply_context_to_chat(chat, context)
-        apply_instructions(chat, context[:system]) if context[:system]
-        (context[:tool_classes] || []).each { |tc| chat.with_tool(prepare_tool_class(tc)) }
-        context[:messages].each { |msg| chat.messages << msg }
-      end
-
-      # Builds a TokenBudget for this agent's model if possible.
-      # When context_window is set at the class level, that value is used directly
-      # (bypassing the RubyLLM catalogue) — useful for locally-hosted models where
-      # the loaded context length differs from the catalogue value.
-      # Returns nil when the model is not registered in RubyLLM (e.g. local/unknown models).
-      def build_token_budget
-        model_name = self.class.model
-        return nil unless model_name
-
-        if (cw = self.class.context_window)
-          Phronomy::LlmContextWindow::TokenBudget.new(
-            context_window: cw,
-            max_output_tokens: self.class.max_output_tokens || 0,
-            overhead: self.class.context_overhead
-          )
-        else
-          Phronomy::LlmContextWindow::TokenBudget.new(
-            model: model_name,
-            max_output_tokens: self.class.max_output_tokens,
-            overhead: self.class.context_overhead
+      def _apply_runtime_projection_to_chat(chat, projection, invocation: nil)
+        if projection.system
+          apply_instructions(
+            chat,
+            projection.system,
+            cache: projection.model_config["cache_instructions"],
+            provider: projection.model_config["provider"]
           )
         end
-      rescue Phronomy::LlmContextWindow::UnknownModelError, RubyLLM::ModelNotFoundError
-        nil
-      end
-
-      # Returns the chat class to instantiate for this invocation.
-      # When {Phronomy.configuration.parallel_tool_execution} is true,
-      # returns {ParallelToolChat} so that concurrent tool dispatch is enabled.
-      # Falls back to +nil+ otherwise, signalling {#build_chat} to use the
-      # standard +RubyLLM.chat+ factory.
-      def build_chat_class
-        Phronomy.configuration.parallel_tool_execution ? Phronomy::MultiAgent::ParallelToolChat : nil
+        projection.tool_classes.each do |tool_class|
+          chat.with_tool(prepare_tool_class(tool_class, invocation: invocation))
+        end
+        projection.messages.each { |message| chat.messages << message }
+        chat
       end
 
-      def build_chat
+      def build_chat(model_config: nil)
+        config = model_config || {
+          "model" => self.class.model,
+          "provider" => self.class.provider,
+          "temperature" => self.class.temperature,
+          "max_output_tokens" => self.class.max_output_tokens,
+          "parallel_tool_execution" => Phronomy.configuration.parallel_tool_execution
+        }
         opts = {}
-        m = self.class.model
-        opts[:model] = m if m
-        p = self.class.provider
-        if p
-          opts[:provider] = p
+        model = config["model"]
+        opts[:model] = model if model
+        provider = config["provider"]
+        if provider
+          opts[:provider] = provider.to_sym
           opts[:assume_model_exists] = true
         end
-        t = self.class.temperature
-        parallel_class = build_chat_class
-        chat = if parallel_class
-          parallel_class.new(**opts)
-        else
-          RubyLLM.chat(**opts)
+        parallel_class = config["parallel_tool_execution"] ?
+          Phronomy::MultiAgent::ParallelToolChat : nil
+        chat = parallel_class ? parallel_class.new(**opts) : RubyLLM.chat(**opts)
+        chat.with_temperature(config["temperature"]) if config["temperature"]
+        if config["max_output_tokens"] && chat.respond_to?(:with_max_output_tokens)
+          chat.with_max_output_tokens(config["max_output_tokens"])
         end
-        chat.with_temperature(t) if t
         chat
       end
 
@@ -884,12 +736,8 @@ module Phronomy
         end
       end
 
-      # Applies system instructions to a chat object.
-      # When cache_instructions is enabled and the provider is Anthropic,
-      # attaches a cache_control marker so that the fixed system prompt is
-      # eligible for prompt caching.
-      def apply_instructions(chat, text)
-        if self.class.cache_instructions && anthropic_provider?
+      def apply_instructions(chat, text, cache: false, provider: nil)
+        if cache && provider.to_s == "anthropic"
           content = RubyLLM::Providers::Anthropic::Content.new(text, cache: true)
           chat.with_instructions(content)
         else
@@ -897,14 +745,6 @@ module Phronomy
         end
       end
 
-      # Returns true when this agent explicitly declares `provider :anthropic`.
-      # Provider is intentionally checked via the DSL value rather than inferred
-      # from the model name, because cache_control format is API-endpoint-specific
-      # (Anthropic direct vs. Bedrock vs. OpenRouter all differ).
-      def anthropic_provider?
-        self.class.provider == :anthropic
-      end
-
       def extract_message(input)
         case input
         when String then input
@@ -913,29 +753,26 @@ module Phronomy
         end
       end
 
-      # Raises CancellationError if the cancellation_token in config is cancelled.
-      # No-op when config has no cancellation_token or the token is not cancelled.
-      #
-      # @param config [Hash] the invocation config hash
-      # @param message [String] the message for the CancellationError
-      # @raise [Phronomy::CancellationError]
-      # @api public
       def check_cancellation!(config, message = "invocation cancelled")
+        timeout_deadline = config[:phronomy_timeout_deadline]
+        raise Phronomy::TimeoutError, message if timeout_deadline&.expired?
+
         ct = config[:cancellation_token]
-        raise Phronomy::CancellationError, message if ct&.cancelled?
+        return unless ct&.cancelled?
+
+        if ct.respond_to?(:remaining_monotonic_seconds) &&
+            ct.remaining_monotonic_seconds == 0.0
+          raise Phronomy::TimeoutError, message
+        end
+        raise Phronomy::CancellationError, message
       end
 
-      # Builds the final Tool class to register with RubyLLM. Alias and Tool
-      # result filters remain wrappers; authorization is handled only by
-      # ToolInvocation before Tool#call begins.
-      def prepare_tool_class(tool_class)
+      def prepare_tool_class(tool_class, invocation: nil)
         return tool_class unless tool_class.is_a?(Class)
 
         resolved = if (alias_name = self.class.tool_aliases[tool_class])
-          parent_description = tool_class.description
           Class.new(tool_class) do
             tool_name alias_name
-            description parent_description if parent_description
           end
         else
           tool_class