girb 0.1.2 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 69a7d9cee0ae606d21d75c1fc94c1aef3665c8e38e4f704c9e8f899d7e70b943
-  data.tar.gz: 898823b1d088a67f8adb5e93705bb547d623eb0564d1831fe39cfa98757e233e
+  metadata.gz: 3fb74de93bd206f42859682f712f57bf0603c2348e665775b6c19833af65fd1f
+  data.tar.gz: af6f430afff9ca6123bddfc4a87820956cbff3fda65721d86f39f5ad688cdea5
 SHA512:
-  metadata.gz: 93e107025ea0480db5b0403531a3af424836dfbef23a7f7f174e8c89036b1b3d140571ba0334a3c2f1ff7fda89ab91df2c5478f18f945474fd1ca836eb3ae5c3
-  data.tar.gz: bd5097cc780074724642e3c2932d23178eea0140e6bdd9460489abb97a0ac3f567577d1ecd6153d29ef896ed6803ed9c1988995d64ffd47db3c08dac702f6b21
+  metadata.gz: 8998f2942d8cf0ed23012c65dbede91b88231a0e26e31ed2b808c8cc513dc69bf162fb709320768880f59536ab5a5e1031fac0f8ac5cfdb096281d0abcae3b49
+  data.tar.gz: 1fda60427ec07042e05d2840f4ef99ba0740552e3735b10012d46c990ba62deeb653c21fc19c5653ae03e60150af9083fa3869deace3c7b3e0780632a0cbaa59

data/CHANGELOG.md

@@ -1,5 +1,84 @@
 # Changelog
 
+## [0.3.0] - 2026-02-07
+
+### Added
+
+- **Session persistence**: Persist AI conversation history across sessions
+  - Enable with `Girb.debug_session = "session_name"`
+  - `qq session status/list/clear` commands for session management
+  - Sessions saved to `.girb/sessions/<session_id>.json`
+  - Auto-cleanup of sessions inactive for 7+ days
+  - Works in both IRB and debug modes
+- **Persisted conversations in `get_session_history` tool**
+  - Access previous session's AI conversations
+- **`run_debug_command` tool for IRB mode**
+  - AI can now execute debug commands (next, step, continue, etc.) in `binding.girb`
+  - Enables autonomous step-by-step debugging in IRB sessions
+- **Seamless `binding.girb` to debug mode transition**
+  - When AI executes debug commands (next, step, etc.) in `binding.girb`, automatically transitions to debug mode
+  - Original user instruction is preserved and passed to debug mode for continuous execution
+  - AI can autonomously step through code with `auto_continue: true`
+
+### Changed
+
+- Debug mode AI command changed from `ai` to `qq` (consistent with IRB mode)
+- Separate prompts for different modes (auto-detected):
+  - Breakpoint mode (`binding.girb`): Focus on actual code in file
+  - Interactive mode (`girb` command): Focus on session history
+  - Rails mode (`rails console`): Rails-specific guidance
+- Debug commands in IRB mode are now injected via `ReadmultilinePatch` to ensure proper execution at IRB's top level
+- Improved debug prompt to prefer conditional breakpoints for loops (efficient) over repeated stepping (slow)
+- Continuation message now warns AI not to re-execute already-run commands
+
+### Fixed
+
+- Exclude forwardable from exception capture (false SyntaxError detection)
+- Exclude rubygems from exception capture (false LoadError during gem activation)
+- Fix `binding.girb` Ctrl+Space keybinding registration
+- Fix `binding.girb` not loading `.girbrc` (provider configuration missing)
+- Fix `binding.girb` to properly pass binding context (debug commands now work on user's script)
+- Fix deadlock when making API calls in debug mode by temporarily disabling Ruby's `Timeout` module
+- Fix `GIRB_DIR` constant scope for proper frame filtering in debugger
+
+## [0.2.0] - 2026-02-05
+
+### Added
+
+- **Debug gem (rdbg) integration**: AI assistant for step-through debugging
+  - `qq <question>` command in debugger
+  - Ctrl+Space to send input to AI
+  - Auto-routing of non-ASCII (Japanese) input to AI
+  - `run_debug_command` tool for AI to execute debugger commands (step, next, continue, break, etc.)
+- **Auto-continue for autonomous AI investigation**
+  - `continue_analysis` tool for IRB mode context refresh
+  - AI can loop through investigate-execute-analyze cycles
+  - Configurable iteration limits (MAX_ITERATIONS = 20)
+- **Ctrl+C interrupt support** for both IRB and debug modes
+  - Graceful interruption of long-running AI operations
+  - AI summarizes progress when interrupted
+- **Debug session history tracking**
+  - Track debugger commands and AI conversations
+  - `get_session_history` tool for debug mode
+- **Efficient variable tracking** with silent breakpoints
+  - `break file:line if: ($var << x; false)` pattern for recording without stopping
+
+### Changed
+
+- Separate tool sets for IRB and debug modes
+  - SHARED_TOOLS: Common tools for both modes
+  - IRB_TOOLS: SessionHistoryTool, ContinueAnalysis
+  - DEBUG_TOOLS: DebugSessionHistoryTool, RunDebugCommand
+- Improved prompts for debug mode
+  - Guidance on variable persistence across frames
+  - Instructions for efficient breakpoint usage
+  - Context-aware investigation (don't use tools for greetings)
+
+### Fixed
+
+- Tool calls now include IDs for proper conversation history
+- Auto-continue loop properly exits when debug commands are queued
+
 ## [0.1.2] - 2026-02-03
 
 ### Added
@@ -7,6 +86,7 @@
 - `.girbrc` configuration file support with directory traversal
 - Railtie for automatic Rails console integration
 - GirbrcLoader utility for finding and loading `.girbrc` files
+- `get_current_directory` tool for non-Rails environments
 
 ### Changed
 

data/README.md

@@ -1,38 +1,77 @@
 # girb (Generative IRB)
 
-An AI assistant embedded in your IRB session. It understands your runtime context and helps with debugging and development.
+An AI assistant for Ruby development. Works with IRB, Rails console, and the debug gem.
 
 [日本語版 README](README_ja.md)
 
 ## Features
 
-- **Context Awareness**: Automatically understands local variables, instance variables, and self object
-- **Exception Capture**: Automatically captures recent exceptions - just ask "why did this fail?" after an error
-- **Session History Understanding**: Tracks IRB input history and understands conversation flow
-- **Tool Execution**: AI autonomously executes code, inspects objects, and retrieves source code
-- **Multi-language Support**: Detects user's language and responds in the same language
-- **Customizable**: Add custom prompts for project-specific instructions
-- **Provider Agnostic**: Use any LLM provider or implement your own
+- **Context Awareness**: Understands local variables, instance variables, and runtime state
+- **Tool Execution**: AI autonomously executes code, inspects objects, and reads files
+- **Autonomous Investigation**: AI loops through investigate-execute-analyze cycles
+- **Multi-environment Support**: Works with IRB, Rails console, and debug gem (rdbg)
+- **Provider Agnostic**: Use any LLM (OpenAI, Anthropic, Gemini, Ollama, etc.)
 
-## Installation
+## Quick Start
 
-### For Rails Projects
+```bash
+# 1. Install
+gem install girb girb-ruby_llm
 
-Add to your Gemfile:
+# 2. Set your API key
+export GEMINI_API_KEY="your-api-key"  # or OPENAI_API_KEY, ANTHROPIC_API_KEY
 
+# 3. Create ~/.girbrc
 ```ruby
-group :development do
-  gem 'girb-ruby_llm'  # or girb-gemini
+require 'girb-ruby_llm'
+Girb.configure do |c|
+  c.provider = Girb::Providers::RubyLlm.new(model: 'gemini-2.5-flash')
 end
 ```
 
-Then run:
+# 4. Run
+girb
+```
+
+Then type a question and press **Ctrl+Space**, or use `qq <question>`.
+
+## Table of Contents
+
+1. [Configuration](#1-configuration) - Common setup for all environments
+2. [Ruby Scripts (IRB)](#2-ruby-scripts-irb) - Using with pure Ruby
+3. [Rails](#3-rails) - Using with Rails console
+4. [Debug Gem (rdbg)](#4-debug-gem-rdbg) - Step-through debugging with AI
+
+---
+
+## 1. Configuration
+
+### Installation
 
 ```bash
-bundle install
+gem install girb girb-ruby_llm
+```
+
+Available provider gems:
+- [girb-ruby_llm](https://github.com/rira100000000/girb-ruby_llm) - OpenAI, Anthropic, Gemini, Ollama, etc. (Recommended)
+- [girb-gemini](https://github.com/rira100000000/girb-gemini) - Google Gemini only
+
+### API Keys
+
+Set the API key for your chosen LLM provider as an environment variable:
+
+```bash
+export GEMINI_API_KEY="your-api-key"
+# or OPENAI_API_KEY, ANTHROPIC_API_KEY, etc.
 ```
 
-Create a `.girbrc` file in your project root:
+For detailed setup instructions (Ollama, other providers, advanced options), see the provider gem documentation:
+- [girb-ruby_llm](https://github.com/rira100000000/girb-ruby_llm)
+- [girb-gemini](https://github.com/rira100000000/girb-gemini)
+
+### Create .girbrc
+
+Create a `.girbrc` file in your project root (or home directory for global config):
 
 ```ruby
 # .girbrc
@@ -43,70 +82,104 @@ Girb.configure do |c|
 end
 ```
 
-Now `rails console` will automatically load girb!
+girb searches for `.girbrc` in this order:
+1. Current directory → parent directories (up to root)
+2. `~/.girbrc` as fallback
 
-### For Non-Rails Projects
+### Model Examples
 
-Install globally:
+```ruby
+# Google Gemini
+c.provider = Girb::Providers::RubyLlm.new(model: 'gemini-2.5-flash')
 
-```bash
-gem install girb girb-ruby_llm
+# OpenAI
+c.provider = Girb::Providers::RubyLlm.new(model: 'gpt-5.2-2025-12-11')
+
+# Anthropic
+c.provider = Girb::Providers::RubyLlm.new(model: 'claude-opus-4-5')
 ```
 
-Create a `.girbrc` file in your project directory:
+### Configuration Options
 
 ```ruby
-# .girbrc
-require 'girb-ruby_llm'
-
 Girb.configure do |c|
+  # Required: LLM provider
   c.provider = Girb::Providers::RubyLlm.new(model: 'gemini-2.5-flash')
+
+  # Optional: Debug output
+  c.debug = true
+
+  # Optional: Custom system prompt
+  c.custom_prompt = <<~PROMPT
+    This is production. Always confirm before destructive operations.
+  PROMPT
 end
 ```
 
-Then use `girb` command instead of `irb`.
+### Environment Variables (Fallback)
 
-## How .girbrc Works
+Used when provider is not configured in `.girbrc`:
 
-girb searches for `.girbrc` in the following order:
+| Variable | Description |
+|----------|-------------|
+| `GIRB_PROVIDER` | Provider gem (e.g., `girb-ruby_llm`) |
+| `GIRB_MODEL` | Model name (e.g., `gemini-2.5-flash`) |
+| `GIRB_DEBUG` | Set to `1` for debug output |
 
-1. Current directory, then parent directories (up to root)
-2. `~/.girbrc` as fallback
+### Session Persistence (Optional)
+
+Persist AI conversation history across sessions. Only enabled when you explicitly set a session ID.
 
-This allows you to:
+#### Enable
 
-- **Project-specific settings**: Place `.girbrc` in your project root
-- **Shared settings**: Place `.girbrc` in a parent directory (e.g., `~/work/.girbrc` for all work projects)
-- **Global default**: Place `.girbrc` in your home directory
+Set a session ID in `.girbrc`:
 
-## Providers
+```ruby
+Girb.configure do |c|
+  c.provider = Girb::Providers::RubyLlm.new(model: 'gemini-2.5-flash')
+end
 
-Currently available providers:
+# Enable session persistence (optional)
+Girb.debug_session = "my-project"
+```
 
-- [girb-ruby_llm](https://github.com/rira100000000/girb-ruby_llm) - Multiple providers via RubyLLM (OpenAI, Anthropic, Gemini, Ollama, etc.)
-- [girb-gemini](https://github.com/rira100000000/girb-gemini) - Google Gemini
+Or set dynamically in code:
 
-You can also [create your own provider](#custom-providers).
+```ruby
+Girb.debug_session = "debug-user-auth"
+debugger  # Conversations in this session will be saved
+```
 
-## Usage
+#### Session Management Commands
 
-### For Rails Projects
+Use in IRB or debug mode:
 
-```bash
-rails console
 ```
+qq session status  # Show current session status
+qq session list    # List saved sessions
+qq session clear   # Clear current session
+```
+
+#### Behavior
 
-girb is automatically loaded via Railtie.
+- Sessions are saved to `.girb/sessions/<session_id>.json`
+- Sessions inactive for 7+ days are automatically deleted
+- Resuming with the same session ID continues the previous conversation
+- Use `get_session_history` tool to reference past conversations
 
-### For Non-Rails Projects
+---
+
+## 2. Ruby Scripts (IRB)
+
+### Usage
+
+Use `girb` command instead of `irb`:
 
 ```bash
 girb
 ```
 
-### Debug with binding.girb
-
-Insert `binding.girb` in your code:
+Or insert `binding.girb` in your code:
 
 ```ruby
 def problematic_method
@@ -118,140 +191,221 @@ end
 
 ### How to Ask AI
 
-#### Method 1: Ctrl+Space
+**Ctrl+Space**: Press after typing your question
+
+```
+irb(main):001> Why did this fail?[Ctrl+Space]
+```
 
-Press `Ctrl+Space` after typing to send your input as a question to AI.
+**qq command**: Use the qq method
 
 ```
-irb(main):001> What's causing this error?[Ctrl+Space]
+irb(main):001> qq How do I use this method?
 ```
 
-#### Method 2: qq command
+### Available Tools (IRB)
+
+| Tool | Description |
+|------|-------------|
+| `evaluate_code` | Execute Ruby code |
+| `inspect_object` | Inspect object details |
+| `get_source` | Get method/class source code |
+| `list_methods` | List methods of an object |
+| `find_file` | Search for files |
+| `read_file` | Read file contents |
+| `get_session_history` | Get IRB session history |
+| `continue_analysis` | Request context refresh for autonomous investigation |
+
+### Example
 
 ```
-irb(main):001> qq "How do I use this method?"
+irb(main):001> x = [1, 2, 3]
+irb(main):002> What methods can I use to find the sum?[Ctrl+Space]
+You can use `x.sum` which returns 6. Alternatively, `x.reduce(:+)` or `x.inject(0, :+)`.
 ```
 
-## Configuration Options
+---
 
-Add to your `.girbrc`:
+## 3. Rails
 
-```ruby
-require 'girb-ruby_llm'
+### Installation
 
-Girb.configure do |c|
-  # Debug output (default: false)
-  c.debug = true
+Add to your Gemfile:
 
-  # Custom prompt (optional)
-  c.custom_prompt = <<~PROMPT
-    This is a production environment. Always confirm before destructive operations.
-  PROMPT
+```ruby
+group :development do
+  gem 'girb'
+  gem 'girb-ruby_llm'
 end
 ```
 
-### Command Line Options
-
 ```bash
-girb --debug    # Enable debug output
-girb -d         # Same as above
-girb --help     # Show help
+bundle install
 ```
 
-### Environment Variables
+### Configuration
 
-For `girb` command, you can also configure via environment variables (used when no `.girbrc` is found):
+Create `.girbrc` in your Rails project root. See [Configuration](#1-configuration) for details.
 
-| Variable | Description |
-|----------|-------------|
-| `GIRB_PROVIDER` | Provider gem to load (e.g., `girb-ruby_llm`, `girb-gemini`) |
-| `GIRB_MODEL` | Model to use (e.g., `gemini-2.5-flash`, `gpt-4o`) |
-| `GIRB_DEBUG` | Set to `1` to enable debug output |
+### Usage
 
-## Available Tools
+Just run `rails console` - girb loads automatically via Railtie:
 
-| Tool | Description |
-|------|-------------|
-| `evaluate_code` | Execute Ruby code in IRB context |
-| `inspect_object` | Inspect object details |
-| `get_source` | Get source code of methods or classes |
-| `list_methods` | List methods of an object |
-| `find_file` | Search for files in the project |
-| `read_file` | Read file contents |
-| `session_history` | Get IRB session history |
+```bash
+rails console
+```
 
-### Additional Tools in Rails Environment
+### Additional Tools (Rails)
 
 | Tool | Description |
 |------|-------------|
-| `query_model` | Execute queries on ActiveRecord models |
+| `query_model` | Execute ActiveRecord queries |
 | `model_info` | Get model schema information |
 
-## Custom Providers
+### Example
 
-Implement your own LLM provider:
+```
+irb(main):001> user = User.find(1)
+irb(main):002> user.update(name: "test")
+=> false
+irb(main):003> Why did the update fail?[Ctrl+Space]
+Checking `user.errors.full_messages` shows:
+- "Email can't be blank"
+The email attribute is being cleared during the update.
+```
 
-```ruby
-class MyProvider < Girb::Providers::Base
-  def initialize(api_key:)
-    @api_key = api_key
-  end
+---
 
-  def chat(messages:, system_prompt:, tools:)
-    # messages: Array of { role: :user/:assistant/:tool_call/:tool_result, content: "..." }
-    # tools: Array of { name: "...", description: "...", parameters: {...} }
+## 4. Debug Gem (rdbg)
 
-    # Call your LLM API here
-    response = call_my_llm(messages, system_prompt, tools)
+Step-through debugging with AI assistance.
 
-    # Return a Response object
-    Girb::Providers::Base::Response.new(
-      text: response.text,
-      function_calls: response.tool_calls&.map { |tc| { name: tc.name, args: tc.args } }
-    )
-  end
+### Configuration
+
+Same `.girbrc` as above.
+
+### For Standalone Ruby Scripts
+
+Add `require "debug"` and `require "girb"`, then use `debugger` statement:
+
+**Note:** `require "debug"` must come before `require "girb"`.
+
+```ruby
+require "debug"
+require "girb"
+
+def calculate(x)
+  result = x * 2
+  debugger  # Stops here with AI assistance
+  result + 1
 end
 
-Girb.configure do |c|
-  c.provider = MyProvider.new(api_key: ENV['MY_API_KEY'])
+calculate(5)
+```
+
+Run with ruby:
+
+```bash
+ruby your_script.rb
+```
+
+### For Rails
+
+Create an initializer to load girb after debug gem:
+
+```ruby
+# config/initializers/girb.rb
+require "girb" if Rails.env.development? || Rails.env.test?
+```
+
+Then use `debugger` statement in your code:
+
+```ruby
+def show
+  @user = User.find(params[:id])
+  debugger  # Stops here with AI assistance
 end
 ```
 
-## Examples
+### How to Ask AI (Debug Mode)
 
-### Debugging Assistance
+- **`qq <question>`** - Ask AI a question
+- **Ctrl+Space** - Send current input to AI
+- **Natural language** - Non-ASCII input (e.g., Japanese) automatically routes to AI
 
 ```
-irb(main):001> user = User.find(1)
-irb(main):002> user.update(name: "test")
-=> false
-irb(main):003> Why did the update fail?[Ctrl+Space]
-Checking `user.errors.full_messages` shows validation errors:
-- "Email can't be blank"
-The email might be getting cleared when updating the name.
+(rdbg) qq What is the value of result here?
+(rdbg) 次の行に進んで[Ctrl+Space]
 ```
 
-### Code Understanding
+### AI Can Execute Debug Commands
+
+The AI can run debugger commands for you:
 
 ```
-irb(main):001> Where is the User model defined in this project?[Ctrl+Space]
-It's defined in app/models/user.rb.
+(rdbg) qq Step through this loop and tell me when x becomes 1
 ```
 
-### Pattern Recognition
+The AI will use `step`, `next`, `continue`, `break`, etc. automatically.
+
+### Ctrl+C to Interrupt
+
+Press Ctrl+C to interrupt long-running AI operations. The AI will summarize progress.
+
+### Available Tools (Debug Mode)
+
+| Tool | Description |
+|------|-------------|
+| `evaluate_code` | Execute Ruby code in current context |
+| `inspect_object` | Inspect object details |
+| `get_source` | Get method/class source code |
+| `read_file` | Read source files |
+| `run_debug_command` | Execute debugger commands |
+| `get_session_history` | Get debug session history |
+
+### Example: Variable Tracking
 
 ```
-irb(main):001> a = 1
-irb(main):002> b = 2
-irb(main):003> What would z be if I continue with c = 3 and beyond?[Ctrl+Space]
-Following the pattern a=1, b=2, c=3..., z would be 26.
+(rdbg) qq Track all values of x through this loop and report when done
+
+[AI sets breakpoints, runs continue, collects values]
+
+Tracked values of x: [7, 66, 85, 11, 53, 42, 99, 23]
+Loop completed.
 ```
 
+---
+
+## Custom Providers
+
+Implement your own LLM provider:
+
+```ruby
+class MyProvider < Girb::Providers::Base
+  def initialize(api_key:)
+    @api_key = api_key
+  end
+
+  def chat(messages:, system_prompt:, tools:, binding: nil)
+    # Call your LLM API
+    response = call_my_llm(messages, system_prompt, tools)
+
+    Girb::Providers::Base::Response.new(
+      text: response.text,
+      function_calls: response.tool_calls&.map { |tc| { name: tc.name, args: tc.args } }
+    )
+  end
+end
+```
+
+---
+
 ## Requirements
 
-- Ruby 3.2.0 or higher
-- IRB 1.6.0 or higher
-- An LLM provider gem (girb-ruby_llm or girb-gemini)
+- Ruby 3.2.0+
+- IRB 1.6.0+ (for IRB/Rails usage)
+- debug gem (for rdbg usage)
+- An LLM provider gem
 
 ## License
 
@@ -259,4 +413,4 @@ MIT License
 
 ## Contributing
 
-Bug reports and feature requests are welcome at [GitHub Issues](https://github.com/rira100000000/girb/issues).
+Bug reports and feature requests welcome at [GitHub Issues](https://github.com/rira100000000/girb/issues).