riffer 0.27.2 → 0.29.0

data/lib/riffer/agent.rb

@@ -21,33 +21,32 @@ require "json"
 class Riffer::Agent
   include Riffer::Messages::Converter
   extend Riffer::Helpers::ClassNameConverter
-  extend Riffer::Helpers::Validations
 
-  DEFAULT_MAX_STEPS = 16 #: Integer
   INTERRUPT_MAX_STEPS = :max_steps #: Symbol
 
+  # 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.
@@ -64,15 +63,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.
@@ -80,8 +72,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.
@@ -89,8 +80,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.
@@ -98,90 +88,35 @@ 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
+  def self.uses_tools(value = nil)
+    value.nil? ? config.tools_config : (config.tools_config = value)
   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)
-  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).
   #
@@ -189,34 +124,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.
@@ -230,13 +156,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.
@@ -257,22 +184,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.
@@ -285,22 +214,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.
@@ -310,120 +224,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.
   #
+  # 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.
+  #
+  # +context:+ flows through Proc-based instructions, model, skills resolution,
+  # tool resolution, guardrails, and tool runtime. It is fixed for the
+  # lifetime of the 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.
-  #
-  #--
-  #: ((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]
+  #: (?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 || {})
 
-    tripwire, modifications = run_before_guardrails
-    all_modifications.concat(modifications)
-    return build_response("", tripwire: tripwire, modifications: all_modifications) if tripwire
+    provider_class, @model_name = resolve_provider_and_model
+    @provider = provider_class.new(**@config.provider_options)
 
-    run_generate_loop(all_modifications)
-  end
-
-  # Streams a response from the agent.
-  #
-  # Raises Riffer::ArgumentError if structured output is configured.
-  #
-  #--
-  #: ((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
+    @context.skills = resolve_skills(provider_class)
 
-    @context = context
-    prepare_run
-    initialize_messages(prompt_or_messages, files: files)
-
-    Enumerator.new do |yielder|
-      tripwire, modifications = run_before_guardrails
-      modifications.each { |m| yielder << Riffer::StreamEvents::GuardrailModification.new(m) }
+    @structured_output = resolve_structured_output
+    @tools = resolve_tools
+    @tool_runtime = resolve_tool_runtime
 
-      if tripwire
-        yielder << Riffer::StreamEvents::GuardrailTripwire.new(tripwire)
-        next
-      end
+    @instruction_message = build_instruction_message
+    @skills_message = build_skills_message
 
-      run_stream_loop(yielder)
-    end
+    @session = session || Riffer::Agent::Session.new(messages: [@instruction_message, @skills_message].compact)
+    @session.set(Riffer::Agent::Session::Repair.prune_orphans(@session.messages))
   end
 
-  # 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
-  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+.
   #
-  # Returns +nil+ when no skills are configured or the catalog is empty.
+  # Raises Riffer::ArgumentError if structured output is configured.
+  #
+  # 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.
@@ -431,6 +361,13 @@ class Riffer::Agent
   # Call from an +on_message+ callback to cleanly interrupt the loop.
   # Equivalent to <tt>throw :riffer_interrupt, reason</tt>.
   #
+  # When +Riffer.config.experimental_history_healing+ is enabled, riffer
+  # fills any orphaned +tool_use+ on the way out with a placeholder
+  # +Riffer::Messages::Tool+ carrying +error_type: :interrupted+. The
+  # filled call_ids are exposed on
+  # +Riffer::Agent::Response#healed_tool_call_ids+ (and the streaming
+  # +Riffer::StreamEvents::Interrupt+ event).
+  #
   #--
   #: (?(String | Symbol)?) -> void
   def interrupt!(reason = nil)
@@ -440,366 +377,132 @@ class Riffer::Agent
   private
 
   #--
-  #: (?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
-
-      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)
-
-        throw :riffer_interrupt, INTERRUPT_MAX_STEPS if step >= self.class.max_steps
-
-        execute_tool_calls(processed_response)
-      end
-
-      response = extract_final_response
-
-      return build_response(response&.content || "", modifications: all_modifications, structured_output: validate_structured_output(response))
-    end
-
-    # catch returns the thrown value when throw :riffer_interrupt fires;
-    # the return above exits on the successful (non-interrupted) path.
-    @interrupted = true
-    response = extract_final_response
-
-    build_response(response&.content || "", modifications: all_modifications, interrupted: true, interrupt_reason: reason, structured_output: validate_structured_output(response))
+  #: () -> 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
 
   #--
-  #: (Riffer::Messages::Base) -> void
-  def add_message(message)
-    @messages << message
-    @message_callbacks.each { |callback| callback.call(message) }
+  #: () -> Riffer::Messages::System?
+  def build_skills_message
+    skills = @context.skills
+    return nil unless skills&.system_prompt
+    Riffer::Messages::System.new(skills.system_prompt)
   end
 
+  # Resolves +Config#model+ to a "provider/model" string (calling the Proc
+  # form against +@context+), parses it, and looks up the provider class.
+  #
+  # Returns +[provider_class, model_name]+. Raises Riffer::ArgumentError on
+  # an invalid model string or an unregistered provider.
+  #
   #--
-  #: (Riffer::TokenUsage?) -> void
-  def track_token_usage(usage)
-    return unless usage
-
-    @token_usage = @token_usage ? @token_usage + usage : usage
-  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)
 
-  #--
-  #: ((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)
-      @messages = prompt_or_messages.map { |item| convert_to_message_object(item) }
-    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
-  end
+    provider_name, model_name = model_string.split("/", 2)
 
-  #--
-  #: (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})"
+    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
-  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
+    provider_class = Riffer::Providers::Repository.find(provider_name)
+    raise Riffer::ArgumentError, "Provider not found: #{provider_name}" unless provider_class
 
-  #--
-  #: (?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) }
+    [provider_class, model_name]
   end
 
+  # Resolves the skills backend, lists skills, and selects an adapter.
+  # Returns nil if skills are unconfigured or the backend is empty.
+  #
   #--
-  #: (Enumerator::Yielder) -> void
-  def run_stream_loop(yielder)
-    step = count_assistant_messages
+  #: (singleton(Riffer::Providers::Base)) -> Riffer::Skills::Context?
+  def resolve_skills(provider_class)
+    skills_config = @config.skills_config
+    return nil unless skills_config
 
-    if @skills_state
-      @skills_state.on_activate = ->(name) { yielder << Riffer::StreamEvents::SkillActivation.new(name) }
-    end
-
-    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)
-      end
-      :completed
-    end
+    backend = skills_config.backend || Riffer.config.skills.default_backend
+    return nil unless backend
 
-    unless completed == :completed
-      @interrupted = true
-      yielder << Riffer::StreamEvents::Interrupt.new(reason: completed)
-    end
-  end
+    backend = Riffer::Helpers::CallOrValue.resolve(backend, context: @context)
+    return nil if backend.list_skills.empty?
 
-  #--
-  #: () -> Riffer::Messages::Assistant
-  def call_llm
-    provider_instance.generate_text(
-      messages: @messages,
-      model: @model_name,
-      tools: resolved_tools,
-      **merged_model_options
-    )
-  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
 
-  #--
-  #: () -> Enumerator[Riffer::StreamEvents::Base, void]
-  def call_llm_stream
-    provider_instance.stream_text(
-      messages: @messages,
-      model: @model_name,
-      tools: resolved_tools,
-      **merged_model_options
+    skills_context = Riffer::Skills::Context.new(
+      backend: backend,
+      skills: skills,
+      adapter: adapter_class.new(skill_activate_tool: skill_activate_tool_class)
     )
-  end
 
-  #--
-  #: () -> Riffer::Providers::Base
-  def provider_instance
-    @provider_instance ||= provider_class.new(**self.class.provider_options)
-  end
+    if skills_config.activate
+      names = Array(Riffer::Helpers::CallOrValue.resolve(skills_config.activate, context: @context))
+      names.each { |name| skills_context.activate(name) }
+    end
 
-  #--
-  #: (Riffer::Messages::Assistant) -> bool
-  def has_tool_calls?(response)
-    response.is_a?(Riffer::Messages::Assistant) && !response.tool_calls.empty?
+    skills_context
   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)
-
-    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
+  #: () -> Riffer::Agent::StructuredOutput?
+  def resolve_structured_output
+    params = @config.structured_output
+    params ? Riffer::Agent::StructuredOutput.new(params) : nil
   end
 
-  # Executes tool calls left unfinished by a prior interrupt.
+  # Resolves the full tool catalog for the agent:
   #
-  # 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.
+  # - 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.
+  #
+  # 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).
   #
   #--
-  #: () -> 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
-    pending = pending_tool_calls
-    return if pending.empty?
-
-    runtime = resolve_tool_runtime
-    results = runtime.execute(pending, tools: resolved_tools, context: @context)
-
-    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
-
-  def pending_tool_calls
-    last_assistant_idx = @messages.rindex { |m| m.is_a?(Riffer::Messages::Assistant) }
-    return [] unless last_assistant_idx
-
-    assistant = @messages[last_assistant_idx]
-    return [] 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.tool_calls.reject { |tc| executed_ids.include?(tc.call_id) }
-  end
+  #: () -> Array[singleton(Riffer::Tool)]
+  def resolve_tools
+    tools = Riffer::Helpers::CallOrValue.resolve(@config.tools_config, context: @context, default: [])
 
-  #--
-  #: () -> 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
+    skills_config = @config.skills_config
 
-  #--
-  #: (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
+    if skills_config
+      skill_activate_tool_class = skills_config.activate_tool || Riffer.config.skills.default_activate_tool
 
-  #--
-  #: () -> void
-  def clear_resolved_model
-    @resolved_model = nil
-    @provider_instance = nil if @model_config.is_a?(Proc)
-  end
+      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
 
-  #--
-  #: (?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
@@ -814,7 +517,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)
@@ -823,7 +526,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?
@@ -841,145 +544,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]?) -> Riffer::Agent::Response
-  def build_response(content, tripwire: nil, modifications: [], interrupted: false, interrupt_reason: nil, structured_output: nil)
-    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)
-  end
 end