riffer 0.28.0 → 0.29.1

data/lib/riffer/agent/session/repair.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+# Riffer::Agent::Session::Repair holds the pure transformations that keep the
+# +tool_use+ ↔ +tool_result+ invariant on a message array. No state, no
+# instance — module-level functions only. Each entry point is gated by
+# +Riffer.config.experimental_history_healing+: when the flag is off the
+# function returns its input unchanged.
+#
+# Two seams:
+#
+# - +fill_orphans+ — fills orphan +tool_use+ blocks with placeholder
+#   results. Used on interrupt (caller-issued or +max_steps+).
+# - +prune_orphans+ — drops orphan +tool_use+ blocks and parentless Tool
+#   messages from a caller-provided seed so it is well-formed before the
+#   next inference call. Used at construction time when
+#   +Riffer::Agent.new(session:)+ receives a session.
+module Riffer::Agent::Session::Repair
+  # Placeholder used to fill orphan +tool_use+ blocks. Emitted as the
+  # +Riffer::Tools::Response+ body for each filled call_id.
+  ORPHAN_PLACEHOLDER = ->(_tool_call) {
+    Riffer::Tools::Response.error("Tool call interrupted before completion.", type: :interrupted)
+  } #: ^(Riffer::Messages::Assistant::ToolCall) -> Riffer::Tools::Response
+
+  # Fills any orphaned +tool_use+ in +messages+ with the
+  # +ORPHAN_PLACEHOLDER+ response. Each placeholder Tool message is
+  # inserted immediately after its parent assistant message. Returns
+  # +[new_messages, filled_call_ids]+; +filled_call_ids+ is empty when
+  # there are no orphans.
+  #
+  # No-op when +Riffer.config.experimental_history_healing+ is off:
+  # returns +[messages, []]+ with the same array reference.
+  #
+  #--
+  #: (Array[Riffer::Messages::Base]) -> [Array[Riffer::Messages::Base], Array[String]]
+  def self.fill_orphans(messages)
+    return [messages, []] unless Riffer.config.experimental_history_healing
+
+    result_ids = messages.filter_map { |m| m.tool_call_id if m.is_a?(Riffer::Messages::Tool) }
+    filled = [] #: 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 = ORPHAN_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
+        )
+        filled << tc.call_id
+      end
+    end
+
+    [new_messages, filled]
+  end
+
+  # Prunes 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.
+  #
+  # 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.
+  #
+  # No-op when +Riffer.config.experimental_history_healing+ is off:
+  # returns +messages+ unchanged.
+  #
+  #--
+  #: (Array[Riffer::Messages::Base]) -> Array[Riffer::Messages::Base]
+  def self.prune_orphans(messages)
+    return messages unless Riffer.config.experimental_history_healing
+
+    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
+end

data/lib/riffer/agent/session.rb

@@ -0,0 +1,270 @@
+# frozen_string_literal: true
+# rbs_inline: enabled
+
+# Riffer::Agent::Session owns the conversation handle for an agent: the message
+# array, the +on_message+ callback list, and the +tool_use+ ↔ +tool_result+
+# invariant that keeps tool calls and their results consistent.
+#
+# Access via +agent.session+. Sessions are constructed by +Riffer::Agent+
+# and live for the lifetime of the agent.
+#
+#   agent.session.add(msg)                  # append + fire callbacks
+#   agent.session.set([msg1, msg2])         # bulk replace (silent)
+#   agent.session.unset                     # clear (silent)
+#   agent.session.remove(id: "a_1")
+#   agent.session.update(id: "a_1", content: "...")
+#   agent.session.find { |m| m.id == "a_1" }
+#
+class Riffer::Agent::Session
+  include Enumerable #[Riffer::Messages::Base]
+
+  # @rbs @callbacks: Array[^(Riffer::Messages::Base) -> void]
+
+  # The message history.
+  attr_reader :messages #: Array[Riffer::Messages::Base]
+
+  #--
+  #: (?messages: Array[Riffer::Messages::Base]) -> void
+  def initialize(messages: [])
+    @messages = messages
+    @callbacks = [] #: Array[^(Riffer::Messages::Base) -> void]
+  end
+
+  # Registers a callback invoked once per message appended via +#add+.
+  #
+  # Callbacks do NOT fire for +#set+, +#unset+, +#remove+, or +#update+.
+  # Returns +self+ to allow chaining.
+  #
+  # 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?
+    @callbacks << block
+    self
+  end
+
+  # Appends +message+ and fires every registered callback once with it.
+  #
+  # Pass +silent: true+ to skip +on_message+ callbacks — used for
+  # non-inference inputs like user messages, which subscribers don't
+  # expect to observe through the callback channel. Inference-produced
+  # messages (Assistant, Tool) always go through +add+ without +silent+.
+  #
+  #--
+  #: (Riffer::Messages::Base, ?silent: bool) -> Riffer::Messages::Base
+  def add(message, silent: false)
+    @messages << message
+    @callbacks.each { |callback| callback.call(message) } unless silent
+    message
+  end
+
+  # Replaces the message history wholesale. Does NOT fire +on_message+
+  # callbacks; registered callbacks persist across the swap.
+  #
+  # Used for seeding, guardrail rewrites, and history healing — cases
+  # where firing callbacks would double-emit messages that subscribers
+  # have already observed (or never produced).
+  #
+  #--
+  #: (Array[Riffer::Messages::Base]) -> self
+  def set(messages)
+    @messages = messages
+    self
+  end
+
+  # Clears the session. Does NOT fire +on_message+ callbacks; registered
+  # callbacks persist.
+  #
+  #--
+  #: () -> self
+  def unset
+    @messages = []
+    self
+  end
+
+  # 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
+  # +#update+ to rewrite a tool result instead.
+  #
+  # Returns the removed message, or +nil+ when no message has the given id
+  # (idempotent).
+  #
+  #--
+  #: (id: String) -> Riffer::Messages::Base?
+  def remove(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 cannot drop a Tool message (would orphan the parent's tool_use); use #update instead"
+    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
+
+  # Partial in-place update. Looks up a message by either +id:+ or
+  # +tool_call_id:+ (exactly one required), constructs a replacement of the
+  # same concrete type with +attrs+ overlaid on the existing fields, and
+  # swaps it in place.
+  #
+  # When the target is an assistant message and the update drops one or more
+  # entries from +tool_calls+, every +Riffer::Messages::Tool+ result whose
+  # +tool_call_id+ matches a dropped call is removed atomically — keeping the
+  # +tool_use+ ↔ +tool_result+ invariant intact.
+  #
+  # Raises Riffer::ArgumentError when neither or both lookup keys are
+  # provided, or when no message matches.
+  #
+  #--
+  #: (?id: String?, ?tool_call_id: String?, **untyped) -> Riffer::Messages::Base
+  def update(id: nil, tool_call_id: nil, **attrs)
+    raise Riffer::ArgumentError, "update requires either id: or tool_call_id:" if id.nil? && tool_call_id.nil?
+    raise Riffer::ArgumentError, "update accepts id: or tool_call_id:, not both" if id && tool_call_id
+
+    idx = if id
+      @messages.index { |m| m.id == id }
+    else
+      @messages.index { |m| m.is_a?(Riffer::Messages::Tool) && m.tool_call_id == tool_call_id }
+    end
+
+    unless idx
+      key = id ? "id #{id.inspect}" : "tool_call_id #{tool_call_id.inspect}"
+      raise Riffer::ArgumentError, "no message found for #{key}"
+    end
+
+    old = @messages[idx] #: Riffer::Messages::Base
+    replacement = rebuild_message(old, attrs)
+    @messages[idx] = replacement
+    cascade_dropped_tool_calls(old, replacement)
+    replacement
+  end
+
+  # Returns the call_ids of every +tool_call+ on any assistant message that
+  # has no matching +Riffer::Messages::Tool+ result anywhere in history.
+  #
+  # Zero-cost validation hook for callers that want to check the
+  # +tool_use+ ↔ +tool_result+ invariant before mutating or persisting.
+  #
+  #--
+  #: () -> 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
+
+  # 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.
+  #
+  #--
+  #: () -> [Riffer::Messages::Assistant?, 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] #: Riffer::Messages::Assistant
+    return [assistant, []] if assistant.tool_calls.empty?
+
+    executed_ids = (@messages[(last_assistant_idx + 1)..] || []).filter_map { |m|
+      m.tool_call_id if m.is_a?(Riffer::Messages::Tool)
+    }
+
+    [assistant, assistant.tool_calls.reject { |tc| executed_ids.include?(tc.call_id) }]
+  end
+
+  #--
+  #: () -> Enumerator[Riffer::Messages::Base, self]
+  #: () { (Riffer::Messages::Base) -> void } -> untyped
+  def each(&block)
+    return @messages.each unless block
+    @messages.each(&block)
+  end
+
+  # The number of LLM steps completed in this session, derived from the
+  # count of assistant messages. Used by the agent loop to enforce
+  # +max_steps+ on resume.
+  #
+  #--
+  #: () -> Integer
+  def steps
+    @messages.count { |m| m.is_a?(Riffer::Messages::Assistant) }
+  end
+
+  # The most recent +Riffer::Messages::Assistant+ in the session, or +nil+
+  # when none exists.
+  #
+  #--
+  #: () -> Riffer::Messages::Assistant?
+  def final_assistant_message
+    # TODO: Replace with rfind when minimum Ruby is 4.0+
+    # rubocop:disable Style/ReverseFind
+    @messages.reverse_each.find { |m| m.is_a?(Riffer::Messages::Assistant) } #: Riffer::Messages::Assistant?
+    # rubocop:enable Style/ReverseFind
+  end
+
+  private
+
+  #: (Riffer::Messages::Base, Riffer::Messages::Base) -> void
+  def cascade_dropped_tool_calls(old, replacement)
+    return unless old.is_a?(Riffer::Messages::Assistant)
+    return unless replacement.is_a?(Riffer::Messages::Assistant)
+
+    removed_ids = old.tool_calls.map(&:call_id) - replacement.tool_calls.map(&:call_id)
+    return if removed_ids.empty?
+
+    @messages.reject! { |m| m.is_a?(Riffer::Messages::Tool) && removed_ids.include?(m.tool_call_id) }
+  end
+
+  #: (Riffer::Messages::Base, Hash[Symbol, untyped]) -> Riffer::Messages::Base
+  def rebuild_message(old, attrs)
+    case old
+    when Riffer::Messages::Assistant
+      Riffer::Messages::Assistant.new(
+        attrs.fetch(:content, old.content),
+        id: attrs.fetch(:id, old.id),
+        tool_calls: attrs.fetch(:tool_calls, old.tool_calls),
+        token_usage: attrs.fetch(:token_usage, old.token_usage),
+        structured_output: attrs.fetch(:structured_output, old.structured_output)
+      )
+    when Riffer::Messages::Tool
+      Riffer::Messages::Tool.new(
+        attrs.fetch(:content, old.content),
+        tool_call_id: old.tool_call_id,
+        name: attrs.fetch(:name, old.name),
+        id: attrs.fetch(:id, old.id),
+        error: attrs.fetch(:error, old.error),
+        error_type: attrs.fetch(:error_type, old.error_type)
+      )
+    when Riffer::Messages::User
+      Riffer::Messages::User.new(
+        attrs.fetch(:content, old.content),
+        id: attrs.fetch(:id, old.id),
+        files: attrs.fetch(:files, old.files)
+      )
+    else
+      old.class.new(
+        attrs.fetch(:content, old.content),
+        id: attrs.fetch(:id, old.id)
+      )
+    end
+  end
+end

data/lib/riffer/{structured_output → agent/structured_output}/result.rb

@@ -13,7 +13,7 @@
 #     result.error   #=> "JSON parse error: ..."
 #   end
 #
-class Riffer::StructuredOutput::Result
+class Riffer::Agent::StructuredOutput::Result
   attr_reader :object #: Hash[Symbol, untyped]?
   attr_reader :error #: String?
 

data/lib/riffer/{structured_output.rb → agent/structured_output.rb}

@@ -3,16 +3,16 @@
 
 require "json"
 
-# Riffer::StructuredOutput provides parse/validate for structured JSON
+# Riffer::Agent::StructuredOutput provides parse/validate for structured JSON
 # responses from LLM providers.
 #
 #   params = Riffer::Params.new
 #   params.required(:sentiment, String)
-#   so = Riffer::StructuredOutput.new(params)
+#   so = Riffer::Agent::StructuredOutput.new(params)
 #   result = so.parse_and_validate('{"sentiment":"positive","score":0.9}')
 #   result.object  #=> {sentiment: "positive", score: 0.9}
 #
-class Riffer::StructuredOutput
+class Riffer::Agent::StructuredOutput
   attr_reader :params #: Riffer::Params
 
   #--
@@ -34,7 +34,7 @@ class Riffer::StructuredOutput
   # Returns a Result with the validated object on success, or an error message on failure.
   #
   #--
-  #: (String) -> Riffer::StructuredOutput::Result
+  #: (String) -> Riffer::Agent::StructuredOutput::Result
   def parse_and_validate(json_string)
     parsed = JSON.parse(json_string, symbolize_names: true)
     validated = @params.validate(parsed)