rubyn-code 0.5.0 → 0.7.0

data/lib/rubyn_code/agent/loop.rb

@@ -9,7 +9,7 @@ require_relative 'llm_caller'
 
 module RubynCode
   module Agent
-    class Loop
+    class Loop # rubocop:disable Metrics/ClassLength -- core agent loop: LLM calls, tool dispatch, recovery, hooks
       include SystemPromptBuilder
       include ResponseParser
       include ToolProcessor
@@ -18,6 +18,7 @@ module RubynCode
       include LlmCaller
 
       MAX_ITERATIONS = Config::Defaults::MAX_ITERATIONS
+      GOAL_MAX_ITERATIONS = Config::Defaults::GOAL_MAX_ITERATIONS
 
       # @param opts [Hash] keyword arguments for loop configuration
       # @option opts [LLM::Client]                    :llm_client
@@ -39,6 +40,7 @@ module RubynCode
         assign_dependencies(opts)
         assign_callbacks(opts)
         @plan_mode = false
+        @static_prompt_sections = nil
       end
 
       # @return [Boolean]
@@ -61,19 +63,36 @@ module RubynCode
         @skill_ttl&.tick!
         autoload_triggered_skills(user_input)
         @conversation.add_user_message(user_input)
+        reset_system_prompt_cache!
         reset_iteration_state
 
-        MAX_ITERATIONS.times do |iteration|
+        iteration = 0
+        loop do
           result = run_iteration(iteration)
           return result if result
+
+          iteration += 1
+          break unless keep_iterating?(iteration)
         end
 
-        RubynCode::Debug.warn("Hit MAX_ITERATIONS (#{MAX_ITERATIONS})")
-        max_iterations_warning
+        RubynCode::Debug.warn("Hit iteration limit (#{iteration})")
+        max_iterations_warning(iteration)
       end
 
       private
 
+      # Decide whether the loop should run another iteration after `iteration`
+      # turns. Normally capped at MAX_ITERATIONS, but while a Stop hook (e.g. an
+      # active /goal) is keeping the agent alive we extend up to a hard ceiling
+      # — a goal can need more tool turns than a single request. The GoalHook's
+      # own max-attempts valve terminates an unsatisfiable goal; the ceiling is
+      # only a runaway guard.
+      def keep_iterating?(iteration)
+        return true if iteration < MAX_ITERATIONS
+
+        @stop_block_active && iteration < GOAL_MAX_ITERATIONS
+      end
+
       def assign_dependencies(opts)
         assign_required_deps(opts)
         assign_optional_deps(opts)
@@ -148,6 +167,7 @@ module RubynCode
         @max_tokens_override   = nil
         @output_recovery_count = 0
         @task_budget_remaining = nil
+        @stop_block_active     = false # true while a Stop hook keeps us going
       end
 
       def run_iteration(iteration)
@@ -199,6 +219,13 @@ module RubynCode
 
         @conversation.add_assistant_message(response_content(response))
 
+        # Stop hook: a hook may block stopping (e.g. an active /goal). When
+        # blocked, the reason is injected as user feedback and the loop keeps
+        # iterating instead of returning the final text. While blocked, the
+        # loop is allowed to run past MAX_ITERATIONS (see #keep_iterating?).
+        @stop_block_active = stop_blocked?(text)
+        return nil if @stop_block_active
+
         # Decision-based compaction (topic switch, milestone)
         @decision_compactor&.check!(@conversation)
 
@@ -208,6 +235,19 @@ module RubynCode
         text
       end
 
+      # Fires the :stop hook. If a hook blocks (returns { block: true }), the
+      # reason is appended as a user message so the next iteration acts on it.
+      #
+      # @return [Boolean] true if stopping was blocked (keep iterating)
+      def stop_blocked?(text)
+        decision = @hook_runner.fire(:stop, conversation: @conversation, response_text: text)
+        return false unless decision.is_a?(Hash) && decision[:block]
+
+        RubynCode::Debug.agent('Stop blocked by hook — continuing')
+        @conversation.add_user_message(decision[:reason])
+        true
+      end
+
       # Empty LLM response (0 content blocks). Common after dispatching
       # background_run — the LLM has nothing to say until results arrive.
       # Wait briefly for jobs, then either continue or accept the empty response.
@@ -243,15 +283,15 @@ module RubynCode
       # after text responses — mirrors Claude Code's "pause for compaction"
       # behavior that keeps context manageable in long sessions.
       def compact_if_needed
-        return unless @context_manager.needs_compaction?(@conversation.messages)
+        return unless @context_manager.needs_compaction?(@conversation)
 
-        est = @context_manager.estimated_tokens(@conversation.messages)
+        est = @context_manager.estimated_tokens(@conversation)
         RubynCode::Debug.token(
           "Context over threshold (#{est}) — running compaction"
         )
         @context_manager.check_compaction!(@conversation)
 
-        after = @context_manager.estimated_tokens(@conversation.messages)
+        after = @context_manager.estimated_tokens(@conversation)
         RubynCode::Debug.token("Compacted: #{est} → #{after} tokens")
       rescue StandardError => e
         RubynCode::Debug.warn("Compaction failed: #{e.message}")
@@ -266,8 +306,8 @@ module RubynCode
         @max_tokens_override = Config::Defaults::ESCALATED_MAX_OUTPUT_TOKENS
       end
 
-      def max_iterations_warning
-        warning = "Reached maximum iteration limit (#{MAX_ITERATIONS}). " \
+      def max_iterations_warning(limit = MAX_ITERATIONS)
+        warning = "Reached maximum iteration limit (#{limit}). " \
                   'The conversation may be incomplete. Please review the ' \
                   'current state and continue if needed.'
         @conversation.add_assistant_message([{ type: 'text', text: warning }])

data/lib/rubyn_code/agent/system_prompt_builder.rb

@@ -10,7 +10,7 @@ module RubynCode
     module SystemPromptBuilder # rubocop:disable Metrics/ModuleLength -- heavily extracted, residual 3 lines over
       include Prompts
 
-      INSTRUCTION_FILES = %w[RUBYN.md CLAUDE.md AGENT.md].freeze
+      INSTRUCTION_FILES = %w[RUBYN.md CLAUDE.md AGENTS.md AGENT.md].freeze
 
       private
 
@@ -19,16 +19,49 @@ module RubynCode
         parts << PLAN_MODE_PROMPT if @plan_mode
         parts << "Working directory: #{@project_root}" if @project_root
         append_response_mode(parts)
+        static = static_prompt_sections
+        parts << static unless static.empty?
+        parts.join("\n")
+      end
+
+      # The static sections hit SQLite (memories, instincts) and walk the
+      # filesystem (instruction files, profile), so they're assembled once
+      # per user turn instead of on every iteration of the tool loop. Only
+      # the plan-mode flag and response-mode line vary mid-turn, and those
+      # stay in build_system_prompt.
+      def static_prompt_sections
+        @static_prompt_sections ||= build_static_prompt_sections
+      end
+
+      def build_static_prompt_sections
+        parts = []
         append_project_profile(parts)
         append_codebase_index(parts)
         append_memories(parts)
         append_project_instructions(parts)
         append_instincts(parts)
         append_skills(parts)
+        append_chisel_ruleset(parts)
         append_deferred_tools(parts)
         parts.join("\n")
       end
 
+      # Chisel's "write the minimum that works" ruleset, injected only when the
+      # user has turned it on (chisel_mode != off). Guarded so a config or
+      # resolution error never breaks prompt assembly.
+      def append_chisel_ruleset(parts)
+        section = Chisel.prompt_section
+        parts << "\n#{section}" unless section.empty?
+      rescue StandardError
+        nil
+      end
+
+      # Called at the start of each user turn so memory, instruction, and
+      # tool changes made between turns show up in the next prompt.
+      def reset_system_prompt_cache!
+        @static_prompt_sections = nil
+      end
+
       def append_response_mode(parts)
         text = last_user_text
         return if text.empty?
@@ -182,7 +215,9 @@ module RubynCode
 
         db = DB::Connection.instance
         search = Memory::Search.new(db, project_path: @project_root)
-        recent = search.recent(limit: 20)
+        # touch: false — assembling the prompt is not a memory "access";
+        # touching here would issue a SQLite write and inflate access counts.
+        recent = search.recent(limit: 20, touch: false)
         return '' if recent.empty?
 
         recent.map { |m| format_memory(m) }.join("\n")

data/lib/rubyn_code/agent/tool_processor.rb

@@ -116,7 +116,9 @@ module RubynCode
 
       def execute_tool(tool_name, tool_input)
         discover_tool(tool_name)
-        @hook_runner.fire(:pre_tool_use, tool_name: tool_name, tool_input: tool_input)
+        pre_decision = @hook_runner.fire(:pre_tool_use, tool_name: tool_name, tool_input: tool_input)
+        raise RubynCode::UserDeniedError, pre_decision[:reason] if pre_decision.is_a?(Hash) && pre_decision[:deny]
+
         result = dispatch_tool(tool_name, tool_input)
         @hook_runner.fire(:post_tool_use, tool_name: tool_name, tool_input: tool_input, result: result)
         signal_decision_compactor(tool_name, tool_input, result)

data/lib/rubyn_code/auth/oauth.rb

@@ -3,7 +3,6 @@
 require 'securerandom'
 require 'digest'
 require 'base64'
-require 'faraday'
 require 'json'
 
 module RubynCode
@@ -163,6 +162,7 @@ module RubynCode
       end
 
       def http_client
+        require 'faraday'
         @http_client ||= Faraday.new do |f|
           f.options.timeout = 30
           f.options.open_timeout = 10

data/lib/rubyn_code/auth/token_store.rb

@@ -11,13 +11,27 @@ module RubynCode
       EXPIRY_BUFFER_SECONDS = 300 # 5 minutes
       KEYCHAIN_SERVICE = 'Claude Code-credentials'
 
+      # Strategy chain: each method returns a token hash or nil.
+      # First non-nil result wins. Adding a new auth source is a one-line entry.
+      LOAD_STRATEGIES = %i[
+        load_from_keychain
+        load_from_credentials_file
+        load_from_file
+        load_from_env
+      ].freeze
+
       class << self
         # Load tokens with fallback chain:
         # 1. macOS Keychain (Claude Code's OAuth token)
-        # 2. Local YAML file (~/.rubyn-code/tokens.yml)
-        # 3. ANTHROPIC_API_KEY environment variable
+        # 2. Claude Code credentials file (~/.claude/.credentials.json)
+        # 3. Local YAML file (~/.rubyn-code/tokens.yml)
+        # 4. ANTHROPIC_API_KEY environment variable
         def load
-          load_from_keychain || load_from_file || load_from_env
+          LOAD_STRATEGIES.each do |strategy|
+            result = send(strategy)
+            return result if result
+          end
+          nil
         end
 
         # Load API key for a given provider. Anthropic uses the full fallback chain.
@@ -68,7 +82,12 @@ module RubynCode
         end
 
         def valid?
-          tokens = self.load
+          valid_tokens?(self.load)
+        end
+
+        # Validate an already-loaded token hash without re-reading the
+        # keychain — lets callers cache the result of `load`.
+        def valid_tokens?(tokens)
           return false unless tokens&.fetch(:access_token, nil)
           return true if tokens[:type] == :api_key
           return true unless tokens[:expires_at]
@@ -88,6 +107,7 @@ module RubynCode
           default
         end
 
+        # macOS only: read from Keychain Services
         def load_from_keychain
           return nil unless RUBY_PLATFORM.include?('darwin')
 
@@ -102,6 +122,21 @@ module RubynCode
           nil
         end
 
+        # Linux/other: Claude Code stores OAuth in a plain JSON file
+        def load_from_credentials_file
+          path = Config::Defaults::CLAUDE_CREDENTIALS_FILE
+          return nil unless File.exist?(path)
+
+          warn_insecure_permissions(path)
+
+          oauth = JSON.parse(File.read(path))['claudeAiOauth']
+          return nil unless oauth&.dig('accessToken')
+
+          build_keychain_tokens(oauth)
+        rescue StandardError
+          nil
+        end
+
         def build_keychain_tokens(oauth)
           {
             access_token: oauth['accessToken'],
@@ -137,6 +172,16 @@ module RubynCode
           { access_token: api_key, refresh_token: nil, expires_at: nil, type: :api_key, source: :env }
         end
 
+        # Warn when credentials file has loose permissions (no system ACLs on Linux)
+        def warn_insecure_permissions(path)
+          mode = File.stat(path).mode & 0o777
+          return if mode == 0o600
+
+          warn "[rubyn-code] WARNING: #{path} has mode #{format('%04o', mode)}, expected 0600"
+        rescue StandardError
+          nil # best-effort — don't fail a token load over a stat
+        end
+
         def write_tokens_file(data)
           File.write(tokens_path, YAML.dump(data))
           File.chmod(0o600, tokens_path)

data/lib/rubyn_code/checkpoint/hook.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module RubynCode
+  module Checkpoint
+    # A :pre_tool_use hook that snapshots a file's original contents into the
+    # current checkpoint just before a mutating tool changes it. Only the
+    # file-mutating tools are watched; everything else is ignored.
+    class Hook
+      MUTATING_TOOLS = %w[write_file edit_file].freeze
+
+      # @param manager [Checkpoint::Manager]
+      def initialize(manager:)
+        @manager = manager
+      end
+
+      # @return [nil] never blocks the tool (returns no deny decision)
+      def call(tool_name:, tool_input: {}, **_kwargs)
+        return nil unless MUTATING_TOOLS.include?(tool_name.to_s)
+
+        path = tool_input[:path] || tool_input['path']
+        @manager.record_file(path) if path
+        nil
+      end
+    end
+  end
+end

data/lib/rubyn_code/checkpoint/manager.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+
+module RubynCode
+  # Checkpoints let a user rewind a session, mirroring Claude Code's /rewind.
+  # A checkpoint is taken at the start of each user turn and captures:
+  #   - the conversation state (so chat can be rolled back), and
+  #   - the original contents of every file mutated during that turn (so code
+  #     can be restored).
+  #
+  # File contents are captured lazily by Checkpoint::Hook on :pre_tool_use,
+  # just before a mutating tool runs, so only files that actually change are
+  # snapshotted.
+  module Checkpoint
+    # Marker stored for a path that did not exist when first touched, so a
+    # rewind deletes it rather than recreating empty content.
+    ABSENT = :absent
+
+    class Manager
+      MAX_CHECKPOINTS = 30
+
+      def initialize(project_root:)
+        @project_root = project_root
+        @checkpoints = []
+        @seq = 0
+        @current = nil
+      end
+
+      # Open a new checkpoint for a user turn. Captures the conversation as it
+      # stands before the agent acts.
+      #
+      # @param label [String] short description (usually the user's message)
+      # @param conversation [Agent::Conversation]
+      # @return [Integer] the checkpoint id
+      def checkpoint!(label:, conversation:)
+        @seq += 1
+        @current = {
+          id: @seq,
+          label: summarize(label),
+          messages: Array(conversation.messages).dup,
+          files: {}
+        }
+        @checkpoints << @current
+        @checkpoints.shift while @checkpoints.size > MAX_CHECKPOINTS
+        @seq
+      end
+
+      # Record a file's original contents before it is mutated (once per
+      # checkpoint per path). No-op when no checkpoint is open.
+      #
+      # @param path [String] absolute or project-relative path
+      # @return [void]
+      def record_file(path)
+        return unless @current && path
+
+        abs = File.expand_path(path.to_s, @project_root)
+        return if @current[:files].key?(abs)
+
+        @current[:files][abs] = File.file?(abs) ? File.read(abs) : ABSENT
+      rescue StandardError => e
+        RubynCode::Debug.warn("Checkpoint capture failed for #{path}: #{e.message}")
+      end
+
+      # @return [Array<Hash>] {id:, label:, files:} newest last
+      def list
+        @checkpoints.map { |c| { id: c[:id], label: c[:label], files: c[:files].size } }
+      end
+
+      def empty? = @checkpoints.empty?
+
+      def latest_id = @checkpoints.last&.fetch(:id)
+
+      # Restore a checkpoint. Scope :both (default), :code, or :chat.
+      # Checkpoints newer than the restored one are discarded.
+      #
+      # @return [Hash, nil] summary { id:, files_restored: } or nil if not found
+      def restore(id, conversation, scope: :both)
+        checkpoint = @checkpoints.find { |c| c[:id] == id }
+        return nil unless checkpoint
+
+        restored_files = restore_files(checkpoint) if %i[both code].include?(scope)
+        conversation.replace!(checkpoint[:messages].dup) if %i[both chat].include?(scope)
+
+        @checkpoints.reject! { |c| c[:id] > id }
+        @current = nil
+        { id: id, files_restored: restored_files || 0 }
+      end
+
+      private
+
+      def restore_files(checkpoint)
+        checkpoint[:files].each do |abs, content|
+          if content == ABSENT
+            FileUtils.rm_f(abs)
+          else
+            File.write(abs, content)
+          end
+        end
+        checkpoint[:files].size
+      end
+
+      def summarize(label)
+        text = label.to_s.tr("\n", ' ').strip
+        text.length > 60 ? "#{text[0, 57]}…" : text
+      end
+    end
+  end
+end

data/lib/rubyn_code/chisel/debt.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module RubynCode
+  module Chisel
+    # Harvests inline deferral markers from the codebase. A marker is a code
+    # comment whose text begins with the lowercase tag "chisel:" and records a
+    # simplification you consciously postponed (e.g. a comment reading
+    # "chisel: collapse this adapter once a second caller exists").
+    #
+    # Finding them is a deterministic grep — stdlib does it, so there's no LLM
+    # round-trip here (Chisel's own ladder, applied to Chisel).
+    module Debt
+      Item = Data.define(:file, :line, :note)
+
+      # The whole line must be a comment whose first token is the lowercase tag:
+      # optional indentation, a `#` or `//` leader, then `chisel:`, then the note.
+      # Anchoring to line-start means a `chisel:` substring inside a string
+      # literal or a trailing code comment is NOT harvested — only a marker on its
+      # own comment line is. Case-sensitive on purpose, so a descriptive comment
+      # that merely starts with "Chisel:" is not a marker.
+      MARKER = %r{\A\s*(?:#|//)\s*chisel:\s*(\S.*)}
+
+      SCAN_EXTENSIONS = %w[.rb .rake .erb .ru .gemspec].freeze
+      SKIP_DIRS = %w[.git node_modules vendor coverage tmp log].freeze
+
+      module_function
+
+      # @param root [String, nil] project root to scan
+      # @return [Array<Item>] markers found, in file/line order
+      def scan(root)
+        return [] unless root
+
+        base = File.expand_path(root)
+        return [] unless Dir.exist?(base)
+
+        source_files(base).flat_map { |path| scan_file(base, path) }
+      end
+
+      # @param base [String] expanded project root (no trailing slash)
+      # @return [Array<String>] absolute paths of scannable source files
+      def source_files(base)
+        pattern = File.join(base, '**', "*{#{SCAN_EXTENSIONS.join(',')}}")
+        Dir.glob(pattern).reject { |path| skip?(base, path) }.sort
+      end
+
+      def skip?(base, path)
+        rel = path.delete_prefix("#{base}/")
+        SKIP_DIRS.any? { |dir| rel == dir || rel.start_with?("#{dir}/") || rel.include?("/#{dir}/") }
+      end
+
+      # @return [Array<Item>] markers in a single file ([] if it can't be read)
+      def scan_file(base, path)
+        rel = path.delete_prefix("#{base}/")
+        items = []
+        File.foreach(path).with_index(1) do |line, number|
+          match = MARKER.match(line)
+          items << Item.new(file: rel, line: number, note: match[1].strip) if match
+        end
+        items
+      rescue StandardError
+        []
+      end
+    end
+  end
+end

data/lib/rubyn_code/chisel/inspection.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module RubynCode
+  module Chisel
+    # Builds the over-engineering audit instruction shared by /chisel-review
+    # (scope: :diff) and /chisel-audit (scope: :repo). Both judge by the same
+    # decision ladder and exclude the same safety floor, so the two commands
+    # can never drift apart — they differ only in what code they look at.
+    #
+    # Detection is delegated to the agent and its tools (git_diff, bash, grep,
+    # read_file); this module only assembles the prompt.
+    module Inspection
+      SMELLS = <<~SMELLS.strip
+        Flag code that skips a rung of the ladder:
+        - speculative abstractions, wrappers, or base classes with a single caller
+        - reinvented stdlib or already-installed-gem functionality
+        - needless indirection, configurability, or options nobody uses
+        - dead parameters, unused branches, premature generalization
+        - a class where a method would do; a method where one line would do
+      SMELLS
+
+      OUTPUT_CONTRACT = <<~CONTRACT.strip
+        Return a ranked deletion/simplification list, most impactful first. For
+        each item give:
+        - `file:line`
+        - what it is (one line)
+        - which rung of the ladder it skipped
+        - the concrete simpler form (delete it / inline it / replace with stdlib X)
+
+        If nothing is over-engineered, say so plainly instead of inventing work.
+      CONTRACT
+
+      READ_ONLY_NOTE = 'This is a READ-ONLY review: report the list, do not edit any files.'
+
+      module_function
+
+      # @param scope [Symbol] :diff (review changes) or :repo (audit codebase)
+      # @param target [String, nil] base ref for :diff (default "main"),
+      #   or an optional path to scope :repo
+      # @return [String] the full instruction to send to the agent
+      # @raise [ArgumentError] on an unknown scope
+      def prompt(scope:, target: nil)
+        [lead_in(scope, target), Chisel::LADDER, SMELLS, OUTPUT_CONTRACT, guardrails]
+          .join("\n\n")
+      end
+
+      # Read-only guard + the shared safety floor, reused verbatim from Chisel
+      # so the exclusion list can never drift from the always-on ruleset.
+      #
+      # @return [String]
+      def guardrails
+        "#{READ_ONLY_NOTE}\n\n#{Chisel::SAFETY_FLOOR}\n" \
+          'Those are never over-engineering — leave them even if they add code.'
+      end
+
+      # @return [String]
+      def lead_in(scope, target)
+        case scope
+        when :diff then diff_lead_in(presence(target) || 'main')
+        when :repo then repo_lead_in(presence(target))
+        else raise ArgumentError, "unknown Chisel inspection scope: #{scope.inspect}"
+        end
+      end
+
+      # @param value [#to_s, nil]
+      # @return [String, nil] the trimmed value, or nil if blank
+      def presence(value)
+        str = value.to_s.strip
+        str.empty? ? nil : str
+      end
+
+      def diff_lead_in(base)
+        <<~LEAD.strip
+          Chisel review — find over-engineering in my current changes.
+
+          Gather the diff with `git diff #{base}...` plus any uncommitted changes
+          (`git diff` and `git diff --staged`). Judge ONLY the added or changed
+          lines against the Chisel decision ladder below.
+        LEAD
+      end
+
+      def repo_lead_in(path)
+        scope_line = path ? "Scope the sweep to `#{path}`." : 'Sweep the whole repository.'
+        <<~LEAD.strip
+          Chisel audit — find accumulated over-engineering in this codebase.
+
+          #{scope_line} Use grep and file reads to survey the code, then judge it
+          against the Chisel decision ladder below.
+        LEAD
+      end
+    end
+  end
+end