rubino-agent 0.3.0

data/lib/rubino/skills/registry.rb

@@ -0,0 +1,208 @@
+# frozen_string_literal: true
+
+module Rubino
+  module Skills
+    # Discovers and manages skills from configured paths.
+    # Skills are loaded lazily - metadata is parsed upfront but
+    # full content is only loaded when the skill is invoked.
+    class Registry
+      # Flat-file skills: <dir>/<name>.md (legacy, kept for back-compat).
+      FLAT_GLOB = "*.md"
+      # Directory skills: <dir>/<name>/SKILL.md (Claude skill layout).
+      DIR_GLOB = File.join("*", "SKILL.md")
+
+      # Skills shipped *inside the gem* (skills/<name>/SKILL.md at the gem
+      # root, packaged via the gemspec's git-ls-files list). These are
+      # ALWAYS discovered — they don't depend on the user's skills.paths
+      # config (which `setup` freezes into config.yml) and they survive the
+      # folder-trust filter because this is an absolute path under the
+      # installed gem, owned by the user, not anything a visited repo can
+      # influence. This is how built-in skills (e.g. ruby-expert) reach every
+      # install with no copy step and update automatically on gem upgrade.
+      BUILTIN_SKILLS_DIR = File.expand_path("../../../skills", __dir__)
+
+      # +include_project_local+ controls whether the cwd `.rubino/skills`
+      # catalogue is discovered. Folder-trust passes false for an UNtrusted
+      # primary root so a hostile repo's skill descriptions can't be auto-
+      # injected into the system prompt before the user vouches for the folder
+      # (the home `~/.rubino/skills` catalogue is always loaded — it's the
+      # user's own, not attacker-controllable by cd-ing into a repo).
+      # +include_builtin+ controls whether the gem-bundled BUILTIN_SKILLS_DIR is
+      # scanned. Always on in production (built-ins ship with every install).
+      # When left nil it falls back to the `skills.include_builtin` config key
+      # (default true), so a caller that only has the config — like the prompt
+      # assembler, which builds its own Registry — can still opt out; tests that
+      # assert an exact catalogue pass false to isolate from the shipped skills.
+      def initialize(config: nil, state_repository: nil, include_project_local: true, include_builtin: nil)
+        @config = config || Rubino.configuration
+        @state_repository = state_repository
+        @include_project_local = include_project_local
+        @include_builtin = include_builtin.nil? ? (@config.dig("skills", "include_builtin") != false) : include_builtin
+        @skills = {}
+        @discovered = false
+      end
+
+      # A registry aligned with the prompt assembler's folder-trust gate (#63):
+      # in an untrusted cwd the project-local catalogue is excluded, so the
+      # /skills picker and activation surface only skills the assembler will
+      # actually pin into the system prompt — never a chip claiming an active
+      # skill whose SKILL.md is withheld.
+      def self.trusted(**)
+        new(include_project_local: project_local_trusted?, **)
+      end
+
+      # Mirrors Context::PromptAssembler#project_local_trusted?: trust-gate the
+      # cwd, but never let the check itself break discovery on a real error.
+      def self.project_local_trusted?
+        Rubino::Trust.trusted?(Rubino::Workspace.primary_root)
+      rescue StandardError
+        true
+      end
+
+      # Discovers all available skills from configured paths. Both the flat
+      # layout (<name>.md) and the directory layout (<name>/SKILL.md) are
+      # supported. When a name collides, the directory skill wins (it is the
+      # richer unit: it can carry bundled references/scripts/assets).
+      def discover!
+        previously_discovered = @discovered
+        known_before = @skills.keys
+        @skills.clear
+        skill_paths.each do |dir|
+          expanded = resolve_path(dir)
+          next unless File.directory?(expanded)
+
+          add_skills(Dir.glob(File.join(expanded, FLAT_GLOB)))
+          add_skills(Dir.glob(File.join(expanded, DIR_GLOB)))
+        end
+        @discovered = true
+        # Skill CREATION has no in-process tool — the agent writes files — so the
+        # cleanest available signal is a RE-scan surfacing a skill we hadn't seen
+        # before. Only count on a re-discover (not the first scan, which is just
+        # initial enumeration) so existing skills aren't booked as "created".
+        count_created!(known_before) if previously_discovered
+        @skills
+      end
+
+      # Returns all discovered skills (discovers on first call)
+      def all
+        discover! unless @discovered
+        @skills.values
+      end
+
+      # Finds a skill by name
+      def find(name)
+        discover! unless @discovered
+        @skills[name.to_s]
+      end
+
+      # Returns skill summaries for prompt inclusion (names + descriptions only).
+      # Disabled skills (per StateRepository) are excluded so a skill toggled
+      # off never appears in the system-prompt index (Skills::PromptIndex).
+      def summaries
+        enabled.map(&:summary)
+      end
+
+      # Loads and returns the full content of a skill by name. Returns nil when
+      # the skill is unknown; the disabled case is surfaced by #enabled? so the
+      # caller (SkillTool) can give a distinct "disabled" message.
+      def load_skill(name)
+        skill = find(name)
+        return nil unless skill
+
+        skill.content
+      end
+
+      # Returns skill names
+      def names
+        all.map(&:name)
+      end
+
+      # Skills not toggled off in the StateRepository (default-enabled when no
+      # row exists). Single source of truth for the enabled-filter shared by the
+      # system-prompt index (via #summaries) and the `skill` tool (via this).
+      def enabled
+        all.select { |skill| enabled?(skill.name) }
+      end
+
+      # Whether a skill is enabled (default-enabled when no state row exists).
+      def enabled?(name)
+        state_repository.enabled?(name)
+      end
+
+      private
+
+      # Increments +skills_created_total+ once per skill name that appears in a
+      # re-scan but was absent from the prior scan. NOTE: this is the only clean
+      # in-process creation signal available (there is no skill-creation tool);
+      # a skill created on disk is therefore counted the next time the registry
+      # re-discovers, not at write time. A skill removed and re-added would be
+      # re-counted — acceptable for a usage signal, not a ledger.
+      def count_created!(known_before)
+        new_names = @skills.keys - known_before
+        return if new_names.empty?
+
+        Rubino::Metrics.counter(:skills_created_total).increment(by: new_names.size)
+      end
+
+      def state_repository
+        @state_repository ||= StateRepository.new
+      end
+
+      # Resolves a configured skills dir to an absolute path. The stock
+      # "~/.rubino/..." entries follow the resolved home (RUBINO_HOME → else
+      # ~/.rubino), same resolver config/.env/DB/commands use, so an isolated
+      # home actually has its skills discovered (#135) instead of the literal
+      # path expanding against the REAL home. Any other path expands verbatim.
+      def resolve_path(dir)
+        if dir.to_s == "~/.rubino" || dir.to_s.start_with?("~/.rubino/")
+          File.join(Config::Loader.default_home_path, dir.to_s.delete_prefix("~/.rubino"))
+        else
+          File.expand_path(dir)
+        end
+      end
+
+      # Builds a Skill per path and indexes it by name. Called with flat paths
+      # first, then directory paths, so directory skills override flat ones on
+      # a name collision (see #discover!).
+      def add_skills(paths)
+        paths.each do |path|
+          skill = Skill.new(path: path)
+          @skills[skill.name] = skill
+        end
+      end
+
+      def skill_paths
+        paths = @config.dig("skills", "paths") || [
+          ".rubino/skills",
+          "~/.rubino/skills"
+        ]
+        unless @include_project_local
+          # Untrusted primary root: drop the project-local (cwd-relative) skill
+          # dirs, keeping only absolute / home (~) paths the user controls.
+          paths = paths.reject { |p| project_local_path?(p) }
+        end
+
+        # Built-in (gem-bundled) skills are scanned FIRST so a user skill of the
+        # same name — discovered later in .rubino/skills or ~/.rubino/skills —
+        # overrides the built-in on the registry's name-indexed merge (last
+        # writer wins in #add_skills). That lets a user shadow/customize a
+        # shipped skill while still getting the built-ins for free by default.
+        @include_builtin ? [BUILTIN_SKILLS_DIR, *paths] : paths
+      end
+
+      # A skill path is "project-local" when it resolves under the primary
+      # workspace root (the cwd a hostile repo could ship skills in), as
+      # opposed to an absolute or ~/.rubino path the user owns.
+      def project_local_path?(path)
+        return false if path.to_s.start_with?("~", "/")
+
+        expanded = File.expand_path(path.to_s)
+        root = File.expand_path(Workspace.primary_root)
+        expanded == root || expanded.start_with?("#{root}#{File::SEPARATOR}")
+      rescue StandardError
+        # Conservative: if we can't tell, treat as project-local and drop it.
+        true
+      end
+    end
+  end
+end

data/lib/rubino/skills/skill.rb

@@ -0,0 +1,176 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module Rubino
+  module Skills
+    # Represents a single skill. Two layouts are supported:
+    #   * flat file  — <dir>/<name>.md (the skill name is the basename)
+    #   * directory  — <dir>/<name>/SKILL.md (the skill name is the dir name,
+    #     plus bundled files under references/ scripts/ assets/ etc.)
+    #
+    # In both cases `path` points at the markdown body that carries the
+    # name/description frontmatter. Directory skills also expose `linked_files`
+    # (relative paths of bundled files) and can read a specific bundled file
+    # sandboxed to the skill's own directory.
+    class Skill
+      attr_reader :name, :description, :path, :metadata, :linked_files
+
+      def initialize(path:)
+        @path = path
+        @metadata = {}
+        @content = nil
+        @linked_files = []
+        @directory = directory_skill? ? File.dirname(path) : nil
+        discover_linked_files! if directory?
+        parse_frontmatter!
+      end
+
+      # True when this skill is backed by a <name>/SKILL.md directory.
+      def directory?
+        !@directory.nil?
+      end
+
+      # The skill's own directory (only for directory skills).
+      def dir
+        @directory
+      end
+
+      # Returns the full skill content (loaded lazily)
+      def content
+        @content ||= load_content
+      end
+
+      # Returns true if the skill has been fully loaded
+      def loaded?
+        !@content.nil?
+      end
+
+      # Reads a bundled file by its relative path, sandboxed to the skill dir.
+      # Returns the file contents, or nil if the skill has no directory, the
+      # path escapes the skill dir, or the file does not exist.
+      #
+      # Resolve and read happen back-to-back with no listing step in between, so
+      # the caller can't observe a "present in the listing but unreadable" state
+      # from THIS method. A File::ENOENT between #file? and #read (the skill dir
+      # being torn down mid-call) is swallowed to nil rather than raised, so a
+      # concurrent teardown reads as a clean miss instead of a crash (W3).
+      def read_file(relative_path)
+        return nil unless directory?
+
+        resolved = resolve_within_dir(relative_path)
+        return nil unless resolved && File.file?(resolved)
+
+        File.read(resolved)
+      rescue Errno::ENOENT, Errno::EACCES
+        nil
+      end
+
+      # Live relative paths of bundled files, recomputed from disk. Unlike the
+      # +linked_files+ snapshot taken at init, this reflects the current dir
+      # state — so an error message built from it can't list a file that
+      # #read_file just failed to find (the W3 self-contradiction). Empty for
+      # flat-file skills.
+      def current_linked_files
+        return [] unless directory?
+
+        collect_linked_files
+      end
+
+      # Returns a summary for the agent to see available skills
+      def summary
+        "#{@name}: #{@description}"
+      end
+
+      private
+
+      def directory_skill?
+        File.basename(@path) == "SKILL.md"
+      end
+
+      # Caches the init-time snapshot in +@linked_files+ (the system-prompt
+      # hint shows this). The live recompute path uses #collect_linked_files
+      # directly so the two never drift in logic.
+      def discover_linked_files!
+        @linked_files = collect_linked_files
+      end
+
+      # Relative paths of bundled files under the skill dir, excluding SKILL.md
+      # itself and vcs/junk dirs. Sorted for deterministic output. Re-globs the
+      # directory on every call, so it reflects current disk state.
+      def collect_linked_files
+        files = Dir.glob(File.join(@directory, "**", "*"), File::FNM_DOTMATCH).filter_map do |entry|
+          next unless File.file?(entry)
+
+          rel = entry.delete_prefix("#{@directory}#{File::SEPARATOR}")
+          next if rel == "SKILL.md"
+          next if rel.split(File::SEPARATOR).any? { |seg| EXCLUDED_DIRS.include?(seg) }
+
+          rel
+        end
+        files.sort
+      end
+
+      # Resolves a relative path against the skill dir and rejects anything that
+      # escapes it (via .., absolute paths, or symlinks pointing outside).
+      def resolve_within_dir(relative_path)
+        return nil if relative_path.nil? || relative_path.to_s.empty?
+
+        root = File.realpath(@directory)
+        target = File.expand_path(relative_path.to_s, root)
+        candidate = File.exist?(target) ? File.realpath(target) : target
+
+        return nil unless candidate == root || candidate.start_with?("#{root}#{File::SEPARATOR}")
+
+        candidate
+      rescue Errno::ENOENT, Errno::EACCES, Errno::ELOOP
+        nil
+      end
+
+      def parse_frontmatter!
+        raw = File.read(@path)
+
+        if raw.start_with?("---")
+          parts = raw.split("---", 3)
+          if parts.size >= 3
+            begin
+              @metadata = YAML.safe_load(parts[1], permitted_classes: [Symbol]) || {}
+            rescue Psych::SyntaxError => e
+              warn "rubino: skipping malformed frontmatter in #{@path} " \
+                   "(line #{e.line}: #{e.problem})"
+              @metadata = {}
+            end
+            @metadata = {} unless @metadata.is_a?(Hash)
+            @name = (@metadata["name"] || default_name).to_s
+            @description = @metadata["description"] || ""
+          else
+            @name = default_name
+            @description = ""
+          end
+        else
+          @name = default_name
+          @description = raw.lines.first&.strip&.sub(/^#\s*/, "") || ""
+        end
+      end
+
+      # For a directory skill the name is the directory name; for a flat file
+      # it is the markdown basename.
+      def default_name
+        directory? ? File.basename(@directory) : File.basename(@path, ".md")
+      end
+
+      def load_content
+        raw = File.read(@path)
+
+        if raw.start_with?("---")
+          parts = raw.split("---", 3)
+          parts.size >= 3 ? parts[2].strip : raw
+        else
+          raw
+        end
+      end
+
+      EXCLUDED_DIRS = %w[.git .svn .hg node_modules __pycache__ .DS_Store].freeze
+    end
+  end
+end

data/lib/rubino/skills/skill_tool.rb

@@ -0,0 +1,215 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module Rubino
+  module Skills
+    # Tool that allows the agent to load a skill on demand, and (Variant A —
+    # reference-style affordance) to CREATE a new skill inline during the turn.
+    #
+    # The agent sees skill names/descriptions in the system prompt and can invoke
+    # this tool to load the full skill instructions into context, or — after a
+    # complex, repeatable task — to distil what it just did into a new skill with
+    # action: "create" (0 extra LLM calls; the create happens inline on the
+    # tool-call the model already emitted).
+    class SkillTool < Tools::Base
+      # kebab-case, <=64 chars, mirrors the skill-creator frontmatter contract.
+      NAME_RE = /\A[a-z0-9]+(?:-[a-z0-9]+)*\z/
+
+      def initialize(registry: nil)
+        @registry = registry || Registry.new
+      end
+
+      def name
+        "skill"
+      end
+
+      def description
+        "Load a specialized skill's instructions into context, or create a new " \
+          "skill. action defaults to \"load\": use it when a task matches one of " \
+          "the available skills listed under \"## Skills\" in the system prompt " \
+          "(pass file_path to load a bundled file). After finishing a complex, " \
+          "multi-step task (typically 5+ tool calls) that is likely to recur and " \
+          "isn't already covered, call action: \"create\" with name, description, " \
+          "and body to save it as a reusable skill."
+      end
+
+      def input_schema
+        {
+          type: "object",
+          properties: {
+            action: {
+              type: "string",
+              enum: %w[load create],
+              description: "\"load\" (default) loads an existing skill; " \
+                           "\"create\" writes a new skill from name/description/body."
+            },
+            name: {
+              type: "string",
+              description: "The skill name. For load: the skill to load. " \
+                           "For create: a kebab-case name (<=64 chars)."
+            },
+            file_path: {
+              type: "string",
+              description: "Optional (load only). Relative path of a bundled file within the " \
+                           "skill (e.g. 'references/api.md', 'scripts/run.py') to load " \
+                           "its contents. Use the linked_files listed when the skill " \
+                           "body is first loaded."
+            },
+            description: {
+              type: "string",
+              description: "Required for create. One line: what the skill is for and WHEN " \
+                           "it applies (the only text future runs see before loading it)."
+            },
+            body: {
+              type: "string",
+              description: "Required for create. The markdown body: proven step-by-step " \
+                           "instructions, commands, and pitfalls. Be specific and prescriptive."
+            }
+          },
+          required: %w[name]
+        }
+      end
+
+      def risk_level
+        :low
+      end
+
+      # action: "load" (default) — three-level progressive disclosure:
+      #   skill(name)                       -> Level 2: SKILL.md body
+      #   skill(name, file_path: "ref.md")  -> Level 3: one bundled file
+      # action: "create" — write a new <name>/SKILL.md inline (Variant A).
+      def call(arguments)
+        action = (arguments["action"] || arguments[:action] || "load").to_s
+        return create(arguments) if action == "create"
+
+        skill_name = arguments["name"] || arguments[:name]
+        file_path  = arguments["file_path"] || arguments[:file_path]
+
+        skill = @registry.find(skill_name)
+        return not_found(skill_name) unless skill
+        return disabled(skill_name) unless @registry.enabled?(skill_name)
+
+        return load_bundled_file(skill, skill_name, file_path) if file_path && !file_path.to_s.empty?
+
+        load_body(skill, skill_name)
+      end
+
+      private
+
+      # ---- create (Variant A: inline, 0 extra LLM calls) --------------------
+
+      def create(arguments)
+        skill_name  = (arguments["name"] || arguments[:name]).to_s.strip
+        description = (arguments["description"] || arguments[:description]).to_s.strip
+        body        = (arguments["body"] || arguments[:body]).to_s
+
+        err = validate_create(skill_name, description, body)
+        return err if err
+
+        return duplicate(skill_name) if @registry.find(skill_name)
+
+        path = write_skill(skill_name, description, body)
+        # Re-discover so the new skill is immediately usable. The disk-diff in
+        # Registry#discover! is the SINGLE source of truth for
+        # skills_created_total — it books the just-written skill on this re-scan,
+        # so we must NOT increment the counter inline here too (that would
+        # double-count one creation).
+        @registry.discover!
+        Rubino.active_event_bus&.emit(
+          Interaction::Events::SKILL_CREATED,
+          name: skill_name, file_path: path
+        )
+        "Created skill '#{skill_name}' at #{path}. It is now available to load " \
+          "with skill(name: \"#{skill_name}\")."
+      rescue StandardError => e
+        "Could not create skill '#{skill_name}': #{e.message}"
+      end
+
+      def validate_create(skill_name, description, body)
+        return "Cannot create skill: name is required." if skill_name.empty?
+        unless skill_name.match?(NAME_RE) && skill_name.length <= 64
+          return "Cannot create skill: name must be kebab-case (lowercase letters, " \
+                 "digits, hyphens) and <=64 chars; got #{skill_name.inspect}."
+        end
+        return "Cannot create skill: description is required." if description.empty?
+        return "Cannot create skill: description must be <=1024 chars." if description.length > 1024
+        return "Cannot create skill: body is required." if body.strip.empty?
+
+        nil
+      end
+
+      def write_skill(skill_name, description, body)
+        dir = File.join(skills_write_dir, skill_name)
+        FileUtils.mkdir_p(dir)
+        path = File.join(dir, "SKILL.md")
+        content = "---\nname: #{skill_name}\ndescription: #{yaml_scalar(description)}\n---\n\n"
+        content << body
+        content << "\n" unless content.end_with?("\n")
+        File.write(path, content)
+        path
+      end
+
+      # Quote the description so a colon/newline can't break the YAML frontmatter.
+      def yaml_scalar(text)
+        one_line = text.tr("\n", " ").strip
+        %("#{one_line.gsub('"', '\\"')}")
+      end
+
+      # First configured skills path (project-local .rubino/skills by
+      # default) — the same source the Registry discovers from, so a created
+      # skill is found on the immediate re-discover.
+      def skills_write_dir
+        dir = (Rubino.configuration.dig("skills", "paths") || [".rubino/skills"]).first
+        File.expand_path(dir.to_s)
+      end
+
+      def duplicate(skill_name)
+        "A skill named '#{skill_name}' already exists; not overwriting. " \
+          "Pick a different name or load the existing one with skill(name: \"#{skill_name}\")."
+      end
+
+      # ---- load (unchanged) -------------------------------------------------
+
+      def load_body(skill, skill_name)
+        body = "Skill '#{skill_name}' loaded:\n\n#{skill.content}"
+        body << linked_files_hint(skill, skill_name) unless skill.linked_files.empty?
+        announce_loaded(skill_name)
+        body
+      end
+
+      def announce_loaded(skill_name)
+        Metrics.counter(:skills_loaded_total).increment
+        Rubino.active_event_bus&.emit(
+          Interaction::Events::SKILL_LOADED,
+          name: skill_name
+        )
+      end
+
+      def linked_files_hint(skill, skill_name)
+        listing = skill.linked_files.map { |f| "  - #{f}" }.join("\n")
+        "\n\nBundled files (load with skill(name: \"#{skill_name}\", file_path: \"...\")):\n#{listing}"
+      end
+
+      def load_bundled_file(skill, skill_name, file_path)
+        contents = skill.read_file(file_path)
+        if contents
+          "Skill '#{skill_name}' file '#{file_path}':\n\n#{contents}"
+        else
+          available = skill.current_linked_files.join(", ")
+          "File '#{file_path}' not found in skill '#{skill_name}'. " \
+            "Available files: #{available.empty? ? "(none)" : available}"
+        end
+      end
+
+      def not_found(skill_name)
+        available = @registry.names.join(", ")
+        "Skill '#{skill_name}' not found. Available skills: #{available}"
+      end
+
+      def disabled(skill_name)
+        "Skill '#{skill_name}' is disabled."
+      end
+    end
+  end
+end

data/lib/rubino/skills/state_repository.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+module Rubino
+  module Skills
+    # Persists per-skill enable/disable flags in the `skill_states` table.
+    #
+    # Default-enabled semantics: a skill with no row is treated as enabled,
+    # so #enabled? returns true for unknown names. Only an explicit #set with
+    # `enabled: false` disables a skill, and the choice survives restarts.
+    #
+    # Writes go through Sequel's `insert_conflict(target: :name)` which maps
+    # to SQLite's `INSERT ... ON CONFLICT(name) DO UPDATE` (UPSERT).
+    class StateRepository
+      def initialize(db: nil)
+        @db = db || Rubino.database.db
+      end
+
+      def enabled?(name)
+        row = @db[:skill_states].where(name: name.to_s).first
+        return true if row.nil?
+
+        row[:enabled] == true
+      end
+
+      def set(name, enabled:)
+        now = Time.now.utc.iso8601
+        @db[:skill_states]
+          .insert_conflict(target: :name, update: { enabled: enabled, updated_at: now })
+          .insert(name: name.to_s, enabled: enabled, updated_at: now)
+      end
+
+      def all
+        @db[:skill_states].all.to_h { |row| [row[:name], row[:enabled] == true] }
+      end
+    end
+  end
+end

data/lib/rubino/skills/toggle.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Rubino
+  module Skills
+    # ONE enable/disable write path for every surface (#188): the HTTP API
+    # toggle (PUT /v1/skills/:name), the in-chat `/skills enable|disable`
+    # and the `rubino skills enable|disable` CLI verbs all validate against
+    # the registry and persist through the same StateRepository write —
+    # previously the API operation was the ONLY caller of StateRepository#set,
+    # so a CLI-only user literally could not disable a skill.
+    module Toggle
+      # Persists the enabled flag for +name+. Returns the registered Skill
+      # (state written), or nil when the name is unknown (nothing written) —
+      # the caller decides how to surface the miss (404 for the API, a
+      # lowercase ✗ line for CLI/chat).
+      def self.set(name, enabled:, registry: nil, state_repository: nil)
+        registry ||= Registry.new
+        skill = registry.find(name)
+        return nil unless skill
+
+        (state_repository || StateRepository.new).set(name, enabled: enabled)
+        skill
+      end
+    end
+  end
+end