rubino-agent 0.3.0

data/lib/rubino/tools/shell_tail_tool.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+module Rubino
+  module Tools
+    # Blocking variant of shell_output: waits up to `timeout` seconds for new
+    # bytes to arrive on a background shell, then returns them. Returns
+    # immediately if bytes are already buffered or if the process has exited.
+    #
+    # Lets an agent "follow" a long-running job (CI, build, watcher) without
+    # busy-polling shell_output. The polling itself is implemented internally
+    # as a short-interval loop on ShellRegistry.read_new — switching to a
+    # condition variable would shave ~50ms of jitter and is a refactor for
+    # later; for v1, 100ms polling under the agent's tool-call latency is
+    # invisible.
+    class ShellTailTool < Base
+      DEFAULT_TIMEOUT = 30
+      MAX_TIMEOUT     = 300
+      POLL_INTERVAL   = 0.1
+
+      def name
+        "shell_tail"
+      end
+
+      def description
+        "Follow a background shell — block until new stdout/stderr bytes " \
+          "arrive on its run_id, the process exits, or `timeout` seconds " \
+          "elapse. Default timeout #{DEFAULT_TIMEOUT}s (max #{MAX_TIMEOUT}s). " \
+          "Returns the new bytes plus a status header. Use for `tail -F`-style " \
+          "following; use shell_output for a one-shot read."
+      end
+
+      def input_schema
+        {
+          type: "object",
+          properties: {
+            run_id: { type: "string", description: "run_id from shell run_in_background:true" },
+            timeout: { type: "integer",
+                       description: "Max seconds to block (default #{DEFAULT_TIMEOUT}, max #{MAX_TIMEOUT})" }
+          },
+          required: %w[run_id]
+        }
+      end
+
+      def risk_level
+        :low
+      end
+
+      def call(arguments)
+        run_id  = arguments["run_id"] || arguments[:run_id]
+        timeout = (arguments["timeout"] || arguments[:timeout] || DEFAULT_TIMEOUT).to_i
+        timeout = timeout.clamp(1, MAX_TIMEOUT)
+
+        return "Error: run_id is required" if run_id.nil? || run_id.to_s.empty?
+
+        registry = ShellRegistry.instance
+        entry    = registry.find(run_id)
+        return "Error: no background shell with run_id=#{run_id}" unless entry
+
+        body     = ""
+        deadline = Time.now + timeout
+
+        loop do
+          body = registry.read_new(entry)
+          break unless body.empty?
+
+          # Process has exited and no bytes left to drain — return now with
+          # whatever the final status says.
+          break if registry.status(entry) != :running
+
+          # User pressed Ctrl+C during a tail. Don't keep blocking — return
+          # an empty body with a "cancelled" hint so the model can react.
+          if cancellation_requested?
+            return { output: tail_header(run_id, registry, entry, body, cancelled: true),
+                     error_code: :cancelled }
+          end
+
+          break if Time.now >= deadline
+
+          sleep POLL_INTERVAL
+        end
+
+        status    = registry.status(entry)
+        exit_code = registry.exit_code(entry)
+        registry.remove(run_id) unless status == :running
+
+        text = if body.empty?
+                 tail_header(run_id, registry, entry, body)
+               else
+                 "#{tail_header(run_id, registry, entry, body)}\n#{body}"
+               end
+        { output: text,
+          metrics: "#{body.bytesize}B · #{status}",
+          exit_code: exit_code,
+          error_code: tail_error_code(status, exit_code) }
+      end
+
+      private
+
+      def tail_header(run_id, registry, entry, body, cancelled: false)
+        status    = registry.status(entry)
+        exit_code = registry.exit_code(entry)
+        header    = "[#{run_id}] status=#{status}"
+        header << " exit=#{exit_code}" if exit_code
+        header << " (#{body.bytesize} new bytes)"
+        header << " (cancelled by user)" if cancelled
+        header << "\n(no new output before deadline)" if body.empty? && status == :running && !cancelled
+        header
+      end
+
+      def tail_error_code(status, exit_code)
+        return nil if %i[running completed].include?(status)
+        return :exit_nonzero if exit_code && exit_code != 0
+
+        :shell_error
+      end
+    end
+  end
+end

data/lib/rubino/tools/shell_tool.rb

@@ -0,0 +1,330 @@
+# frozen_string_literal: true
+
+require "open3"
+
+module Rubino
+  module Tools
+    # Executes shell commands.
+    #
+    # Modes:
+    #   - foreground (default): blocks until exit or `timeout` seconds, then
+    #     SIGTERMs the process group and returns whatever was captured.
+    #   - background (`run_in_background: true`): registers the process with
+    #     ShellRegistry, returns a run_id immediately. Read its output later
+    #     with `shell_output`, terminate it with `shell_kill`.
+    #
+    # Gatekeeping (allowlist, deny rules, approval prompts) lives in
+    # Security::ApprovalPolicy and is enforced by the ToolExecutor before we
+    # get here — this class only runs the command and resolves cwd.
+    #
+    # As defense-in-depth, #call re-checks the command against the hardline
+    # blocklist (Security::HardlineGuard — the single source of truth, also
+    # used by ApprovalPolicy). yolo skips approvals by design, but the point
+    # of yolo is "trust the model to move fast", not "let it wipe the root
+    # filesystem if it confuses paths" — so catastrophic, unrecoverable
+    # commands are refused here even if the policy was somehow bypassed.
+    class ShellTool < Base
+      DEFAULT_TIMEOUT = 120
+      MAX_TIMEOUT     = 600
+
+      # 128 + SIGPIPE(13): under `pipefail`, a benign early-exit consumer
+      # (`cmd | head -1`) makes an upstream stage report SIGPIPE and the
+      # pipeline returns 141 even though nothing actually went wrong.
+      SIGPIPE_EXIT = 141
+
+      # Single decision point for "does this exit code count as success?".
+      # Used by both the [Exit code: …] suffix and the ✓/✗ presentation
+      # (via shell_error_code → Result#errorish?) so the two can't drift.
+      def self.success_exit?(code)
+        code.zero? || code == SIGPIPE_EXIT
+      end
+
+      def name
+        "shell"
+      end
+
+      def description
+        "Execute a shell command. " \
+          "Foreground: blocks until the command exits or `timeout` seconds elapse " \
+          "(default #{DEFAULT_TIMEOUT}s, max #{MAX_TIMEOUT}s). " \
+          "Background: pass `run_in_background: true` to fire-and-forget; the tool " \
+          "returns a run_id. Use the `shell_output` tool to read its stdout/stderr, " \
+          "`shell_input` to answer an interactive prompt it emits (Y/N, menu), " \
+          "and `shell_kill` to terminate it."
+      end
+
+      def input_schema
+        {
+          type: "object",
+          properties: {
+            command: {
+              type: "string",
+              description: "The shell command to execute"
+            },
+            cwd: {
+              type: "string",
+              description: "Working directory (defaults to current)"
+            },
+            timeout: {
+              type: "integer",
+              description: "Foreground timeout in seconds (default #{DEFAULT_TIMEOUT}, max #{MAX_TIMEOUT}). Ignored when run_in_background is true."
+            },
+            run_in_background: {
+              type: "boolean",
+              description: "If true, start the command detached and return a run_id immediately."
+            }
+          },
+          required: %w[command]
+        }
+      end
+
+      def risk_level
+        :high
+      end
+
+      def call(arguments)
+        command    = arguments["command"]           || arguments[:command]
+        cwd        = arguments["cwd"]               || arguments[:cwd]
+        background = arguments["run_in_background"] || arguments[:run_in_background] || false
+        timeout    = arguments["timeout"]           || arguments[:timeout] || DEFAULT_TIMEOUT
+        timeout    = [[timeout.to_i, 1].max, MAX_TIMEOUT].min
+
+        return "Error: command is required" if command.nil? || command.to_s.empty?
+
+        if (denied = destructive_pattern_match(command))
+          return { output: "Error: refusing to run #{denied} — this is hardcoded as " \
+                           "destructive and not overridable by --yolo. " \
+                           "If you genuinely need this, run it manually outside the agent.",
+                   error_code: :denied_command }
+        end
+
+        working_dir = resolve_cwd(cwd)
+        return "Error: cannot access working directory: #{cwd.inspect}" unless working_dir
+
+        if background
+          spawn_background(command, working_dir)
+        else
+          run = execute_foreground(command, working_dir, timeout)
+          # exit_code / timed_out / cancelled are surfaced as structured
+          # keys so downstream code (and the model) doesn't have to parse
+          # `[Exit code: N]` out of free-form text to know whether the
+          # command succeeded. The text suffix stays for visual continuity
+          # in the scrollback and for tests that grep for it.
+          { output: run[:text],
+            metrics: foreground_metric(run),
+            body: Util::Output.preview(run[:text]),
+            body_kind: :plain,
+            exit_code: run[:exit_code],
+            timed_out: run[:timed_out],
+            cancelled: run[:cancelled],
+            error_code: shell_error_code(run) }
+        end
+      end
+
+      def shell_error_code(run)
+        return :timeout       if run[:timed_out]
+        return :cancelled     if run[:cancelled]
+        return :shell_error   if run[:shell_error]
+        return :exit_nonzero  if run[:exit_code] && !self.class.success_exit?(run[:exit_code])
+
+        nil
+      end
+
+      # One-liner for the `done · shell` header. Reads the structured run
+      # fields directly — no regex archaeology on the text suffix.
+      def foreground_metric(run)
+        status = if run[:timed_out]            then "timeout"
+                 elsif run[:cancelled]         then "cancelled"
+                 elsif run[:shell_error]       then "shell error"
+                 elsif run[:exit_code].nil?    then "no exit"
+                 elsif run[:exit_code].zero?   then "exit 0"
+                 else                               "exit #{run[:exit_code]}"
+                 end
+        "#{status} · #{format_ms(run[:duration_ms])}"
+      end
+
+      def format_ms(ms)
+        if ms < 1000      then "#{ms}ms"
+        elsif ms < 60_000 then "#{(ms / 1000.0).round(1)}s"
+        else
+          mins, rem = ms.divmod(60_000)
+          "#{mins}m#{(rem / 1000.0).round}s"
+        end
+      end
+
+      private
+
+      # Defense-in-depth: the ApprovalPolicy already denies hardline commands
+      # before we get here, but the tool re-checks against the SAME single
+      # source (Security::HardlineGuard) so a future caller that bypasses the
+      # policy still can't wipe the host. No divergent inline list.
+      def destructive_pattern_match(command)
+        Security::HardlineGuard.block_reason(command)
+      end
+
+      # Resolves cwd via realpath so symlinks and "../" are fully expanded;
+      # returns nil if the directory does not exist or is unreadable.
+      def resolve_cwd(cwd)
+        candidate = cwd || Rubino::Workspace.primary_root
+        path = File.realpath(File.expand_path(candidate))
+        File.directory?(path) ? path : nil
+      rescue Errno::ENOENT, Errno::EACCES, Errno::ELOOP
+        nil
+      end
+
+      def spawn_background(command, cwd)
+        entry = ShellRegistry.instance.spawn(command: command, cwd: cwd)
+        "Started background shell #{entry.id} (pid #{entry.pid})\n  " \
+          "command: #{command}\n  " \
+          "cwd:     #{cwd}\n" \
+          "Read output:  shell_output run_id=#{entry.id}\n" \
+          "Send input:   shell_input  run_id=#{entry.id} text=...\n" \
+          "Terminate:    shell_kill   run_id=#{entry.id}"
+      rescue StandardError => e
+        "Error starting background shell: #{e.message}"
+      end
+
+      # Runs in its own process group so we can SIGTERM the whole subtree on
+      # timeout (a bare `kill pid` would leave child processes orphaned).
+      # Returns a structured hash — the wrapper builds the model-facing text
+      # from the same data, keeping the parse path single-sourced.
+      def execute_foreground(command, cwd, timeout)
+        rd = nil
+        rd, wr = IO.pipe
+        # bash -o pipefail (instead of bare `/bin/sh -c`) so a crash in the
+        # MIDDLE of a pipeline surfaces as the pipeline's exit status instead
+        # of being masked by an innocuous last stage (#156).
+        pid = Process.spawn("bash", "-o", "pipefail", "-c", command,
+                            chdir: cwd, pgroup: true, out: wr, err: wr)
+        pgid = pid
+        wr.close
+
+        # Drain the merged stdout+stderr pipe line-by-line so each chunk can
+        # be streamed to the UI/event stream as the subprocess writes it,
+        # not just at end-of-command. The accumulated string is still the
+        # canonical model-facing output. `each_line` only yields on \n or
+        # EOF, so a process emitting unterminated progress (`\r`-only) will
+        # still buffer until newline — acceptable for v1; live progress
+        # bars are a separate problem.
+        output_buf = +""
+        output_thr = Thread.new do
+          begin
+            rd.each_line do |line|
+              output_buf << line
+              emit_chunk(line)
+            end
+          rescue IOError, Errno::EBADF
+            # pipe closed under us — process exited
+          ensure
+            rd.close unless rd.closed?
+          end
+          output_buf
+        end
+        started_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+        begin
+          deadline = Time.now + timeout
+          status   = nil
+          loop do
+            wpid, status = Process.waitpid2(pid, Process::WNOHANG)
+            break if wpid
+
+            if cancellation_requested?
+              terminate_group(pgid)
+              sleep 0.5
+              begin
+                Process.kill("KILL", -pgid)
+              rescue StandardError
+                nil
+              end
+              begin
+                Process.waitpid2(pid)
+              rescue StandardError
+                nil
+              end
+              return foreground_result(
+                stdout: output_thr.value,
+                suffix: "[Command cancelled by user — SIGTERM sent]",
+                cancelled: true,
+                duration_ms: elapsed_ms(started_at)
+              )
+            end
+
+            if Time.now >= deadline
+              terminate_group(pgid)
+              _, status = Process.waitpid2(pid, Process::WNOHANG)
+              unless status
+                sleep 2
+                _, status = Process.waitpid2(pid, Process::WNOHANG)
+              end
+              unless status
+                begin
+                  Process.kill("KILL", -pgid)
+                rescue StandardError
+                  nil
+                end
+                _, status = Process.waitpid2(pid)
+              end
+              return foreground_result(
+                stdout: output_thr.value,
+                suffix: "[Command timed out after #{timeout}s — SIGTERM sent]",
+                timed_out: true,
+                duration_ms: elapsed_ms(started_at)
+              )
+            end
+            sleep 0.05
+          end
+
+          code = status&.exitstatus
+          foreground_result(stdout: output_thr.value,
+                            suffix: exit_suffix(code),
+                            exit_code: code,
+                            duration_ms: elapsed_ms(started_at))
+        rescue Errno::ECHILD
+          foreground_result(stdout: output_thr.value,
+                            duration_ms: elapsed_ms(started_at))
+        end
+      rescue StandardError => e
+        { text: "Shell error: #{e.message}", exit_code: nil, timed_out: false,
+          cancelled: false, shell_error: true, duration_ms: 0 }
+      ensure
+        rd.close if rd && !rd.closed?
+      end
+
+      # nil for a clean exit; an honest [Exit code: N] otherwise. 141 keeps
+      # the real code in the text but carries the SIGPIPE note so neither
+      # the human nor the model reads it as a failure.
+      def exit_suffix(code)
+        return nil if code.nil? || code.zero?
+
+        if code == SIGPIPE_EXIT
+          "[Exit code: #{code} — SIGPIPE: downstream consumer closed early; treated as success]"
+        else
+          "[Exit code: #{code}]"
+        end
+      end
+
+      def foreground_result(stdout:, duration_ms:, suffix: nil,
+                            exit_code: nil, timed_out: false, cancelled: false)
+        text = stdout.to_s
+        text = "#{text}\n#{suffix}" if suffix
+        { text: text,
+          exit_code: exit_code,
+          timed_out: timed_out,
+          cancelled: cancelled,
+          shell_error: false,
+          duration_ms: duration_ms }
+      end
+
+      def elapsed_ms(started_at)
+        ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - started_at) * 1000).round
+      end
+
+      def terminate_group(pgid)
+        Process.kill("TERM", -pgid)
+      rescue Errno::ESRCH, Errno::EPERM
+        # Already dead or not ours — fine.
+      end
+    end
+  end
+end

data/lib/rubino/tools/steer_tool.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+module Rubino
+  module Tools
+    # steer — the MODEL-callable parent->child steering note (S2). The model
+    # counterpart of the human `/agents <id> steer "..."` affordance: a parent
+    # agent parks a note onto one of ITS OWN running children; the note is folded
+    # into that child's context at its next turn boundary (Loop#inject_steered_input
+    # via the child's steer_queue) and PERSISTS — it changes the child's
+    # trajectory, unlike the ephemeral `probe`.
+    #
+    # SCOPED AT CALL (the S1 correction): steer is registered for ALL agents and
+    # authorized by OWNERSHIP at call time. The caller is the thread-local
+    # Rubino.current_subagent_id (nil ⇒ the human / top-level agent). The target
+    # must be the caller's OWN DIRECT child (BackgroundTasks.owned_by?), so a node
+    # with no children simply gets a "not your child" error. This tool does NOT
+    # touch the human CLI path (executor.rb's steer_agent stays unscoped) and is
+    # NOT on any strip list.
+    #
+    # Mechanism reuse: it wraps BackgroundTasks#steer verbatim (the SAME wire the
+    # human CLI uses) — no new transport, no new state.
+    class SteerTool < Base
+      def name
+        "steer"
+      end
+
+      # Gated by the same `tools.task` delegation key — steering a child is
+      # meaningless without the delegation substrate. Disabling delegation
+      # disables steer too.
+      def config_key
+        "task"
+      end
+
+      def description
+        "Steer one of YOUR OWN running subagents: park a short note that is " \
+          "folded into that child's context at its NEXT turn (it persists and " \
+          "changes what the child does). Use it to course-correct a child you " \
+          "started — add a constraint, narrow the scope, flag something it missed. " \
+          "You can ONLY steer subagents you started (your direct children); you " \
+          "cannot steer yourself, a sibling, or a finished child. The note is " \
+          "queued, not delivered instantly — the child sees it between turns."
+      end
+
+      def input_schema
+        {
+          type: "object",
+          properties: {
+            task_id: { type: "string", description: "The id (sa_…) of YOUR running subagent to steer." },
+            note: { type: "string",
+                    description: "The steering note to fold into the child's next turn. Keep it short and self-contained." }
+          },
+          required: %w[task_id note]
+        }
+      end
+
+      # Steering a child is a low-risk, non-destructive nudge (the child carries
+      # its own approval/risk gates for anything it does next).
+      def risk_level
+        :low
+      end
+
+      def call(arguments)
+        task_id = (arguments["task_id"] || arguments[:task_id]).to_s.strip
+        note    = (arguments["note"]    || arguments[:note]).to_s.strip
+        return "Error: note is required" if note.empty?
+
+        caller_id = Rubino.current_subagent_id
+        registry  = BackgroundTasks.instance
+        entry     = task_id.empty? ? nil : registry.find(task_id)
+
+        # No such id at all → it is not a steerable running subagent.
+        return "Cannot steer #{task_id} — no such running subagent." unless entry
+        # Self-steer is meaningless and would loop a note into your own context.
+        return "Error: cannot steer yourself." if task_id == caller_id
+        # Ownership: only a DIRECT child of the caller may be steered.
+        unless registry.owned_by?(caller_id, task_id)
+          return "Error: #{task_id} is not one of your subagents — you can only steer children you started."
+        end
+        # A finished child has no live loop to fold the note into.
+        return "Cannot steer #{task_id} — it already finished (#{entry.status})." unless live?(entry.status)
+
+        # Wraps the SAME wire the human CLI uses. A false here means the child's
+        # queue vanished between checks (a just-finished child) — treat as gone.
+        return "Cannot steer #{task_id} — no such running subagent." unless registry.steer(task_id, note)
+
+        # A child parked on a BLOCKING ask_parent has no next turn until the ask
+        # is answered — the note IS queued (deliver-on-unblock), but saying
+        # "enters child context next turn" would let the parent believe the
+        # redirect took effect (#198). Be honest and point at the one action
+        # that unblocks the child.
+        if parked_on_ask?(entry)
+          return "steer ▸ #{task_id} ← #{Rubino::Util::Output.elide(note, 80)}  (queued — but #{task_id} is BLOCKED " \
+                 "on ask_parent and will NOT see it until you answer its question: " \
+                 "#{Rubino::Util::Output.elide(entry.ask_question, 120)} — unblock it with " \
+                 "answer_child(task_id: \"#{task_id}\", answer: \"…\"))"
+        end
+
+        "steer ▸ #{task_id} ← #{Rubino::Util::Output.elide(note, 80)}  (parked · enters child context next turn)"
+      end
+
+      private
+
+      # Mirrors BackgroundTasks#live_status? — a child still holds a loop (its
+      # thread is alive) while running, awaiting approval, or blocked on an
+      # escalated ask_parent (waiting on the human OR on its agent-parent).
+      def live?(status)
+        %i[running needs_approval blocked_on_human blocked_on_parent].include?(status)
+      end
+
+      # True when the child's thread is PARKED on a blocking ask_parent gate (a
+      # non-blocking ask keeps working, so its steer is consumable as normal).
+      def parked_on_ask?(entry)
+        entry.ask_gate && entry.ask_blocking &&
+          %i[blocked_on_human blocked_on_parent].include?(entry.status)
+      end
+    end
+  end
+end

data/lib/rubino/tools/subagent_probe.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+require_relative "../llm/adapter_factory"
+
+module Rubino
+  module Tools
+    # probe — the parent\'s EPHEMERAL read-only peek into a running subagent (the
+    # second mechanism of the parent<->subagent comm design).
+    #
+    # Unlike `steer` (a persisted note that changes the child\'s trajectory),
+    # `probe` is read-only and DISCARDED: it takes a SNAPSHOT of the child\'s
+    # current messages, runs ONE side-inference ([child messages] + question) on
+    # the child\'s own model, and returns the answer to the parent. Nothing is
+    # appended to the child\'s history, the child\'s loop is never touched, and
+    # the Q&A never enters the timeline — so a probe can never alter what the
+    # subagent does. The cost is one extra model round-trip that is billed but
+    # thrown away (keep probes short).
+    #
+    # Reuse: the snapshot is just Session::Store#for_session on the child\'s own
+    # session id (the child Runner exposes #session); the inference is a one-shot
+    # AdapterFactory.build(...).chat — the SAME adapter seam Lifecycle and the
+    # auxiliary client use. No new transport, no shared state.
+    class SubagentProbe
+      # The instruction prepended to the one-shot so the child\'s model answers AS
+      # the subagent, from its context-so-far, without trying to continue the task.
+      PREAMBLE = "You are the subagent above. Answer the following question from " + "your current context ONLY — do not take any action or continue " + "your task; this is a read-only check. Be brief."
+
+      # @param adapter_factory [#call] test seam: a callable taking the resolved
+      #   model id and returning an LLM adapter (anything responding to #chat).
+      #   Defaults to the real AdapterFactory.build for the child\'s model.
+      def initialize(adapter_factory: nil, message_store: nil)
+        @adapter_factory = adapter_factory
+        @message_store   = message_store
+      end
+
+      # Runs the ephemeral peek and returns the answer string. Best-effort: any
+      # failure (no session yet, model error) returns a short diagnostic rather
+      # than raising — a probe must never break the parent REPL.
+      def peek(entry:, question:)
+        snapshot = snapshot_messages(entry)
+        messages = [{ role: "user", content: PREAMBLE }] + snapshot +
+                   [{ role: "user", content: question.to_s }]
+
+        adapter  = build_adapter(entry)
+        response = adapter.chat(messages: messages)
+        text     = response.respond_to?(:content) ? response.content.to_s : response.to_s
+        text.strip.empty? ? "(no answer)" : text.strip
+      rescue StandardError => e
+        "(probe failed: #{e.message})"
+      end
+
+      private
+
+      # The child\'s current transcript as plain {role:, content:} text messages.
+      # Tool/assistant rows with no textual content are dropped (the peek only
+      # needs the readable context, not the tool_use/result wiring), so the
+      # snapshot is a clean prompt the one-shot model can answer from.
+      def snapshot_messages(entry)
+        session = entry.runner&.session
+        return [] unless session && session[:id]
+
+        store.for_session(session[:id]).filter_map do |m|
+          c = m.content.to_s
+          next if c.strip.empty?
+
+          { role: normalize_role(m.role), content: c }
+        end
+      end
+
+      # Map persisted roles to the chat roles the adapter expects; a `tool` row
+      # becomes a user-visible context line (its content is the tool output).
+      def normalize_role(role)
+        %w[user assistant].include?(role.to_s) ? role.to_s : "user"
+      end
+
+      def store
+        @message_store ||= Session::Store.new
+      end
+
+      def build_adapter(entry)
+        model = (entry.runner.respond_to?(:model_id) ? entry.runner.model_id : nil) if entry.runner
+        model ||= Rubino.configuration.model_default
+        return @adapter_factory.call(model) if @adapter_factory
+
+        LLM::AdapterFactory.build(model_id: model, config: Rubino.configuration)
+      end
+    end
+  end
+end