rubyn-code 0.1.0

data/lib/rubyn_code/protocols/interrupt_handler.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module RubynCode
+  module Protocols
+    # Handles SIGINT (Ctrl-C) gracefully with a two-stage interrupt protocol.
+    #
+    # First Ctrl-C sets the interrupted flag so the current LLM call can
+    # check and abort gracefully. A second Ctrl-C within 2 seconds forces
+    # an immediate exit.
+    module InterruptHandler
+      @interrupted = false
+      @last_interrupt_at = nil
+      @callbacks = []
+      @mutex = Mutex.new
+
+      class << self
+        # Installs the SIGINT trap with the two-stage interrupt protocol.
+        #
+        # @return [void]
+        def setup!
+          @mutex.synchronize do
+            @interrupted = false
+            @last_interrupt_at = nil
+          end
+
+          trap("INT") do
+            handle_interrupt
+          end
+        end
+
+        # Returns whether the interrupted flag is currently set.
+        #
+        # @return [Boolean]
+        def interrupted?
+          @mutex.synchronize { @interrupted }
+        end
+
+        # Clears the interrupted flag and resets the last interrupt timestamp.
+        #
+        # @return [void]
+        def reset!
+          @mutex.synchronize do
+            @interrupted = false
+            @last_interrupt_at = nil
+          end
+        end
+
+        # Registers a callback to be invoked on the first interrupt.
+        # Callbacks are executed in registration order.
+        #
+        # @yield the block to run on interrupt
+        # @return [void]
+        def on_interrupt(&block)
+          @mutex.synchronize do
+            @callbacks << block
+          end
+        end
+
+        # Clears all registered callbacks. Intended for test cleanup.
+        #
+        # @return [void]
+        def clear_callbacks!
+          @mutex.synchronize { @callbacks.clear }
+        end
+
+        private
+
+        # Core interrupt handler logic. Called from the SIGINT trap.
+        # Signal handlers must be reentrant-safe and avoid complex operations.
+        def handle_interrupt
+          now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+          if @last_interrupt_at && (now - @last_interrupt_at) < 2.0
+            # Second Ctrl-C within 2 seconds: force exit
+            $stderr.write("\nForce exiting...\n")
+            exit!(1)
+          end
+
+          @last_interrupt_at = now
+          @interrupted = true
+
+          $stderr.write("\nInterrupted. Press Ctrl-C again within 2s to force exit.\n")
+
+          # Fire callbacks outside the mutex to avoid deadlock in signal context.
+          # We read the callbacks array directly since signal handlers should be fast.
+          @callbacks.each do |callback|
+            callback.call
+          rescue StandardError
+            # Swallow errors in signal handlers to avoid crashing
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rubyn_code/protocols/plan_approval.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require "tty-prompt"
+require "tty-reader"
+require "pastel"
+
+module RubynCode
+  module Protocols
+    # Presents a plan to the user for approval before executing significant changes.
+    #
+    # This protocol ensures that destructive or wide-reaching operations are
+    # reviewed by a human before proceeding.
+    module PlanApproval
+      APPROVED = :approved
+      REJECTED = :rejected
+
+      class << self
+        # Displays a plan and asks the user to approve or reject it.
+        #
+        # @param plan_text [String] the plan description to display
+        # @param prompt [String, nil] optional custom prompt message
+        # @return [Symbol] :approved or :rejected
+        def request(plan_text, prompt: nil)
+          pastel = Pastel.new
+          tty = build_prompt
+
+          $stdout.puts
+          $stdout.puts pastel.cyan.bold("Proposed Plan")
+          $stdout.puts pastel.cyan("=" * 60)
+          $stdout.puts plan_text
+          $stdout.puts pastel.cyan("=" * 60)
+          $stdout.puts
+
+          if prompt
+            $stdout.puts pastel.yellow(prompt)
+            $stdout.puts
+          end
+
+          approved = tty.yes?(
+            pastel.yellow.bold("Do you approve this plan?"),
+            default: false
+          )
+
+          if approved
+            $stdout.puts pastel.green("Plan approved.")
+            APPROVED
+          else
+            $stdout.puts pastel.red("Plan rejected.")
+            REJECTED
+          end
+        rescue TTY::Reader::InputInterrupt
+          $stdout.puts pastel.red("\nPlan rejected (interrupted).")
+          REJECTED
+        end
+
+        private
+
+        # Builds a TTY::Prompt instance configured for non-destructive interrupt handling.
+        #
+        # @return [TTY::Prompt]
+        def build_prompt
+          TTY::Prompt.new(interrupt: :noop)
+        end
+      end
+    end
+  end
+end

data/lib/rubyn_code/protocols/shutdown_handshake.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module RubynCode
+  module Protocols
+    # Graceful shutdown protocol for agent teammates.
+    #
+    # Implements a cooperative handshake where a coordinator requests
+    # shutdown and the target agent acknowledges after saving state.
+    module ShutdownHandshake
+      # Default timeout in seconds when waiting for a shutdown response.
+      TIMEOUT = 10
+
+      class << self
+        # Initiates a shutdown request to a teammate and waits for acknowledgement.
+        #
+        # @param mailbox [Teams::Mailbox] the team mailbox
+        # @param from [String] the requesting agent name
+        # @param to [String] the target agent name to shut down
+        # @param timeout [Integer] seconds to wait for response (default: 10)
+        # @return [Symbol] :acknowledged or :timeout
+        def initiate(mailbox:, from:, to:, timeout: TIMEOUT)
+          mailbox.send(
+            from: from,
+            to: to,
+            content: "shutdown_request",
+            message_type: "shutdown_request"
+          )
+
+          deadline = Time.now + timeout
+
+          loop do
+            messages = mailbox.read_inbox(from)
+            response = messages.find do |msg|
+              msg[:from] == to && msg[:message_type] == "shutdown_response"
+            end
+
+            return :acknowledged if response
+
+            return :timeout if Time.now >= deadline
+
+            sleep(0.25)
+          end
+        end
+
+        # Sends a shutdown response (approval or denial) from the target agent.
+        #
+        # @param mailbox [Teams::Mailbox] the team mailbox
+        # @param from [String] the responding agent name
+        # @param to [String] the agent that requested the shutdown
+        # @param approve [Boolean] whether to approve the shutdown (default: true)
+        # @return [String] the message id
+        def respond(mailbox:, from:, to:, approve: true)
+          content = approve ? "shutdown_approved" : "shutdown_denied"
+
+          mailbox.send(
+            from: from,
+            to: to,
+            content: content,
+            message_type: "shutdown_response"
+          )
+        end
+
+        # Performs a full graceful shutdown for an agent: saves state,
+        # sends acknowledgement, and sets status to offline.
+        #
+        # @param agent_name [String] the agent being shut down
+        # @param mailbox [Teams::Mailbox] the team mailbox
+        # @param session_persistence [#save_session] persistence layer for saving session state
+        # @param conversation [Agent::Conversation] the agent's conversation to persist
+        # @param requester [String, nil] the agent that requested shutdown (for acknowledgement)
+        # @return [void]
+        def graceful_shutdown(agent_name, mailbox:, session_persistence:, conversation:, requester: nil)
+          # Step 1: Save current session state
+          save_state(agent_name, session_persistence, conversation)
+
+          # Step 2: Send shutdown acknowledgement if there is a requester
+          if requester
+            respond(mailbox: mailbox, from: agent_name, to: requester, approve: true)
+          end
+
+          # Step 3: Broadcast offline status to all listeners
+          mailbox.send(
+            from: agent_name,
+            to: "_system",
+            content: "#{agent_name} is now offline",
+            message_type: "status_change"
+          )
+        end
+
+        private
+
+        # Saves the agent's session state via the persistence layer.
+        #
+        # @param agent_name [String]
+        # @param session_persistence [#save_session]
+        # @param conversation [Agent::Conversation]
+        # @return [void]
+        def save_state(agent_name, session_persistence, conversation)
+          session_persistence.save_session(
+            agent_name: agent_name,
+            messages: conversation.messages
+          )
+        rescue StandardError => e
+          $stderr.puts "[ShutdownHandshake] Warning: failed to save state for '#{agent_name}': #{e.message}"
+        end
+      end
+    end
+  end
+end

data/lib/rubyn_code/skills/catalog.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module RubynCode
+  module Skills
+    class Catalog
+      SKILL_GLOB = "**/*.md"
+
+      attr_reader :skills_dirs
+
+      def initialize(skills_dirs)
+        @skills_dirs = Array(skills_dirs)
+        @index = nil
+      end
+
+      def descriptions
+        entries = available
+        return "" if entries.empty?
+
+        entries.map { |entry| "- /#{entry[:name]}: #{entry[:description]}" }.join("\n")
+      end
+
+      def available
+        build_index unless @index
+        @index
+      end
+
+      def find(name)
+        entry = available.find { |e| e[:name] == name.to_s }
+        entry&.fetch(:path)
+      end
+
+      private
+
+      def build_index
+        @index = []
+
+        skills_dirs.each do |dir|
+          next unless File.directory?(dir)
+
+          Dir.glob(File.join(dir, SKILL_GLOB)).sort.each do |path|
+            entry = extract_metadata(path)
+            @index << entry if entry
+          end
+        end
+
+        @index.uniq! { |e| e[:name] }
+      end
+
+      def extract_metadata(path)
+        header = File.read(path, 1024, encoding: "UTF-8")
+                     .encode("UTF-8", invalid: :replace, undef: :replace, replace: "")
+        doc = Document.parse(header, filename: path)
+
+        name = if doc.name.empty? || doc.name == "unknown"
+                 File.basename(path, ".md")
+               else
+                 doc.name
+               end
+
+        {
+          name: name,
+          description: doc.description,
+          path: File.expand_path(path)
+        }
+      rescue StandardError
+        nil
+      end
+    end
+  end
+end

data/lib/rubyn_code/skills/document.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module RubynCode
+  module Skills
+    class Document
+      FRONTMATTER_PATTERN = /\A---\s*\n(.+?\n)---\s*\n(.*)\z/m
+
+      attr_reader :name, :description, :tags, :body
+
+      def initialize(name:, description:, tags:, body:)
+        @name = name
+        @description = description
+        @tags = tags
+        @body = body
+      end
+
+      class << self
+        def parse(content, filename: nil)
+          match = FRONTMATTER_PATTERN.match(content)
+
+          if match
+            frontmatter = YAML.safe_load(match[1], permitted_classes: [Symbol]) || {}
+            body = match[2].to_s.strip
+
+            new(
+              name: frontmatter["name"].to_s,
+              description: frontmatter["description"].to_s,
+              tags: Array(frontmatter["tags"]),
+              body: body
+            )
+          else
+            body = content.to_s.strip
+            title = extract_title(body)
+            derived_name = filename ? File.basename(filename, ".*").tr("_", "-") : title_to_name(title)
+            tags = derive_tags(derived_name, body)
+
+            new(
+              name: derived_name,
+              description: title,
+              tags: tags,
+              body: body
+            )
+          end
+        end
+
+        def parse_file(path)
+          raise Error, "Skill file not found: #{path}" unless File.exist?(path)
+          raise Error, "Not a file: #{path}" unless File.file?(path)
+
+          content = File.read(path, encoding: "UTF-8")
+          parse(content, filename: path)
+        end
+
+        private
+
+        def extract_title(body)
+          first_line = body.lines.first&.strip || ""
+          first_line.start_with?("#") ? first_line.sub(/^#+\s*/, "") : first_line[0..80]
+        end
+
+        def title_to_name(title)
+          title.downcase.gsub(/[^a-z0-9]+/, "-").gsub(/^-|-$/, "")[0..40]
+        end
+
+        def derive_tags(name, body)
+          tags = []
+          tags << "ruby" if body.match?(/\bruby\b/i) || name.include?("ruby")
+          tags << "rails" if body.match?(/\brails\b/i) || name.include?("rails")
+          tags << "rspec" if body.match?(/\brspec\b/i) || name.include?("rspec")
+          tags << "testing" if body.match?(/\b(test|spec|minitest)\b/i)
+          tags << "patterns" if body.match?(/\b(pattern|design|solid)\b/i)
+          tags << "refactoring" if body.match?(/\brefactor/i)
+          tags.uniq
+        end
+      end
+    end
+  end
+end

data/lib/rubyn_code/skills/loader.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module RubynCode
+  module Skills
+    class Loader
+      attr_reader :catalog
+
+      def initialize(catalog)
+        @catalog = catalog
+        @loaded = {}
+      end
+
+      def load(name)
+        name = name.to_s
+
+        if @loaded.key?(name)
+          return @loaded[name]
+        end
+
+        path = catalog.find(name)
+        raise Error, "Skill not found: #{name}" unless path
+
+        doc = Document.parse_file(path)
+        content = format_skill(doc)
+
+        @loaded[name] = content
+        content
+      end
+
+      def loaded
+        @loaded.keys
+      end
+
+      def descriptions_for_prompt
+        catalog.descriptions
+      end
+
+      private
+
+      def format_skill(doc)
+        parts = []
+        parts << "<skill name=\"#{escape_xml(doc.name)}\">"
+        parts << doc.body unless doc.body.empty?
+        parts << "</skill>"
+        parts.join("\n")
+      end
+
+      def escape_xml(text)
+        text.to_s
+            .gsub("&", "&amp;")
+            .gsub("<", "&lt;")
+            .gsub(">", "&gt;")
+            .gsub("\"", "&quot;")
+      end
+    end
+  end
+end

data/lib/rubyn_code/sub_agents/runner.rb

@@ -0,0 +1,168 @@
+# frozen_string_literal: true
+
+module RubynCode
+  module SubAgents
+    class Runner
+      AGENT_TOOL_SETS = {
+        explore: %w[read_file glob grep bash].freeze,
+        general: nil # resolved at runtime to exclude sub-agent tools
+      }.freeze
+
+      SUB_AGENT_TOOLS = %w[sub_agent spawn_agent].freeze
+      MAX_ITERATIONS_HARD_LIMIT = 50
+
+      class << self
+        def call(prompt:, llm_client:, project_root:, agent_type: :explore, max_iterations: 30)
+          new(
+            prompt: prompt,
+            llm_client: llm_client,
+            project_root: project_root,
+            agent_type: agent_type,
+            max_iterations: max_iterations
+          ).run
+        end
+      end
+
+      def initialize(prompt:, llm_client:, project_root:, agent_type:, max_iterations:)
+        @prompt = prompt
+        @llm_client = llm_client
+        @project_root = File.expand_path(project_root)
+        @agent_type = agent_type.to_sym
+        @max_iterations = [max_iterations.to_i, MAX_ITERATIONS_HARD_LIMIT].min
+      end
+
+      def run
+        conversation = build_conversation
+        executor = build_executor
+        tool_defs = build_tool_definitions
+
+        iteration = 0
+        final_text = ""
+
+        loop do
+          break if iteration >= @max_iterations
+
+          response = request_llm(conversation, tool_defs)
+          iteration += 1
+
+          text_content = extract_text(response)
+          tool_calls = extract_tool_calls(response)
+
+          if tool_calls.empty?
+            final_text = text_content
+            break
+          end
+
+          conversation << { role: "assistant", content: response }
+
+          tool_results = execute_tools(executor, tool_calls)
+          conversation << { role: "user", content: tool_results }
+
+          final_text = text_content unless text_content.empty?
+        end
+
+        Summarizer.call(final_text)
+      end
+
+      private
+
+      def build_conversation
+        [
+          { role: "user", content: @prompt }
+        ]
+      end
+
+      def build_executor
+        Tools::Executor.new(project_root: @project_root)
+      end
+
+      def build_tool_definitions
+        allowed = allowed_tool_names
+        Tools::Registry.all
+                       .select { |t| allowed.include?(t.tool_name) }
+                       .map(&:to_schema)
+      end
+
+      def allowed_tool_names
+        preset = AGENT_TOOL_SETS[@agent_type]
+
+        if preset
+          # Only include tools that are actually registered
+          registered = Tools::Registry.tool_names
+          preset & registered
+        else
+          # :general — all registered tools minus sub-agent spawning tools
+          Tools::Registry.tool_names - SUB_AGENT_TOOLS
+        end
+      end
+
+      def request_llm(conversation, tool_defs)
+        @llm_client.chat(
+          messages: conversation,
+          tools: tool_defs
+        )
+      end
+
+      def extract_text(response)
+        case response
+        when String
+          response
+        when Hash
+          content = response[:content] || response["content"]
+          extract_text_from_content(content)
+        when Array
+          extract_text_from_content(response)
+        else
+          response.to_s
+        end
+      end
+
+      def extract_text_from_content(content)
+        return content.to_s unless content.is_a?(Array)
+
+        content
+          .select { |block| block_type(block) == "text" }
+          .map { |block| block[:text] || block["text"] }
+          .compact
+          .join("\n")
+      end
+
+      def extract_tool_calls(response)
+        content = case response
+                  when Hash then response[:content] || response["content"]
+                  when Array then response
+                  else return []
+                  end
+
+        return [] unless content.is_a?(Array)
+
+        content.select { |block| block_type(block) == "tool_use" }
+      end
+
+      def block_type(block)
+        (block[:type] || block["type"]).to_s
+      end
+
+      def execute_tools(executor, tool_calls)
+        tool_calls.map do |call|
+          tool_name = call[:name] || call["name"]
+          tool_input = call[:input] || call["input"] || {}
+          tool_id = call[:id] || call["id"]
+
+          # Prevent recursive sub-agent spawning
+          result = if SUB_AGENT_TOOLS.include?(tool_name)
+                     "Error: Sub-agents cannot spawn other sub-agents."
+                   else
+                     executor.execute(tool_name, tool_input)
+                   end
+
+          {
+            type: "tool_result",
+            tool_use_id: tool_id,
+            content: result.to_s
+          }
+        end
+      end
+    end
+  end
+end

data/lib/rubyn_code/sub_agents/summarizer.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module RubynCode
+  module SubAgents
+    module Summarizer
+      DEFAULT_MAX_LENGTH = 2000
+      TRUNCATION_SUFFIX = "\n\n[... output truncated ...]"
+
+      class << self
+        def call(text, max_length: DEFAULT_MAX_LENGTH)
+          return "" if text.nil? || text.empty?
+
+          text = text.to_s.strip
+
+          return text if text.length <= max_length
+
+          truncate_with_context(text, max_length)
+        end
+
+        private
+
+        def truncate_with_context(text, max_length)
+          usable = max_length - TRUNCATION_SUFFIX.length
+          return text[0, max_length] if usable <= 0
+
+          # Keep the beginning (context setup) and end (final result) of the output.
+          # The end usually contains the most relevant conclusion.
+          head_size = (usable * 0.4).to_i
+          tail_size = usable - head_size
+
+          head = text[0, head_size]
+          tail = text[-tail_size, tail_size]
+
+          # Trim to nearest newline boundaries when possible to avoid mid-line cuts.
+          head = trim_to_last_newline(head)
+          tail = trim_to_first_newline(tail)
+
+          "#{head}#{TRUNCATION_SUFFIX}\n\n#{tail}"
+        end
+
+        def trim_to_last_newline(text)
+          last_nl = text.rindex("\n")
+          return text unless last_nl && last_nl > (text.length * 0.5)
+
+          text[0..last_nl]
+        end
+
+        def trim_to_first_newline(text)
+          first_nl = text.index("\n")
+          return text unless first_nl && first_nl < (text.length * 0.3)
+
+          text[(first_nl + 1)..]
+        end
+      end
+    end
+  end
+end