riffer 0.28.0 → 0.29.1

data/lib/riffer/agent.rb

@@ -19,42 +19,36 @@ require "json"
 #   agent.generate('Hello!')
 #
 class Riffer::Agent
+  # @rbs self.@config: Riffer::Agent::Config?
+
   include Riffer::Messages::Converter
   extend Riffer::Helpers::ClassNameConverter
-  extend Riffer::Helpers::Validations
 
-  DEFAULT_MAX_STEPS = 16 #: Integer
   INTERRUPT_MAX_STEPS = :max_steps #: Symbol
 
-  # Placeholder used to fill orphan +tool_use+ blocks when
-  # +Riffer.config.experimental_history_healing+ is enabled and an
-  # interrupt fires mid-tool-use.
-  HEALING_PLACEHOLDER = ->(_tool_call) {
-    Riffer::Tools::Response.error("Tool call interrupted before completion.", type: :interrupted)
-  } #: ^(Riffer::Messages::Assistant::ToolCall) -> Riffer::Tools::Response
+  # Returns the per-class Riffer::Agent::Config value object holding every
+  # DSL setting. Lazily initialized on first read; each subclass has its own.
+  #
+  #--
+  #: () -> Riffer::Agent::Config
+  def self.config
+    @config ||= Riffer::Agent::Config.new
+  end
 
   # Gets or sets the agent identifier.
   #
   #--
   #: (?String?) -> String
   def self.identifier(value = nil)
-    return @identifier || class_name_to_path(name) if value.nil?
-    @identifier = value.to_s
+    value.nil? ? (config.identifier || class_name_to_path(name)) : (config.identifier = value)
   end
 
   # Gets or sets the model string (e.g., "openai/gpt-4o") or Proc.
   #
   #--
   #: (?(String | Proc)?) -> (String | Proc)?
-  def self.model(model_string_or_proc = nil)
-    return @model if model_string_or_proc.nil?
-
-    if model_string_or_proc.is_a?(Proc)
-      @model = model_string_or_proc
-    else
-      validate_is_string!(model_string_or_proc, "model")
-      @model = model_string_or_proc
-    end
+  def self.model(value = nil)
+    value.nil? ? config.model : (config.model = value)
   end
 
   # Gets or sets the agent instructions.
@@ -71,15 +65,8 @@ class Riffer::Agent
   #
   #--
   #: (?(String | Proc)?) -> (String | Proc)?
-  def self.instructions(instructions_or_proc = nil)
-    return @instructions if instructions_or_proc.nil?
-
-    if instructions_or_proc.is_a?(Proc)
-      @instructions = instructions_or_proc
-    else
-      validate_is_string!(instructions_or_proc, "instructions")
-      @instructions = instructions_or_proc
-    end
+  def self.instructions(value = nil)
+    value.nil? ? config.instructions : (config.instructions = value)
   end
 
   # Gets or sets provider options passed to the provider client.
@@ -87,8 +74,7 @@ class Riffer::Agent
   #--
   #: (?Hash[Symbol, untyped]?) -> Hash[Symbol, untyped]
   def self.provider_options(options = nil)
-    return @provider_options || {} if options.nil?
-    @provider_options = options
+    options.nil? ? config.provider_options : (config.provider_options = options)
   end
 
   # Gets or sets model options passed to generate_text/stream_text.
@@ -96,8 +82,7 @@ class Riffer::Agent
   #--
   #: (?Hash[Symbol, untyped]?) -> Hash[Symbol, untyped]
   def self.model_options(options = nil)
-    return @model_options || {} if options.nil?
-    @model_options = options
+    options.nil? ? config.model_options : (config.model_options = options)
   end
 
   # Gets or sets the structured output schema for this agent.
@@ -105,89 +90,34 @@ class Riffer::Agent
   # Accepts a Riffer::Params instance or a block evaluated against a new Params.
   #
   #--
-  #: (?Riffer::Params?) ?{ () -> void } -> Riffer::Params?
+  #: (?Riffer::Params?) ?{ (Riffer::Params) [self: Riffer::Params] -> void } -> Riffer::Params?
   def self.structured_output(params = nil, &block)
     if block
-      @structured_output = Riffer::Params.new
-      @structured_output.instance_eval(&block)
-    elsif params.nil?
-      @structured_output
-    else
-      raise Riffer::ArgumentError, "structured_output must be a Riffer::Params" unless params.is_a?(Riffer::Params)
-      @structured_output = params
+      params = Riffer::Params.new
+      params.instance_eval(&block)
     end
+    config.structured_output = params if params
+    config.structured_output
   end
 
   # Gets or sets the maximum number of LLM call steps in the tool-use loop.
   #
-  # Defaults to DEFAULT_MAX_STEPS (16). Set to +Float::INFINITY+ for
-  # unlimited steps.
+  # Defaults to Riffer::Agent::Config::DEFAULT_MAX_STEPS (16). Set to
+  # +Float::INFINITY+ for unlimited steps.
   #
   #--
   #: (?Numeric?) -> Numeric
   def self.max_steps(value = nil)
-    return @max_steps || DEFAULT_MAX_STEPS if value.nil?
-    @max_steps = value
+    value.nil? ? config.max_steps : (config.max_steps = value)
   end
 
   # Gets or sets the tools used by this agent.
   #
   #--
   #: (?(Array[singleton(Riffer::Tool)] | Proc)?) -> (Array[singleton(Riffer::Tool)] | Proc)?
-  def self.uses_tools(tools_or_lambda = nil)
-    return @tools_config if tools_or_lambda.nil?
-    @tools_config = tools_or_lambda
-  end
-
-  # Returns the tool classes the LLM should see for this agent.
-  #
-  # Class-level companion to the instance #resolved_tools. Resolves the
-  # Proc form of +uses_tools+ and appends the skill activation tool when
-  # a +skills+ block is configured. Does not read the skills backend —
-  # the LLM-facing tool schema reflects class-level intent, not the
-  # runtime state of any backend.
-  #
-  # When +uses_tools+ is a Proc, +context+ is forwarded to it.
-  #
-  # The activation tool class is resolved from the agent's
-  # <tt>skills do; activate_tool ...; end</tt> override when set, otherwise
-  # from <tt>Riffer.config.skills.default_activate_tool</tt>.
-  #
-  # Each returned tool class is validated via +validate_as_tool!+, so
-  # callers serializing this list to a provider can rely on every entry
-  # having the metadata required for tool use (name + description).
-  #
-  # Raises Riffer::ArgumentError on tool name conflicts with the skill
-  # activation tool, or when a tool class fails +validate_as_tool!+.
-  #
-  #--
-  #: (?context: Hash[Symbol, untyped]?) -> Array[singleton(Riffer::Tool)]
-  def self.resolved_tool_classes(context: nil)
-    base = resolve_uses_tools_config(context)
-
-    tools = if skills
-      skill_activate_tool_class = skills.activate_tool || Riffer.config.skills.default_activate_tool
-      if base.any? { |t| t.name == skill_activate_tool_class.name }
-        raise Riffer::ArgumentError, "Tool name conflict with skill tools: #{skill_activate_tool_class.name}"
-      end
-      base + [skill_activate_tool_class]
-    else
-      base
-    end
-
-    tools.each(&:validate_as_tool!)
-    tools
-  end
-
-  #--
-  #: (Hash[Symbol, untyped]?) -> Array[singleton(Riffer::Tool)]
-  def self.resolve_uses_tools_config(context)
-    config = uses_tools
-    return [] if config.nil?
-    return config unless config.is_a?(Proc)
-    config.arity.zero? ? config.call : config.call(context)
+  def self.uses_tools(value = nil)
+    value.nil? ? config.tools_config : (config.tools_config = value)
   end
-  private_class_method :resolve_uses_tools_config
 
   # Opts this agent into tools from all MCP registrations that share any of
   # the given tag(s).
@@ -196,34 +126,25 @@ class Riffer::Agent
   #
   #: (String | Symbol) -> void
   def self.use_mcp(tag)
-    @mcp_configs ||= []
-    @mcp_configs << {tags: [tag.to_sym]}
+    config.add_mcp(tag)
   end
 
   # Returns the accumulated +use_mcp+ configurations for this agent class.
   #
   #: () -> Array[Hash[Symbol, untyped]]
   def self.mcp_configs
-    @mcp_configs || []
+    config.mcp_configs
   end
 
   # Gets or sets the tool runtime for this agent.
   #
-  # Accepts a Riffer::ToolRuntime subclass, a Riffer::ToolRuntime instance,
-  # or a Proc.
-  #
-  # Inherited by subclasses. When unset, walks the ancestor chain and
-  # falls back to the global <tt>Riffer.config.tool_runtime</tt>.
+  # Accepts a Riffer::Tools::Runtime subclass, a Riffer::Tools::Runtime instance,
+  # or a Proc. Defaults to <tt>Riffer.config.tool_runtime</tt> when unset.
   #
   #--
-  #: (?(singleton(Riffer::ToolRuntime) | Riffer::ToolRuntime | Proc)?) -> (singleton(Riffer::ToolRuntime) | Riffer::ToolRuntime | Proc)?
+  #: (?(singleton(Riffer::Tools::Runtime) | Riffer::Tools::Runtime | Proc)?) -> (singleton(Riffer::Tools::Runtime) | Riffer::Tools::Runtime | Proc)
   def self.tool_runtime(value = nil)
-    if value.nil?
-      return @tool_runtime if instance_variable_defined?(:@tool_runtime)
-      superclass.respond_to?(:tool_runtime) ? superclass.tool_runtime : nil
-    else
-      @tool_runtime = value
-    end
+    value.nil? ? config.tool_runtime : (config.tool_runtime = value)
   end
 
   # Configures skills for this agent via a block DSL.
@@ -237,13 +158,14 @@ class Riffer::Agent
   #   end
   #
   #--
-  #: () ?{ () -> void } -> Riffer::Skills::Config?
+  #: () ?{ (Riffer::Skills::Config) [self: Riffer::Skills::Config] -> void } -> Riffer::Skills::Config?
   def self.skills(&block)
     if block
-      @skills_config = Riffer::Skills::Config.new
-      @skills_config.instance_eval(&block)
+      skills_config = Riffer::Skills::Config.new
+      skills_config.instance_eval(&block)
+      config.skills_config = skills_config
     end
-    @skills_config
+    config.skills_config
   end
 
   # Finds an agent class by identifier.
@@ -264,22 +186,24 @@ class Riffer::Agent
 
   # Generates a response using a new agent instance.
   #
-  # See #generate for parameters and return value.
+  # +context:+ is threaded into +new+; +prompt+ and +files:+ are forwarded
+  # to +#generate+.
   #
   #--
-  #: (*untyped, **untyped) -> Riffer::Agent::Response
-  def self.generate(...)
-    new.generate(...)
+  #: (?String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?, ?context: Hash[Symbol, untyped]?) -> Riffer::Agent::Response
+  def self.generate(prompt = nil, files: nil, context: nil)
+    new(context: context).generate(prompt, files: files)
   end
 
   # Streams a response using a new agent instance.
   #
-  # See #stream for parameters and return value.
+  # +context:+ is threaded into +new+; +prompt+ and +files:+ are forwarded
+  # to +#stream+.
   #
   #--
-  #: (*untyped, **untyped) -> Enumerator[Riffer::StreamEvents::Base, void]
-  def self.stream(...)
-    new.stream(...)
+  #: (?String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?, ?context: Hash[Symbol, untyped]?) -> Enumerator[Riffer::StreamEvents::Base, void]
+  def self.stream(prompt = nil, files: nil, context: nil)
+    new(context: context).stream(prompt, files: files)
   end
 
   # Registers a guardrail for input, output, or both phases.
@@ -292,22 +216,7 @@ class Riffer::Agent
   #--
   #: (Symbol, with: singleton(Riffer::Guardrail), **untyped) -> void
   def self.guardrail(phase, with:, **options)
-    valid_phases = [*Riffer::Guardrails::PHASES, :around]
-    raise Riffer::ArgumentError, "Invalid guardrail phase: #{phase}" unless valid_phases.include?(phase)
-    raise Riffer::ArgumentError, "Guardrail must be a Riffer::Guardrail subclass" unless with.is_a?(Class) && with <= Riffer::Guardrail
-
-    @guardrails ||= {before: [], after: []}
-    config = {class: with, options: options}
-
-    case phase
-    when :before
-      @guardrails[:before] << config
-    when :after
-      @guardrails[:after] << config
-    when :around
-      @guardrails[:before] << config
-      @guardrails[:after] << config
-    end
+    config.add_guardrail(phase, klass: with, options: options)
   end
 
   # Returns the registered guardrail configs for a given phase.
@@ -317,127 +226,136 @@ class Riffer::Agent
   #--
   #: (Symbol) -> Array[Hash[Symbol, untyped]]
   def self.guardrails_for(phase)
-    @guardrails ||= {before: [], after: []}
-    @guardrails[phase] || []
-  end
-
-  # The message history for the agent.
-  attr_reader :messages #: Array[Riffer::Messages::Base]
-
-  # Cumulative token usage across all LLM calls.
-  attr_reader :token_usage #: Riffer::TokenUsage?
+    config.guardrails_for(phase)
+  end
+
+  # The conversation handle. See Riffer::Agent::Session.
+  attr_reader :session #: Riffer::Agent::Session
+
+  # The per-instance Riffer::Agent::Config. Either the class-level default or
+  # an explicit Config passed to +Agent.new(config:)+.
+  attr_reader :config #: Riffer::Agent::Config
+
+  # The system message built from the configured +instructions+, or +nil+
+  # when no instructions are configured. Built once at +Agent.new+ using the
+  # constructor +context:+ and cached. Useful for persistence flows.
+  attr_reader :instruction_message #: Riffer::Messages::System?
+
+  # The system message describing the configured skills catalog, or +nil+
+  # when skills are unconfigured or the catalog is empty. Built once at
+  # +Agent.new+ and cached.
+  attr_reader :skills_message #: Riffer::Messages::System?
+
+  # The mutable runtime context, a +Riffer::Agent::Context+ value object
+  # threaded into every Proc-based DSL setting, guardrail, tool runtime,
+  # and skills resolution, and shared with every +Riffer::Agent::Run+
+  # this agent executes. Exposes:
+  #
+  # - +context.skills+ — the resolved +Riffer::Skills::Context+ (when
+  #   skills are configured), set at +Agent.new+ time.
+  # - +context.token_usage+ — the cumulative +Riffer::Providers::TokenUsage+,
+  #   updated by each Run as the loop progresses.
+  # - +context[:key]+ / <tt>context.dig(:key)</tt> — Hash-style reads for
+  #   caller-provided keys (e.g. <tt>context[:agent]</tt>,
+  #   <tt>context[:tenant]</tt>). +:skills+ and +:token_usage+ are
+  #   reserved and cannot be passed by the caller.
+  attr_reader :context #: Riffer::Agent::Context
+
+  # The resolved model name (the part after "provider/"), used as the model
+  # argument on every LLM call. Resolved eagerly at +Agent.new+.
+  attr_reader :model_name #: String
+
+  # The provider client. Built eagerly at +Agent.new+ from the configured
+  # provider class and +Config#provider_options+, then handed to every
+  # +Riffer::Agent::Run+ this agent executes. Public so tests can pre-queue
+  # responses on +Riffer::Providers::Mock+ before calling +#generate+.
+  attr_reader :provider #: Riffer::Providers::Base
+
+  # The +Riffer::Agent::StructuredOutput+ wrapping the configured schema, or +nil+
+  # when structured output is not configured. Resolved eagerly at +Agent.new+.
+  attr_reader :structured_output #: Riffer::Agent::StructuredOutput?
+
+  # The tool classes the LLM sees on every call this agent makes. Resolved
+  # eagerly at +Agent.new+ (Proc-form +uses_tools+ is called against
+  # +context+ once; MCP tools and the skill_activate tool are merged in).
+  attr_reader :tools #: Array[singleton(Riffer::Tool)]
+
+  # The tool runtime instance used to execute tool calls. Resolved eagerly
+  # at +Agent.new+ (Proc-form +tool_runtime+ is called against +context+ once).
+  attr_reader :tool_runtime #: Riffer::Tools::Runtime
 
   # Initializes a new agent.
   #
-  # Raises Riffer::ArgumentError if the configured model string is invalid
-  # (must be "provider/model" format).
-  #
-  #--
-  #: () -> void
-  def initialize
-    @messages = []
-    @message_callbacks = []
-    @token_usage = nil
-    @interrupted = false
-    @model_config = self.class.model
-    @instructions_config = self.class.instructions
-
-    if @model_config.is_a?(Proc)
-      @provider_name = nil
-      @model_name = nil
-    else
-      parse_model_string!(@model_config)
-    end
-  end
-
-  # Generates a response from the agent.
-  #
-  # When +Riffer.config.experimental_history_healing+ is enabled, seeded
-  # message arrays that violate the +tool_use+ ↔ +tool_result+ invariant
-  # are silently repaired before the run begins.
+  # When +session:+ is omitted, a fresh +Riffer::Agent::Session+ is built and seeded
+  # with the system instruction message and skills catalog (when configured),
+  # using +context:+. When +session:+ is provided, the agent uses it as-is —
+  # the caller is responsible for the session's contents (typical use case:
+  # cross-process resume from persisted history). With
+  # +Riffer.config.experimental_history_healing+ on, a provided session is
+  # healed at construction time so the +tool_use+ ↔ +tool_result+ invariant
+  # holds before the next inference call.
   #
-  #--
-  #: ((String | Array[Hash[Symbol, untyped] | Riffer::Messages::Base]), ?files: Array[Hash[Symbol, untyped] | Riffer::FilePart]?, ?context: Hash[Symbol, untyped]?) -> Riffer::Agent::Response
-  def generate(prompt_or_messages, files: nil, context: nil)
-    @context = context
-    prepare_run
-    @structured_output = resolve_structured_output
-    initialize_messages(prompt_or_messages, files: files)
-
-    all_modifications = [] #: Array[Riffer::Guardrails::Modification]
-
-    tripwire, modifications = run_before_guardrails
-    all_modifications.concat(modifications)
-    return build_response("", tripwire: tripwire, modifications: all_modifications) if tripwire
-
-    run_generate_loop(all_modifications)
-  end
-
-  # Streams a response from the agent.
-  #
-  # Raises Riffer::ArgumentError if structured output is configured.
+  # +context:+ flows through Proc-based instructions, model, skills resolution,
+  # tool resolution, guardrails, and tool runtime. It is fixed for the
+  # lifetime of the agent.
   #
-  # See +#generate+ for the +experimental_history_healing+ behavior on
-  # seeded arrays.
+  # Raises Riffer::ArgumentError if the configured model string is invalid
+  # (must be "provider/model" format).
   #
   #--
-  #: ((String | Array[Hash[Symbol, untyped] | Riffer::Messages::Base]), ?files: Array[Hash[Symbol, untyped] | Riffer::FilePart]?, ?context: Hash[Symbol, untyped]?) -> Enumerator[Riffer::StreamEvents::Base, void]
-  def stream(prompt_or_messages, files: nil, context: nil)
-    raise Riffer::ArgumentError, "Structured output is not supported with streaming. Use #generate instead." if self.class.structured_output
+  #: (?session: Riffer::Agent::Session?, ?context: Hash[Symbol, untyped]?, ?config: Riffer::Agent::Config?) -> void
+  def initialize(session: nil, context: nil, config: nil)
+    @config = config || self.class.config
+    @context = Riffer::Agent::Context.new(context || {})
 
-    @context = context
-    prepare_run
-    initialize_messages(prompt_or_messages, files: files)
+    provider_class, @model_name = resolve_provider_and_model
+    @provider = provider_class.new(**@config.provider_options)
 
-    Enumerator.new do |yielder|
-      tripwire, modifications = run_before_guardrails
-      modifications.each { |m| yielder << Riffer::StreamEvents::GuardrailModification.new(m) }
+    @context.skills = resolve_skills(provider_class)
 
-      if tripwire
-        yielder << Riffer::StreamEvents::GuardrailTripwire.new(tripwire)
-        next
-      end
+    @structured_output = resolve_structured_output
+    @tools = resolve_tools
+    @tool_runtime = resolve_tool_runtime
 
-      run_stream_loop(yielder)
-    end
-  end
+    @instruction_message = build_instruction_message
+    @skills_message = build_skills_message
 
-  # Registers a callback to be invoked when messages are added during generation.
-  #
-  # Raises Riffer::ArgumentError if no block is given.
-  #
-  #--
-  #: () { (Riffer::Messages::Base) -> void } -> self
-  def on_message(&block)
-    raise Riffer::ArgumentError, "on_message requires a block" unless block_given?
-    @message_callbacks << block
-    self
+    @session = session || Riffer::Agent::Session.new(messages: [@instruction_message, @skills_message].compact)
+    @session.set(Riffer::Agent::Session::Repair.prune_orphans(@session.messages))
   end
 
-  # Generates the instruction system message for this agent.
+  # Generates a response from the agent.
   #
-  # Useful for database persistence workflows where the system messages
-  # need to be stored independently.
+  # Runs the inference loop via +Riffer::Agent::Run.generate+. When +prompt+
+  # is given, a new +Riffer::Messages::User+ is appended to the session
+  # (silently — +on_message+ does not fire for user inputs) and then the
+  # loop runs. When +prompt+ is omitted, the loop runs against the current
+  # session — useful for resuming a persisted conversation whose last turn
+  # is already a user message, or for picking up pending tool calls after
+  # an interrupt.
   #
-  # Returns +nil+ when no instructions are configured.
+  # +files:+ requires +prompt+. Pass files to attach to the new user message.
   #
   #--
-  #: (?context: Hash[Symbol, untyped]?) -> Riffer::Messages::System?
-  def generate_instruction_message(context: nil)
-    build_instruction_message(context)
+  #: (?String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?) -> Riffer::Agent::Response
+  def generate(prompt = nil, files: nil)
+    Riffer::Agent::Run.generate(agent: self, prompt: prompt, files: files)
   end
 
-  # Generates the skills catalog system message for this agent.
+  # Streams a response from the agent.
   #
-  # Useful for database persistence workflows where the system messages
-  # need to be stored independently.
+  # Runs the inference loop via +Riffer::Agent::Run.stream+, returning an
+  # +Enumerator+ of +Riffer::StreamEvents+.
+  #
+  # Raises Riffer::ArgumentError if structured output is configured.
   #
-  # Returns +nil+ when no skills are configured or the catalog is empty.
+  # See +#generate+ for prompt/files semantics.
   #
   #--
-  #: (?context: Hash[Symbol, untyped]?) -> Riffer::Messages::System?
-  def generate_skills_message(context: nil)
-    build_skills_message(resolve_skills(context))
+  #: (?String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?) -> Enumerator[Riffer::StreamEvents::Base, void]
+  def stream(prompt = nil, files: nil)
+    raise Riffer::ArgumentError, "Structured output is not supported with streaming. Use #generate instead." if @structured_output
+    Riffer::Agent::Run.stream(agent: self, prompt: prompt, files: files)
   end
 
   # Interrupts the agent loop.
@@ -458,599 +376,135 @@ class Riffer::Agent
     throw :riffer_interrupt, reason
   end
 
-  # Returns the message with the given id, or +nil+ when no message matches.
-  #
-  #--
-  #: (String) -> Riffer::Messages::Base?
-  def message_by_id(id)
-    @messages.find { |m| m.id == id }
-  end
+  private
 
-  # Returns the +Riffer::Messages::Tool+ message that satisfies +tool_call_id+,
-  # or +nil+ when no such tool result exists in history.
-  #
   #--
-  #: (String) -> Riffer::Messages::Tool?
-  # TODO: Replace with rfind when minimum Ruby is 4.0+
-  # rubocop:disable Style/ReverseFind
-  def tool_message_for(tool_call_id)
-    @messages.reverse.find { |m| m.is_a?(Riffer::Messages::Tool) && m.tool_call_id == tool_call_id } #: Riffer::Messages::Tool?
+  #: () -> Riffer::Messages::System?
+  def build_instruction_message
+    content = Riffer::Helpers::CallOrValue.resolve(@config.instructions, context: @context)
+    return nil if content.nil? || content.empty?
+    Riffer::Messages::System.new(content)
   end
-  # rubocop:enable Style/ReverseFind
 
-  # Returns the most recent +Riffer::Messages::Assistant+ in history, or
-  # +nil+ when no assistant message has been recorded yet.
-  #
   #--
-  #: () -> Riffer::Messages::Assistant?
-  # TODO: Replace with rfind when minimum Ruby is 4.0+
-  # rubocop:disable Style/ReverseFind
-  def last_assistant
-    @messages.reverse.find { |m| m.is_a?(Riffer::Messages::Assistant) } #: Riffer::Messages::Assistant?
+  #: () -> Riffer::Messages::System?
+  def build_skills_message
+    skills = @context.skills
+    return nil unless skills&.system_prompt
+    Riffer::Messages::System.new(skills.system_prompt)
   end
-  # rubocop:enable Style/ReverseFind
 
-  # Returns the call_ids of every +tool_call+ on any assistant message that
-  # has no matching +Riffer::Messages::Tool+ result anywhere in history.
+  # Resolves +Config#model+ to a "provider/model" string (calling the Proc
+  # form against +@context+), parses it, and looks up the provider class.
   #
-  # Zero-cost validation hook for callers that want to check the
-  # +tool_use+ ↔ +tool_result+ invariant before mutating or persisting.
+  # Returns +[provider_class, model_name]+. Raises Riffer::ArgumentError on
+  # an invalid model string or an unregistered provider.
   #
   #--
-  #: () -> Array[String]
-  def orphaned_tool_call_ids
-    result_ids = @messages.filter_map { |m| m.tool_call_id if m.is_a?(Riffer::Messages::Tool) }
-    @messages.flat_map { |m|
-      next [] unless m.is_a?(Riffer::Messages::Assistant)
-      m.tool_calls.reject { |tc| result_ids.include?(tc.call_id) }.map(&:call_id)
-    }
-  end
+  #: () -> [singleton(Riffer::Providers::Base), String]
+  def resolve_provider_and_model
+    model_string = Riffer::Helpers::CallOrValue.resolve(@config.model, context: @context)
+    raise Riffer::ArgumentError, "Invalid model string: #{model_string}" unless model_string.is_a?(String)
 
-  # Replaces the content of an assistant message in place. Preserves +id+,
-  # +tool_calls+, +token_usage+, and +structured_output+. Lookup is by id.
-  #
-  # When +content+ is empty, delegates to +remove_message+ — including the
-  # cascade that drops dependent +Riffer::Messages::Tool+ children.
-  #
-  # Raises Riffer::ArgumentError when no assistant message has the given id.
-  #
-  #--
-  #: (id: String, content: String) -> Riffer::Messages::Base?
-  def replace_assistant_content(id:, content:)
-    return remove_message(id: id) if content.empty?
-
-    idx = @messages.index { |m| m.is_a?(Riffer::Messages::Assistant) && m.id == id }
-    raise Riffer::ArgumentError, "no assistant message with id #{id.inspect}" unless idx
-
-    old = @messages[idx] #: Riffer::Messages::Assistant
-    replacement = Riffer::Messages::Assistant.new(
-      content,
-      id: old.id,
-      tool_calls: old.tool_calls,
-      token_usage: old.token_usage,
-      structured_output: old.structured_output
-    )
-    @messages[idx] = replacement
-    replacement
-  end
+    provider_name, model_name = model_string.split("/", 2)
 
-  # Removes a message by id. When the target is an assistant message that
-  # carries +tool_calls+, every +Riffer::Messages::Tool+ result whose
-  # +tool_call_id+ matches one of those calls is removed atomically — keeping
-  # the +tool_use+ ↔ +tool_result+ invariant intact.
-  #
-  # Raises Riffer::ArgumentError when called on a +Riffer::Messages::Tool+
-  # message — that would orphan the parent's +tool_use+. Use
-  # +replace_tool_result+ instead.
-  #
-  # Returns the removed message, or +nil+ when no message has the given id
-  # (idempotent).
-  #
-  #--
-  #: (id: String) -> Riffer::Messages::Base?
-  def remove_message(id:)
-    idx = @messages.index { |m| m.id == id }
-    return nil unless idx
-
-    target = @messages[idx]
-    if target.is_a?(Riffer::Messages::Tool)
-      raise Riffer::ArgumentError,
-        "remove_message cannot drop a Tool message (would orphan the parent's tool_use); use replace_tool_result instead"
+    unless provider_name.is_a?(String) && !provider_name.strip.empty? && model_name.is_a?(String) && !model_name.strip.empty?
+      raise Riffer::ArgumentError, "Invalid model string: #{model_string}"
     end
 
-    if target.is_a?(Riffer::Messages::Assistant) && !target.tool_calls.empty?
-      child_ids = target.tool_calls.map(&:call_id)
-      @messages.reject! { |m| m.is_a?(Riffer::Messages::Tool) && child_ids.include?(m.tool_call_id) }
-      @messages.delete(target)
-    else
-      @messages.delete_at(idx)
-    end
-    target
-  end
+    provider_class = Riffer::Providers::Repository.find(provider_name)
+    raise Riffer::ArgumentError, "Provider not found: #{provider_name}" unless provider_class
 
-  # Replaces a tool result's content (and optional error fields) in place.
-  # Lookup is by +tool_call_id+. Preserves the existing message's +name+ and
-  # +id+.
-  #
-  # Raises Riffer::ArgumentError when no Tool message exists for the given
-  # +tool_call_id+.
-  #
-  #--
-  #: (tool_call_id: String, content: String, ?error: String?, ?error_type: Symbol?) -> Riffer::Messages::Tool
-  def replace_tool_result(tool_call_id:, content:, error: nil, error_type: nil)
-    idx = @messages.index { |m| m.is_a?(Riffer::Messages::Tool) && m.tool_call_id == tool_call_id }
-    raise Riffer::ArgumentError, "no tool result for tool_call_id #{tool_call_id.inspect}" unless idx
-
-    old = @messages[idx] #: Riffer::Messages::Tool
-    replacement = Riffer::Messages::Tool.new(
-      content,
-      id: old.id,
-      tool_call_id: old.tool_call_id,
-      name: old.name,
-      error: error,
-      error_type: error_type
-    )
-    @messages[idx] = replacement
-    replacement
+    [provider_class, model_name]
   end
 
-  private
-
-  # Fills any orphaned +tool_use+ in history with the +HEALING_PLACEHOLDER+
-  # response. Each placeholder Tool message is inserted immediately after
-  # its parent assistant message. Returns the array of call_ids that were
-  # filled, in order; +[]+ when there are no orphans.
-  #
-  # Bypasses +on_message+ — placeholders are not inference output.
-  # Consumers learn that healing happened via the structured
-  # +Riffer::Agent::Response#healed_tool_call_ids+ field (and the streaming
-  # +Interrupt+ event's matching field).
+  # Resolves the skills backend, lists skills, and selects an adapter.
+  # Returns nil if skills are unconfigured or the backend is empty.
   #
   #--
-  #: () -> Array[String]
-  def heal_orphan_tool_calls
-    result_ids = @messages.filter_map { |m| m.tool_call_id if m.is_a?(Riffer::Messages::Tool) }
-    healed = [] #: Array[String]
-    new_messages = [] #: Array[Riffer::Messages::Base]
-
-    @messages.each do |m|
-      new_messages << m
-      next unless m.is_a?(Riffer::Messages::Assistant) && !m.tool_calls.empty?
-
-      m.tool_calls.each do |tc|
-        next if result_ids.include?(tc.call_id)
-
-        response = HEALING_PLACEHOLDER.call(tc)
-        new_messages << Riffer::Messages::Tool.new(
-          response.content,
-          tool_call_id: tc.call_id,
-          name: tc.name,
-          error: response.error_message,
-          error_type: response.error_type
-        )
-        healed << tc.call_id
-      end
-    end
-
-    @messages = new_messages
-    healed
-  end
-
-  #--
-  #: (?Array[Riffer::Guardrails::Modification]) -> Riffer::Agent::Response
-  def run_generate_loop(all_modifications = [])
-    step = count_assistant_messages
-
-    reason = catch(:riffer_interrupt) do
-      execute_pending_tool_calls
+  #: (singleton(Riffer::Providers::Base)) -> Riffer::Skills::Context?
+  def resolve_skills(provider_class)
+    skills_config = @config.skills_config
+    return nil unless skills_config
 
-      loop do
-        response = call_llm
-        step += 1
-
-        track_token_usage(response.token_usage)
-
-        processed_response, tripwire, modifications = run_after_guardrails(response)
-        all_modifications.concat(modifications)
-
-        return build_response("", tripwire: tripwire, modifications: all_modifications) if tripwire
-
-        add_message(processed_response)
-
-        break unless has_tool_calls?(processed_response)
+    backend = skills_config.backend || Riffer.config.skills.default_backend
+    return nil unless backend
 
-        throw :riffer_interrupt, INTERRUPT_MAX_STEPS if step >= self.class.max_steps
+    backend = Riffer::Helpers::CallOrValue.resolve(backend, context: @context)
+    return nil if backend.list_skills.empty?
 
-        execute_tool_calls(processed_response)
-      end
+    skills = backend.list_skills.to_h { |s| [s.name, s] }
+    adapter_class = skills_config.adapter || provider_class.skills_adapter(@model_name)
+    skill_activate_tool_class = skills_config.activate_tool || Riffer.config.skills.default_activate_tool
 
-      response = extract_final_response
+    skills_context = Riffer::Skills::Context.new(
+      backend: backend,
+      skills: skills,
+      adapter: adapter_class.new(skill_activate_tool: skill_activate_tool_class)
+    )
 
-      return build_response(response&.content || "", modifications: all_modifications, structured_output: validate_structured_output(response))
+    if skills_config.activate
+      names = Array(Riffer::Helpers::CallOrValue.resolve(skills_config.activate, context: @context))
+      names.each { |name| skills_context.activate(name) }
     end
 
-    # catch returns the thrown value when throw :riffer_interrupt fires;
-    # the return above exits on the successful (non-interrupted) path.
-    @interrupted = true
-    healed = Riffer.config.experimental_history_healing ? heal_orphan_tool_calls : []
-    response = extract_final_response
-
-    build_response(response&.content || "", modifications: all_modifications, interrupted: true, interrupt_reason: reason, structured_output: validate_structured_output(response), healed_tool_call_ids: healed)
-  end
-
-  #--
-  #: (Riffer::Messages::Base) -> void
-  def add_message(message)
-    @messages << message
-    @message_callbacks.each { |callback| callback.call(message) }
-  end
-
-  #--
-  #: (Riffer::TokenUsage?) -> void
-  def track_token_usage(usage)
-    return unless usage
-
-    @token_usage = @token_usage ? @token_usage + usage : usage
-  end
-
-  #--
-  #: ((String | Array[Hash[Symbol, untyped] | Riffer::Messages::Base]), ?files: Array[Hash[Symbol, untyped] | Riffer::FilePart]?) -> void
-  def initialize_messages(prompt_or_messages, files: nil)
-    if prompt_or_messages.is_a?(Array)
-      raise Riffer::ArgumentError, "cannot pass an array of messages on an agent with existing messages; use a string to continue the conversation or a new agent instance to start fresh" if @messages.any?
-      raise Riffer::ArgumentError, "cannot provide both files and messages; attach files to individual messages instead" if files && !files.empty?
-      validate_seed_ids!(prompt_or_messages)
-      converted = prompt_or_messages.map { |item| convert_to_message_object(item) }
-      @messages = Riffer.config.experimental_history_healing ? heal_seeded_history(converted) : converted
-    elsif @messages.any?
-      file_parts = (files || []).map { |f| convert_to_file_part(f) }
-      @messages << Riffer::Messages::User.new(prompt_or_messages, files: file_parts)
-    else
-      @messages = []
-      sys = build_instruction_message
-      @messages << sys if sys
-      skills = build_skills_message
-      @messages << skills if skills
-      file_parts = (files || []).map { |f| convert_to_file_part(f) }
-      @messages << Riffer::Messages::User.new(prompt_or_messages, files: file_parts)
-    end
+    skills_context
   end
 
   #--
-  #: (Array[Hash[Symbol, untyped] | Riffer::Messages::Base]) -> void
-  def validate_seed_ids!(items)
-    strategy = Riffer.config.message_id_strategy
-    return if strategy == :none
-
-    items.each_with_index do |item, idx|
-      raw_id = case item
-      when Hash then item[:id]
-      when Riffer::Messages::Base then item.id
-      else next # type errors surface later via convert_to_message_object
-      end
-      next unless raw_id.nil?
-      raise Riffer::ArgumentError,
-        "seeded message at index #{idx} is missing :id (required when Riffer.config.message_id_strategy = #{strategy.inspect})"
-    end
+  #: () -> Riffer::Agent::StructuredOutput?
+  def resolve_structured_output
+    params = @config.structured_output
+    params ? Riffer::Agent::StructuredOutput.new(params) : nil
   end
 
-  # Repairs a seeded message array so the +tool_use+ ↔ +tool_result+
-  # invariant holds. Drops orphaned tool exchanges (assistant +tool_call+
-  # with no matching Tool result) and parentless Tool messages. Returns a
-  # new array; the input is not mutated.
+  # Resolves the full tool catalog for the agent:
   #
-  # Pending tool_calls on the resume boundary — the last assistant whose
-  # tail is purely Tool results (or empty) — are preserved. They get swept
-  # up by +execute_pending_tool_calls+ at the start of the next
-  # generate/stream call.
+  # - The configured +uses_tools+ value (Proc-form resolved against +context+).
+  # - The skill activation tool, when a +skills+ block is configured. The
+  #   activation tool class comes from the per-agent +skills do; activate_tool ...; end+
+  #   override when set, otherwise from +Riffer.config.skills.default_activate_tool+.
+  # - All MCP tools matching any +use_mcp+ tag, optionally wrapped in
+  #   AuthenticatedTool when +Riffer.config.mcp.credentials+ is configured.
   #
-  # Only invoked when +Riffer.config.experimental_history_healing+ is on.
+  # Raises Riffer::ArgumentError on tool name conflicts with the skill
+  # activation tool, on duplicate tool names across sources, or on tool
+  # classes missing required metadata (description, params).
   #
   #--
-  #: (Array[Riffer::Messages::Base]) -> Array[Riffer::Messages::Base]
-  def heal_seeded_history(messages)
-    resume_boundary = (messages.length - 1).downto(0).find { |idx|
-      m = messages[idx]
-      m.is_a?(Riffer::Messages::Assistant) &&
-        messages[(idx + 1)..].all? { |later| later.is_a?(Riffer::Messages::Tool) }
-    }
-
-    result_ids = messages.filter_map { |m| m.tool_call_id if m.is_a?(Riffer::Messages::Tool) }
-    parent_ids = messages.flat_map { |m|
-      m.is_a?(Riffer::Messages::Assistant) ? m.tool_calls.map(&:call_id) : []
-    }
-
-    strip_offenders = messages.each_with_index.flat_map { |m, idx|
-      next [] unless m.is_a?(Riffer::Messages::Assistant) && !m.tool_calls.empty?
-      next [] if idx == resume_boundary # preserve pending exchange
-      next [] if m.tool_calls.all? { |tc| result_ids.include?(tc.call_id) }
-      m.tool_calls.map(&:call_id)
-    }
-
-    messages.reject { |m|
-      case m
-      when Riffer::Messages::Assistant
-        !m.tool_calls.empty? && m.tool_calls.any? { |tc| strip_offenders.include?(tc.call_id) }
-      when Riffer::Messages::Tool
-        strip_offenders.include?(m.tool_call_id) || !parent_ids.include?(m.tool_call_id)
-      else
-        false
-      end
-    }
-  end
-
-  #--
-  #: (?Hash[Symbol, untyped]?) -> Riffer::Messages::System?
-  def build_instruction_message(context = @context)
-    content = generate_instructions(context)
-    return nil if content.nil? || content.empty?
-    Riffer::Messages::System.new(content)
-  end
-
-  #--
-  #: (?Riffer::Skills::Context?) -> Riffer::Messages::System?
-  def build_skills_message(skills_state = @skills_state)
-    content = skills_state&.system_prompt
-    return nil if content.nil? || content.empty?
-    Riffer::Messages::System.new(content)
-  end
-
-  #--
-  #: () -> Integer
-  def count_assistant_messages
-    @messages.count { |m| m.is_a?(Riffer::Messages::Assistant) }
-  end
+  #: () -> Array[singleton(Riffer::Tool)]
+  def resolve_tools
+    tools = Riffer::Helpers::CallOrValue.resolve(@config.tools_config, context: @context, default: [])
 
-  #--
-  #: (Enumerator::Yielder) -> void
-  def run_stream_loop(yielder)
-    step = count_assistant_messages
+    skills_config = @config.skills_config
 
-    if @skills_state
-      @skills_state.on_activate = ->(name) { yielder << Riffer::StreamEvents::SkillActivation.new(name) }
-    end
+    if skills_config
+      skill_activate_tool_class = skills_config.activate_tool || Riffer.config.skills.default_activate_tool
 
-    completed = catch(:riffer_interrupt) do
-      execute_pending_tool_calls
-
-      loop do
-        accumulated_content = ""
-        accumulated_tool_calls = []
-        accumulated_token_usage = nil
-        current_tool_call = nil
-
-        call_llm_stream.each do |event|
-          yielder << event
-
-          case event
-          when Riffer::StreamEvents::TextDelta
-            accumulated_content += event.content
-          when Riffer::StreamEvents::TextDone
-            accumulated_content = event.content
-          when Riffer::StreamEvents::ToolCallDelta
-            current_tool_call ||= {item_id: event.item_id, name: event.name, arguments: ""}
-            current_tool_call[:arguments] += event.arguments_delta
-            current_tool_call[:name] ||= event.name
-          when Riffer::StreamEvents::ToolCallDone
-            accumulated_tool_calls << Riffer::Messages::Assistant::ToolCall.new(
-              call_id: event.call_id,
-              name: event.name,
-              arguments: event.arguments
-            )
-            current_tool_call = nil
-          when Riffer::StreamEvents::TokenUsageDone
-            accumulated_token_usage = event.token_usage
-          end
-        end
-
-        response = Riffer::Messages::Assistant.new(
-          accumulated_content,
-          tool_calls: accumulated_tool_calls,
-          token_usage: accumulated_token_usage
-        )
-
-        track_token_usage(accumulated_token_usage)
-        step += 1
-
-        processed_response, tripwire, modifications = run_after_guardrails(response)
-        modifications.each { |m| yielder << Riffer::StreamEvents::GuardrailModification.new(m) }
-
-        if tripwire
-          yielder << Riffer::StreamEvents::GuardrailTripwire.new(tripwire)
-          break
-        end
-
-        add_message(processed_response)
-
-        break unless has_tool_calls?(processed_response)
-
-        throw :riffer_interrupt, INTERRUPT_MAX_STEPS if step >= self.class.max_steps
-
-        execute_tool_calls(processed_response)
+      if tools.any? { |t| t.name == skill_activate_tool_class.name }
+        raise Riffer::ArgumentError, "Tool name conflict with skill tools: #{skill_activate_tool_class.name}"
       end
-      :completed
-    end
-
-    unless completed == :completed
-      @interrupted = true
-      healed = Riffer.config.experimental_history_healing ? heal_orphan_tool_calls : []
-      yielder << Riffer::StreamEvents::Interrupt.new(reason: completed, healed_tool_call_ids: healed)
-    end
-  end
-
-  #--
-  #: () -> Riffer::Messages::Assistant
-  def call_llm
-    provider_instance.generate_text(
-      messages: @messages,
-      model: @model_name,
-      tools: resolved_tools,
-      **merged_model_options
-    )
-  end
-
-  #--
-  #: () -> Enumerator[Riffer::StreamEvents::Base, void]
-  def call_llm_stream
-    provider_instance.stream_text(
-      messages: @messages,
-      model: @model_name,
-      tools: resolved_tools,
-      **merged_model_options
-    )
-  end
-
-  #--
-  #: () -> Riffer::Providers::Base
-  def provider_instance
-    @provider_instance ||= provider_class.new(**self.class.provider_options)
-  end
-
-  #--
-  #: (Riffer::Messages::Assistant) -> bool
-  def has_tool_calls?(response)
-    response.is_a?(Riffer::Messages::Assistant) && !response.tool_calls.empty?
-  end
 
-  #--
-  #: (Riffer::Messages::Assistant) -> void
-  def execute_tool_calls(response)
-    runtime = resolve_tool_runtime
-    results = runtime.execute(response.tool_calls, tools: resolved_tools, context: @context, assistant_message: response)
-
-    results.each do |tool_call, result|
-      add_message(Riffer::Messages::Tool.new(
-        result.content,
-        tool_call_id: tool_call.call_id,
-        name: tool_call.name,
-        error: result.error_message,
-        error_type: result.error_type
-      ))
-    end
-  end
-
-  # Executes tool calls left unfinished by a prior interrupt.
-  #
-  # When an interrupt fires mid-way through tool execution, some tool calls
-  # from the last assistant message may not have been executed yet. This
-  # method detects those gaps by comparing the tool call ids requested by the
-  # last assistant message against the tool result messages that follow it,
-  # then executes any that are missing.
-  #
-  #--
-  #: () -> void
-  # Executes tool calls from the last assistant message that don't yet
-  # have a corresponding tool result. Safe to call unconditionally —
-  # returns immediately when there is nothing pending.
-  def execute_pending_tool_calls
-    assistant, pending = pending_tool_calls
-    return if pending.empty?
-
-    runtime = resolve_tool_runtime
-    results = runtime.execute(pending, tools: resolved_tools, context: @context, assistant_message: assistant)
-
-    results.each do |tool_call, result|
-      add_message(Riffer::Messages::Tool.new(
-        result.content,
-        tool_call_id: tool_call.call_id,
-        name: tool_call.name,
-        error: result.error_message,
-        error_type: result.error_type
-      ))
-    end
-  end
-
-  # Returns +[assistant, pending_tool_calls]+ for the last assistant message.
-  # When there is no assistant message or no pending calls, the second
-  # element is an empty array.
-  #
-  #--
-  #: () -> [untyped, Array[Riffer::Messages::Assistant::ToolCall]]
-  def pending_tool_calls
-    last_assistant_idx = @messages.rindex { |m| m.is_a?(Riffer::Messages::Assistant) }
-    return [nil, []] unless last_assistant_idx
-
-    assistant = @messages[last_assistant_idx]
-    return [assistant, []] if assistant.tool_calls.empty?
-
-    executed_ids = @messages[(last_assistant_idx + 1)..].select { |m|
-      m.is_a?(Riffer::Messages::Tool)
-    }.map(&:tool_call_id)
-
-    [assistant, assistant.tool_calls.reject { |tc| executed_ids.include?(tc.call_id) }]
-  end
-
-  #--
-  #: () -> void
-  def prepare_run
-    @resolved_tools = nil
-    @resolved_tool_runtime = nil
-    clear_resolved_model
-    @interrupted = false
-    resolve_model
-    @skills_state = resolve_skills
-    @context = (@context || {}).merge(skills: @skills_state) if @skills_state
-  end
-
-  #--
-  #: (untyped) -> void
-  def parse_model_string!(model_string)
-    raise Riffer::ArgumentError, "Invalid model string: #{model_string}" unless model_string.is_a?(String)
-    provider_name, model_name = model_string.split("/", 2)
-    raise Riffer::ArgumentError, "Invalid model string: #{model_string}" unless [provider_name, model_name].all? { |part| part.is_a?(String) && !part.strip.empty? }
-    @provider_name = provider_name
-    @model_name = model_name
-  end
-
-  #--
-  #: () -> void
-  def clear_resolved_model
-    @resolved_model = nil
-    @provider_instance = nil if @model_config.is_a?(Proc)
-  end
-
-  #--
-  #: (?Hash[Symbol, untyped]?) -> String?
-  def generate_instructions(context = @context)
-    if @instructions_config.is_a?(Proc)
-      (@instructions_config.arity == 0) ? @instructions_config.call : @instructions_config.call(context)
-    else
-      @instructions_config
+      tools += [skill_activate_tool_class]
     end
-  end
 
-  attr_reader :resolved_model #: String?
-
-  #--
-  #: () -> String
-  def resolve_model
-    @resolved_model ||= if @model_config.is_a?(Proc)
-      model_string = (@model_config.arity == 0) ? @model_config.call : @model_config.call(@context)
-      parse_model_string!(model_string)
-      model_string
-    else
-      @model_config
-    end
+    tools += resolve_mcp_tool_classes
+    assert_distinct_tool_names!(tools)
+    tools.each(&:validate_as_tool!)
+    tools
   end
 
   #--
-  #: () -> Array[singleton(Riffer::Tool)]
-  def resolve_uses_tools_config
-    config = self.class.uses_tools
-
-    if config.nil?
-      []
-    elsif config.is_a?(Proc)
-      (config.arity == 0) ? config.call : config.call(@context)
-    else
-      config
-    end
+  #: () -> Riffer::Tools::Runtime
+  def resolve_tool_runtime
+    runtime = Riffer::Helpers::CallOrValue.resolve(@config.tool_runtime, context: @context)
+    runtime.is_a?(Class) ? runtime.new : runtime
   end
 
   #--
   #: () -> Array[singleton(Riffer::Tool)]
   def resolve_mcp_tool_classes
-    configs = self.class.mcp_configs
+    configs = @config.mcp_configs
     return [] if configs.empty?
 
     cred = Riffer.config.mcp.credentials
@@ -1065,7 +519,7 @@ class Riffer::Agent
   #
   #: (Array[Hash[Symbol, untyped]]) -> Hash[Riffer::Mcp::Registration, Array[Symbol]]
   def gather_mcp_registrations_with_tags(configs)
-    by_reg = {}
+    by_reg = {} #: Hash[Riffer::Mcp::Registration, Array[Symbol]]
     configs.each do |cfg|
       Riffer::Mcp::Registry.find_by_tags(cfg[:tags]).each do |reg|
         (by_reg[reg] ||= []).concat(cfg[:tags] & reg.manifest.tags)
@@ -1074,7 +528,7 @@ class Riffer::Agent
     by_reg
   end
 
-  #: (Riffer::Mcp::Registration, Array[Symbol], Proc?, Hash[Symbol, untyped]) -> Array[singleton(Riffer::Tool)]
+  #: (Riffer::Mcp::Registration, Array[Symbol], (^(manifest: Riffer::Mcp::Manifest, matched_tags: Array[Symbol], context: Riffer::Agent::Context) -> Hash[Symbol, untyped]?)?, Riffer::Agent::Context) -> Array[singleton(Riffer::Tool)]
   def mcp_tools_for_registration(reg, matched_tags, cred, ctx)
     return reg.tools unless cred
     return [] if cred.call(manifest: reg.manifest, matched_tags: matched_tags, context: ctx).nil?
@@ -1092,145 +546,4 @@ class Riffer::Agent
 
     raise Riffer::ArgumentError, "Duplicate tool names: #{dupes.sort.join(", ")}"
   end
-
-  #: () -> Array[singleton(Riffer::Tool)]
-  def resolved_tools
-    @resolved_tools ||= begin
-      tools = self.class.resolved_tool_classes(context: @context) + resolve_mcp_tool_classes
-      assert_distinct_tool_names!(tools)
-      tools.each(&:validate_as_tool!)
-      tools
-    end
-  end
-
-  #--
-  #: () -> Riffer::ToolRuntime
-  def resolve_tool_runtime
-    @resolved_tool_runtime ||= begin
-      config = self.class.tool_runtime || Riffer.config.tool_runtime
-
-      runtime = if config.is_a?(Proc)
-        (config.arity == 0) ? config.call : config.call(@context)
-      else
-        config
-      end
-
-      case runtime
-      when Class then runtime.new
-      when Riffer::ToolRuntime then runtime
-      else raise Riffer::ArgumentError, "Invalid tool_runtime: #{runtime.inspect}"
-      end
-    end
-  end
-
-  # Resolves the skills backend, lists skills, and selects an adapter.
-  #
-  # Returns nil if skills are not configured or empty.
-  # Does not mutate instance state — callers are responsible for
-  # assigning the returned context.
-  #
-  #--
-  #: (?Hash[Symbol, untyped]?) -> Riffer::Skills::Context?
-  def resolve_skills(context = @context)
-    return nil unless self.class.skills
-
-    backend = self.class.skills.backend || Riffer.config.skills.default_backend
-    return nil unless backend
-
-    backend = backend.is_a?(Proc) ? backend.call(context) : backend
-    skills_list = backend.list_skills
-    return nil if skills_list.empty?
-
-    skills = skills_list.to_h { |s| [s.name, s] }
-    adapter_class = self.class.skills.adapter || provider_class.skills_adapter(@model_name)
-    skill_activate_tool_class = self.class.skills.activate_tool || Riffer.config.skills.default_activate_tool
-
-    skills_context = Riffer::Skills::Context.new(
-      backend: backend,
-      skills: skills,
-      adapter: adapter_class.new(skill_activate_tool: skill_activate_tool_class)
-    )
-    ctx = (context || {}).merge(skills: skills_context)
-
-    activate = self.class.skills.activate
-    if activate
-      names = activate.is_a?(Proc) ? activate.call(ctx) : Array(activate)
-      names.each { |name| skills_context.activate(name) }
-    end
-
-    skills_context
-  end
-
-  #--
-  #: () -> singleton(Riffer::Providers::Base)
-  def provider_class
-    klass = Riffer::Providers::Repository.find(@provider_name)
-    raise Riffer::ArgumentError, "Provider not found: #{@provider_name}" unless klass
-    klass
-  end
-
-  #--
-  #: () -> Riffer::Messages::Assistant?
-  def extract_final_response
-    # TODO: Replace with rfind when minimum Ruby is 4.0+
-    # rubocop:disable Style/ReverseFind
-    @messages.reverse.find { |msg| msg.is_a?(Riffer::Messages::Assistant) } #: Riffer::Messages::Assistant?
-    # rubocop:enable Style/ReverseFind
-  end
-
-  #--
-  #: () -> [Riffer::Guardrails::Tripwire?, Array[Riffer::Guardrails::Modification]]
-  def run_before_guardrails
-    guardrails = self.class.guardrails_for(:before)
-    return [nil, []] if guardrails.empty?
-
-    runner = Riffer::Guardrails::Runner.new(guardrails, phase: :before, context: @context)
-    processed_messages, tripwire, modifications = runner.run(@messages)
-    @messages = processed_messages unless tripwire
-    [tripwire, modifications]
-  end
-
-  #--
-  #: (Riffer::Messages::Assistant) -> [untyped, Riffer::Guardrails::Tripwire?, Array[Riffer::Guardrails::Modification]]
-  def run_after_guardrails(response)
-    guardrails = self.class.guardrails_for(:after)
-    return [response, nil, []] if guardrails.empty?
-
-    runner = Riffer::Guardrails::Runner.new(guardrails, phase: :after, context: @context)
-    processed_response, tripwire, modifications = runner.run(response, messages: @messages)
-
-    response_index = @messages.length
-    modifications.each { |m| m.message_indices.map! { response_index } }
-
-    [processed_response, tripwire, modifications]
-  end
-
-  #--
-  #: (Riffer::Messages::Assistant?) -> Hash[Symbol, untyped]?
-  def validate_structured_output(response)
-    return unless response&.structured_output? && @structured_output
-
-    @structured_output.parse_and_validate(response.content).object
-  end
-
-  #--
-  #: () -> Riffer::StructuredOutput?
-  def resolve_structured_output
-    params = self.class.structured_output
-    params ? Riffer::StructuredOutput.new(params) : nil
-  end
-
-  #--
-  #: () -> Hash[Symbol, untyped]
-  def merged_model_options
-    opts = self.class.model_options.dup
-    opts[:structured_output] = @structured_output if @structured_output
-    opts
-  end
-
-  #--
-  #: (String, ?tripwire: Riffer::Guardrails::Tripwire?, ?modifications: Array[Riffer::Guardrails::Modification], ?interrupted: bool, ?interrupt_reason: (String | Symbol)?, ?structured_output: Hash[Symbol, untyped]?, ?healed_tool_call_ids: Array[String]) -> Riffer::Agent::Response
-  def build_response(content, tripwire: nil, modifications: [], interrupted: false, interrupt_reason: nil, structured_output: nil, healed_tool_call_ids: [])
-    Riffer::Agent::Response.new(content, tripwire: tripwire, modifications: modifications, interrupted: interrupted, interrupt_reason: interrupt_reason, structured_output: structured_output, messages: @messages.frozen? ? @messages : @messages.dup.freeze, healed_tool_call_ids: healed_tool_call_ids)
-  end
 end