phronomy 0.15.0 → 0.16.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
@@ -15,6 +15,7 @@ module Phronomy
     #
     # @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,6 +24,7 @@ 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
@@ -31,7 +33,7 @@ module Phronomy
     class Base
       include Phronomy::Runnable
       include Concerns::Filterable
-      include Concerns::BeforeCompletion
+      include Concerns::BeforeLLMInput
       include Concerns::ErrorTranslation
 
       APPROVAL_CONFIGURATION_INIT_MUTEX = Mutex.new
@@ -298,8 +300,9 @@ module Phronomy
           end
         end
 
-        # Tokens reserved for the system prompt + tool definitions overhead.
-        # Subtract this from the context window before computing the memory budget.
+        # Tokens reserved in the legacy build_context path only.
+        # Manifest-first assembly ignores this value because
+        # ContextAssembler estimates actual mandatory content for each LLM Call.
         #
         # @example
         #   class MyAgent < Phronomy::Agent::Base
@@ -314,31 +317,50 @@ module Phronomy
           end
         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,
+        # 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
+
+          # Walk ancestors to support anonymous runtime subclasses and abstract bases.
+          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
+
+        def create(agent_id: SecureRandom.uuid, context: nil, persistence: nil, metadata: {})
+          new(agent_id: agent_id, context: context, 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,6 +368,186 @@ module Phronomy
         end
       end
 
+      attr_reader :agent_id, :persistence
+
+      def initialize(
+        agent_id: SecureRandom.uuid,
+        context: nil,
+        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, 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
+
+      def clear_memory!
+        mutate_context!(:memory_cleared) do |root|
+          root.with(
+            agent_revision: root.agent_revision + 1,
+            context_revision: root.context_revision + 1,
+            memory_generation: root.memory_generation + 1
+          )
+        end
+      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,
+            memory_generation: root.memory_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:, 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)
+          if context
+            imported = context.respond_to?(:records) ? context :
+              Agent::ContextImporter.import_messages(context)
+            records = 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
+            appended = tx.journals.append(agent_id, expected_position: 0, records: records)
+            root = root.with(
+              agent_revision: 1,
+              context_revision: records.any? ? 1 : 0,
+              journal_position: appended.length
+            )
+            tx.agents.save(agent_id, expected_revision: 0, root: root)
+          end
+        end
+        root
+      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
+
+      def ensure_no_active_execution!
+        return if persistence.executions.list_active(agent_id).empty?
+        raise Phronomy::AgentBusyError, "agent has an active or suspended execution: #{agent_id}"
+      end
+
+      public
+
       # 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>]
@@ -386,173 +588,6 @@ module Phronomy
         self
       end
 
-      # Invokes the agent with the given input and returns a result Hash.
-      # Provider errors are translated after the configured LLM adapter returns
-      # its final result. Phronomy does not replay the Agent invocation.
-      #
-      # @param input     [String, Hash] the user message; a Hash may supply
-      #   +:message+, +:query+, or +:user+ as the text key, plus any template
-      #   variables consumed by the configured instructions template.
-      # @param messages  [Array<RubyLLM::Message>] conversation history from a
-      #   previous invocation. The application owns and persists this array;
-      #   pass it on every turn to maintain multi-turn context.
-      # @param thread_id [String, nil] conversation thread identifier, forwarded
-      #   to the compaction context when on_compact is configured.
-      # @param config    [Hash] additional runtime options:
-      #   +:user_id+    (+String+, optional) — caller identity forwarded to the tracer
-      #   +:session_id+ (+String+, optional) — session identity forwarded to the tracer
-      # @param invocation_context [Phronomy::InvocationContext, nil] optional first-class context
-      #   object.  When present, +thread_id+, +cancellation_token+, and +deadline+ are
-      #   derived from it (existing +config:+ keys take precedence as backward-compat
-      #   aliases).  The object is also stored in +config[:invocation_context]+ so that
-      #   +task_id+ / +parent_task_id+ appear in trace spans automatically.
-      # @return [Hash] +{ output: String, messages: Array, usage: Phronomy::TokenUsage }+,
-      #   or +{ output: nil, suspended: true, checkpoint: Phronomy::Agent::Checkpoint,
-      #   messages: Array }+ when the invocation was suspended awaiting tool approval.
-      # @raise [Phronomy::FilterBlockError] when an input or output filter rejects the value
-      # @example Normal invocation
-      #   result = MyAgent.new.invoke("What is Ruby?")
-      #   puts result[:output]
-      # @example Multi-turn conversation
-      #   result1 = agent.invoke("Hi, I'm Alice.")
-      #   result2 = agent.invoke("What's my name?", messages: result1[:messages])
-      # @example Suspend / resume flow
-      #   result = agent.invoke("Perform task X")
-      #   if result[:suspended]
-      #     result = agent.resume(result[:checkpoint], approved: true)
-      #   end
-      #   puts result[:output]
-      # @example With InvocationContext (deadline-based timeout)
-      #   ctx = Phronomy::InvocationContext.new(
-      #     thread_id: "conv-123",
-      #     deadline: Phronomy::Concurrency::Deadline.in(30),
-      #     task_id: SecureRandom.uuid
-      #   )
-      #   result = MyAgent.new.invoke("Hello", invocation_context: ctx)
-      # @api public
-      def invoke(input, messages: [], thread_id: nil, config: {}, invocation_context: nil)
-        if invocation_context
-          thread_id, config = _apply_invocation_context(thread_id, config, invocation_context)
-        end
-        _check_scheduler_reentrancy(:invoke, :invoke_async)
-
-        trace("agent.invoke", input: input, **_build_caller_meta(config)) do |_span|
-          result = invoke_async(
-            input,
-            messages: messages,
-            thread_id: thread_id,
-            config: config
-          ).wait_result
-          [result, result[:usage]]
-        end
-      end
-
-      # Invokes this agent asynchronously and returns a {Phronomy::Task}.
-      #
-      # This is the primary async entry point.  {#invoke} is a synchronous wrapper
-      # that calls this method and blocks the caller until the task completes.
-      # Calling {#invoke} from inside an active scheduler task raises
-      # {Phronomy::SchedulerReentrancyError}; use +invoke_async+ directly in that
-      # context.
-      #
-      # The task is registered with the Runtime task registry so {Runtime#shutdown}
-      # drains in-flight invocations before process exit.
-      #
-      # @example
-      #   task = agent.invoke_async("Hello!")
-      #   result = task.wait_result   # => { output: "...", messages: [...], usage: ... }
-      #
-      # @param input    [String, Hash]
-      # @param messages [Array]
-      # @param thread_id [String, nil]
-      # @param config   [Hash]
-      # @param invocation_context [Phronomy::InvocationContext, nil]
-      # @return [Phronomy::Task]
-      # @api public
-      def invoke_async(input, messages: [], thread_id: nil, config: {},
-        invocation_context: nil, on_tool_approval_required: nil)
-        if invocation_context
-          thread_id, config = _apply_invocation_context(thread_id, config, invocation_context)
-        end
-        result_task = Phronomy::Task.deferred(name: "agent-#{(self.class.name || "anonymous").downcase}-async")
-        approval_snapshot = _approval_configuration_snapshot(on_tool_approval_required)
-        _start_invocation(
-          result_task, input,
-          messages: messages, thread_id: thread_id, config: config,
-          approval_snapshot: approval_snapshot
-        )
-        result_task
-      end
-
-      # Invokes this agent asynchronously and delivers stream events from the
-      # Runtime-owned EventLoop thread.
-      #
-      # The callback must return quickly. Blocking I/O, synchronous Agent calls,
-      # sleep, and heavy CPU work must be delegated by the Application.
-      #
-      # @return [Phronomy::Task] final invocation result
-      # @api public
-      def stream_async(input, messages: [], thread_id: nil, config: {},
-        invocation_context: nil, on_tool_approval_required: nil, &block)
-        raise ArgumentError, "stream_async requires a block" unless block
-
-        if invocation_context
-          thread_id, config = _apply_invocation_context(thread_id, config, invocation_context)
-        end
-
-        result_task = Phronomy::Task.deferred(
-          name: "agent-#{(self.class.name || "anonymous").downcase}-stream-async"
-        )
-        approval_snapshot = _approval_configuration_snapshot(on_tool_approval_required)
-        _start_invocation(
-          result_task,
-          input,
-          messages: messages,
-          thread_id: thread_id,
-          config: config,
-          approval_snapshot: approval_snapshot,
-          mode: :stream,
-          on_event: block
-        )
-        result_task
-      end
-
-      # Synchronous wrapper around {#stream_async}.
-      #
-      # Stream callbacks execute on the EventLoop thread, not on the thread that
-      # calls this method. This method only blocks while waiting for the final Task.
-      # @yield [Phronomy::Agent::StreamEvent]
-      # @return [Hash] same result shape as #invoke
-      # @api public
-      def stream(input, messages: [], thread_id: nil, config: {},
-        invocation_context: nil, on_tool_approval_required: nil, &block)
-        raise ArgumentError, "stream requires a block" unless block
-
-        if invocation_context
-          thread_id, config = _apply_invocation_context(thread_id, config, invocation_context)
-        end
-        _check_scheduler_reentrancy(:stream, :stream_async)
-
-        trace("agent.stream", input: input, **_build_caller_meta(config)) do |_span|
-          result = stream_async(
-            input,
-            messages: messages,
-            thread_id: thread_id,
-            config: config,
-            on_tool_approval_required: on_tool_approval_required,
-            &block
-          ).wait_result
-          [result, result[:usage]]
-        end
-      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.
@@ -594,153 +629,8 @@ 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+.
+      # registered sources are included in every LLM call via the Context Policy.
       #
       # @param source [#fetch] any object responding to +fetch(query:)+
       # @return [void]
@@ -761,50 +651,6 @@ module Phronomy
       end
       protected :instance_knowledge_chunks
 
-      # Starts one AgentInvocation and resolves +result_task+ from that session.
-      # Phronomy translates the adapter's final error but never starts another
-      # AgentInvocation automatically.
-      # @api private
-      def _start_invocation(result_task, input, messages:, thread_id:, config:,
-        approval_snapshot:, mode: :invoke, on_event: nil)
-        effective_config = thread_id ? config.merge(thread_id: thread_id) : config
-        check_cancellation!(effective_config, "invocation cancelled")
-        runtime = Phronomy::Runtime.instance
-        event_loop = runtime.event_loop
-        session = Agent::AgentInvocationSessionBuilder.build(
-          agent: self,
-          input: input,
-          messages: messages,
-          config: effective_config,
-          approval_policy: approval_snapshot[:policy],
-          approval_listener: approval_snapshot[:listener],
-          mode: mode,
-          on_event: on_event,
-          runtime: runtime
-        )
-        callback_error_policy =
-          Phronomy.configuration.stream_callback_error_policy
-        source_task = Phronomy::Task.deferred(name: "#{result_task.name}-source")
-        source_task.on_complete do |invocation, error|
-          _handle_agent_completion(
-            result_task: result_task,
-            invocation: invocation,
-            error: error,
-            mode: mode,
-            listener: on_event,
-            event_loop: event_loop,
-            callback_error_policy: callback_error_policy
-          )
-        end
-
-        # Register completion handling before EventLoop admission. Otherwise an
-        # immediately finishing session can complete source_task before the
-        # callback is installed, causing Task#on_complete to run on this thread.
-        event_loop.register(session, completion: source_task)
-      rescue => e
-        _fail_result_task(result_task, e)
-      end
-
       def _complete_result_task(task, result)
         task.backend.unblock(result, nil)
         task.transition!(:completed, value: result)
@@ -821,83 +667,6 @@ module Phronomy
         translated
       end
 
-      # Completes one Agent execution interval. Execution failures and
-      # Application callback failures are deliberately handled in separate
-      # exception domains.
-      def _handle_agent_completion(result_task:, invocation:, error:, mode:, listener:,
-        event_loop:, callback_error_policy:)
-        if mode == :stream && !event_loop.current?
-          completion_error = error || Phronomy::Error.new(
-            "Stream completion occurred outside the EventLoop"
-          )
-          _fail_result_task(result_task, _translated_error(completion_error))
-          return
-        end
-
-        result = nil
-        execution_error = nil
-        begin
-          raise error if error
-
-          result = _extract_invoke_result(invocation)
-        rescue => e
-          execution_error = _translated_error(e)
-        end
-
-        if execution_error
-          if mode == :stream
-            event = StreamEvent.new(
-              type: :error,
-              payload: {error: execution_error}
-            )
-            callback_error = _deliver_stream_event(listener, event)
-            if callback_error
-              _report_stream_callback_error(
-                callback_error,
-                event: event,
-                invocation_id: invocation&.id,
-                callback_error_policy: callback_error_policy
-              )
-            end
-          end
-
-          # An Application failure while consuming :error never replaces the
-          # original Agent/LLM/Tool/Runtime failure.
-          _fail_result_task(result_task, execution_error)
-          return
-        end
-
-        unless mode == :stream
-          _complete_result_task(result_task, result)
-          return
-        end
-
-        event = _build_stream_terminal_event(result)
-        callback_error = _deliver_stream_event(listener, event)
-        unless callback_error
-          _complete_result_task(result_task, result)
-          return
-        end
-
-        _report_stream_callback_error(
-          callback_error,
-          event: event,
-          invocation_id: invocation&.id,
-          callback_error_policy: callback_error_policy
-        )
-
-        if callback_error_policy == :fail_task
-          wrapped = _build_stream_callback_error(
-            event_type: event.type,
-            callback_error: callback_error,
-            result: result
-          )
-          _fail_result_task(result_task, wrapped)
-        else
-          _complete_result_task(result_task, result)
-        end
-      end
-
       def _build_stream_terminal_event(result)
         if result[:suspended]
           StreamEvent.new(
@@ -976,169 +745,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
-
-      # Parent completion handling is installed before EventLoop registration,
-      # and the parent session is registered before child sessions so immediate
-      # child events cannot be lost.
-      # @api private
-      def _start_approval_resume(result_task, invocation, approved:, config:)
-        invocation.merge_config!(config)
-        invocation.begin_approval_resume!(approved: approved)
-        runtime = Phronomy::Runtime.instance
-        event_loop = runtime.event_loop
-        source_task = Phronomy::Task.deferred(
-          name: "#{result_task.name}-source"
-        )
-        parent_session = Agent::AgentInvocationSessionBuilder.build_for_resume(
-          agent_invocation: invocation,
-          resume_event: :resume,
-          resume_phase: :suspended,
-          runtime: runtime
-        )
-        stream_listener = invocation.stream_listener
-        mode = stream_listener ? :stream : :invoke
-        callback_error_policy =
-          Phronomy.configuration.stream_callback_error_policy
-
-        source_task.on_complete do |completed_invocation, error|
-          _handle_agent_completion(
-            result_task: result_task,
-            invocation: completed_invocation,
-            error: error,
-            mode: mode,
-            listener: stream_listener,
-            event_loop: event_loop,
-            callback_error_policy: callback_error_policy
-          )
-        end
-
-        # The parent must exist before any child can post an immediate result.
-        event_loop.register(parent_session, completion: source_task)
-
-        invocation.tool_invocations.each do |child|
-          child_session = if child.awaiting_approval?
-            Agent::ToolInvocationSessionBuilder.build_for_resume(
-              tool_invocation: child,
-              resume_event: approved ? :approve : :reject,
-              resume_phase: :awaiting_approval,
-              runtime: runtime
-            )
-          elsif !approved && child.authorized?
-            Agent::ToolInvocationSessionBuilder.build_for_resume(
-              tool_invocation: child,
-              resume_event: :cancel,
-              resume_phase: :authorized,
-              runtime: runtime
-            )
-          end
-          _register_tool_invocation_session(event_loop, runtime, child, child_session) if child_session
-        end
-      end
-
-      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 _register_tool_invocation_session(event_loop, runtime, child, session)
-        completion = Phronomy::Task.deferred(name: "tool-session:#{child.id}")
-        completion.on_complete do |_result, error|
-          next unless error
-
-          child.mark_framework_failed!(error)
-          runtime.event_loop.post(
-            Phronomy::Event.new(
-              type: :tool_failed,
-              target_id: child.parent_agent_invocation_id,
-              payload: {tool_invocation_id: child.id}
-            )
-          )
-        end
-        event_loop.register(session, completion: completion)
-      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
 
@@ -1168,11 +774,33 @@ module Phronomy
       end
 
       def _apply_context_to_chat(chat, context)
-        apply_instructions(chat, context[:system]) if context[:system]
+        model_config = context[:model_config] || {}
+        if context[:system]
+          apply_instructions(
+            chat,
+            context[:system],
+            cache: model_config["cache_instructions"],
+            provider: model_config["provider"]
+          )
+        end
         (context[:tool_classes] || []).each { |tc| chat.with_tool(prepare_tool_class(tc)) }
         context[:messages].each { |msg| chat.messages << msg }
       end
 
+      def _replace_chat_messages(chat, projection)
+        chat.messages.clear
+        if projection.system
+          apply_instructions(
+            chat,
+            projection.system,
+            cache: projection.model_config["cache_instructions"],
+            provider: projection.model_config["provider"]
+          )
+        end
+        projection.messages.each { |message| chat.messages << message }
+        chat
+      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
@@ -1189,9 +817,27 @@ module Phronomy
             overhead: self.class.context_overhead
           )
         else
+          ruby_llm_model = RubyLLM.models.find(model_name)
+          return nil unless ruby_llm_model
+
+          registry_context = ruby_llm_model.context_window.to_i
+          registry_max_output = ruby_llm_model.max_output_tokens.to_i
+
+          # Priority: agent explicit → framework default → registry (if < context_window)
+          output_reserve =
+            self.class.max_output_tokens ||
+            Phronomy.configuration.default_output_reserve ||
+            ((registry_max_output < registry_context) ? registry_max_output : nil)
+
+          if output_reserve.nil?
+            raise Phronomy::InvalidContextBudgetConfigurationError,
+              "Cannot determine output token reserve for model '#{model_name}'. " \
+              "Set max_output_tokens on the agent or Phronomy.configure { |c| c.default_output_reserve = N }."
+          end
+
           Phronomy::LlmContextWindow::TokenBudget.new(
-            model: model_name,
-            max_output_tokens: self.class.max_output_tokens,
+            context_window: registry_context,
+            max_output_tokens: output_reserve,
             overhead: self.class.context_overhead
           )
         end
@@ -1208,23 +854,29 @@ module Phronomy
         Phronomy.configuration.parallel_tool_execution ? Phronomy::MultiAgent::ParallelToolChat : nil
       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
 
@@ -1244,8 +896,8 @@ module Phronomy
       # 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
@@ -1278,7 +930,15 @@ module Phronomy
       # @api public
       def check_cancellation!(config, message = "invocation cancelled")
         ct = config[:cancellation_token]
-        raise Phronomy::CancellationError, message if ct&.cancelled?
+        return unless ct&.cancelled?
+
+        # Deadline expiry is a timeout; explicit cancel! is a cancellation.
+        if (ct.respond_to?(:deadline) && ct.deadline && Time.now >= ct.deadline) ||
+            (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