rubino-agent 0.3.0

data/lib/rubino/cli/memory_command.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+require "thor"
+
+module Rubino
+  module CLI
+    # Subcommands for managing persistent memories
+    class MemoryCommand < Thor
+      # Clean `tree`/help label instead of the underscored class-name default (F12).
+      namespace "rubino memory"
+
+      def self.exit_on_failure?
+        true
+      end
+
+      desc "list", "List stored memories (live facts only; --all includes superseded)"
+      option :kind, type: :string, desc: "Filter by memory kind"
+      option :limit, type: :numeric, default: 20, desc: "Max results"
+      option :all, type: :boolean, default: false,
+                   desc: "Include superseded (soft-retired) facts"
+      def list
+        Rubino.ensure_database_ready!
+        memories = backend_store.list(kind: options[:kind], limit: options[:limit],
+                                      include_retired: options[:all])
+
+        if memories.empty?
+          Rubino.ui.info("No memories found.")
+          return
+        end
+
+        rows = memories.map do |m|
+          [m[:id][0..7], m[:kind], "#{m[:content][0..60]}#{self.class.retired_marker(m)}", m[:created_at]]
+        end
+
+        Rubino.ui.table(
+          headers: %w[ID Kind Content Created],
+          rows: rows
+        )
+      end
+
+      desc "show ID", "Show a specific memory"
+      def show(id)
+        memory = backend_store.find(id)
+
+        if memory.nil?
+          Rubino.ui.error("memory not found: #{id}")
+          return
+        end
+
+        self.class.render(memory, ui: Rubino.ui)
+      end
+
+      # ONE fact-details rendering for both surfaces (#184): the CLI verb
+      # above and the in-chat `/memory show <id>` (Commands::Executor).
+      def self.render(memory, ui:)
+        ui.info("ID: #{memory[:id]}")
+        ui.info("Kind: #{memory[:kind]}")
+        ui.info("Confidence: #{memory[:confidence]}")
+        ui.info("Created: #{memory[:created_at]}")
+        # The temporal chain (#88): a soft-retired fact shows when it stopped
+        # being true and which fact replaced it.
+        if memory[:valid_to]
+          ui.info("Retired: #{memory[:valid_to]}")
+          ui.info("Superseded by: #{memory[:superseded_by]}") if memory[:superseded_by]
+        end
+        ui.separator
+        ui.info(memory[:content])
+      end
+
+      desc "delete ID", "Delete a specific memory"
+      def delete(id)
+        if backend_store.delete(id)
+          Rubino.ui.success("Memory deleted: #{id}")
+        else
+          Rubino.ui.error("memory not found: #{id}")
+        end
+      end
+
+      desc "backend [NAME]", "Show the active memory backend, or switch to NAME"
+      def backend(name = nil)
+        return show_backend if name.nil?
+
+        unless Memory::Backends.registered?(name)
+          Rubino.ui.error(
+            "Unknown memory backend: #{name}. Available: #{Memory::Backends.names.join(", ")}"
+          )
+          return
+        end
+
+        Config::Writer.new(config_path: config_path).set("memory.backend", name)
+        Rubino.ui.success("memory.backend = #{name}")
+      end
+
+      # `--all` surfaces soft-retired rows next to live ones; without a flag
+      # they were indistinguishable and the supersession chain needed a `show`
+      # per id (#161). Marks a tombstone with its retirement date and, when
+      # known, the short id of the fact that replaced it. A class method so the
+      # in-chat `/memory --all` table (#184) speaks the same dialect.
+      def self.retired_marker(memory)
+        return "" unless memory[:valid_to]
+
+        marker = " (retired #{memory[:valid_to][0..9]}"
+        marker += " → #{memory[:superseded_by][0..7]}" if memory[:superseded_by]
+        "#{marker})"
+      end
+
+      # ONE backend summary for both surfaces (#184): the CLI `memory backend`
+      # verb and the in-chat `/memory backend`.
+      def self.render_active_backend(ui:)
+        active = Rubino.configuration.dig("memory", "backend") || Memory::Backends::DEFAULT_NAME
+        ui.info("Active backend: #{active}")
+        ui.info("Available: #{Memory::Backends.names.join(", ")}")
+      end
+
+      private
+
+      # Resolve the *configured* memory backend (default: sqlite tiny-Zep), the
+      # same store the agent loop, the in-chat `/memory` view and the HTTP
+      # `/v1/memory` ops use. The old `Memory::Store.new` was hardwired to the
+      # legacy `:memories` table and ignored `memory.backend`, so list/show/delete
+      # never saw the facts the agent actually persists (#94).
+      def backend_store
+        @backend_store ||= Memory::Backends.build
+      end
+
+      def show_backend
+        self.class.render_active_backend(ui: Rubino.ui)
+      end
+
+      def config_path
+        Config::Loader.new.config_path
+      end
+    end
+  end
+end

data/lib/rubino/cli/onboarding_wizard.rb

@@ -0,0 +1,207 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module Rubino
+  module CLI
+    # First-run onboarding (#93). A small, skippable interactive wizard that
+    # takes a brand-new user from an empty home to a working model: pick a
+    # provider/model, paste the key (written to .env, never echoed back), and
+    # persist the matching model.default / model.provider / providers.<name>
+    # block to config.yml. The catalog mirrors DOCS-BLUEPRINT models-and-keys.
+    #
+    # It is only invoked when no usable credential is configured AND we are on a
+    # real TTY (ChatCommand#ensure_model_configured!); non-interactive contexts
+    # get the actionable guidance instead. #run returns true on a completed
+    # setup, false if the user skipped — the caller re-checks usability either
+    # way, so a partial/declined run safely falls through to the guidance+exit.
+    class OnboardingWizard
+      # Each provider: the model.provider to write, a default model id, the .env
+      # key var, and any providers.<name> config block to persist. Ordered so the
+      # recommended default comes first and matches the seeded config default
+      # (config/defaults.rb model.default => openai/gpt-4.1), keeping the from-zero
+      # experience consistent between the wizard and the non-interactive
+      # fail-fast guidance.
+      PROVIDERS = [
+        {
+          key: "openai",
+          label: "OpenAI (GPT) — recommended default",
+          provider: "openai",
+          model: "gpt-4.1",
+          env_var: "OPENAI_API_KEY",
+          config: {}
+        },
+        {
+          key: "minimax",
+          label: "MiniMax (Anthropic-compatible)",
+          provider: "minimax",
+          model: "MiniMax-M2.7",
+          env_var: "MINIMAX_API_KEY",
+          config: {
+            "anthropic_compatible" => true,
+            "base_url" => "https://api.minimax.io/anthropic",
+            "api_key" => "${MINIMAX_API_KEY}"
+          }
+        },
+        {
+          key: "anthropic",
+          label: "Anthropic (Claude)",
+          provider: "anthropic",
+          model: "claude-sonnet-4-5",
+          env_var: "ANTHROPIC_API_KEY",
+          config: {}
+        },
+        {
+          key: "gemini",
+          label: "Google (Gemini)",
+          provider: "google",
+          model: "gemini-2.5-pro",
+          env_var: "GEMINI_API_KEY",
+          config: {}
+        },
+        {
+          key: "gateway",
+          label: "OpenAI-compatible gateway",
+          provider: "gateway",
+          model: "auto",
+          env_var: "OPENAI_API_KEY",
+          config: {
+            "openai_compatible" => true,
+            "assume_model_exists" => true,
+            "base_url" => nil # filled in interactively
+          }
+        }
+      ].freeze
+
+      def initialize(ui: Rubino.ui, input: $stdin, output: $stdout)
+        @ui     = ui
+        @input  = input
+        @output = output
+      end
+
+      # Drives the wizard. Returns true when a provider was configured, false
+      # when the user skipped (empty/`s`/`skip` at the provider prompt).
+      def run
+        @ui.blank_line
+        @ui.info("Welcome to rubino — let's get you connected to a model.")
+        @ui.status("No API key is configured yet. Pick a provider (or press Enter to skip).")
+        @ui.blank_line
+
+        choice = ask_provider
+        return false unless choice
+
+        api_key = ask_api_key(choice)
+        return false if api_key.nil? || api_key.empty?
+
+        base_url = ask_base_url(choice)
+
+        persist!(choice, api_key, base_url)
+        Rubino.reload_configuration!
+
+        @ui.blank_line
+        @ui.success("Configured #{choice[:label]} with model #{choice[:model]}.")
+        @ui.status("Saved to #{config_loader.config_path} and #{config_loader.env_path}.")
+        @ui.blank_line
+        true
+      end
+
+      private
+
+      def ask_provider
+        PROVIDERS.each_with_index do |p, i|
+          @output.puts "  #{i + 1}) #{p[:label]}"
+        end
+
+        # Re-prompt on an invalid choice instead of abandoning the wizard on
+        # the first typo (#31). Only an explicit skip (empty / `s` / `skip`) or
+        # EOF leaves the loop with nil; an out-of-range number just asks again.
+        loop do
+          @output.print "Choose a provider [1-#{PROVIDERS.size}, Enter to skip]: "
+          @output.flush
+          raw = read_line
+          return nil if raw.nil? || raw.strip.empty? || %w[s skip].include?(raw.strip.downcase)
+
+          idx = raw.strip.to_i
+          return PROVIDERS[idx - 1] if idx.between?(1, PROVIDERS.size)
+
+          @ui.warning("Not a valid choice — please pick 1-#{PROVIDERS.size}, or press Enter to skip.")
+        end
+      end
+
+      def ask_api_key(choice)
+        @output.print "Paste your #{choice[:env_var]} (input hidden; Enter to skip): "
+        @output.flush
+        read_secret.to_s.strip
+      end
+
+      # The proxy provider needs a base_url; everyone else uses the upstream
+      # default, so we only ask when the catalog entry left base_url nil.
+      def ask_base_url(choice)
+        return nil unless choice[:config].key?("base_url") && choice[:config]["base_url"].nil?
+
+        @output.print "Enter the gateway base URL (e.g. https://host/v1): "
+        @output.flush
+        read_line.to_s.strip
+      end
+
+      def persist!(choice, api_key, base_url)
+        Rubino.ensure_directories!
+        loader = config_loader
+        # Seed config.yml from defaults the first time so the wizard's keys land
+        # in a complete, hand-editable file rather than a 3-line stub.
+        loader.create_default_config! unless loader.config_exists?
+
+        writer = Config::Writer.new(config_path: loader.config_path)
+        writer.set("model.default", choice[:model])
+        writer.set("model.provider", choice[:provider])
+
+        choice[:config].each do |k, v|
+          value = k == "base_url" && (v.nil? || v.empty?) ? base_url : v
+          next if value.nil?
+
+          writer.set("providers.#{choice[:provider]}.#{k}", value)
+        end
+
+        write_env_key!(loader.env_path, choice[:env_var], api_key)
+      end
+
+      # Appends/updates KEY=value in .env (0600). Does not echo the value. An
+      # existing line for the same key is replaced so re-running setup updates it.
+      def write_env_key!(env_path, var, value)
+        lines = File.exist?(env_path) ? File.readlines(env_path, chomp: true) : []
+        lines.reject! { |l| l =~ /\A#{Regexp.escape(var)}=/ }
+        lines << "#{var}=#{value}"
+        File.write(env_path, lines.join("\n") + "\n")
+        File.chmod(0o600, env_path)
+        # Make the key visible to THIS process too, so the immediate usability
+        # re-check and any subsequent model call in this run can see it.
+        ENV[var] = value
+      end
+
+      def config_loader
+        @config_loader ||= Config::Loader.new
+      end
+
+      def read_line
+        @input.gets
+      rescue StandardError
+        nil
+      end
+
+      # Hidden input for the key. Falls back to a plain read when the terminal
+      # can't toggle echo (piped input in tests).
+      def read_secret
+        if @input.respond_to?(:noecho) && @input.tty?
+          begin
+            secret = @input.noecho(&:gets)
+            @output.puts
+            return secret
+          rescue StandardError
+            # fall through to plain read
+          end
+        end
+        read_line
+      end
+    end
+  end
+end

data/lib/rubino/cli/server_command.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+module Rubino
+  module CLI
+    # Starts the HTTP API server (Rack + Puma).
+    class ServerCommand
+      def initialize(options = {})
+        @options = options
+      end
+
+      def execute
+        # Fail fast: a missing/malformed encryption key blows up on the first
+        # OAuth hit otherwise, with the listener already accepting traffic.
+        Boot::EncryptionKey.validate!
+
+        # The fake LLM provider is dev-only — it replays canned YAML scenarios
+        # instead of talking to a real LLM, so booting the API with it on by
+        # accident would silently serve fake answers to real clients. Refuse
+        # to start unless the operator explicitly opted in.
+        guard_fake_provider!
+
+        port = (@options[:port] || ENV.fetch("RUBINO_API_PORT", 4820)).to_i
+        # Loopback by default (#69); a routable bind is an explicit opt-in.
+        host = @options[:host] || ENV.fetch("RUBINO_API_HOST", "127.0.0.1")
+        api_key = @options[:api_key] || ENV.fetch("RUBINO_API_KEY", nil)
+
+        # When TLS is enabled (RUBINO_TLS=1 or a cert already exists), make
+        # sure a self-signed cert+key exist under RUBINO_HOME and serve over
+        # HTTPS. The web client pins this cert. Local dev / fake leave the
+        # toggle unset and no cert, so the listener stays plain HTTP.
+        tls_cert = tls_key = nil
+        if API::TLS.enabled?
+          API::TLS.ensure_cert!(host: host)
+          tls_cert = API::TLS.cert_path
+          tls_key  = API::TLS.key_path
+        end
+
+        register_metric_descriptions!
+
+        # Without this the tool registry stays empty, Lifecycle#load_tools
+        # returns [], no `tools: [...]` is sent on the wire, and the model
+        # has no choice but to roleplay tools in markdown. The CLI path
+        # (ChatCommand#ensure_setup!) registers tools the same way; both
+        # entry points need the same line.
+        Rubino::Tools::Registry.register_defaults! if Rubino::Tools::Registry.all.empty?
+
+        # Instantiate the shared agent registry at boot so the `task` tool can
+        # resolve subagents (explore/general) over /v1 — the API path uses the
+        # same delegation flow as the CLI. Memoized on Rubino.agent_registry.
+        Rubino.agent_registry
+
+        router = API::Router.new
+        router.get    "/v1/health",                 to: API::Operations::HealthOperation
+        router.get    "/v1/metrics",                to: API::Operations::MetricsOperation
+        router.get    "/v1/sessions",               to: API::Operations::Sessions::IndexOperation
+        router.post   "/v1/sessions",               to: API::Operations::Sessions::CreateOperation
+        router.get    "/v1/sessions/:id",           to: API::Operations::Sessions::ShowOperation
+        router.delete "/v1/sessions/:id",           to: API::Operations::Sessions::DeleteOperation
+        router.post   "/v1/sessions/:id/runs",      to: API::Operations::Runs::CreateOperation
+        router.get    "/v1/runs/:id/events",        to: API::Operations::Runs::EventsOperation
+        router.post   "/v1/runs/:id/stop",          to: API::Operations::Runs::StopOperation
+        router.post   "/v1/sessions/:id/retry",     to: API::Operations::Sessions::RetryOperation
+        router.post   "/v1/sessions/:id/undo",      to: API::Operations::Sessions::UndoOperation
+        router.post   "/v1/runs/:run_id/approvals/:approval_id",         to: API::Operations::Approvals::DecideOperation
+        router.post   "/v1/runs/:run_id/clarifications/:clarify_id",     to: API::Operations::Clarifications::DecideOperation
+        router.get    "/v1/skills",                 to: API::Operations::Skills::ListOperation
+        router.put    "/v1/skills/:name",           to: API::Operations::Skills::ToggleOperation
+        router.get    "/v1/mode",                   to: API::Operations::Mode::ShowOperation
+        router.put    "/v1/mode",                   to: API::Operations::Mode::UpdateOperation
+        router.get    "/v1/models",                 to: API::Operations::Models::ListOperation
+        router.get    "/v1/files",                  to: API::Operations::Files::ReadOperation
+        router.post   "/v1/files",                  to: API::Operations::Files::UploadOperation
+        router.get    "/v1/jobs",                   to: API::Operations::CronJobs::ListOperation
+        router.post   "/v1/jobs",                   to: API::Operations::CronJobs::CreateOperation
+        router.get    "/v1/jobs/:id",               to: API::Operations::CronJobs::ShowOperation
+        router.patch  "/v1/jobs/:id",               to: API::Operations::CronJobs::UpdateOperation
+        router.delete "/v1/jobs/:id",               to: API::Operations::CronJobs::DeleteOperation
+        router.post   "/v1/jobs/:id/pause",         to: API::Operations::CronJobs::PauseOperation
+        router.post   "/v1/jobs/:id/resume",        to: API::Operations::CronJobs::ResumeOperation
+        router.post   "/v1/jobs/:id/trigger",       to: API::Operations::CronJobs::TriggerOperation
+        router.get    "/v1/memory",                 to: API::Operations::Memory::IndexOperation
+        router.get    "/v1/memory/stats",           to: API::Operations::Memory::StatsOperation
+        router.delete "/v1/memory/:id",             to: API::Operations::Memory::DeleteOperation
+        router.get    "/v1/tasks",                   to: API::Operations::Tasks::IndexOperation
+        router.get    "/v1/tasks/:id",               to: API::Operations::Tasks::ShowOperation
+        router.post   "/v1/tasks/:id/stop",          to: API::Operations::Tasks::StopOperation
+        router.get    "/v1/oauth/providers",                  to: API::Operations::OAuth::Providers::ListOperation
+        router.post   "/v1/oauth/providers/:id/connect",      to: API::Operations::OAuth::Providers::ConnectOperation
+        router.post   "/v1/oauth/providers/:id/callback",     to: API::Operations::OAuth::Providers::CallbackOperation
+        router.get    "/v1/oauth/connections",                to: API::Operations::OAuth::Connections::ListOperation
+        router.delete "/v1/oauth/connections/:id",            to: API::Operations::OAuth::Connections::DisconnectOperation
+
+        ::Rubino::OAuth::Registry.load_from_config!
+        Jobs::Scheduler.instance.load_all!
+        # Drains any webhook delivery that was persisted as pending before a
+        # prior crash/restart. See Jobs::WebhookDelivery#resume_pending!.
+        Jobs::Scheduler.instance.resume_pending_webhooks!
+
+        Rubino::API::Server.new(
+          port: port,
+          host: host,
+          api_key: api_key,
+          router: router,
+          tls_cert: tls_cert,
+          tls_key: tls_key
+        ).start!
+      end
+
+      private
+
+      def guard_fake_provider!
+        provider = Rubino.configuration.model_provider
+        return unless provider.to_s == "fake"
+        return if ENV["RUBINO_ALLOW_FAKE"] == "1"
+
+        warn "fake provider is dev-only — set RUBINO_ALLOW_FAKE=1 to opt in."
+        exit(1)
+      end
+
+      # HELP text is looked up by Metrics.counter/.histogram at first-touch, so
+      # this must run before any metric is incremented (i.e. before the Rack
+      # stack is built). When adding a new Metrics.counter/.histogram anywhere
+      # in the codebase, add its HELP line here — the metrics_help_spec asserts
+      # every registered metric carries a description.
+      def register_metric_descriptions!
+        Metrics.describe(:http_requests_total, "Total HTTP requests handled, labelled by method/path/status.")
+        Metrics.describe(:http_request_duration_seconds, "HTTP request duration in seconds.")
+        Metrics.describe(:cron_fires_total, "Number of cron jobs fired, labelled by job and outcome.")
+        Metrics.describe(:webhook_deliveries_total, "Webhook deliveries attempted, labelled by outcome.")
+        Metrics.describe(:oauth_token_exchanges_total, "OAuth token exchanges, labelled by provider and outcome.")
+        Metrics.describe(:runs_total, "Runs started, labelled by source.")
+        Metrics.describe(:runs_completed_total, "Total number of runs that have completed (success+failure+cancelled).")
+        Metrics.describe(:skills_loaded_total, "Number of times a skill was successfully loaded via the `skill` tool.")
+        Metrics.describe(:skills_created_total,
+                         "Number of new skills observed by the registry on a re-scan (disk-diff signal; no creation tool exists).")
+      end
+    end
+  end
+end

data/lib/rubino/cli/session_command.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+require "thor"
+
+module Rubino
+  module CLI
+    # Subcommands for managing chat sessions
+    class SessionCommand < Thor
+      # Clean `tree`/help label instead of the underscored class-name default (F12).
+      namespace "rubino sessions"
+
+      def self.exit_on_failure?
+        true
+      end
+
+      desc "list", "List recent sessions"
+      option :limit,  type: :numeric, default: 20, desc: "Max results"
+      option :status, type: :string,  desc: "Filter by status"
+      option :search, type: :string,  desc: "Filter by title (substring match)"
+      def list
+        Rubino.ensure_database_ready!
+        repo = Session::Repository.new
+        # Reap sessions left "active" by a process that died without ending them
+        # (hard terminal kill / SIGKILL, #11) so the list never shows a stale
+        # "active" for a window that is actually gone.
+        repo.reap_orphaned_active!
+        sessions = repo.list(limit: options[:limit], status: options[:status],
+                             search: options[:search])
+
+        if sessions.empty?
+          Rubino.ui.info("No sessions found.")
+          return
+        end
+
+        rows = sessions.map do |s|
+          [s[:id][0..7], s[:title] || "(untitled)", s[:status],
+           s[:message_count].to_s, s[:created_at]]
+        end
+
+        Rubino.ui.table(
+          headers: %w[ID Title Status Messages Created],
+          rows: rows
+        )
+      end
+
+      desc "show ID", "Show session details"
+      def show(id)
+        Rubino.ensure_database_ready!
+        repo = Session::Repository.new
+        session = repo.find(id)
+
+        # One error, one style (#20): Thor already prints the Thor::Error message
+        # to stderr and exits non-zero (exit_on_failure?), so the extra styled
+        # ui.error line was the same failure repeated in a second format.
+        raise Thor::Error, "session not found: #{id}" if session.nil?
+
+        self.class.render(session, ui: Rubino.ui)
+      end
+
+      # ONE session-details rendering for both surfaces (#183): the CLI verb
+      # above and the in-chat `/sessions show <id>` (Commands::Executor).
+      def self.render(session, ui:)
+        ui.info("Session: #{session[:id]}")
+        ui.info("Title: #{session[:title] || "(untitled)"}")
+        ui.info("Status: #{session[:status]}")
+        ui.info("Model: #{session[:model]}")
+        ui.info("Messages: #{session[:message_count]}")
+        ui.info("Tokens: #{session[:token_count]}")
+        ui.info("Created: #{session[:created_at]}")
+        ui.info("Updated: #{session[:updated_at]}")
+
+        return unless session[:parent_session_id]
+
+        ui.info("Parent: #{session[:parent_session_id]}")
+      end
+
+      desc "delete ID", "Permanently delete a session and all its messages/events"
+      option :force, type: :boolean, default: false, aliases: "-f",
+                     desc: "Skip the confirmation prompt"
+      def delete(id)
+        Rubino.ensure_database_ready!
+        repo = Session::Repository.new
+        session = repo.find(id)
+
+        # Single-styled not-found error (#20), as in #show above.
+        raise Thor::Error, "session not found: #{id}" if session.nil?
+
+        self.class.destroy_with_confirm(session, repo: repo, ui: Rubino.ui, force: options[:force])
+      end
+
+      # ONE confirm-and-destroy flow for both surfaces (#183): the CLI verb
+      # above and the in-chat `/sessions delete <id>`.
+      def self.destroy_with_confirm(session, repo:, ui:, force: false)
+        unless force
+          confirmed = ui.confirm_destructive(
+            "Delete session #{session[:id][0..7]} '#{session[:title] || "(untitled)"}'? " \
+            "This will also remove its messages, events, and tool calls."
+          )
+          unless confirmed
+            ui.info("Aborted.")
+            return
+          end
+        end
+
+        repo.destroy!(session[:id])
+        ui.success("Deleted session #{session[:id][0..7]}.")
+      end
+
+      desc "compact ID", "Manually trigger compaction on a session"
+      def compact(id)
+        Rubino.ensure_database_ready!
+        repo = Session::Repository.new
+        session = repo.find(id)
+
+        # Single-styled not-found error (#20), as in #show above.
+        raise Thor::Error, "session not found: #{id}" if session.nil?
+
+        Rubino.ui.info("Compacting session #{id}...")
+        compressor = Context::Compressor.new(session_id: id)
+        result = compressor.compact!
+        Rubino.ui.compression_finished(result)
+      end
+    end
+  end
+end