console_agent 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 35e4cf8ecceb5241ce1b18f2cac6d8a235b3185f7839b2143eca6233390375d5
-  data.tar.gz: 7ebfc01003d9995ce65645a1f15955747cd59197c891e294d2152f3101fd583c
+  metadata.gz: d1d37fc84ac3f2d29832d282e6db1fd394308de2b967843c3a0c9748560a7025
+  data.tar.gz: 28bd6c25529dbedfa12d2353a1648304517bab933f0a4f25e91285ccaaf08e10
 SHA512:
-  metadata.gz: 1bfdf0d1b5a6278101d7cda640ac710a1aef589e5a1adc4194876404d897a53bcfa27cd423029abc76a117eb6ab2ba13a14e605c4447c1452ab78d0f7b98b960
-  data.tar.gz: 7589590b8dcbfd4268070ce59da381741ca1643152b2689829d741a6cc325e7d9130576629a3155ba0267fb0ea86623a584f9a6e6c2956143e043da43e551501
+  metadata.gz: 6451c8b62eba1159e0233be04dabbc86bcb3b6f1dcbd6cd658c8d5517a27f1ad6a20884d30d87fabcbe75d8a51d12a6dfa2d4a59ed0adb648ce56d3b81765636
+  data.tar.gz: 3448b25930e4613a4599698d98ec1c5a2d84b113a3221d98239dc0f09351455be817882b308910bfd8bf01eab00d01670c11256624bb7cd7a30745538095c2ea

data/README.md

@@ -59,6 +59,7 @@ The AI calls tools behind the scenes to learn your app — schema, models, assoc
 | `ai "query"` | One-shot: ask, review code, confirm |
 | `ai! "query"` | Interactive: ask and keep chatting |
 | `ai? "query"` | Explain only, never executes |
+| `ai_init` | Generate/update app guide for better context |
 
 ### Multi-Step Plans
 
@@ -112,6 +113,30 @@ ai> how does sharding work?
 
 Next time, it already knows — no re-reading files, fewer tokens.
 
+### Application Guide
+
+Run `ai_init` to have the AI explore your app and generate a guide that gets loaded into every future conversation:
+
+```
+irb> ai_init
+  No existing guide. Exploring the app...
+  Thinking...
+  -> list_models
+     240 models
+  -> describe_model("User")
+     119 associations, 6 validations
+  -> describe_model("Account")
+     25 associations
+  -> search_code("Sharding", dir: "config")
+     Found 36 matches
+  ...
+  Guide saved to .console_agent/console_agent.md (3204 chars)
+```
+
+The guide is a markdown file covering your app's models, relationships, data architecture, and gotchas. Unlike memories (which require a tool call to recall), the guide is injected directly into the system prompt — so the AI starts every session already knowing your app.
+
+Run `ai_init` again anytime to update it.
+
 ### Interactive Mode
 
 ```

data/lib/console_agent/console_methods.rb

@@ -130,12 +130,26 @@ module ConsoleAgent
       nil
     end
 
+    def ai_init
+      require 'console_agent/context_builder'
+      require 'console_agent/providers/base'
+      require 'console_agent/executor'
+      require 'console_agent/repl'
+
+      repl = Repl.new(__console_agent_binding)
+      repl.init_guide
+    rescue => e
+      $stderr.puts "\e[31mConsoleAgent error: #{e.message}\e[0m"
+      nil
+    end
+
     def ai(query = nil)
       if query.nil?
         $stderr.puts "\e[33mUsage: ai \"your question here\"\e[0m"
         $stderr.puts "\e[33m  ai  \"query\"  - ask + confirm execution\e[0m"
         $stderr.puts "\e[33m  ai! \"query\"  - enter interactive mode (or ai! with no args)\e[0m"
         $stderr.puts "\e[33m  ai? \"query\"  - explain only, no execution\e[0m"
+        $stderr.puts "\e[33m  ai_init      - generate/update app guide for better AI context\e[0m"
         $stderr.puts "\e[33m  ai_sessions  - list recent sessions\e[0m"
         $stderr.puts "\e[33m  ai_resume    - resume a session by name or id\e[0m"
         $stderr.puts "\e[33m  ai_name      - name a session: ai_name 42, \"my_label\"\e[0m"

data/lib/console_agent/context_builder.rb

@@ -15,10 +15,32 @@ module ConsoleAgent
       parts = []
       parts << smart_system_instructions
       parts << environment_context
+      parts << guide_context
       parts << memory_context
       parts.compact.join("\n\n")
     end
 
+    def environment_context
+      lines = ["## Environment"]
+      lines << "- Ruby #{RUBY_VERSION}"
+      lines << "- Rails #{Rails.version}" if defined?(Rails) && Rails.respond_to?(:version)
+
+      if defined?(ActiveRecord::Base) && ActiveRecord::Base.connected?
+        adapter = ActiveRecord::Base.connection.adapter_name rescue 'unknown'
+        lines << "- Database adapter: #{adapter}"
+      end
+
+      if defined?(Bundler)
+        key_gems = %w[devise cancancan pundit sidekiq delayed_job resque
+                      paperclip carrierwave activestorage shrine
+                      pg mysql2 sqlite3 mongoid]
+        loaded = key_gems.select { |g| Gem.loaded_specs.key?(g) }
+        lines << "- Key gems: #{loaded.join(', ')}" unless loaded.empty?
+      end
+
+      lines.join("\n")
+    end
+
     private
 
     def smart_system_instructions
@@ -67,25 +89,14 @@ module ConsoleAgent
       PROMPT
     end
 
-    def environment_context
-      lines = ["## Environment"]
-      lines << "- Ruby #{RUBY_VERSION}"
-      lines << "- Rails #{Rails.version}" if defined?(Rails) && Rails.respond_to?(:version)
-
-      if defined?(ActiveRecord::Base) && ActiveRecord::Base.connected?
-        adapter = ActiveRecord::Base.connection.adapter_name rescue 'unknown'
-        lines << "- Database adapter: #{adapter}"
-      end
-
-      if defined?(Bundler)
-        key_gems = %w[devise cancancan pundit sidekiq delayed_job resque
-                      paperclip carrierwave activestorage shrine
-                      pg mysql2 sqlite3 mongoid]
-        loaded = key_gems.select { |g| Gem.loaded_specs.key?(g) }
-        lines << "- Key gems: #{loaded.join(', ')}" unless loaded.empty?
-      end
+    def guide_context
+      content = ConsoleAgent.storage.read(ConsoleAgent::GUIDE_KEY)
+      return nil if content.nil? || content.strip.empty?
 
-      lines.join("\n")
+      "## Application Guide\n\n#{content.strip}"
+    rescue => e
+      ConsoleAgent.logger.debug("ConsoleAgent: guide context failed: #{e.message}")
+      nil
     end
 
     def memory_context

data/lib/console_agent/railtie.rb

@@ -15,7 +15,7 @@ module ConsoleAgent
 
       # Welcome message
       if $stdout.respond_to?(:tty?) && $stdout.tty?
-        $stdout.puts "\e[36m[ConsoleAgent] AI assistant loaded. Try: ai \"show me all tables\"\e[0m"
+        $stdout.puts "\e[36m[ConsoleAgent v#{ConsoleAgent::VERSION}] AI assistant loaded. Try: ai \"show me all tables\"\e[0m"
       end
 
       # Pre-build context in background

data/lib/console_agent/repl.rb

@@ -90,6 +90,62 @@ module ConsoleAgent
       nil
     end
 
+    def init_guide
+      storage = ConsoleAgent.storage
+      existing_guide = begin
+        content = storage.read(ConsoleAgent::GUIDE_KEY)
+        (content && !content.strip.empty?) ? content.strip : nil
+      rescue
+        nil
+      end
+
+      if existing_guide
+        $stdout.puts "\e[36m  Existing guide found (#{existing_guide.length} chars). Will update.\e[0m"
+      else
+        $stdout.puts "\e[36m  No existing guide. Exploring the app...\e[0m"
+      end
+
+      require 'console_agent/tools/registry'
+      init_tools = Tools::Registry.new(mode: :init)
+      sys_prompt = init_system_prompt(existing_guide)
+      messages = [{ role: :user, content: "Explore this Rails application and generate the application guide." }]
+
+      # Temporarily increase timeout — init conversations are large
+      original_timeout = ConsoleAgent.configuration.timeout
+      ConsoleAgent.configuration.timeout = [original_timeout, 120].max
+
+      result, _ = send_query_with_tools(messages, system_prompt: sys_prompt, tools_override: init_tools)
+
+      guide_text = result.text.to_s.strip
+      # Strip markdown code fences if the LLM wrapped the response
+      guide_text = guide_text.sub(/\A```(?:markdown)?\s*\n?/, '').sub(/\n?```\s*\z/, '')
+      # Strip LLM preamble/thinking before the actual guide content
+      guide_text = guide_text.sub(/\A.*?(?=^#\s)/m, '') if guide_text =~ /^#\s/m
+
+      if guide_text.empty?
+        $stdout.puts "\e[33m  No guide content generated.\e[0m"
+        return nil
+      end
+
+      storage.write(ConsoleAgent::GUIDE_KEY, guide_text)
+
+      path = storage.respond_to?(:root_path) ? File.join(storage.root_path, ConsoleAgent::GUIDE_KEY) : ConsoleAgent::GUIDE_KEY
+      $stdout.puts "\e[32m  Guide saved to #{path} (#{guide_text.length} chars)\e[0m"
+      display_usage(result)
+      nil
+    rescue Interrupt
+      $stdout.puts "\n\e[33m  Interrupted.\e[0m"
+      nil
+    rescue Providers::ProviderError => e
+      $stderr.puts "\e[31mConsoleAgent Error: #{e.message}\e[0m"
+      nil
+    rescue => e
+      $stderr.puts "\e[31mConsoleAgent Error: #{e.class}: #{e.message}\e[0m"
+      nil
+    ensure
+      ConsoleAgent.configuration.timeout = original_timeout if original_timeout
+    end
+
     def interactive
       init_interactive_state
       interactive_loop
@@ -330,6 +386,50 @@ module ConsoleAgent
       @context ||= context_builder.build
     end
 
+    def init_system_prompt(existing_guide)
+      env = context_builder.environment_context
+
+      prompt = <<~PROMPT
+        You are a Rails application analyst. Your job is to explore this Rails app using the
+        available tools and produce a concise markdown guide that will be injected into future
+        AI assistant sessions.
+
+        #{env}
+
+        EXPLORATION STRATEGY — be efficient to avoid timeouts:
+        1. Start with list_models to see all models and their associations
+        2. Pick the 5-8 CORE models and call describe_model on those only
+        3. Call describe_table on only 3-5 key tables (skip tables whose models already told you enough)
+        4. Use search_code sparingly — only for specific patterns you suspect (sharding, STI, concerns)
+        5. Use read_file only when you need to understand a specific pattern (read small sections, not whole files)
+        6. Do NOT exhaustively describe every table or model — focus on what's important
+
+        IMPORTANT: Keep your total tool calls under 20. Prioritize breadth over depth.
+
+        Produce a markdown document with these sections:
+        - **Application Overview**: What the app does, key domain concepts
+        - **Key Models & Relationships**: Core models and how they relate
+        - **Data Architecture**: Important tables, notable columns, any partitioning/sharding
+        - **Important Patterns**: Custom concerns, service objects, key abstractions
+        - **Common Maintenance Tasks**: Typical console operations for this app
+        - **Gotchas**: Non-obvious behaviors, tricky associations, known quirks
+
+        Keep it concise — aim for 1-2 pages. Focus on what a console user needs to know.
+        Do NOT wrap the output in markdown code fences.
+      PROMPT
+
+      if existing_guide
+        prompt += <<~UPDATE
+
+          Here is the existing guide. Update and merge with any new findings:
+
+          #{existing_guide}
+        UPDATE
+      end
+
+      prompt.strip
+    end
+
     def send_query(query, conversation: nil)
       ConsoleAgent.configuration.validate!
 
@@ -342,45 +442,43 @@ module ConsoleAgent
       send_query_with_tools(messages)
     end
 
-    def send_query_with_tools(messages)
+    def send_query_with_tools(messages, system_prompt: nil, tools_override: nil)
       require 'console_agent/tools/registry'
-      tools = Tools::Registry.new(executor: @executor)
+      tools = tools_override || Tools::Registry.new(executor: @executor)
+      active_system_prompt = system_prompt || context
       max_rounds = ConsoleAgent.configuration.max_tool_rounds
       total_input = 0
       total_output = 0
       result = nil
       new_messages = []  # Track messages added during tool use
+      last_thinking = nil
+      last_tool_names = []
 
       exhausted = false
 
       max_rounds.times do |round|
         if round == 0
           $stdout.puts "\e[2m  Thinking...\e[0m"
+        else
+          # Show buffered thinking text before the "Calling LLM" line
+          if last_thinking
+            last_thinking.split("\n").each do |line|
+              $stdout.puts "\e[2m  #{line}\e[0m"
+            end
+          end
+          $stdout.puts "\e[2m  #{llm_status(round, messages, total_input, last_thinking, last_tool_names)}\e[0m"
         end
 
-        begin
-          result = with_escape_monitoring do
-            provider.chat_with_tools(messages, tools: tools, system_prompt: context)
-          end
-        rescue Interrupt
-          redirect = prompt_for_redirect
-          if redirect
-            messages << { role: :user, content: redirect }
-            new_messages << messages.last
-            next
-          else
-            raise
-          end
+        result = with_escape_monitoring do
+          provider.chat_with_tools(messages, tools: tools, system_prompt: active_system_prompt)
         end
         total_input += result.input_tokens || 0
         total_output += result.output_tokens || 0
 
         break unless result.tool_use?
 
-        # Show what the LLM is thinking (if it returned text alongside tool calls)
-        if result.text && !result.text.strip.empty?
-          $stdout.puts "\e[2m  #{result.text.strip}\e[0m"
-        end
+        # Buffer thinking text for display before next LLM call
+        last_thinking = (result.text && !result.text.strip.empty?) ? result.text.strip : nil
 
         # Add assistant message with tool calls to conversation
         assistant_msg = provider.format_assistant_message(result)
@@ -388,6 +486,7 @@ module ConsoleAgent
         new_messages << assistant_msg
 
         # Execute each tool and show progress
+        last_tool_names = result.tool_calls.map { |tc| tc[:name] }
         result.tool_calls.each do |tc|
           # ask_user and execute_plan handle their own display
           if tc[:name] == 'ask_user' || tc[:name] == 'execute_plan'
@@ -419,7 +518,7 @@ module ConsoleAgent
       if exhausted
         $stdout.puts "\e[33m  Hit tool round limit (#{max_rounds}). Forcing final answer. Increase with: ConsoleAgent.configure { |c| c.max_tool_rounds = 200 }\e[0m"
         messages << { role: :user, content: "You've used all available tool rounds. Please provide your best answer now based on what you've learned so far." }
-        result = provider.chat(messages, system_prompt: context)
+        result = provider.chat(messages, system_prompt: active_system_prompt)
         total_input += result.input_tokens || 0
         total_output += result.output_tokens || 0
       end
@@ -477,13 +576,29 @@ module ConsoleAgent
       end
     end
 
-    def prompt_for_redirect
-      $stdout.puts "\n\e[33m  Interrupted. What should the AI do differently?\e[0m"
-      $stdout.puts "\e[2m  (Press Enter with no input to abort entirely)\e[0m"
-      $stdout.print "\e[33m  redirect> \e[0m"
-      input = $stdin.gets
-      return nil if input.nil? || input.strip.empty?
-      input.strip
+
+    def llm_status(round, messages, tokens_so_far, last_thinking = nil, last_tool_names = [])
+      status = "Calling LLM (round #{round + 1}, #{messages.length} msgs"
+      status += ", ~#{format_tokens(tokens_so_far)} ctx" if tokens_so_far > 0
+      status += ")"
+      if !last_thinking && last_tool_names.any?
+        # Summarize tools when there's no thinking text
+        counts = last_tool_names.tally
+        summary = counts.map { |name, n| n > 1 ? "#{name} x#{n}" : name }.join(", ")
+        status += " after #{summary}"
+      end
+      status += "..."
+      status
+    end
+
+    def format_tokens(count)
+      if count >= 1_000_000
+        "#{(count / 1_000_000.0).round(1)}M"
+      elsif count >= 1_000
+        "#{(count / 1_000.0).round(1)}K"
+      else
+        count.to_s
+      end
     end
 
     def format_tool_args(name, args)
@@ -547,8 +662,12 @@ module ConsoleAgent
         lines = result.split("\n")
         "#{lines.length} files"
       when 'read_file'
-        lines = result.split("\n")
-        "#{lines.length} lines"
+        if result =~ /^Lines (\d+)-(\d+) of (\d+):/
+          "lines #{$1}-#{$2} of #{$3}"
+        else
+          lines = result.split("\n")
+          "#{lines.length} lines"
+        end
       when 'search_code'
         if result.start_with?('Found')
           result.split("\n").first

data/lib/console_agent/tools/code_tools.rb

@@ -1,7 +1,7 @@
 module ConsoleAgent
   module Tools
     class CodeTools
-      MAX_FILE_LINES = 200
+      MAX_FILE_LINES = 500
       MAX_LIST_ENTRIES = 100
       MAX_SEARCH_RESULTS = 50
 
@@ -28,7 +28,7 @@ module ConsoleAgent
         "Error listing files: #{e.message}"
       end
 
-      def read_file(path)
+      def read_file(path, start_line: nil, end_line: nil)
         return "Error: path is required." if path.nil? || path.strip.empty?
 
         root = rails_root
@@ -45,12 +45,24 @@ module ConsoleAgent
         return "File '#{path}' not found." unless File.exist?(full_path)
         return "Error: '#{path}' is a directory, not a file." if File.directory?(full_path)
 
-        lines = File.readlines(full_path)
-        if lines.length > MAX_FILE_LINES
-          numbered = lines.first(MAX_FILE_LINES).each_with_index.map { |line, i| "#{i + 1}: #{line}" }
-          numbered.join + "\n... truncated (#{lines.length} total lines, showing first #{MAX_FILE_LINES})"
+        all_lines = File.readlines(full_path)
+        total = all_lines.length
+
+        # Apply line range if specified (1-based, inclusive)
+        if start_line || end_line
+          s = [(start_line || 1).to_i, 1].max
+          e = [(end_line || total).to_i, total].min
+          return "Error: start_line (#{s}) is beyond end of file (#{total} lines)." if s > total
+          lines = all_lines[(s - 1)..(e - 1)] || []
+          offset = s - 1
+          numbered = lines.each_with_index.map { |line, i| "#{offset + i + 1}: #{line}" }
+          header = "Lines #{s}-#{[e, s + lines.length - 1].min} of #{total}:\n"
+          header + numbered.join
+        elsif total > MAX_FILE_LINES
+          numbered = all_lines.first(MAX_FILE_LINES).each_with_index.map { |line, i| "#{i + 1}: #{line}" }
+          numbered.join + "\n... truncated (#{total} total lines, showing first #{MAX_FILE_LINES}). Use start_line/end_line to read specific sections."
         else
-          lines.each_with_index.map { |line, i| "#{i + 1}: #{line}" }.join
+          all_lines.each_with_index.map { |line, i| "#{i + 1}: #{line}" }.join
         end
       rescue => e
         "Error reading file '#{path}': #{e.message}"

data/lib/console_agent/tools/registry.rb

@@ -8,8 +8,9 @@ module ConsoleAgent
       # Tools that should never be cached (side effects or user interaction)
       NO_CACHE = %w[ask_user save_memory delete_memory execute_plan].freeze
 
-      def initialize(executor: nil)
+      def initialize(executor: nil, mode: :default)
         @executor = executor
+        @mode = mode
         @definitions = []
         @handlers = {}
         @cache = {}
@@ -142,15 +143,17 @@ module ConsoleAgent
 
         register(
           name: 'read_file',
-          description: 'Read the contents of a file in this Rails app. Capped at 200 lines.',
+          description: 'Read the contents of a file in this Rails app. Returns up to 500 lines by default. Use start_line/end_line to read specific sections of large files.',
           parameters: {
             'type' => 'object',
             'properties' => {
-              'path' => { 'type' => 'string', 'description' => 'Relative file path (e.g. "app/models/user.rb")' }
+              'path' => { 'type' => 'string', 'description' => 'Relative file path (e.g. "app/models/user.rb")' },
+              'start_line' => { 'type' => 'integer', 'description' => 'First line to read (1-based). Optional — omit to start from beginning.' },
+              'end_line' => { 'type' => 'integer', 'description' => 'Last line to read (1-based, inclusive). Optional — omit to read to end.' }
             },
             'required' => ['path']
           },
-          handler: ->(args) { code.read_file(args['path']) }
+          handler: ->(args) { code.read_file(args['path'], start_line: args['start_line'], end_line: args['end_line']) }
         )
 
         register(
@@ -167,21 +170,23 @@ module ConsoleAgent
           handler: ->(args) { code.search_code(args['query'], args['directory']) }
         )
 
-        register(
-          name: 'ask_user',
-          description: 'Ask the console user a clarifying question. Use this when you need specific information to write accurate code (e.g. which user they are, which record to target, what value to use). Do NOT generate placeholder values like YOUR_USER_ID — ask instead.',
-          parameters: {
-            'type' => 'object',
-            'properties' => {
-              'question' => { 'type' => 'string', 'description' => 'The question to ask the user' }
+        unless @mode == :init
+          register(
+            name: 'ask_user',
+            description: 'Ask the console user a clarifying question. Use this when you need specific information to write accurate code (e.g. which user they are, which record to target, what value to use). Do NOT generate placeholder values like YOUR_USER_ID — ask instead.',
+            parameters: {
+              'type' => 'object',
+              'properties' => {
+                'question' => { 'type' => 'string', 'description' => 'The question to ask the user' }
+              },
+              'required' => ['question']
             },
-            'required' => ['question']
-          },
-          handler: ->(args) { ask_user(args['question']) }
-        )
+            handler: ->(args) { ask_user(args['question']) }
+          )
 
-        register_memory_tools
-        register_execute_plan
+          register_memory_tools
+          register_execute_plan
+        end
       end
 
       def register_memory_tools

data/lib/console_agent/version.rb

@@ -1,3 +1,3 @@
 module ConsoleAgent
-  VERSION = '0.5.0'.freeze
+  VERSION = '0.6.0'.freeze
 end

data/lib/console_agent.rb

@@ -2,6 +2,8 @@ require 'console_agent/version'
 require 'console_agent/configuration'
 
 module ConsoleAgent
+  GUIDE_KEY = 'console_agent.md'.freeze
+
   class << self
     def configuration
       @configuration ||= Configuration.new

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: console_agent
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Cortfr