rubino-agent 0.3.0

data/lib/rubino/agent/degenerate_recovery.rb

@@ -0,0 +1,271 @@
+# frozen_string_literal: true
+
+module Rubino
+  module Agent
+    # The degenerate-response recovery ladder — a faithful, rung-by-rung port of
+    # the `if not agent._has_content_after_think_block(final_response):` block in
+    # the reference conversation loop.
+    #
+    # This is the load-bearing machinery that cures MiniMax's "completed but
+    # empty" / thinking-only responses: a structurally-valid text response whose
+    # visible content is empty once the <think> reasoning is stripped. Rather than
+    # surfacing that as a finished (empty) turn, the ladder walks seven rungs IN
+    # ORDER, each a cheaper-or-smarter recovery than giving up:
+    #
+    #   1. partial-stream recovery   — content already streamed to the user before
+    #                                  the turn went degenerate? Use it.
+    #   2. prior-turn content        — the previous turn already delivered a real
+    #                                  answer alongside HOUSEKEEPING tools? Reuse it.
+    #   3. post-tool empty nudge     — empty right after a tool round? Append a
+    #                                  user-level "continue" hint and re-issue.
+    #   4. thinking-only prefill ×2  — the model reasoned (<think>) but never spoke?
+    #                                  Re-issue the SAME request with an assistant
+    #                                  PREFILL seed so it continues into visible
+    #                                  text. THE key MiniMax cure.
+    #   5. empty-content retry ×3    — truly empty (no text, no reasoning)? Retry.
+    #   6. empty → fallback          — retries exhausted? Hand to FallbackChain.
+    #                                  NOT BUILT — Slice 7 seam, falls through.
+    #   7. terminal                  — still stuck? Raise EmptyModelResponseError.
+    #                                  (We DROP the reference "(empty)" sentinel-replay
+    #                                  machinery and raise,
+    #                                  so Run::Executor maps it to FAILED, never
+    #                                  completed-but-empty.)
+    #
+    # OWNS the two per-turn counters the reference keeps on the agent — prefill
+    # attempts (≤2) and empty-content retries (≤3). A fresh instance is built per
+    # model call (per ModelCallRunner#call!), so the counters reset exactly where
+    # the reference resets them to 0 on a successful content turn.
+    #
+    # The ladder needs a little turn state the bare AdapterResponse does not carry
+    # (what streamed before the drop, the prior assistant turn, whether a tool
+    # round just ran). That is threaded in via RecoveryState, NOT re-derived here.
+    class DegenerateResponseRecovery
+      # Per-turn recovery state the ladder reads. Built by the runner/loop and
+      # handed to #recover with each degenerate response.
+      #
+      #   response                : the degenerate AdapterResponse just received
+      #   streamed_text           : visible text already streamed to the user this
+      #                             call (rung 1); "" when nothing/streamed off
+      #   messages                : the live api-messages array for this turn —
+      #                             the SAME reference the loop owns, so a rung-3
+      #                             nudge appended here is seen on re-issue
+      #   prior_turn_content      : last assistant content delivered alongside
+      #                             tool calls in a PRIOR turn (rung 2), or nil
+      #   prior_tools_all_housekeeping : true only when every tool in that prior
+      #                             turn was housekeeping (memory/todo). The gem
+      #                             has no housekeeping taxonomy yet, so this is
+      #                             false today and rung 2 is a faithful no-op.
+      RecoveryState = Struct.new(
+        :response, :streamed_text, :messages,
+        :prior_turn_content, :prior_tools_all_housekeeping,
+        keyword_init: true
+      )
+
+      # A directive the runner acts on. `kind` is one of:
+      #   :use      — return `content` as the final answer (rungs 1, 2)
+      #   :nudge    — request.messages was mutated; re-issue the same request (rung 3)
+      #   :prefill  — re-issue carrying `seed` as request.prefill (rung 4)
+      #   :retry    — re-issue the same request unchanged (rung 5)
+      #   :raise    — terminal: raise EmptyModelResponseError (rungs 6→7)
+      # `attempt` is the 1-based retry index on a :retry, so the runner can
+      # escalate its invalid-response backoff across the ≤3 retries.
+      Directive = Struct.new(:kind, :content, :seed, :attempt, keyword_init: true)
+
+      DEFAULT_PREFILL_MAX = 2
+      DEFAULT_EMPTY_MAX   = 3
+
+      # The user-level hint appended after an empty post-tool turn (rung 3),
+      # verbatim from the reference implementation.
+      NUDGE_TEXT =
+        "You just executed tool calls but returned an empty response. " \
+        "Please process the tool results above and continue with the task."
+
+      def initialize(validator: ResponseValidator.new, ui: nil,
+                     prefill_max: DEFAULT_PREFILL_MAX, empty_max: DEFAULT_EMPTY_MAX)
+        @validator    = validator
+        @ui           = ui
+        @prefill_max  = prefill_max
+        @empty_max    = empty_max
+        @prefill_attempts = 0
+        @empty_attempts   = 0
+        # _post_tool_empty_retried — the nudge fires at most once per turn.
+        @nudged = false
+      end
+
+      # Walk the ladder for one degenerate response and return a Directive.
+      # Mirrors the reference conversation loop rung for rung, in order.
+      def recover(state)
+        # ── Rung 1: partial-stream recovery ──────────────────
+        # If real content was streamed to the user before the turn came back
+        # degenerate, deliver it instead of wasting calls on retries.
+        if content_after_think?(state.streamed_text)
+          note("↻ Stream interrupted — using delivered content as final response")
+          return Directive.new(kind: :use, content: strip_think(state.streamed_text))
+        end
+
+        # ── Rung 2: prior-turn content fallback ──────────────
+        # The previous turn already delivered a real answer alongside
+        # HOUSEKEEPING-only tools; the model has nothing more to say. Reuse it
+        # rather than retrying. Guarded on all-housekeeping so mid-task
+        # narration ("I'll scan the directory…") falls through to the nudge.
+        if state.prior_turn_content && state.prior_tools_all_housekeeping
+          note("↻ Empty response after tool calls — using earlier content as final answer")
+          return Directive.new(kind: :use, content: strip_think(state.prior_turn_content))
+        end
+
+        has_inline_thinking = inline_thinking?(state.response)
+
+        # ── Rung 3: post-tool empty nudge ────────────────────
+        # Empty right after a tool round (and NOT a thinking-only response —
+        # that routes to prefill below). Append the empty assistant turn then a
+        # user-level nudge so the sequence stays valid (tool → assistant →
+        # user), and re-issue. Fires at most once per turn.
+        if prior_was_tool?(state.messages) && !@nudged && !has_inline_thinking
+          @nudged = true
+          note("⚠️ Model returned empty after tool calls — nudging to continue")
+          append_nudge!(state.messages, state.response)
+          return Directive.new(kind: :nudge)
+        end
+
+        # ── Rung 4: thinking-only prefill-to-continue ×2 ─────
+        # The model produced reasoning (structured thinking field OR inline
+        # <think>) but no visible text. Re-issue the SAME request seeded with an
+        # assistant PREFILL so the model continues from its own reasoning into
+        # the visible answer. THE MiniMax cure.
+        if has_structured?(state.response) && @prefill_attempts < @prefill_max
+          @prefill_attempts += 1
+          note("↻ Thinking-only response — prefilling to continue " \
+               "(#{@prefill_attempts}/#{@prefill_max})")
+          return Directive.new(kind: :prefill, seed: prefill_seed(state.response))
+        end
+
+        # ── Rung 5: empty-content retry ×3 ───────────────────
+        # Truly empty (nothing usable once <think> is stripped), OR a reasoning
+        # model that has now exhausted its prefill attempts. Plain retry.
+        truly_empty       = strip_think(state.response.content).empty?
+        prefill_exhausted = has_structured?(state.response) && @prefill_attempts >= @prefill_max
+        if truly_empty && (!has_structured?(state.response) || prefill_exhausted) &&
+           @empty_attempts < @empty_max
+          @empty_attempts += 1
+          note("⚠️ Empty response from model — retrying (#{@empty_attempts}/#{@empty_max})")
+          return Directive.new(kind: :retry, attempt: @empty_attempts)
+        end
+
+        # ── Rung 6: empty → fallback ─────────────────────────
+        # SLICE-7 seam. The reference here tries _try_activate_fallback() and, on a
+        # successful switch, resets _empty_content_retries to 0 and continues on
+        # the new provider. FallbackChain is not built yet (Slice 7), so there
+        # is no provider to switch to — fall straight through to rung 7. When
+        # FallbackChain lands, attempt the switch here and return :retry on
+        # success (zeroing @empty_attempts).
+
+        # ── Rung 7: terminal ─────────────────────────────────
+        # Exhausted every rung. We DROP the reference "(empty)" sentinel-replay
+        # machinery: the runner raises EmptyModelResponseError so the
+        # run is marked FAILED, never completed-but-empty.
+        Directive.new(kind: :raise)
+      end
+
+      private
+
+      # Append the empty assistant turn then the user nudge, so the on-the-wire
+      # sequence stays valid: tool(result) → assistant("(empty)") → user(nudge).
+      # A bare tool → user is rejected by most strict providers. Mirrors the
+      # reference implementation.
+      def append_nudge!(messages, response)
+        messages << {
+          role: "assistant",
+          content: response.content.to_s.empty? ? "(empty)" : response.content,
+          tool_calls: response.has_tool_calls? ? response.tool_calls : nil
+        }
+        messages << { role: "user", content: NUDGE_TEXT }
+      end
+
+      # The assistant-seed text for prefill-to-continue. The reference re-appends the
+      # model's own interim (thinking) message and lets the model continue from
+      # it; on our boundary the equivalent is seeding the next assistant turn
+      # with the reasoning the model already produced, so it continues into the
+      # visible answer. Prefer the structured thinking field; fall back to the
+      # inline <think> content. Returns "" only if nothing is recoverable (the
+      # boundary still sends a continuation prompt — an empty prefill is a plain
+      # re-issue, harmless).
+      def prefill_seed(response)
+        seed = response.thinking.to_s
+        seed = think_only(response.content) if seed.strip.empty?
+        seed.to_s
+      end
+
+      # True when the response carries reasoning by ANY channel the reference checks:
+      # a structured thinking field OR an inline <think>/<thinking>/<reasoning>
+      # block in the content (Ollama/Qwen put it there).
+      def has_structured?(response)
+        return true if response.thinking.to_s.strip != ""
+
+        inline_thinking?(response)
+      end
+
+      # Inline-thinking detector — matches the reference _has_inline_thinking regex.
+      def inline_thinking?(response)
+        !!(response.content.to_s =~ /<think>|<thinking>|<reasoning>/i)
+      end
+
+      # Any recent message a tool result? The reference checks the last 5 messages.
+      def prior_was_tool?(messages)
+        Array(messages).last(5).any? { |m| (m[:role] || m["role"]).to_s == "tool" }
+      end
+
+      # True when visible text survives stripping the <think> block — the gem's
+      # ResponseValidator already owns this judgement, so reuse it on a synthetic
+      # content-only response rather than duplicating the filter.
+      def content_after_think?(text)
+        return false if text.to_s.strip.empty?
+
+        !@validator.degenerate?(content_probe(text))
+      end
+
+      def strip_think(text)
+        think_only(text).empty? ? collapse(text) : visible_after_think(text)
+      end
+
+      # The visible content with <think> blocks removed, stripped.
+      def visible_after_think(text)
+        visible = +""
+        filter  = LLM::InlineThinkFilter.new
+        emit    = ->(type, str) { visible << str if type == :content }
+        filter.feed(text.to_s, &emit)
+        filter.flush(&emit)
+        visible.strip
+      end
+
+      # Just the think-block contents, for the prefill seed.
+      def think_only(text)
+        thinking = +""
+        filter   = LLM::InlineThinkFilter.new
+        emit     = ->(type, str) { thinking << str if type == :thinking }
+        filter.feed(text.to_s, &emit)
+        filter.flush(&emit)
+        thinking.strip
+      end
+
+      def collapse(text)
+        text.to_s.strip
+      end
+
+      # Minimal AdapterResponse-shaped probe so we can reuse ResponseValidator
+      # #degenerate? on a raw streamed string.
+      def content_probe(text)
+        LLM::AdapterResponse.new(
+          content: text.to_s, tool_calls: [], input_tokens: 0, output_tokens: 0,
+          model_id: nil
+        )
+      end
+
+      def note(text)
+        @ui&.note(text)
+      rescue StandardError
+        # UI may be a Null/test double without #note — never let status text
+        # abort recovery.
+      end
+    end
+  end
+end

data/lib/rubino/agent/fallback_chain.rb

@@ -0,0 +1,194 @@
+# frozen_string_literal: true
+
+module Rubino
+  module Agent
+    # The provider/model fallback chain — a faithful port of the reference
+    # `_fallback_chain` + `try_activate_fallback`
+    # and the per-turn `_restore_primary_runtime`.
+    #
+    # WHAT IT DOES. The primary backend is index 0; `agent.fallback_models` lists
+    # the ordered fallbacks. When the primary keeps failing — invalid/empty
+    # responses (eager fallback), rate-limit/overload, or an exhausted
+    # retry budget, or empty-after-retries — the runner
+    # / recovery ladder calls #activate_next! to rotate to the next backend and
+    # rebuild the adapter. At the TOP of each new turn ConversationLoop#run calls
+    # #restore_primary! so every turn gets a fresh attempt with the preferred
+    # model.
+    #
+    # DEDUP. An entry that resolves to the CURRENT provider/model/base_url is
+    # skipped — falling back to the backend that just failed only loops the
+    # failure. We keep advancing past skipped entries in a
+    # single #activate_next! call, exactly like the reference recursive
+    # `return agent._try_activate_fallback()`.
+    #
+    # GLOBAL-CONFIG ISOLATION (the heart of this slice).
+    # `RubyLLM.configure` is process-global; a naive provider swap would corrupt
+    # concurrent sessions on the API/server path. So fallback adapters are built
+    # with `isolate_config: true`: each scopes its provider config (base_url /
+    # api_key / timeout) into a per-adapter `RubyLLM::Context` and NEVER writes
+    # the global. The primary adapter is passed in as-is (it already configured
+    # the global at construction, exactly as before), so a single-provider setup
+    # — and the no-fallback case — is byte-identical to pre-Slice-7 behaviour.
+    #
+    # NO-OP WHEN UNCONFIGURED. With an empty `fallback_models` the chain holds
+    # only the primary: #activate_next! is always false and #current_adapter is
+    # always the primary. Nothing is rebuilt, nothing is mutated.
+    class FallbackChain
+      # One backend in the chain. provider/model are required to be usable; an
+      # entry missing either is treated as invalid and skipped on advance.
+      Entry = Struct.new(:provider, :model, :base_url, :api_key, keyword_init: true) do
+        def usable?
+          !provider.to_s.strip.empty? && !model.to_s.strip.empty?
+        end
+      end
+
+      # primary_adapter : the already-built primary LLM adapter (index 0). The
+      #                   chain never rebuilds it — restore just points back to it.
+      # config          : the live Configuration (reads agent.fallback_models and
+      #                   the providers.* blocks the fallback entries inherit).
+      # adapter_builder : injectable seam for tests; defaults to AdapterFactory.
+      def initialize(primary_adapter:, config:, ui: nil, event_bus: nil,
+                     tool_executor: nil, cancel_token: nil,
+                     adapter_builder: LLM::AdapterFactory)
+        @primary         = primary_adapter
+        @config          = config
+        @ui              = ui
+        @event_bus       = event_bus
+        @tool_executor   = tool_executor
+        @cancel_token    = cancel_token
+        @adapter_builder = adapter_builder
+
+        @entries = build_entries
+        @index   = 0
+        @active  = @primary
+      end
+
+      # The adapter the loop/runner should issue calls against right now.
+      def current_adapter
+        @active
+      end
+
+      # True once a fallback has been activated this turn — lets callers emit the
+      # "switched to fallback" status only when something actually changed.
+      def active?
+        @index.positive?
+      end
+
+      # Advance to the next usable, non-duplicate fallback and rebuild the
+      # adapter. Returns true if it actually switched, false when the chain is
+      # exhausted (or empty). Mirrors try_activate_fallback (helpers.py:1020):
+      # skip invalid entries and entries that resolve to the current backend,
+      # advancing past them within this one call.
+      def activate_next!
+        loop do
+          return false if @index >= @entries.size
+
+          entry = @entries[@index]
+          @index += 1
+
+          next unless entry.usable?
+          next if duplicate_of_current?(entry)
+
+          @active = build_adapter(entry)
+          return true
+        end
+      end
+
+      # Reset to the primary at the top of each turn. No-op cost when
+      # we never left the primary; rebuilds nothing (the primary adapter is the
+      # one handed in at construction).
+      def restore_primary!
+        @index  = 0
+        @active = @primary
+      end
+
+      private
+
+      # The fallback entries (NOT including the implicit primary at index 0).
+      def build_entries
+        Array(@config.dig("agent", "fallback_models")).filter_map do |raw|
+          next unless raw.is_a?(Hash)
+
+          Entry.new(
+            provider: fetch(raw, "provider"),
+            model: fetch(raw, "model"),
+            base_url: fetch(raw, "base_url"),
+            api_key: fetch(raw, "api_key")
+          )
+        end
+      end
+
+      def fetch(hash, key)
+        value = hash[key] || hash[key.to_sym]
+        value.to_s.strip.empty? ? nil : value.to_s
+      end
+
+      # Skip an entry whose RESOLVED provider+model (or base_url+model) matches the
+      # active adapter — falling back to the same backend just loops the failure.
+      def duplicate_of_current?(entry)
+        resolved = LLM::ProviderResolver.resolve(entry.model, explicit_provider: entry.provider)
+        cur_provider = @active.provider.to_s.strip.downcase
+        cur_model    = @active.model_id.to_s.strip
+
+        return true if resolved.to_s.strip.downcase == cur_provider && entry.model.to_s.strip == cur_model
+
+        entry_base = normalize_url(entry.base_url)
+        cur_base   = normalize_url(current_base_url)
+        !entry_base.empty? && !cur_base.empty? &&
+          entry_base == cur_base && entry.model.to_s.strip == cur_model
+      end
+
+      # The base_url the active adapter is pointed at (its provider's config
+      # base_url), for the dedup comparison.
+      def current_base_url
+        @config.provider_config(@active.provider)["base_url"]
+      end
+
+      def normalize_url(url)
+        url.to_s.strip.sub(%r{/+\z}, "").downcase
+      end
+
+      # Rebuild the adapter for a fallback entry. The entry's base_url/api_key
+      # override the providers.<name> block for THIS adapter only; everything is
+      # scoped into a per-call RubyLLM::Context via isolate_config: true so the
+      # process-global RubyLLM.configure is never mutated.
+      def build_adapter(entry)
+        @adapter_builder.build(
+          model_id: entry.model,
+          provider: entry.provider,
+          config: config_for(entry),
+          ui: @ui,
+          event_bus: @event_bus,
+          tool_executor: @tool_executor,
+          cancel_token: @cancel_token,
+          isolate_config: true
+        )
+      end
+
+      # A per-entry Configuration whose providers.<provider> block carries the
+      # entry's base_url/api_key overrides, leaving the shared config untouched
+      # (deep-dup of the provider section only — nothing else is copied or
+      # mutated). The adapter reads base_url/api_key from here.
+      def config_for(entry)
+        overrides = {}
+        overrides["base_url"] = entry.base_url if entry.base_url
+        overrides["api_key"]  = entry.api_key  if entry.api_key
+        return @config if overrides.empty?
+
+        raw      = deep_dup(@config.raw)
+        provider = entry.provider.to_s
+        raw["providers"] ||= {}
+        raw["providers"][provider] = (raw["providers"][provider] || {}).merge(overrides)
+        Config::Configuration.new(raw: raw)
+      end
+
+      def deep_dup(obj)
+        case obj
+        when Hash  then obj.each_with_object({}) { |(k, v), h| h[k] = deep_dup(v) }
+        when Array then obj.map { |v| deep_dup(v) }
+        else obj
+        end
+      end
+    end
+  end
+end

data/lib/rubino/agent/iteration_budget.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module Rubino
+  module Agent
+    # Manages turn and iteration budgets to prevent runaway loops.
+    class IterationBudget
+      def initialize(config: nil, max_tool_iterations: nil)
+        @config = config || Rubino.configuration
+        @max_turns = @config.agent_max_turns
+        # An explicit override (the CLI `--max-turns N` flag, threaded through
+        # Runner → Lifecycle) wins over the config default so the documented
+        # control knob actually caps tool iterations (#141). A nil/blank
+        # override falls back to the configured budget, unchanged.
+        @max_tool_iterations = positive_int(max_tool_iterations) || @config.agent_max_tool_iterations
+        @max_turn_seconds = @config.agent_max_turn_seconds
+        @turn_started_at = Time.now
+      end
+
+      # Returns true if the agent can continue iterating
+      def can_continue?(iteration)
+        within_iteration_limit?(iteration) && within_time_limit?
+      end
+
+      private
+
+      # Coerce an override to a positive Integer, or nil if it's absent/garbage
+      # (so the config default is used). Accepts the numeric Thor option, which
+      # arrives as a Float, and rejects 0/negative values as "no cap given".
+      def positive_int(value)
+        return nil if value.nil?
+
+        n = Integer(value, exception: false) || Float(value, exception: false)&.to_i
+        n if n && n.positive?
+      end
+
+      # A nil cap means "unbounded": never stop on that dimension rather than
+      # crashing the turn comparing a number with nil (#139).
+      def within_iteration_limit?(iteration)
+        @max_tool_iterations.nil? || iteration <= @max_tool_iterations
+      end
+
+      def within_time_limit?
+        return true if @max_turn_seconds.nil?
+
+        elapsed = Time.now - @turn_started_at
+        elapsed < @max_turn_seconds
+      end
+    end
+  end
+end