riffer 0.28.0 → 0.29.0

data/lib/riffer/agent/config.rb

@@ -0,0 +1,173 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+# Typed configuration object holding every class-level DSL setting on a
+# Riffer::Agent subclass.
+#
+# Each subclass of Riffer::Agent owns one Config, accessible via the class
+# method <tt>config</tt>. The class-level DSL (+model+, +instructions+, +uses_tools+,
+# etc.) reads and mutates this Config in place. Append-style DSL methods
+# (+use_mcp+, +guardrail+) are handled by the +add_mcp+ and +add_guardrail+
+# helpers below.
+#
+# Config stores Procs unresolved. Per-instance resolution happens elsewhere
+# (instructions, model, tools, tool runtime, skills).
+class Riffer::Agent::Config
+  DEFAULT_MAX_STEPS = 16 #: Integer
+
+  attr_reader :identifier #: String?
+  attr_reader :model #: (String | Proc)?
+  attr_reader :instructions #: (String | Proc)?
+  attr_accessor :provider_options #: Hash[Symbol, untyped]
+  attr_accessor :model_options #: Hash[Symbol, untyped]
+  attr_reader :structured_output #: Riffer::Params?
+  attr_accessor :max_steps #: Numeric
+  attr_accessor :tools_config #: (Array[singleton(Riffer::Tool)] | Proc)?
+  attr_reader :mcp_configs #: Array[Hash[Symbol, untyped]]
+  attr_reader :tool_runtime #: (singleton(Riffer::Tools::Runtime) | Riffer::Tools::Runtime | Proc)
+  attr_accessor :skills_config #: Riffer::Skills::Config?
+  attr_reader :guardrails #: Hash[Symbol, Array[Hash[Symbol, untyped]]]
+
+  # Builds a new Config. All fields are optional; unset fields take the
+  # documented defaults.
+  #
+  # Raises Riffer::ArgumentError if +model+ or +instructions+ is provided
+  # as a non-String, non-Proc value (or as an empty String).
+  #
+  #--
+  #: (?identifier: String?, ?model: (String | Proc)?, ?instructions: (String | Proc)?, ?provider_options: Hash[Symbol, untyped], ?model_options: Hash[Symbol, untyped], ?structured_output: Riffer::Params?, ?max_steps: Numeric, ?tools_config: (Array[singleton(Riffer::Tool)] | Proc)?, ?mcp_configs: Array[Hash[Symbol, untyped]], ?tool_runtime: (singleton(Riffer::Tools::Runtime) | Riffer::Tools::Runtime | Proc), ?skills_config: Riffer::Skills::Config?, ?guardrails: Hash[Symbol, Array[Hash[Symbol, untyped]]]) -> void
+  def initialize(
+    identifier: nil,
+    model: nil,
+    instructions: nil,
+    provider_options: {},
+    model_options: {},
+    structured_output: nil,
+    max_steps: DEFAULT_MAX_STEPS,
+    tools_config: nil,
+    mcp_configs: [],
+    tool_runtime: Riffer.config.tool_runtime,
+    skills_config: nil,
+    guardrails: {before: [], after: []}
+  )
+    @provider_options = provider_options
+    @model_options = model_options
+    @max_steps = max_steps
+    @tools_config = tools_config
+    @mcp_configs = mcp_configs
+    @skills_config = skills_config
+    @guardrails = guardrails
+    self.identifier = identifier
+    self.model = model
+    self.instructions = instructions
+    self.structured_output = structured_output
+    self.tool_runtime = tool_runtime
+  end
+
+  # Sets +identifier+. Accepts +nil+ or any value, coerced to String.
+  #
+  #--
+  #: (untyped) -> String?
+  def identifier=(value)
+    @identifier = value&.to_s
+  end
+
+  # Sets +structured_output+. Accepts a Riffer::Params instance or +nil+.
+  #
+  # Raises Riffer::ArgumentError on any other type.
+  #
+  #--
+  #: (Riffer::Params?) -> Riffer::Params?
+  def structured_output=(value)
+    raise Riffer::ArgumentError, "structured_output must be a Riffer::Params" unless value.nil? || value.is_a?(Riffer::Params)
+    @structured_output = value
+  end
+
+  # Sets +tool_runtime+. Accepts a Riffer::Tools::Runtime subclass, a
+  # Riffer::Tools::Runtime instance, or a Proc.
+  #
+  # Raises Riffer::ArgumentError on any other type.
+  #
+  #--
+  #: ((singleton(Riffer::Tools::Runtime) | Riffer::Tools::Runtime | Proc)) -> (singleton(Riffer::Tools::Runtime) | Riffer::Tools::Runtime | Proc)
+  def tool_runtime=(value)
+    valid = (value.is_a?(Class) && value < Riffer::Tools::Runtime) || value.is_a?(Riffer::Tools::Runtime) || value.is_a?(Proc)
+    raise Riffer::ArgumentError, "tool_runtime must be a Riffer::Tools::Runtime subclass, instance, or a Proc" unless valid
+    @tool_runtime = value
+  end
+
+  # Sets +model+. Accepts a String ("provider/model"), a Proc, or +nil+.
+  #
+  # Raises Riffer::ArgumentError on non-String, non-Proc, or empty-String values.
+  #
+  #--
+  #: ((String | Proc)?) -> (String | Proc)?
+  def model=(value)
+    validate_string_or_proc!(value, "model")
+    @model = value
+  end
+
+  # Sets +instructions+. Accepts a String, a Proc, or +nil+.
+  #
+  # Raises Riffer::ArgumentError on non-String, non-Proc, or empty-String values.
+  #
+  #--
+  #: ((String | Proc)?) -> (String | Proc)?
+  def instructions=(value)
+    validate_string_or_proc!(value, "instructions")
+    @instructions = value
+  end
+
+  # Appends an MCP tag entry to +mcp_configs+.
+  #
+  #--
+  #: (String | Symbol) -> Array[Hash[Symbol, untyped]]
+  def add_mcp(tag)
+    @mcp_configs << {tags: [tag.to_sym]}
+  end
+
+  # Appends a guardrail entry to +guardrails+ for the given phase.
+  #
+  # [phase] +:before+, +:after+, or +:around+. +:around+ appends to both
+  #   +:before+ and +:after+.
+  # [klass] the Riffer::Guardrail subclass to register.
+  # [options] options forwarded to the guardrail at runtime.
+  #
+  # Raises Riffer::ArgumentError on an invalid phase or non-Guardrail class.
+  #
+  #--
+  #: (Symbol, klass: singleton(Riffer::Guardrail), ?options: Hash[Symbol, untyped]) -> void
+  def add_guardrail(phase, klass:, 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 klass.is_a?(Class) && klass <= Riffer::Guardrail
+
+    cfg = {class: klass, options: options}
+    case phase
+    when :before
+      @guardrails[:before] << cfg
+    when :after
+      @guardrails[:after] << cfg
+    when :around
+      @guardrails[:before] << cfg
+      @guardrails[:after] << cfg
+    end
+  end
+
+  # Returns the guardrail entries for the given phase, or +[]+ if none.
+  #
+  #--
+  #: (Symbol) -> Array[Hash[Symbol, untyped]]
+  def guardrails_for(phase)
+    @guardrails[phase] || []
+  end
+
+  private
+
+  #: (untyped, String) -> void
+  def validate_string_or_proc!(value, name)
+    return if value.nil? || value.is_a?(Proc)
+    raise Riffer::ArgumentError, "#{name} must be a String" unless value.is_a?(String)
+    raise Riffer::ArgumentError, "#{name} cannot be empty" if value.strip.empty?
+  end
+end

data/lib/riffer/agent/context.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+# Typed value object wrapping the runtime context Hash held by a
+# Riffer::Agent. Exposes first-class accessors for the framework-managed
+# entries — +skills+ and +token_usage+ — and preserves +#[]+ / +#dig+
+# reads so tools (which receive +context:+ as a keyword) keep working
+# with both built-in and caller-provided keys.
+#
+# Reserved keys (+:skills+, +:token_usage+) cannot be set by the caller
+# at construction; they are owned by Riffer and written through the typed
+# setters. Type invariants are enforced on write — +skills+ must be a
+# +Riffer::Skills::Context+ (or nil); +token_usage+ must be a
+# +Riffer::Providers::TokenUsage+ (or nil).
+#
+#   context = Riffer::Agent::Context.new(user_id: 42)
+#   context[:user_id]    # => 42
+#   context.skills       # => nil
+#   context.token_usage  # => nil
+#
+class Riffer::Agent::Context
+  # Keys reserved for framework use. Passing any of these to the
+  # constructor raises +Riffer::ArgumentError+.
+  RESERVED_KEYS = [:skills, :token_usage].freeze #: Array[Symbol]
+
+  # Builds a new context.
+  #
+  # [data] caller-provided Hash passed as <tt>Agent.new(context:)</tt>.
+  #        Duped before storage so caller mutations do not affect the
+  #        agent. Must not contain any +RESERVED_KEYS+.
+  #
+  # Raises Riffer::ArgumentError when +data+ contains a reserved key.
+  #
+  #--
+  #: (?Hash[Symbol, untyped]) -> void
+  def initialize(data = {})
+    reserved = data.keys & RESERVED_KEYS
+    if reserved.any?
+      raise Riffer::ArgumentError,
+        "Reserved keys cannot be passed in context: #{reserved.join(", ")}"
+    end
+
+    @data = data.dup
+    @data[:skills] = nil
+    @data[:token_usage] = nil
+  end
+
+  # The agent's resolved +Riffer::Skills::Context+, or +nil+ when skills
+  # are not configured.
+  #
+  #--
+  #: () -> Riffer::Skills::Context?
+  def skills
+    @data[:skills]
+  end
+
+  # Sets the resolved skills context. Called once by +Riffer::Agent+
+  # during construction.
+  #
+  # Raises Riffer::ArgumentError if +value+ is neither +nil+ nor a
+  # +Riffer::Skills::Context+.
+  #
+  #--
+  #: (Riffer::Skills::Context?) -> Riffer::Skills::Context?
+  def skills=(value)
+    unless value.nil? || value.is_a?(Riffer::Skills::Context)
+      raise Riffer::ArgumentError,
+        "skills must be a Riffer::Skills::Context or nil, got #{value.class}"
+    end
+    @data[:skills] = value
+  end
+
+  # The cumulative +Riffer::Providers::TokenUsage+ across every Run on this agent,
+  # or +nil+ before the first response is recorded.
+  #
+  #--
+  #: () -> Riffer::Providers::TokenUsage?
+  def token_usage
+    @data[:token_usage]
+  end
+
+  # Sets the cumulative token usage. Called by +Riffer::Agent::Run+ after
+  # each LLM response.
+  #
+  # Raises Riffer::ArgumentError if +value+ is neither +nil+ nor a
+  # +Riffer::Providers::TokenUsage+.
+  #
+  #--
+  #: (Riffer::Providers::TokenUsage?) -> Riffer::Providers::TokenUsage?
+  def token_usage=(value)
+    unless value.nil? || value.is_a?(Riffer::Providers::TokenUsage)
+      raise Riffer::ArgumentError,
+        "token_usage must be a Riffer::Providers::TokenUsage or nil, got #{value.class}"
+    end
+    @data[:token_usage] = value
+  end
+
+  # Hash-style read. Preserved so downstream tool runtimes pulling
+  # caller-provided keys via <tt>context[:agent]</tt> or
+  # <tt>context[:tenant]</tt> keep working unchanged.
+  #
+  #--
+  #: (Symbol) -> untyped
+  def [](key)
+    @data[key]
+  end
+
+  # Hash-style dig. Preserved for tools using
+  # <tt>context&.dig(:user_id)</tt>.
+  #
+  #--
+  #: (*Symbol) -> untyped
+  def dig(*keys)
+    @data.dig(*keys)
+  end
+
+  # Returns a copy of the underlying Hash. Mutating the result does not
+  # affect this context.
+  #
+  #--
+  #: () -> Hash[Symbol, untyped]
+  def to_h
+    @data.dup
+  end
+end

data/lib/riffer/agent/run.rb

@@ -0,0 +1,308 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+# Riffer::Agent::Run is the generation loop. A pure module of functions over an
+# +agent+ — Agent owns every per-call value (provider, model, tools, tool
+# runtime, structured output, session, context); Run just orchestrates.
+#
+# Tools and user code see the agent's +context+ (a +Riffer::Agent::Context+)
+# unchanged through the loop, so downstream tool runtimes can read
+# caller-provided keys via <tt>context[:agent]</tt> /
+# <tt>context.dig(:key)</tt>, or the framework built-ins via
+# +context.skills+. Cumulative token usage is updated into
+# +agent.context.token_usage+ as the loop progresses.
+#
+#   Riffer::Agent::Run.generate(agent: my_agent, prompt: "Hello")
+#   Riffer::Agent::Run.stream(agent: my_agent, prompt: "Hello")
+#
+module Riffer::Agent::Run
+  extend self
+  include Riffer::Messages::Converter
+
+  # Runs the generate loop for the given agent. See Riffer::Agent#generate
+  # for prompt/files semantics.
+  #
+  #--
+  #: (agent: Riffer::Agent, ?prompt: String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?) -> Riffer::Agent::Response
+  def generate(agent:, prompt: nil, files: nil)
+    append_user_message(agent, prompt, files: files)
+    run_loop(agent)
+  end
+
+  # Runs the streaming loop for the given agent. See Riffer::Agent#stream
+  # for prompt/files semantics.
+  #
+  #--
+  #: (agent: Riffer::Agent, ?prompt: String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?) -> Enumerator[Riffer::StreamEvents::Base, void]
+  def stream(agent:, prompt: nil, files: nil)
+    append_user_message(agent, prompt, files: files)
+    Enumerator.new { |stream_yielder| run_loop(agent, stream_yielder: stream_yielder) }
+  end
+
+  private
+
+  # The generation loop. When +stream_yielder+ is provided, per-step events are
+  # pushed to it (and +stream+ discards the return value). When +stream_yielder+
+  # is +nil+, no events are emitted and +generate+ returns the Response
+  # directly. The two modes share every step of the loop — the only
+  # divergences are the LLM call shape (atomic vs. accumulated stream)
+  # and whether per-step events are emitted.
+  #
+  #--
+  #: (Riffer::Agent, ?stream_yielder: Enumerator::Yielder?) -> Riffer::Agent::Response
+  def run_loop(agent, stream_yielder: nil)
+    all_modifications = [] #: Array[Riffer::Guardrails::Modification]
+
+    run_before_guardrails(agent, stream_yielder, all_modifications) { |tripped| return tripped }
+
+    skills = agent.context.skills
+
+    if stream_yielder && skills
+      skills.on_activate = ->(name) { stream_yielder << Riffer::StreamEvents::SkillActivation.new(name) }
+    end
+
+    step = agent.session.steps
+
+    reason = catch(:riffer_interrupt) do
+      execute_pending_tool_calls(agent)
+
+      loop do
+        response = stream_yielder ? accumulate_streamed_response(agent, stream_yielder) : call_llm(agent)
+        step += 1
+        track_token_usage(agent, response.token_usage)
+
+        processed_response = run_after_guardrails(agent, response, stream_yielder, all_modifications) { |tripped| return tripped }
+
+        agent.session.add(processed_response)
+
+        break unless processed_response.has_tool_calls?
+
+        throw :riffer_interrupt, Riffer::Agent::INTERRUPT_MAX_STEPS if step >= agent.config.max_steps
+
+        execute_tool_calls(agent, processed_response)
+      end
+
+      return final_response(agent, all_modifications)
+    end
+
+    # catch returns the thrown value when throw :riffer_interrupt fires;
+    # the return above exits on the successful (non-interrupted) path.
+    new_messages, filled = Riffer::Agent::Session::Repair.fill_orphans(agent.session.messages)
+    agent.session.set(new_messages)
+    stream_yielder << Riffer::StreamEvents::Interrupt.new(reason: reason, healed_tool_call_ids: filled) if stream_yielder
+    final_response(agent, all_modifications, interrupted: true, interrupt_reason: reason, healed_tool_call_ids: filled)
+  end
+
+  # Consumes one provider stream, forwarding every event to +stream_yielder+
+  # and folding it into an +Assistant+ message.
+  #
+  #--
+  #: (Riffer::Agent, Enumerator::Yielder) -> Riffer::Messages::Assistant
+  def accumulate_streamed_response(agent, stream_yielder)
+    accumulated_content = ""
+    accumulated_tool_calls = [] #: Array[Riffer::Messages::Assistant::ToolCall]
+    accumulated_token_usage = nil #: Riffer::Providers::TokenUsage?
+
+    call_llm_stream(agent).each do |event|
+      stream_yielder << event
+
+      case event
+      when Riffer::StreamEvents::TextDelta
+        accumulated_content += event.content
+      when Riffer::StreamEvents::TextDone
+        accumulated_content = event.content
+      when Riffer::StreamEvents::ToolCallDone
+        accumulated_tool_calls << Riffer::Messages::Assistant::ToolCall.new(
+          call_id: event.call_id,
+          name: event.name,
+          arguments: event.arguments
+        )
+      when Riffer::StreamEvents::TokenUsageDone
+        accumulated_token_usage = event.token_usage
+      end
+    end
+
+    Riffer::Messages::Assistant.new(
+      accumulated_content,
+      tool_calls: accumulated_tool_calls,
+      token_usage: accumulated_token_usage
+    )
+  end
+
+  # Appends +new_modifications+ to +all_modifications+ and emits a
+  # +GuardrailModification+ event for each one when streaming.
+  #
+  #--
+  #: (Enumerator::Yielder?, Array[Riffer::Guardrails::Modification], Array[Riffer::Guardrails::Modification]) -> void
+  def record_modifications!(stream_yielder, all_modifications, new_modifications)
+    all_modifications.concat(new_modifications)
+    new_modifications.each { |m| stream_yielder << Riffer::StreamEvents::GuardrailModification.new(m) } if stream_yielder
+  end
+
+  # Emits a +GuardrailTripwire+ event when streaming and returns the
+  # short-circuit +Response+ for a tripped guardrail.
+  #
+  #--
+  #: (Riffer::Agent, Enumerator::Yielder?, Riffer::Guardrails::Tripwire, Array[Riffer::Guardrails::Modification]) -> Riffer::Agent::Response
+  def tripwire_response(agent, stream_yielder, tripwire, all_modifications)
+    stream_yielder << Riffer::StreamEvents::GuardrailTripwire.new(tripwire) if stream_yielder
+    build_response(agent, "", tripwire: tripwire, modifications: all_modifications)
+  end
+
+  # Builds the final +Response+ from the session's last assistant
+  # message, validating structured output when configured. +extra+
+  # carries the interrupt-only fields (+interrupted:+, +interrupt_reason:+,
+  # +healed_tool_call_ids:+) on the interrupt exit path.
+  #
+  #--
+  #: (Riffer::Agent, Array[Riffer::Guardrails::Modification], **untyped) -> Riffer::Agent::Response
+  def final_response(agent, all_modifications, **extra)
+    response = agent.session.final_assistant_message
+    build_response(agent, response&.content || "", modifications: all_modifications, structured_output: validate_structured_output(agent, response), **extra)
+  end
+
+  #--
+  #: (Riffer::Agent) -> Riffer::Messages::Assistant
+  def call_llm(agent)
+    agent.provider.generate_text(
+      messages: agent.session.messages,
+      model: agent.model_name,
+      tools: agent.tools,
+      **merged_model_options(agent)
+    )
+  end
+
+  #--
+  #: (Riffer::Agent) -> Enumerator[Riffer::StreamEvents::Base, void]
+  def call_llm_stream(agent)
+    agent.provider.stream_text(
+      messages: agent.session.messages,
+      model: agent.model_name,
+      tools: agent.tools,
+      **merged_model_options(agent)
+    )
+  end
+
+  #--
+  #: (Riffer::Agent, Riffer::Messages::Assistant, ?tool_calls: Array[Riffer::Messages::Assistant::ToolCall]) -> void
+  def execute_tool_calls(agent, assistant_message, tool_calls: assistant_message.tool_calls)
+    return if tool_calls.empty?
+
+    results = agent.tool_runtime.execute(tool_calls, tools: agent.tools, context: agent.context, assistant_message: assistant_message)
+
+    results.each do |tool_call, result|
+      agent.session.add(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.
+  #
+  # Detects gaps between the last assistant message's requested tool calls
+  # and the tool result messages that follow it, executing any that are
+  # missing. Safe to call unconditionally.
+  #
+  #--
+  #: (Riffer::Agent) -> void
+  def execute_pending_tool_calls(agent)
+    assistant_message, pending = agent.session.pending_tool_calls
+    execute_tool_calls(agent, assistant_message, tool_calls: pending) if assistant_message
+  end
+
+  # Runs the +:before+ guardrail phase. Records any modifications into
+  # +all_modifications+ (and emits them when streaming). When a tripwire
+  # fires, yields the short-circuit +Response+ — the caller's block is
+  # expected to +return+ it from +run_loop+.
+  #
+  #--
+  #: (Riffer::Agent, Enumerator::Yielder?, Array[Riffer::Guardrails::Modification]) { (Riffer::Agent::Response) -> void } -> void
+  def run_before_guardrails(agent, stream_yielder, all_modifications)
+    guardrails = agent.config.guardrails_for(:before)
+    return if guardrails.empty?
+
+    runner = Riffer::Guardrails::Runner.new(guardrails, phase: :before, context: agent.context)
+    processed_messages, tripwire, modifications = runner.run(agent.session.messages)
+    agent.session.set(processed_messages) unless tripwire
+    record_modifications!(stream_yielder, all_modifications, modifications)
+    yield tripwire_response(agent, stream_yielder, tripwire, all_modifications) if tripwire
+  end
+
+  # Runs the +:after+ guardrail phase against the assistant +response+.
+  # Records any modifications into +all_modifications+ (and emits them
+  # when streaming). When a tripwire fires, yields the short-circuit
+  # +Response+ — the caller's block is expected to +return+ it from
+  # +run_loop+. Otherwise returns the post-guardrails assistant message.
+  #
+  #--
+  #: (Riffer::Agent, Riffer::Messages::Assistant, Enumerator::Yielder?, Array[Riffer::Guardrails::Modification]) { (Riffer::Agent::Response) -> void } -> untyped
+  def run_after_guardrails(agent, response, stream_yielder, all_modifications)
+    guardrails = agent.config.guardrails_for(:after)
+    return response if guardrails.empty?
+
+    runner = Riffer::Guardrails::Runner.new(guardrails, phase: :after, context: agent.context)
+    processed_response, tripwire, modifications = runner.run(response, messages: agent.session.messages)
+
+    response_index = agent.session.messages.length
+    modifications.each { |m| m.message_indices.map! { response_index } }
+
+    record_modifications!(stream_yielder, all_modifications, modifications)
+    yield tripwire_response(agent, stream_yielder, tripwire, all_modifications) if tripwire
+
+    processed_response
+  end
+
+  #--
+  #: (Riffer::Agent, Riffer::Messages::Assistant?) -> Hash[Symbol, untyped]?
+  def validate_structured_output(agent, response)
+    return unless response&.structured_output? && agent.structured_output
+
+    agent.structured_output.parse_and_validate(response.content).object
+  end
+
+  #--
+  #: (Riffer::Agent) -> Hash[Symbol, untyped]
+  def merged_model_options(agent)
+    opts = agent.config.model_options.dup
+    opts[:structured_output] = agent.structured_output if agent.structured_output
+    opts
+  end
+
+  #--
+  #: (Riffer::Agent, 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(agent, content, tripwire: nil, modifications: [], interrupted: false, interrupt_reason: nil, structured_output: nil, healed_tool_call_ids: [])
+    messages = agent.session.messages
+    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
+
+  # Appends a +User+ message to the session. No-ops when +prompt+ is nil
+  # and +files+ is empty (the caller had nothing to add). Raises when
+  # +files+ are supplied without a +prompt+ — the provider needs text to
+  # anchor the attachments.
+  #
+  #--
+  #: (Riffer::Agent, String?, ?files: Array[Hash[Symbol, untyped] | Riffer::Messages::FilePart]?) -> void
+  def append_user_message(agent, prompt, files: nil)
+    raise Riffer::ArgumentError, "files: requires a prompt" if files && !files.empty? && prompt.nil?
+    return unless prompt
+
+    file_parts = (files || []).map { |f| convert_to_file_part(f) }
+    agent.session.add(Riffer::Messages::User.new(prompt, files: file_parts), silent: true)
+  end
+
+  # Accumulates token usage into +agent.context.token_usage+. Updates the
+  # context so cumulative usage persists across every run on the agent.
+  #
+  #--
+  #: (Riffer::Agent, Riffer::Providers::TokenUsage?) -> void
+  def track_token_usage(agent, usage)
+    return unless usage
+
+    current = agent.context.token_usage
+    agent.context.token_usage = current ? current + usage : usage
+  end
+end