rubino-agent 0.3.0

data/lib/rubino/llm/tool_bridge.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+require "ruby_llm"
+
+module Rubino
+  module LLM
+    # Wraps a Rubino::Tools::Base instance into a RubyLLM::Tool subclass
+    # so that ruby_llm can register it, serialize its schema to the LLM, and
+    # dispatch tool calls through our full execution pipeline.
+    #
+    # When a ToolExecutor is provided (always the case in production), tool
+    # execution goes through:
+    #   ApprovalPolicy → tool.call() → truncation → ToolCallRepository.record
+    #
+    # This ensures identical behavior regardless of LLM provider — there is
+    # now a single tool-execution path in the entire application.
+    module ToolBridge
+      # Returns a RubyLLM::Tool instance wrapping agent_tool.
+      def self.for(agent_tool, ui: nil, event_bus: nil, tool_executor: nil)
+        klass = bridge_class_for(agent_tool.name)
+        klass.new(agent_tool,
+                  ui: ui || Rubino.ui,
+                  event_bus: event_bus || Rubino.event_bus,
+                  tool_executor: tool_executor)
+      end
+
+      def self.bridge_class_for(tool_name)
+        @cache ||= {}
+        @cache[tool_name] ||= build_class(tool_name)
+      end
+
+      def self.build_class(tool_name)
+        klass = Class.new(::RubyLLM::Tool) do
+          define_method(:name) { tool_name }
+
+          define_method(:initialize) do |agent_tool, ui:, event_bus:, tool_executor:|
+            @agent_tool    = agent_tool
+            @ui            = ui
+            @event_bus     = event_bus
+            @tool_executor = tool_executor
+          end
+
+          define_method(:description) { @agent_tool.description }
+          define_method(:params_schema) { @agent_tool.input_schema }
+
+          define_method(:execute) do |**kwargs|
+            name = @agent_tool.name
+            args = kwargs.transform_keys(&:to_s)
+
+            if @tool_executor
+              # Full pipeline: approval check → tool.call → truncation → audit record
+              result = @tool_executor.execute(
+                name: name,
+                arguments: args,
+                call_id: nil
+              )
+              result.output
+            else
+              # Fallback: direct call (tests / one-shot mode without full Lifecycle)
+              @event_bus&.emit(Rubino::Interaction::Events::TOOL_STARTED, name: name)
+              @ui&.tool_started(name, arguments: args)
+
+              begin
+                output = @agent_tool.call(args)
+                result = Rubino::Tools::Result.success(
+                  name: name, call_id: nil, output: output.to_s
+                )
+                @event_bus&.emit(Rubino::Interaction::Events::TOOL_FINISHED, name: name)
+                @ui&.tool_finished(name, result: result)
+                result.output
+              rescue StandardError => e
+                @event_bus&.emit(Rubino::Interaction::Events::TOOL_FINISHED, name: name)
+                @ui&.tool_finished(name)
+                "Error: #{e.message}"
+              end
+            end
+          end
+        end
+
+        const_name = "Bridge_#{tool_name.gsub(/[^a-zA-Z0-9]/, "_")}"
+        unless Rubino::LLM::ToolBridge.const_defined?(const_name, false)
+          Rubino::LLM::ToolBridge.const_set(const_name, klass)
+        end
+
+        klass
+      end
+    end
+  end
+end

data/lib/rubino/logger.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require "json"
+require "logger"
+
+module Rubino
+  # Structured JSON-line logger with built-in redaction of sensitive fields.
+  #
+  #   Rubino.logger.info(event: "api.server.starting", port: 4820)
+  #   #=> {"ts":"2026-05-31T...","level":"info","event":"api.server.starting","port":4820}
+  #
+  # Each level method (#debug, #info, #warn, #error, #fatal) takes **fields
+  # and emits one structured line per call.
+  #
+  # Configuration via environment:
+  #   RUBINO_LOG_LEVEL  — debug|info|warn|error|fatal (default: info)
+  #   RUBINO_LOG_FORMAT — json|pretty                  (default: json)
+  #
+  # Redaction: any key whose name (case-insensitive) appears in REDACT_KEYS is
+  # replaced with REDACTED at any nesting depth before the line is serialized.
+  # This covers tokens, secrets, and raw Authorization headers passing through
+  # middleware logs.
+  class Logger
+    LEVELS = { debug: ::Logger::DEBUG, info: ::Logger::INFO, warn: ::Logger::WARN, error: ::Logger::ERROR,
+               fatal: ::Logger::FATAL }.freeze
+
+    # Keys (matched case-insensitively against String form) whose values are
+    # replaced with REDACTED before logging. Recursive — applies at any depth.
+    REDACT_KEYS = %w[
+      access_token refresh_token id_token
+      client_secret api_key password secret bearer
+      authorization http_authorization
+    ].freeze
+
+    # Replacement string written in place of redacted values.
+    REDACTED = "[REDACTED]"
+
+    def initialize(io: $stdout, level: ENV.fetch("RUBINO_LOG_LEVEL", "info"),
+                   format: ENV.fetch("RUBINO_LOG_FORMAT", "json"))
+      @logger = ::Logger.new(io)
+      @logger.level = LEVELS.fetch(level.to_sym, ::Logger::INFO)
+      @format = format.to_sym
+      @logger.formatter = formatter
+    end
+
+    # Rebinds the underlying sink to a new IO (or path) WITHOUT replacing the
+    # Logger object, so existing references (and the memoized Rubino.logger)
+    # keep working. Level and format are preserved.
+    #
+    # The interactive CLI uses this to route structured JSON lines to a file
+    # instead of the terminal $stdout that the raw-mode TUI owns (#125):
+    # otherwise a warn/info event (e.g. a network blip during a background
+    # subagent) prints raw JSON into the rendered conversation and corrupts the
+    # bottom-composer frame. Returns the previous IO so the caller can restore
+    # it on exit.
+    def reopen(io)
+      previous = @logger.instance_variable_get(:@logdev)&.dev
+      @logger.reopen(io)
+      previous
+    end
+
+    LEVELS.each_key do |level|
+      define_method(level) do |**fields|
+        @logger.public_send(level) { self.class.redact(fields) }
+      end
+    end
+
+    # Recursively walk a value, masking entries whose key matches REDACT_KEYS.
+    # Hash and Array are descended; scalars pass through unchanged.
+    # Public because middleware and tests call it directly.
+    #
+    # @param value [Object] any value (typically Hash, Array, or scalar)
+    # @return [Object] same shape as input with sensitive values replaced by REDACTED
+    def self.redact(value)
+      case value
+      when Hash
+        value.each_with_object({}) do |(k, v), out|
+          out[k] = REDACT_KEYS.include?(k.to_s.downcase) ? REDACTED : redact(v)
+        end
+      when Array
+        value.map { |v| redact(v) }
+      else
+        value
+      end
+    end
+
+    private
+
+    def formatter
+      if @format == :pretty
+        ->(severity, time, _progname, fields) { "[#{time.iso8601}] #{severity.downcase} #{fields.inspect}\n" }
+      else
+        lambda { |severity, time, _progname, fields|
+          "#{JSON.generate({ ts: time.iso8601, level: severity.downcase }.merge(fields))}\n"
+        }
+      end
+    end
+  end
+end

data/lib/rubino/mcp/manager.rb

@@ -0,0 +1,180 @@
+# frozen_string_literal: true
+
+require "ruby_llm/mcp"
+
+module Rubino
+  module MCP
+    # Manages multiple MCP client connections.
+    # Reads server definitions from config, starts clients,
+    # and registers their tools into the agent's tool registry.
+    class Manager
+      # clients: name => live RubyLLM::MCP client.
+      # last_errors: name => the most recent start failure message (cleared on a
+      # successful start) — the "why is my server missing?" answer /mcp's
+      # drill-in shows (#182).
+      attr_reader :clients, :last_errors
+
+      def initialize(config: nil)
+        @config = config || Rubino.configuration
+        @clients = {}
+        @last_errors = {}
+        route_mcp_logging!
+      end
+
+      # Initializes all configured MCP servers
+      def start_all!
+        server_configs = @config.dig("mcp", "servers") || {}
+
+        server_configs.each do |name, server_config|
+          start_server(name, server_config)
+        end
+
+        register_all_tools!
+        @clients
+      end
+
+      # Starts a single MCP server by name
+      def start_server(name, server_config)
+        transport = server_config["transport"] || "stdio"
+        client_opts = build_client_options(name, transport, server_config)
+
+        client = RubyLLM::MCP.client(**client_opts)
+        @clients[name.to_s] = client
+        @last_errors.delete(name.to_s)
+
+        Rubino.event_bus.emit(:mcp_server_started, name: name)
+        client
+      rescue StandardError => e
+        @last_errors[name.to_s] = e.message
+        Rubino.ui.warning("MCP server '#{name}' failed to start: #{e.message}")
+        nil
+      end
+
+      # Stops all MCP clients (deregistering their tools — see #stop_server).
+      # `keys.each`, NOT `each_key`: stop_server deletes from @clients, which
+      # would raise mid-iteration without the snapshot.
+      def stop_all!
+        @clients.keys.each { |name| stop_server(name) } # rubocop:disable Style/HashEachMethods
+      end
+
+      # Stops a specific MCP client AND deregisters its MCPToolWrapper
+      # instances from Tools::Registry (#182) — before, nothing ever
+      # unregistered them, so a stopped server left dead tools the model could
+      # still call.
+      def stop_server(name)
+        client = @clients.delete(name.to_s)
+        return nil unless client
+
+        deregister_tools(name.to_s)
+        begin
+          client.stop
+        rescue StandardError => e
+          Rubino.ui.warning("Error stopping MCP '#{name}': #{e.message}")
+        end
+        Rubino.event_bus.emit(:mcp_server_stopped, name: name)
+        client
+      end
+
+      # Registers all MCP tools into the agent's tool registry.
+      # Per-agent mcp_servers scoping is NOT applied here — it lives in
+      # Agent::Definition#resolved_tools (#173), the single seam every
+      # consumer of an agent's tool set goes through.
+      def register_all_tools!
+        @clients.each_key { |server_name| register_server_tools(server_name) }
+      end
+
+      # Registers ONE started server's tools — the `/mcp <server> on` path
+      # (#182) re-registers only that server instead of re-reading every
+      # client's tool list.
+      def register_server_tools(name)
+        client = @clients[name.to_s]
+        return unless client
+
+        client.tools.each do |mcp_tool|
+          wrapped = MCPToolWrapper.new(mcp_tool, server_name: name.to_s)
+          Tools::Registry.register(wrapped)
+        end
+      rescue StandardError => e
+        Rubino.ui.warning("Failed to load tools from '#{name}': #{e.message}")
+      end
+
+      # Checks health of all connected servers
+      def health_check
+        @clients.map do |name, client|
+          alive = begin
+            client.alive?
+          rescue StandardError
+            false
+          end
+          { name: name, alive: alive }
+        end
+      end
+
+      # Returns true if any MCP servers are configured
+      def configured?
+        servers = @config.dig("mcp", "servers")
+        servers.is_a?(Hash) && !servers.empty?
+      end
+
+      private
+
+      # Drops a stopped server's wrappers from the registry (keyed by the
+      # prefixed tool name, so only that server's entries match).
+      def deregister_tools(server_name)
+        Tools::Registry.all.each do |tool|
+          next unless tool.is_a?(MCPToolWrapper) && tool.server_name == server_name
+
+          Tools::Registry.unregister(tool.name)
+        end
+      end
+
+      # ruby_llm-mcp logs to $stdout by default — including every line the
+      # stdio server prints on ITS stderr (e.g. "Secure MCP Filesystem Server
+      # running on stdio"), relayed at INFO. That raw logger line pollutes
+      # one-shot `rubino prompt` output, doctor, tools and the chat banner
+      # (#174 — same class as the fixed #99). Route the gem's logger to a file
+      # under the resolved home, next to RUBYLLM_DEBUG's ruby_llm.log.
+      def route_mcp_logging!
+        log_path = File.join(Config::Loader.default_home_path, "logs", "mcp.log")
+        FileUtils.mkdir_p(File.dirname(log_path))
+        RubyLLM::MCP.config.logger = ::Logger.new(log_path, progname: "RubyLLM::MCP", level: ::Logger::INFO)
+      rescue StandardError
+        # Logging is never worth breaking MCP boot; worst case the gem keeps
+        # its default logger.
+        nil
+      end
+
+      def build_client_options(name, transport, server_config)
+        opts = {
+          name: name.to_s,
+          transport_type: transport.to_sym
+        }
+
+        case transport
+        when "stdio"
+          opts[:config] = {
+            command: server_config["command"],
+            args: server_config["args"] || [],
+            env: server_config["env"] || {}
+          }
+        when "sse"
+          opts[:config] = {
+            url: server_config["url"],
+            headers: server_config["headers"] || {}
+          }
+        when "streamable"
+          opts[:config] = {
+            url: server_config["url"],
+            headers: server_config["headers"] || {}
+          }
+          opts[:config][:oauth] = server_config["oauth"] if server_config["oauth"]
+        end
+
+        # Optional: request timeout
+        opts[:request_timeout] = server_config["timeout"] if server_config["timeout"]
+
+        opts
+      end
+    end
+  end
+end

data/lib/rubino/mcp/mcp_tool_wrapper.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+module Rubino
+  module MCP
+    # Wraps an MCP tool (from ruby_llm-mcp) into the Rubino::Tools::Base interface.
+    # This allows MCP tools to be used seamlessly alongside built-in tools.
+    class MCPToolWrapper < Tools::Base
+      attr_reader :mcp_tool, :server_name
+
+      def initialize(mcp_tool, server_name:)
+        @mcp_tool = mcp_tool
+        @server_name = server_name
+      end
+
+      def name
+        # Prefix with server name to avoid collisions
+        "#{@server_name}_#{@mcp_tool.name}"
+      end
+
+      def description
+        @mcp_tool.description
+      end
+
+      def input_schema
+        # The server-advertised JSON schema lives in RubyLLM::MCP::Tool#params_schema.
+        # The inherited RubyLLM::Tool#parameters DSL accessor is ALWAYS empty for
+        # MCP tools — forwarding it sent every tool to the model with `parameters:
+        # {}`, so the model had to guess argument names and every call failed
+        # server-side validation with -32602 (#170).
+        schema = @mcp_tool.params_schema if @mcp_tool.respond_to?(:params_schema)
+        schema || { type: "object", properties: {} }
+      end
+
+      def risk_level
+        # MCP tools are external, default to medium risk
+        :medium
+      end
+
+      def call(arguments)
+        result = @mcp_tool.execute(**symbolize_keys(arguments))
+        # ruby_llm-mcp reports tool failures by RETURNING `{ error: "…" }`
+        # instead of raising. Map both failure paths onto the registry's
+        # "Error: …" convention (Tools::Result#errorish?) so an errored MCP
+        # call renders ✗ like any built-in tool, not "✓ done" (#172).
+        error = result[:error] || result["error"] if result.is_a?(Hash)
+        return "Error: MCP tool #{@server_name}/#{@mcp_tool.name}: #{error}" if error
+
+        result.to_s
+      rescue StandardError => e
+        "Error: MCP tool #{@server_name}/#{@mcp_tool.name}: #{e.message}"
+      end
+
+      # Override to provide the raw MCP tool definition for LLM
+      def to_tool_definition
+        {
+          name: name,
+          description: description,
+          parameters: input_schema
+        }
+      end
+
+      private
+
+      def symbolize_keys(hash)
+        hash.transform_keys(&:to_sym)
+      end
+    end
+  end
+end

data/lib/rubino/mcp.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Rubino
+  # MCP (Model Context Protocol) integration module.
+  # Manages connections to MCP servers and exposes their tools
+  # to the agent via the standard Tools::Registry.
+  module MCP
+    class << self
+      # The shared, booted Manager (nil until boot! succeeds).
+      attr_reader :manager
+
+      # MCP is opt-in by configuration (#95): a non-empty `mcp.servers`
+      # block enables it; an explicit `mcp.enabled: false` switches it off
+      # without deleting the server definitions.
+      def enabled?(config = Rubino.configuration)
+        servers = config.dig("mcp", "servers")
+        return false unless servers.is_a?(Hash) && !servers.empty?
+
+        config.dig("mcp", "enabled") != false
+      end
+
+      # Boots the shared Manager once per process: connects to every
+      # configured server and registers their prefixed tools in
+      # Tools::Registry (#91). Best-effort — MCP is an optional
+      # integration and must never break boot, so any failure is a
+      # warning, not an error.
+      def boot!
+        return @manager if @manager
+        return nil unless enabled?
+
+        manager = Manager.new
+        manager.start_all!
+        @manager = manager
+      rescue StandardError => e
+        Rubino.ui.warning("MCP startup failed: #{e.message}")
+        nil
+      end
+
+      # `/mcp reload` (#182): stop every server (deregistering their tools),
+      # drop the memoized Manager, re-read config.yml fresh and boot again —
+      # so a server added to config becomes usable without restarting chat.
+      # Returns the new Manager, or nil when the re-read config leaves MCP
+      # disabled (no servers / mcp.enabled: false).
+      def reload!
+        @manager&.stop_all!
+        @manager = nil
+        Rubino.reload_configuration!
+        boot!
+      end
+
+      # Clears the booted Manager (used by tests).
+      def reset!
+        @manager = nil
+      end
+    end
+  end
+end

data/lib/rubino/memory/backend.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+module Rubino
+  module Memory
+    # Duck-typed contract for a pluggable memory backend.
+    #
+    # A backend owns the WRITE path (store / replace / forget / extract), the
+    # READ path the prompt assembler depends on (user_profile / project_context
+    # / retrieve), and the admin surface that powers `rubino memory ...`
+    # (list / find). The method set is the union of what the rest of the gem
+    # already calls today — extracting this interface is a mechanical refactor,
+    # not a rewrite.
+    #
+    # The injection-defense floor (ThreatScanner + the char-budget enforced in
+    # Memory::Store) lives in the shared write path, so no backend can splice
+    # tainted or over-budget content into a future system prompt. Concrete
+    # backends override only what they need; the base raises NotImplementedError
+    # for the operations that have no sensible default.
+    class Backend
+      # Backend registry key (e.g. "default"). Subclasses must override.
+      def self.backend_name
+        raise NotImplementedError, "#{self} must define .backend_name"
+      end
+
+      def initialize(config: nil)
+        @config = config || Rubino.configuration
+      end
+
+      # Deps present + configured (no network). Backends with optional
+      # dependencies override this; the default is always available.
+      def available?
+        true
+      end
+
+      # -- WRITE path --
+
+      # Persist one memory entry. Returns the stored row (Hash) or raises a
+      # Memory::Store::ThreatDetectedError / BudgetExceededError on refusal.
+      def store(kind:, content:, source_session_id: nil, confidence: 1.0, metadata: {})
+        raise NotImplementedError, "#{self.class} must implement #store"
+      end
+
+      # Replace the content of the first entry of `kind` whose content includes
+      # `old_text`. Returns the matched row, or nil if nothing matched.
+      def replace(kind:, old_text:, content:)
+        raise NotImplementedError, "#{self.class} must implement #replace"
+      end
+
+      # Delete the first entry of `kind` whose content includes `old_text`.
+      # Returns the matched row, or nil if nothing matched.
+      def forget(kind:, old_text:)
+        raise NotImplementedError, "#{self.class} must implement #forget"
+      end
+
+      # Mine a session's messages for durable facts and persist them.
+      # Returns the list of stored entries.
+      def extract(session_id)
+        raise NotImplementedError, "#{self.class} must implement #extract"
+      end
+
+      # -- READ path (consumed by lifecycle#load_memory -> PromptAssembler) --
+
+      # User-profile text (String) or nil.
+      def user_profile
+        raise NotImplementedError, "#{self.class} must implement #user_profile"
+      end
+
+      # Project-context text (String) or nil.
+      def project_context
+        raise NotImplementedError, "#{self.class} must implement #project_context"
+      end
+
+      # Memories relevant to the turn. `query` lets a relevance-aware backend
+      # rank by the last user message; the default backend ignores it and
+      # returns everything that fits, exactly as today. Returns an array of
+      # rows ([{id:, kind:, content:, ...}]).
+      def retrieve(session_id:, query: nil)
+        raise NotImplementedError, "#{self.class} must implement #retrieve"
+      end
+
+      # -- admin (powers `rubino memory list/show/delete`) --
+
+      # Live entries only by default; `include_retired: true` opts into the
+      # supersession history on backends that soft-retire (sqlite).
+      def list(kind: nil, limit: 20, include_retired: false)
+        raise NotImplementedError, "#{self.class} must implement #list"
+      end
+
+      def find(id)
+        raise NotImplementedError, "#{self.class} must implement #find"
+      end
+
+      def delete(id)
+        raise NotImplementedError, "#{self.class} must implement #delete"
+      end
+
+      # Total number of stored memories. Powers the CLI /status line and the
+      # web dashboard's memory card via GET /v1/memory/stats.
+      def count
+        raise NotImplementedError, "#{self.class} must implement #count"
+      end
+    end
+  end
+end

data/lib/rubino/memory/backends/default.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+module Rubino
+  module Memory
+    module Backends
+      # The default memory backend: a thin façade over the existing
+      # Store / Retriever / Extractor. Behavior is byte-identical to the
+      # pre-pluggable implementation — every call delegates to the same code
+      # paths (and therefore the same ThreatScanner + char-budget guards in
+      # Memory::Store) that the seams called directly before.
+      #
+      # Named "default" because it is SQLite-table-backed today but is the
+      # baseline every install gets unless `memory.backend` is changed.
+      class Default < Backend
+        def self.backend_name
+          "default"
+        end
+
+        def initialize(config: nil, store: nil, retriever: nil)
+          super(config: config)
+          @store = store || Store.new(config: @config)
+          @retriever = retriever || Retriever.new(store: @store, config: @config)
+        end
+
+        # -- WRITE path --
+
+        def store(kind:, content:, source_session_id: nil, confidence: 1.0, metadata: {})
+          @store.create(
+            kind: kind,
+            content: content,
+            source_session_id: source_session_id,
+            confidence: confidence,
+            metadata: metadata
+          )
+        end
+
+        def replace(kind:, old_text:, content:)
+          target = find_by_substring(kind, old_text)
+          return nil unless target
+
+          @store.update(target[:id], content: content)
+          target
+        end
+
+        def forget(kind:, old_text:)
+          target = find_by_substring(kind, old_text)
+          return nil unless target
+
+          @store.delete(target[:id])
+          target
+        end
+
+        def extract(session_id)
+          Extractor.new(store: @store).extract_from_session(session_id)
+        end
+
+        # -- READ path --
+
+        def user_profile
+          @retriever.user_profile
+        end
+
+        def project_context
+          @retriever.project_context
+        end
+
+        # `query` is accepted for contract compatibility but ignored — the
+        # default backend returns "everything that fits", exactly as today.
+        def retrieve(session_id:, query: nil)
+          @retriever.relevant_for_session(session_id)
+        end
+
+        # -- admin --
+
+        # The legacy store hard-deletes on replace — there are no retired
+        # rows, so `include_retired` is accepted for contract parity only.
+        def list(kind: nil, limit: 20, include_retired: false)
+          @store.list(kind: kind, limit: limit)
+        end
+
+        def find(id)
+          @store.find(id)
+        end
+
+        def delete(id)
+          @store.delete(id)
+        end
+
+        def count
+          @store.count
+        end
+
+        private
+
+        def find_by_substring(kind, needle)
+          @store.by_kind(kind, limit: 500).find { |m| m[:content].to_s.include?(needle.to_s) }
+        end
+      end
+    end
+  end
+end