rubino-agent 0.3.0

data/lib/rubino/agent/model_call_runner.rb

@@ -0,0 +1,383 @@
+# frozen_string_literal: true
+
+module Rubino
+  module Agent
+    # The INNER retry loop of the conversation loop — a faithful port of the
+    # reference `while retry_count < max_retries` block (the invalid-response
+    # path and the error path).
+    #
+    # ONE responsibility: issue a single model call against the LLM boundary and,
+    # when it comes back unusable or raises a transient error, retry it with
+    # backoff until it succeeds or the retry budget is exhausted. It OWNS the
+    # `retry_count`. The outer Loop hands it a built LLM::Request and gets back a
+    # validated AdapterResponse (or an exception).
+    #
+    # Control flow per attempt:
+    #   call boundary
+    #     → raises?  → ErrorClassifier.classify → retryable & budget left?
+    #                    yes: backoff (error-path preset, honour Retry-After), retry
+    #                    no : re-raise (permanent / budget exhausted)
+    #     → returns? → ResponseValidator#valid?
+    #                    valid          : return it
+    #                    :empty_response: backoff (invalid-response preset), retry
+    #                                     up to empty_response_max_retries, then
+    #                                     raise EmptyModelResponseError
+    #                    other invalid  : return as-is (nil / interrupted — the
+    #                                     caller maps these to StreamInterruptedError;
+    #                                     not the runner's job to retry)
+    #
+    # TWO backoff sites, two budgets, exactly as the reference:
+    #   * invalid/empty response  → BackoffPolicy::INVALID_RESPONSE (5s/120s),
+    #                               empty_response_max_retries (small, default 2)
+    #   * transient API error     → BackoffPolicy::ERROR_PATH (2s/60s),
+    #                               agent.api_max_retries
+    #
+    # The degenerate/empty-response path delegates to DegenerateResponseRecovery
+    # (Slice 5) — the seven-rung ladder (partial-stream → prior-turn → post-tool
+    # nudge → thinking-only prefill ×2 → empty retry ×3 → fallback seam →
+    # terminal raise) ported from the reference conversation loop. See
+    # #apply_recovery!.
+    #
+    # NOT in scope here (left as clear seams):
+    #   * eager fallback on an invalid response and fallback-on-max-retries
+    #     (the reference _try_activate_fallback, which RESETS
+    #     retry_count to 0) is Slice 7 — see the `# SLICE-7` seam below. The
+    #     counter is structured so a future fallback can reset it.
+    class ModelCallRunner
+      def initialize(llm:, config:, ui:, event_bus:, cancel_token: nil,
+                     fallback_chain: nil, validator: ResponseValidator.new)
+        @llm = llm
+        # SLICE-7: the provider/model fallback chain. When present, the live
+        # adapter for each attempt is the chain's CURRENT adapter (so a rotation
+        # takes effect on the very next call), and a fallback-worthy failure
+        # rotates it. Nil in tests/one-shot callers → behave as a fixed @llm.
+        @fallback_chain = fallback_chain
+        @config       = config
+        @ui           = ui
+        @event_bus    = event_bus
+        @cancel_token = cancel_token
+        @validator    = validator
+      end
+
+      # Run the inner retry loop for one model call. `request` is a built
+      # LLM::Request; an optional block forwards stream chunks straight through to
+      # the boundary (matching `@llm.call(request) { |chunk| }`). Returns a
+      # validated AdapterResponse, or raises EmptyModelResponseError / the
+      # classified API error.
+      #
+      # `iteration` is purely for the warning/telemetry text (which loop turn this
+      # call belongs to); it has no control-flow role.
+      def call!(request, iteration: nil, &)
+        # Error-path budget — distinct from the empty/degenerate budgets, which
+        # the recovery ladder owns (see #recovery). Kept here so a transient API
+        # error can't bleed into the empty-retry count.
+        error_attempts = 0
+
+        # The degenerate-response recovery ladder (Slice 5). Fresh per call! so
+        # its per-turn counters (prefill ≤2, empty ≤3) reset exactly where the
+        # reference zeroes them on a successful content turn.
+        recovery = recovery_for(iteration)
+
+        # The live request we (re)issue. Rungs 3/4 mutate it: a nudge appends to
+        # request.messages in place; a prefill re-issues with the seed attached.
+        current = request
+        # Visible text streamed to the user this call — fuels rung 1
+        # (partial-stream recovery). The caller's block still sees every chunk.
+        streamed = +""
+        wrapped  = capture_streamed(streamed, &)
+
+        # :recovered is thrown by the ladder's rung-1/2 ":use" directive — the
+        # recovered final content, wrapped as a synthetic text response.
+        catch(:recovered) do
+          loop do
+            @cancel_token&.check!
+
+            begin
+              response = active_llm.call(current, &wrapped)
+            rescue Rubino::Interrupted
+              # User cancellation propagates immediately — never classified, never
+              # retried (the reference treats interrupt as terminal at every backoff site).
+              raise
+            rescue StandardError => e
+              error_attempts = handle_error!(e, error_attempts, iteration)
+              next
+            end
+
+            # User cancellation that arrived MID-STREAM may not surface as a raise:
+            # once a chunk has flowed the adapter RETURNS the buffered (possibly
+            # empty) partial instead of raising, so a Ctrl+C right as the stream
+            # drained lands here as an "empty" response. Re-check the cancel token
+            # BEFORE validation so the interrupt is terminal — otherwise the empty
+            # partial is classified :empty_response and the recovery ladder prints
+            # a spurious "Empty response — retrying (1/2)" before the cancel is
+            # acknowledged (D4). The interrupt is the correct terminal outcome.
+            @cancel_token&.check!
+
+            ok, reason = @validator.valid?(response)
+
+            # Structurally invalid AND not an empty turn (nil / interrupted
+            # truncated-stream partial). SLICE-7 eager fallback:
+            # an invalid/malformed response is a common rate-limit symptom, so
+            # rotate to the next provider immediately rather than surfacing it as
+            # a failed turn. On a switch, reset the per-call counters and retry on
+            # the new adapter; otherwise hand it back untouched — the Loop maps it
+            # to StreamInterruptedError. Not the recovery ladder's job.
+            if !ok && reason != :empty_response
+              if activate_fallback!(iteration)
+                error_attempts = 0
+                recovery = recovery_for(iteration)
+                streamed.clear # partial belongs to the failed provider, not the new one
+                next
+              end
+              throw(:recovered, response)
+            end
+
+            # Usable iff structurally valid AND not degenerate (thinking-only /
+            # blank-after-think). A degenerate response passes #valid? (its content
+            # is non-empty <think> text) but carries no real answer — route it, and
+            # any 200-OK-but-empty turn, through the ladder.
+            throw(:recovered, response) if ok && !@validator.degenerate?(response)
+
+            current, switched = apply_recovery!(recovery, response, current, streamed, iteration)
+            # SLICE-7 rung 6: the ladder rotated to a fallback. Reset
+            # the per-call counters (fresh recovery, zeroed error budget) and retry
+            # on the new adapter — the reference zeroes _empty_content_retries here.
+            next unless switched
+
+            error_attempts = 0
+            recovery = recovery_for(iteration)
+            streamed.clear
+          end
+        end
+      end
+
+      private
+
+      # The degenerate/empty-response path (Slice 5). A response reached here is
+      # either 200-OK-but-empty or thinking-only — structurally present but with
+      # no real answer. Hand it to the DegenerateResponseRecovery ladder
+      # (conversation_loop.py:3903-4171) and act on the directive it returns:
+      #
+      #   :use     — the ladder recovered final content (partial-stream / prior
+      #              turn). Short-circuit the inner loop by raising back to the
+      #              caller? No — return it as a synthetic text response so the
+      #              Loop's normal text path persists and finishes the turn.
+      #   :nudge   — request.messages was mutated in place; re-issue unchanged.
+      #   :prefill — re-issue the SAME request carrying the assistant seed so the
+      #              model continues from its own reasoning into visible text.
+      #   :retry   — plain re-issue (with invalid-response backoff).
+      #   :raise   — empty-retries exhausted (rung 5 done). Rung 6 (SLICE-7)
+      #              attempts a provider/model fallback HERE before
+      #              the rung-7 terminal raise: on a switch, re-issue the SAME
+      #              request on the new adapter; only on exhaustion does it raise
+      #              EmptyModelResponseError.
+      #
+      # Returns [request, switched] — the request to issue on the next loop turn
+      # (for :nudge/:prefill/:retry, and for a rung-6 fallback), and whether a
+      # fallback was activated (so the caller resets its per-call counters). For
+      # :use it returns from the whole call! via a thrown result.
+      def apply_recovery!(recovery, response, request, streamed, iteration)
+        state = DegenerateResponseRecovery::RecoveryState.new(
+          response: response,
+          streamed_text: streamed.dup,
+          messages: request.messages,
+          prior_turn_content: nil,
+          prior_tools_all_housekeeping: false
+        )
+
+        directive = recovery.recover(state)
+
+        case directive.kind
+        when :use
+          throw(:recovered, synthetic_text_response(response, directive.content))
+        when :nudge
+          @event_bus.emit(Interaction::Events::MODEL_CALL_STARTED,
+                          iteration: iteration, empty_retry: true)
+          [request, false]
+        when :prefill
+          @event_bus.emit(Interaction::Events::MODEL_CALL_STARTED,
+                          iteration: iteration, prefill: true)
+          [with_prefill(request, directive.seed), false]
+        when :retry
+          @event_bus.emit(Interaction::Events::MODEL_CALL_STARTED,
+                          iteration: iteration, empty_retry: directive.attempt)
+          backoff.sleep(empty_backoff(directive.attempt))
+          [request, false]
+        else # :raise — rung 6 fallback, then rung 7 terminal
+          return [request, true] if activate_fallback!(iteration)
+
+          @ui.warning("Empty response from model — recovery exhausted")
+          raise Rubino::EmptyModelResponseError,
+                "model returned an empty/degenerate response (no usable text, " \
+                "no tool calls) on iteration #{iteration} after the recovery ladder " \
+                "was exhausted"
+        end
+      end
+
+      # A fresh recovery ladder per call!. Counters (prefill ≤2, empty ≤3) reset
+      # here so they behave per-turn, as the reference zeroes them on success.
+      def recovery_for(_iteration)
+        DegenerateResponseRecovery.new(
+          validator: @validator,
+          ui: @ui,
+          empty_max: empty_response_max_retries
+        )
+      end
+
+      # Re-issue the same request with the prefill seed attached. The Request is
+      # an immutable value object, so build a copy that carries everything the
+      # original did plus +prefill+. The adapter seats it as a trailing assistant
+      # message on the wire (RubyLLMAdapter#apply_prefill).
+      def with_prefill(request, seed)
+        LLM::Request.new(
+          messages: request.messages,
+          tools: request.tools,
+          temperature: request.temperature,
+          max_tokens: request.max_tokens,
+          thinking: request.thinking,
+          prefill: seed,
+          image_paths: request.image_paths,
+          stream: request.stream?
+        )
+      end
+
+      # Wrap the caller's stream block so we accumulate visible :content text for
+      # the partial-stream rung, while still forwarding every chunk untouched.
+      # When the caller passed no block (non-streaming turn), there is nothing to
+      # capture and nothing to forward.
+      def capture_streamed(buffer, &block)
+        return nil unless block
+
+        lambda do |chunk|
+          buffer << chunk[:text].to_s if chunk.is_a?(Hash) && chunk[:type] == :content
+          block.call(chunk)
+        end
+      end
+
+      # A synthetic text AdapterResponse carrying the ladder-recovered content,
+      # so the Loop's normal text-only path persists and finishes the turn. Token
+      # usage is copied from the degenerate response (the spend already happened).
+      def synthetic_text_response(response, content)
+        LLM::AdapterResponse.new(
+          content: content,
+          tool_calls: [],
+          input_tokens: response.input_tokens,
+          output_tokens: response.output_tokens,
+          model_id: response.model_id,
+          stop_reason: response.stop_reason
+        )
+      end
+
+      # Error-path retry. Classify; on a permanent error or an
+      # exhausted budget re-raise (with the adapter's auth hint when relevant);
+      # otherwise back off (honouring Retry-After) and let the loop retry.
+      #
+      # SLICE-7: the reference at max-retries tries `_try_activate_fallback()`,
+      # which RESETS retry_count to 0 and continues on the new backend. Before
+      # giving up on a permanent error or an exhausted budget, attempt a provider
+      # rotation; on a switch, zero the error budget so the new adapter gets a
+      # full set of retries (return 0 → the loop retries immediately).
+      def handle_error!(error, attempts, iteration)
+        classified = LLM::ErrorClassifier.classify(error)
+
+        unless classified.retryable && attempts < api_max_retries
+          return 0 if activate_fallback!(iteration)
+
+          raise_with_auth_hint(error, classified)
+        end
+
+        attempts += 1
+        wait = error_backoff(attempts, classified, error)
+        @event_bus.emit(Interaction::Events::MODEL_CALL_STARTED,
+                        iteration: iteration, error_retry: attempts)
+        log_safely(event: "llm.retry", attempt: attempts, sleep: wait, error: error.message)
+        backoff.sleep(wait)
+        attempts
+      end
+
+      # Jittered backoff for an invalid/empty response — 5s base, 120s cap,
+      # via the INVALID_RESPONSE preset.
+      def empty_backoff(attempt)
+        backoff.jittered(attempt, **BackoffPolicy::INVALID_RESPONSE)
+      end
+
+      # Jittered backoff for a transient API error — 2s base, 60s cap,
+      # honouring Retry-After on rate limits, with the
+      # overload window ridden out under a higher cap (matching the adapter's old
+      # backoff_cap_for: OVERLOADED/UNKNOWN get the bigger ceiling).
+      def error_backoff(attempt, classified, error)
+        cap = error_backoff_cap(classified)
+        backoff.wait_seconds(attempt, base: BackoffPolicy::ERROR_PATH[:base], max: cap,
+                                      retry_after: retry_after_for(classified, error))
+      end
+
+      def error_backoff_cap(classified)
+        overload = [LLM::FailoverReason::OVERLOADED, LLM::FailoverReason::UNKNOWN]
+        base = BackoffPolicy::ERROR_PATH[:max]
+        overload.include?(classified.reason) ? [base, overload_backoff_cap].max : base
+      end
+
+      # Retry-After to honour, only for rate limits. The header
+      # is reached off the typed error's Faraday response by BackoffPolicy.
+      def retry_after_for(classified, error)
+        return unless classified.reason == LLM::FailoverReason::RATE_LIMIT
+
+        backoff.parse_retry_after(error)
+      end
+
+      # Re-raise a non-retryable / budget-exhausted error, upgrading an auth error
+      # to the actionable "token may have expired" hint (parity with the adapter's
+      # former raise_with_auth_hint).
+      def raise_with_auth_hint(error, classified)
+        raise error unless classified.auth?
+
+        raise Rubino::Error,
+              "Authentication failed (#{error.message}). " \
+              "Token may have expired — re-run `rubino setup` or refresh your API key."
+      end
+
+      # The adapter to issue THIS attempt against. With a fallback chain wired,
+      # always the chain's current adapter (so a rotation takes effect on the
+      # next call); otherwise the fixed @llm. (SLICE-7)
+      def active_llm
+        @fallback_chain ? @fallback_chain.current_adapter : @llm
+      end
+
+      # Rotate to the next configured provider/model. Returns true if it switched
+      # (caller resets its counters and retries on the new adapter), false when
+      # exhausted, when no fallbacks are configured, or when no chain is wired —
+      # making the no-fallback case an inert no-op identical to pre-Slice-7. (SLICE-7)
+      def activate_fallback!(iteration)
+        return false unless @fallback_chain&.activate_next!
+
+        @event_bus.emit(Interaction::Events::MODEL_CALL_STARTED,
+                        iteration: iteration, fallback: true)
+        model = active_llm.respond_to?(:model_id) ? active_llm.model_id : nil
+        @ui.warning(["Switched to fallback model", model].compact.join(": "))
+        true
+      end
+
+      def backoff
+        @backoff ||= BackoffPolicy.new(cancel_token: @cancel_token)
+      end
+
+      def empty_response_max_retries
+        @config.dig("agent", "empty_response_max_retries") || 2
+      end
+
+      def api_max_retries
+        @config.dig("agent", "api_max_retries") || 0
+      end
+
+      def overload_backoff_cap
+        @config.dig("agent", "api_retry_backoff_overload_cap_seconds") || 60
+      end
+
+      def log_safely(**fields)
+        Rubino.logger.warn(**fields)
+      rescue StandardError
+        # Logger may be uninitialized during early boot — swallow.
+      end
+    end
+  end
+end

data/lib/rubino/agent/prompts/build.txt

@@ -0,0 +1,69 @@
+[Identity]
+You are rubino, a software engineering assistant running in the user's
+real environment. You read, edit, and run code with actual tool access —
+treat the file system, git, and the shell as production by default.
+
+[Principles]
+- Smallest change that solves the task. No speculative refactors, no
+  "while I'm here" cleanups, no abstractions for hypothetical futures.
+- Read before you write. Inspect a file with the read tool before editing
+  it. Search with grep/glob before guessing where something lives.
+- Verify your work. After editing, run the test, run the type checker, or
+  re-read the file. If you can't verify, say so explicitly.
+- Be honest. If a step failed, say it failed. If you're guessing, label it
+  as a guess. Never invent file paths, function names, or test results.
+- Root-cause, don't paper over. If something fails, understand why before
+  reaching for `--no-verify`, `rescue StandardError`, or skipping the
+  failing test.
+
+[Tool usage]
+- For file operations use the typed tools, not raw shell:
+  - Read a file with `read`, never with `cat`/`head`/`tail`.
+  - Edit a file with `edit`/`multi_edit`/`patch`, never with `sed`/`awk`.
+  - Search with `grep` or `glob`, never with raw `find` or shell pipelines.
+  - Write a new file with `write`. Don't `echo > file` from the shell.
+- To get the gist of a LARGE document (converted PDF, log, transcript —
+  more than a few hundred lines), use `summarize_file`, not `read`. It
+  map-reduces the file in a separate context and returns only the summary,
+  so the raw text never fills this conversation. Reach for `read` (with
+  offset/limit) or `grep` only when you need exact lines, not an overview.
+- For arbitrary code execution prefer `ruby` (sandboxed eval) over
+  `shell`. Use `shell` for binaries the host already provides.
+- When multiple tool calls are independent (no data dependency), issue
+  them in parallel — one message with several tool uses.
+- Cite files as `path/to/file.rb:42` so the user can jump straight to the
+  line you mean.
+
+[Delegation]
+- The `task` tool runs subagents in the BACKGROUND by default: it returns a
+  task id immediately and the subagent works in parallel. Do NOT block or
+  repeatedly poll — continue with other useful work. A `[background-task] …
+  completed` message arrives in the conversation when each subagent finishes;
+  treat it as new input and fold its result into your plan. You can run
+  several background subagents at once; check one early with `task_result` or
+  stop it with `task_stop`. Pass `background: false` only when the very next
+  step depends on the subagent's output.
+
+[Safety]
+- Destructive shell commands (`rm -rf`, `git push --force`, `git reset
+  --hard`, dropping tables) require explicit user confirmation. Do not
+  run them on your own initiative.
+- Some tool calls are gated by the user's approval policy. If a call is
+  denied, stop and explain what you wanted to do — never retry under a
+  different name to bypass the denial.
+- Don't introduce security issues (command injection, hard-coded
+  secrets, SQL string interpolation). If you spot one in code you're
+  touching, fix it.
+
+[Style]
+- Be concise. Plain prose for short answers, bullets only when there's a
+  real list. No headers for short replies.
+- Do not open with "Great", "Certainly", "Sure", "Of course". State what
+  you're about to do, then do it.
+- End your turn with one short sentence: what changed and what's next.
+- Don't add comments that restate the code. Only add a comment when the
+  *why* would surprise a future reader.
+
+[When in doubt]
+Ask one short question rather than guess. Don't ask if a sensible default
+exists — pick it and say what you picked.

data/lib/rubino/agent/prompts/compaction.txt

@@ -0,0 +1,20 @@
+[Identity]
+You are the compaction utility. You receive a long conversation and
+produce a structured summary that lets a fresh agent pick up where this
+one left off — without re-reading the original transcript.
+
+[Preserve, verbatim where possible]
+- The user's primary goal and any explicit constraints they restated.
+- Every file path you saw modified, with what changed and why.
+- Decisions and trade-offs the user accepted or rejected.
+- Errors, root causes, and the fix applied.
+- Unresolved questions and the next concrete step.
+
+[Drop]
+- Tool-call mechanics, retries, transient errors that were recovered.
+- Pleasantries and meta-discussion.
+
+[Format]
+Structured headings: Goal, Files touched, Decisions, Errors & fixes,
+Open questions, Next step. Be terse but complete — losing a file path or
+a decision is worse than being a few hundred tokens over budget.

data/lib/rubino/agent/prompts/explore.txt

@@ -0,0 +1,19 @@
+[Identity]
+You are explore, a fast read-only sub-agent. You answer locate-and-look
+questions about the codebase: "where is X defined", "which files reference
+Y", "what does Z do".
+
+[How to work]
+- Use `grep` and `glob` for the initial sweep, `read` only for the files
+  you actually need to quote from.
+- Issue independent searches in parallel (one message, multiple tool
+  calls). Do not serialise.
+- Stop as soon as the question is answered. Don't keep grepping for
+  completeness once you have the answer.
+
+[Output]
+- Concrete file paths with line numbers: `lib/foo/bar.rb:88`.
+- Quote at most ~5 lines of context per citation.
+- If you didn't find it, say "not found" and list where you looked —
+  don't invent a plausible location.
+- No preamble, no recap. Just the finding.

data/lib/rubino/agent/prompts/general.txt

@@ -0,0 +1,20 @@
+[Identity]
+You are a general-purpose sub-agent. You receive a single well-scoped
+task from the parent agent and return the result — not a conversation.
+
+[How to work]
+- Treat the prompt as the full brief; do not ask follow-up questions.
+  If a decision is genuinely under-specified, make the reasonable call
+  and note it in the output.
+- Use whatever tools the task needs: read/edit/write, shell, grep, git,
+  webfetch.
+- Issue independent tool calls in parallel.
+- Verify your work before returning (run the test, re-read the file).
+
+[Output]
+- Return raw, structured information. The parent agent reads this, not a
+  human — skip greetings, skip recap, skip "let me know if you need
+  more".
+- Cite file paths with line numbers. If you wrote files, list them.
+- If you couldn't complete the task, say so plainly and explain what
+  blocked you — don't fake success.

data/lib/rubino/agent/prompts/plan.txt

@@ -0,0 +1,31 @@
+[Identity]
+You are rubino in plan mode: a read-only technical analyst. You
+inspect codebases, design changes, and write step-by-step implementation
+plans — but you do not modify files or run destructive commands.
+
+[What to deliver]
+A plan a competent engineer could execute without re-reading the
+codebase. That means:
+- Concrete file paths and line numbers (`app/models/user.rb:42`).
+- The exact change: what gets added, removed, or moved. Show short
+  before/after snippets when the diff is non-obvious.
+- Order of operations, especially when one step unblocks another.
+- Risks and how to detect them (test you'd add, log you'd watch).
+
+[Investigation]
+- Read before you opine. Use `read`, `grep`, `glob` aggressively. If you
+  cite a function or constant, you have read its definition.
+- Cross-check assumptions. A grep hit is not proof of behaviour — open
+  the file.
+- When two designs are reasonable, present both with the trade-off in
+  one sentence, and recommend one.
+
+[Style]
+- Concise. No filler. No "Certainly, here is the plan…".
+- Plain prose for analysis, numbered steps for the executable plan.
+- Be honest about uncertainty. If you couldn't verify something, label
+  it `(unverified)` and say what you'd check next.
+
+You have read tools only. Refuse to edit files or run mutating shell
+commands — say "I'm in plan mode, that's outside my permissions" and
+hand the plan back so the user can switch to build mode.

data/lib/rubino/agent/response_validator.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module Rubino
+  module Agent
+    # Judges a single normalized AdapterResponse on two axes the conversation
+    # loop cares about, mirroring the reference validate_response
+    # and _has_content_after_think_block.
+    #
+    # Unlike the reference — which validates a raw provider object per api_mode and has
+    # to special-case codex/anthropic/bedrock/openai shapes — ruby_llm already
+    # raises typed errors for bad HTTP, so by the time a response reaches here it
+    # is the one normalized AdapterResponse shape. The validator therefore only
+    # judges that shape; there is no per-provider branching to port.
+    #
+    # Two questions, two methods:
+    #   #valid?      STRUCTURAL — is this a usable response at all? (not nil,
+    #                carries some text OR tool calls, not an interrupted partial)
+    #   #degenerate? SEMANTIC — a structurally valid text response that is
+    #                nonetheless useless: thinking-only (no real content after
+    #                the <think> block) or blank visible content.
+    class ResponseValidator
+      # #valid? returns [Boolean, reason]. `reason` is nil when valid, otherwise
+      # a symbol naming the structural defect (for warnings / future telemetry):
+      #   :nil_response   — no response object
+      #   :interrupted    — buffered partial from a truncated stream, not a turn
+      #   :empty_response — neither text nor tool calls
+      def valid?(response)
+        return [false, :nil_response] if response.nil?
+        return [false, :interrupted]  if response.interrupted?
+        return [true, nil]            if response.has_tool_calls?
+        return [false, :empty_response] if response.content.to_s.strip.empty?
+
+        [true, nil]
+      end
+
+      # True when a STRUCTURALLY valid text response carries no real answer:
+      # its visible content is empty once the <think> block is stripped (the
+      # model reasoned but never spoke). Mirrors the reference
+      # `not _has_content_after_think_block(content)`.
+      #
+      # Tool-call responses are never degenerate — the tool call IS the answer.
+      def degenerate?(response)
+        return false if response.nil? || response.interrupted?
+        return false if response.has_tool_calls?
+
+        !content_after_think_block?(response.content)
+      end
+
+      private
+
+      # Ruby mirror of the reference _has_content_after_think_block: strip the <think>
+      # reasoning and check whether any visible text survives. Reuses
+      # InlineThinkFilter (the same sentinel recogniser the stream path uses) by
+      # feeding the whole string once and flushing — we keep only the :content
+      # side, discarding :thinking. Scoped to <think> per Slice 2; the wider tag
+      # zoo (<reasoning>, tool-call XML, …) is not in play for this gem's models.
+      def content_after_think_block?(content)
+        return false if content.to_s.empty?
+
+        visible = +""
+        filter  = LLM::InlineThinkFilter.new
+        emit    = ->(type, text) { visible << text if type == :content }
+        filter.feed(content.to_s, &emit)
+        filter.flush(&emit)
+
+        !visible.strip.empty?
+      end
+    end
+  end
+end