rubyn-code 0.1.0

data/lib/rubyn_code/hooks/built_in.rb

@@ -0,0 +1,124 @@
+# frozen_string_literal: true
+
+module RubynCode
+  module Hooks
+    # Default hooks shipped with rubyn-code. These provide core functionality
+    # such as cost tracking, tool-call logging, and automatic context compaction.
+    module BuiltIn
+      # Records cost data after each LLM call using the BudgetEnforcer.
+      #
+      # Expects the :post_llm_call context to include:
+      #   - response: the raw API response hash (with :usage or "usage" key)
+      #   - budget_enforcer: an Observability::BudgetEnforcer instance (optional)
+      class CostTrackingHook
+        # @param budget_enforcer [Observability::BudgetEnforcer]
+        def initialize(budget_enforcer:)
+          @budget_enforcer = budget_enforcer
+        end
+
+        # @param response [Hash] the LLM API response
+        # @param kwargs [Hash] remaining context (ignored)
+        # @return [void]
+        def call(response:, **_kwargs)
+          return unless @budget_enforcer
+
+          usage = response[:usage] || response["usage"]
+          return unless usage
+
+          model          = response[:model] || response["model"] || "unknown"
+          input_tokens   = usage[:input_tokens] || usage["input_tokens"] || 0
+          output_tokens  = usage[:output_tokens] || usage["output_tokens"] || 0
+          cache_read     = usage[:cache_read_input_tokens] || usage["cache_read_input_tokens"] || 0
+          cache_write    = usage[:cache_creation_input_tokens] || usage["cache_creation_input_tokens"] || 0
+
+          @budget_enforcer.record!(
+            model: model,
+            input_tokens: input_tokens,
+            output_tokens: output_tokens,
+            cache_read_tokens: cache_read,
+            cache_write_tokens: cache_write
+          )
+        end
+      end
+
+      # Logs tool calls and their results via the formatter.
+      #
+      # Listens to :pre_tool_use and :post_tool_use events.
+      class LoggingHook
+        # @param formatter [Output::Formatter]
+        def initialize(formatter:)
+          @formatter = formatter
+        end
+
+        # Handles both :pre_tool_use and :post_tool_use events.
+        #
+        # For :pre_tool_use, logs the tool name and input arguments.
+        # For :post_tool_use, logs the tool result.
+        #
+        # @param tool_name [String] name of the tool
+        # @param tool_input [Hash] input arguments (for pre_tool_use)
+        # @param result [String, nil] tool output (for post_tool_use)
+        # @param kwargs [Hash] remaining context
+        # @return [nil]
+        def call(tool_name:, tool_input: {}, result: nil, **_kwargs)
+          if result.nil?
+            @formatter.tool_call(tool_name, tool_input)
+          else
+            @formatter.tool_result(tool_name, result, success: true)
+          end
+
+          nil
+        end
+      end
+
+      # Triggers a compaction check after each LLM call to keep the context
+      # window within bounds.
+      #
+      # Expects the :post_llm_call context to include:
+      #   - conversation: the Agent::Conversation instance
+      #   - context_manager: a Context::Manager instance (optional)
+      class AutoCompactHook
+        # @param context_manager [Context::Manager]
+        def initialize(context_manager:)
+          @context_manager = context_manager
+        end
+
+        # @param conversation [Agent::Conversation] the current conversation
+        # @param kwargs [Hash] remaining context (ignored)
+        # @return [void]
+        def call(conversation: nil, **_kwargs)
+          return unless @context_manager && conversation
+
+          @context_manager.auto_compact(conversation)
+        rescue NoMethodError
+          # auto_compact not yet available on this context manager
+        end
+      end
+
+      class << self
+        # Registers all built-in hooks on the given registry.
+        #
+        # @param registry [Hooks::Registry]
+        # @param budget_enforcer [Observability::BudgetEnforcer, nil]
+        # @param formatter [Output::Formatter, nil]
+        # @param context_manager [Context::Manager, nil]
+        # @return [void]
+        def register_all!(registry, budget_enforcer: nil, formatter: nil, context_manager: nil)
+          if budget_enforcer
+            registry.on(:post_llm_call, CostTrackingHook.new(budget_enforcer: budget_enforcer), priority: 10)
+          end
+
+          if formatter
+            logging_hook = LoggingHook.new(formatter: formatter)
+            registry.on(:pre_tool_use,  logging_hook, priority: 50)
+            registry.on(:post_tool_use, logging_hook, priority: 50)
+          end
+
+          if context_manager
+            registry.on(:post_llm_call, AutoCompactHook.new(context_manager: context_manager), priority: 90)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/rubyn_code/hooks/registry.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+require "monitor"
+
+module RubynCode
+  module Hooks
+    # Thread-safe registry for hook callables keyed by event type.
+    #
+    # Hooks can be registered as blocks or any object responding to #call.
+    # Each hook is stored with an optional priority (lower runs first).
+    class Registry
+      VALID_EVENTS = %i[
+        pre_tool_use
+        post_tool_use
+        pre_llm_call
+        post_llm_call
+        on_stall
+        on_error
+        on_session_end
+      ].freeze
+
+      Hook = Data.define(:callable, :priority)
+
+      include MonitorMixin
+
+      def initialize
+        super() # MonitorMixin
+        @hooks = {}
+        VALID_EVENTS.each { |event| @hooks[event] = [] }
+      end
+
+      # Registers a hook for the given event.
+      #
+      # @param event [Symbol] one of VALID_EVENTS
+      # @param callable [#call, nil] an object responding to #call, or nil if a block is given
+      # @param priority [Integer] execution order (lower runs first, default 100)
+      # @yield the hook block (used when callable is nil)
+      # @return [void]
+      def on(event, callable = nil, priority: 100, &block)
+        event = event.to_sym
+        validate_event!(event)
+
+        handler = callable || block
+        raise ArgumentError, "A callable or block is required" unless handler
+        raise ArgumentError, "Hook must respond to #call" unless handler.respond_to?(:call)
+
+        synchronize do
+          @hooks[event] << Hook.new(callable: handler, priority: priority)
+          @hooks[event].sort_by!(&:priority)
+        end
+      end
+
+      # Returns an array of callables registered for the given event,
+      # ordered by priority (lowest first).
+      #
+      # @param event [Symbol]
+      # @return [Array<#call>]
+      def hooks_for(event)
+        event = event.to_sym
+        synchronize do
+          (@hooks[event] || []).map(&:callable)
+        end
+      end
+
+      # Clears hooks for a specific event, or all hooks if no event is given.
+      #
+      # @param event [Symbol, nil]
+      # @return [void]
+      def clear!(event = nil)
+        synchronize do
+          if event
+            event = event.to_sym
+            @hooks[event] = [] if @hooks.key?(event)
+          else
+            @hooks.each_key { |e| @hooks[e] = [] }
+          end
+        end
+      end
+
+      # Returns a list of event types that have at least one hook registered.
+      #
+      # @return [Array<Symbol>]
+      def registered_events
+        synchronize do
+          @hooks.select { |_, hooks| hooks.any? }.keys
+        end
+      end
+
+      private
+
+      def validate_event!(event)
+        return if VALID_EVENTS.include?(event)
+
+        raise ArgumentError,
+              "Unknown event #{event.inspect}. Valid events: #{VALID_EVENTS.join(", ")}"
+      end
+    end
+  end
+end

data/lib/rubyn_code/hooks/runner.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module RubynCode
+  module Hooks
+    # Executes registered hooks for a given event in priority order.
+    #
+    # Hook execution is defensive: exceptions raised by individual hooks are
+    # caught and logged rather than allowed to crash the agent. Special
+    # semantics apply to :pre_tool_use (deny gating) and :post_tool_use
+    # (output transformation).
+    class Runner
+      # @param registry [Hooks::Registry] the hook registry to draw from
+      def initialize(registry: Registry.new)
+        @registry = registry
+      end
+
+      # Fires all hooks for the given event with the supplied context.
+      #
+      # @param event [Symbol] the event type
+      # @param context [Hash] keyword arguments passed to each hook
+      # @return [Hash, Object, nil] depends on event semantics:
+      #   - :pre_tool_use => { deny: true, reason: "..." } if any hook denies, else nil
+      #   - :post_tool_use => the (possibly transformed) output
+      #   - all others => nil
+      def fire(event, **context)
+        hooks = @registry.hooks_for(event)
+        return if hooks.empty?
+
+        case event
+        when :pre_tool_use
+          fire_pre_tool_use(hooks, context)
+        when :post_tool_use
+          fire_post_tool_use(hooks, context)
+        else
+          fire_generic(hooks, event, context)
+        end
+      end
+
+      private
+
+      # For :pre_tool_use, if any hook returns a hash with { deny: true },
+      # execution stops and the deny result is returned immediately.
+      def fire_pre_tool_use(hooks, context)
+        hooks.each do |hook|
+          result = safe_call(hook, :pre_tool_use, context)
+          next unless result.is_a?(Hash) && result[:deny]
+
+          return { deny: true, reason: result[:reason] || "Denied by hook" }
+        end
+
+        nil
+      end
+
+      # For :post_tool_use, each hook receives the output from the previous
+      # hook (or the original result). This allows hooks to transform output
+      # in a pipeline fashion.
+      def fire_post_tool_use(hooks, context)
+        output = context[:result]
+
+        hooks.each do |hook|
+          transformed = safe_call(hook, :post_tool_use, context.merge(result: output))
+          output = transformed unless transformed.nil?
+        end
+
+        output
+      end
+
+      # Generic hook execution: run all hooks, ignore return values.
+      def fire_generic(hooks, event, context)
+        hooks.each { |hook| safe_call(hook, event, context) }
+        nil
+      end
+
+      # Calls a hook safely, catching and logging any exceptions.
+      #
+      # @param hook [#call] the hook callable
+      # @param event [Symbol] the event (for error reporting)
+      # @param context [Hash] the context to pass
+      # @return [Object, nil] the hook's return value, or nil on error
+      def safe_call(hook, event, context)
+        hook.call(**context)
+      rescue StandardError => e
+        warn "[RubynCode::Hooks] Hook error during #{event}: #{e.class}: #{e.message}"
+        nil
+      end
+    end
+  end
+end

data/lib/rubyn_code/hooks/user_hooks.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module RubynCode
+  module Hooks
+    class UserHooks
+      # Load hooks from YAML config files.
+      #
+      # Format:
+      # pre_tool_use:
+      #   - tool: bash
+      #     match: "rm -rf"
+      #     action: deny
+      #     reason: "Destructive delete blocked"
+      #   - tool: write_file
+      #     path: "db/migrate/**"
+      #     action: deny
+      #     reason: "Use rails generate migration"
+      # post_tool_use:
+      #   - tool: write_file
+      #     action: log
+      #
+      # @param registry [Hooks::Registry]
+      # @param project_root [String] the project root directory
+      # @return [void]
+      def self.load!(registry, project_root:)
+        paths = [
+          File.join(project_root, ".rubyn-code", "hooks.yml"),
+          File.join(Config::Defaults::HOME_DIR, "hooks.yml")
+        ]
+
+        paths.each do |path|
+          next unless File.exist?(path)
+
+          config = YAML.safe_load_file(path) || {}
+          register_hooks(registry, config)
+        end
+      end
+
+      class << self
+        private
+
+        def register_hooks(registry, config)
+          register_pre_tool_use_hooks(registry, config["pre_tool_use"] || [])
+          register_post_tool_use_hooks(registry, config["post_tool_use"] || [])
+        end
+
+        def register_pre_tool_use_hooks(registry, hook_configs)
+          hook_configs.each do |hook_config|
+            registry.on(:pre_tool_use) do |tool_name:, tool_input:, **|
+              next unless matches?(hook_config, tool_name, tool_input)
+
+              case hook_config["action"]
+              when "deny"
+                { deny: true, reason: hook_config["reason"] || "Blocked by hooks.yml" }
+              end
+            end
+          end
+        end
+
+        def register_post_tool_use_hooks(registry, hook_configs)
+          hook_configs.each do |hook_config|
+            registry.on(:post_tool_use) do |tool_name:, result:, **|
+              next result unless hook_config["tool"].nil? || hook_config["tool"] == tool_name
+
+              if hook_config["action"] == "log"
+                log_dir = ".rubyn-code"
+                FileUtils.mkdir_p(log_dir) unless Dir.exist?(log_dir)
+                File.open(File.join(log_dir, "audit.log"), "a") do |f|
+                  f.puts "[#{Time.now}] #{tool_name}: #{result.to_s[0..200]}"
+                end
+              end
+
+              result
+            end
+          end
+        end
+
+        def matches?(config, tool_name, params)
+          return false if config["tool"] && config["tool"] != tool_name
+          return false if config["match"] && !params.to_s.include?(config["match"])
+          return false if config["path"] && !File.fnmatch?(config["path"], params[:path].to_s)
+
+          true
+        end
+      end
+    end
+  end
+end

data/lib/rubyn_code/learning/extractor.rb

@@ -0,0 +1,191 @@
+# frozen_string_literal: true
+
+require "json"
+require "securerandom"
+
+module RubynCode
+  module Learning
+    # Extracts reusable patterns from session messages using an LLM.
+    #
+    # After a session, the extractor sends recent conversation history to a
+    # cheaper model (Haiku) and asks it to identify patterns that could be
+    # useful in future sessions for the same project.
+    module Extractor
+      # Maximum number of recent messages to analyze.
+      MESSAGE_WINDOW = 30
+
+      # Valid pattern types that the LLM is asked to produce.
+      VALID_TYPES = %w[
+        error_resolution
+        user_correction
+        workaround
+        debugging_technique
+        project_specific
+      ].freeze
+
+      EXTRACTION_PROMPT = <<~PROMPT
+        Analyze the following conversation between a developer and an AI coding assistant.
+        Extract reusable patterns that could help in future sessions for this project.
+
+        For each pattern, provide:
+        - type: one of #{VALID_TYPES.join(', ')}
+        - pattern: a concise description of the learned behavior or fix
+        - context_tags: relevant tags (e.g., framework names, error types, file patterns)
+        - confidence: initial confidence score between 0.3 and 0.8
+
+        Respond with a JSON array of objects. If no patterns are found, respond with [].
+        Only extract patterns that are genuinely reusable, not one-off fixes.
+
+        Example response:
+        [
+          {
+            "type": "error_resolution",
+            "pattern": "When seeing 'PG::UniqueViolation' on users.email, check for missing unique index migration",
+            "context_tags": ["postgresql", "rails", "migration"],
+            "confidence": 0.6
+          }
+        ]
+      PROMPT
+
+      class << self
+        # Extracts instinct patterns from a session's message history.
+        #
+        # @param messages [Array<Hash>] the conversation messages
+        # @param llm_client [LLM::Client] the LLM client for extraction
+        # @param project_path [String] the project root path
+        # @return [Array<Hash>] extracted instinct hashes ready for persistence
+        def call(messages, llm_client:, project_path:)
+          recent = messages.last(MESSAGE_WINDOW)
+          return [] if recent.empty?
+
+          response = request_extraction(recent, llm_client)
+          raw_patterns = parse_response(response)
+
+          instincts = raw_patterns.filter_map do |raw|
+            normalize_pattern(raw, project_path)
+          end
+
+          save_to_db(instincts) unless instincts.empty?
+
+          instincts
+        end
+
+        private
+
+        def request_extraction(messages, llm_client)
+          # Serialize conversation into a single user message to avoid
+          # "must end with user message" errors
+          transcript = messages.map { |m|
+            role = (m[:role] || m["role"] || "unknown").capitalize
+            content = m[:content] || m["content"]
+            text = case content
+                   when String then content
+                   when Array
+                     content.filter_map { |b|
+                       b.respond_to?(:text) ? b.text : (b[:text] || b["text"])
+                     }.join("\n")
+                   else content.to_s
+                   end
+            "#{role}: #{text}"
+          }.join("\n\n")
+
+          llm_client.chat(
+            messages: [{ role: "user", content: "#{EXTRACTION_PROMPT}\n\nConversation:\n#{transcript}" }],
+            max_tokens: 2000
+          )
+        rescue StandardError => e
+          warn "[Learning::Extractor] LLM extraction failed: #{e.message}"
+          nil
+        end
+
+        def save_to_db(instincts)
+          db = DB::Connection.instance
+          now = Time.now.utc.strftime('%Y-%m-%dT%H:%M:%SZ')
+
+          instincts.each do |inst|
+            db.execute(
+              "INSERT INTO instincts (id, project_path, pattern, context_tags, confidence, decay_rate, times_applied, times_helpful, created_at, updated_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)",
+              [
+                SecureRandom.uuid,
+                inst[:project_path],
+                inst[:pattern],
+                JSON.generate(inst[:context_tags]),
+                inst[:confidence],
+                inst[:decay_rate],
+                inst[:times_applied],
+                inst[:times_helpful],
+                now,
+                now
+              ]
+            )
+          end
+        rescue StandardError => e
+          warn "[Learning::Extractor] Failed to save instincts: #{e.message}"
+        end
+
+        def parse_response(response)
+          return [] if response.nil?
+
+          text = extract_text(response)
+          return [] if text.nil? || text.empty?
+
+          # Extract JSON array from response, handling markdown code blocks
+          json_str = text[/\[.*\]/m]
+          return [] if json_str.nil?
+
+          parsed = JSON.parse(json_str)
+          return [] unless parsed.is_a?(Array)
+
+          parsed
+        rescue JSON::ParserError => e
+          warn "[Learning::Extractor] Failed to parse extraction response: #{e.message}"
+          []
+        end
+
+        def extract_text(response)
+          if response.respond_to?(:content)
+            block = response.content.find { |b| b.respond_to?(:text) }
+            block&.text
+          elsif response.is_a?(Hash)
+            response.dig("content", 0, "text")
+          end
+        end
+
+        def normalize_pattern(raw, project_path)
+          type = raw["type"].to_s
+          pattern = raw["pattern"].to_s.strip
+          context_tags = Array(raw["context_tags"]).map(&:to_s)
+          confidence = raw["confidence"].to_f
+
+          return nil if pattern.empty?
+          return nil unless VALID_TYPES.include?(type)
+
+          confidence = confidence.clamp(0.3, 0.8)
+
+          {
+            project_path: project_path,
+            pattern: "[#{type}] #{pattern}",
+            context_tags: context_tags,
+            confidence: confidence,
+            decay_rate: decay_rate_for_type(type),
+            times_applied: 0,
+            times_helpful: 0
+          }
+        end
+
+        # Different pattern types decay at different rates.
+        # Project-specific knowledge decays slower; workarounds decay faster.
+        def decay_rate_for_type(type)
+          case type
+          when "project_specific"     then 0.02
+          when "error_resolution"     then 0.03
+          when "debugging_technique"  then 0.04
+          when "user_correction"      then 0.05
+          when "workaround"           then 0.07
+          else 0.05
+          end
+        end
+      end
+    end
+  end
+end