girb 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '048b4dc3910c2afaa9bb1bd2a1f2f33f51b631b74405368daabec4cbf1ef1e2a'
-  data.tar.gz: d5b46f5c7c0f809053c8b38fd15f9af6709338c62cb2374f0a64b25f283b1807
+  metadata.gz: 3fb74de93bd206f42859682f712f57bf0603c2348e665775b6c19833af65fd1f
+  data.tar.gz: af6f430afff9ca6123bddfc4a87820956cbff3fda65721d86f39f5ad688cdea5
 SHA512:
-  metadata.gz: 3e064f6e9a5dcd1ea6af090ccfc9aff2acc476fcafff772aed594ff15ecb95cfe6513e8e7facccbea490d82d691b9e495d4134fe418f8fb2d0b7bfab0e40fe25
-  data.tar.gz: 3287871b7937ea1234fdb18c6e551b96da944b12a57305b3e6c5fe5e63d2d602afa04aedc88192331176b70062ad4efc1bcfeb5c7bf3285ce603a3e090a1f005
+  metadata.gz: 8998f2942d8cf0ed23012c65dbede91b88231a0e26e31ed2b808c8cc513dc69bf162fb709320768880f59536ab5a5e1031fac0f8ac5cfdb096281d0abcae3b49
+  data.tar.gz: 1fda60427ec07042e05d2840f4ef99ba0740552e3735b10012d46c990ba62deeb653c21fc19c5653ae03e60150af9083fa3869deace3c7b3e0780632a0cbaa59

data/CHANGELOG.md

@@ -1,11 +1,52 @@
 # 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
-  - `ai <question>` command in debugger
+  - `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.)

data/README.md

@@ -1,40 +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
-- **Autonomous Investigation**: AI can loop through investigate-execute-analyze cycles using `continue_analysis`
-- **Debug Gem Integration**: Use with Ruby's debug gem for step-through debugging with AI assistance
-- **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
@@ -45,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,111 +189,192 @@ def problematic_method
 end
 ```
 
-### Debug with debug gem (rdbg)
+### How to Ask AI
 
-For step-through debugging with AI assistance, add `require "girb"` to your script:
+**Ctrl+Space**: Press after typing your question
 
-```ruby
-require "girb"
+```
+irb(main):001> Why did this fail?[Ctrl+Space]
+```
 
-def problematic_method
-  result = some_calculation
-  result
-end
+**qq command**: Use the qq method
 
-problematic_method
 ```
+irb(main):001> qq How do I use this method?
+```
+
+### 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> 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, :+)`.
+```
+
+---
+
+## 3. Rails
+
+### Installation
+
+Add to your Gemfile:
 
-Then run with rdbg:
+```ruby
+group :development do
+  gem 'girb'
+  gem 'girb-ruby_llm'
+end
+```
 
 ```bash
-rdbg your_script.rb
+bundle install
 ```
 
-In the debugger, use:
-- `ai <question>` - Ask AI a question
-- `Ctrl+Space` - Send current input to AI
-- Natural language (non-ASCII) input is automatically routed to AI
+### Configuration
 
-The AI can execute debugger commands like `step`, `next`, `continue`, and set breakpoints for you.
+Create `.girbrc` in your Rails project root. See [Configuration](#1-configuration) for details.
 
-### How to Ask AI
+### Usage
 
-#### Method 1: Ctrl+Space
+Just run `rails console` - girb loads automatically via Railtie:
 
-Press `Ctrl+Space` after typing to send your input as a question to AI.
+```bash
+rails console
+```
+
+### Additional Tools (Rails)
+
+| Tool | Description |
+|------|-------------|
+| `query_model` | Execute ActiveRecord queries |
+| `model_info` | Get model schema information |
+
+### Example
 
 ```
-irb(main):001> What's causing this error?[Ctrl+Space]
+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.
 ```
 
-#### Method 2: qq command
+---
+
+## 4. Debug Gem (rdbg)
 
+Step-through debugging with AI assistance.
+
+### 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
+
+calculate(5)
 ```
-irb(main):001> qq "How do I use this method?"
+
+Run with ruby:
+
+```bash
+ruby your_script.rb
 ```
 
-## Configuration Options
+### For Rails
 
-Add to your `.girbrc`:
+Create an initializer to load girb after debug gem:
 
 ```ruby
-require 'girb-ruby_llm'
+# config/initializers/girb.rb
+require "girb" if Rails.env.development? || Rails.env.test?
+```
 
-Girb.configure do |c|
-  # Debug output (default: false)
-  c.debug = true
+Then use `debugger` statement in your code:
 
-  # Custom prompt (optional)
-  c.custom_prompt = <<~PROMPT
-    This is a production environment. Always confirm before destructive operations.
-  PROMPT
+```ruby
+def show
+  @user = User.find(params[:id])
+  debugger  # Stops here with AI assistance
 end
 ```
 
-### Command Line Options
+### How to Ask AI (Debug Mode)
 
-```bash
-girb --debug    # Enable debug output
-girb -d         # Same as above
-girb --help     # Show help
+- **`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
+
+```
+(rdbg) qq What is the value of result here?
+(rdbg) 次の行に進んで[Ctrl+Space]
 ```
 
-### Environment Variables
+### AI Can Execute Debug Commands
 
-For `girb` command, you can also configure via environment variables (used when no `.girbrc` is found):
+The AI can run debugger commands for you:
 
-| 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 |
+```
+(rdbg) qq Step through this loop and tell me when x becomes 1
+```
+
+The AI will use `step`, `next`, `continue`, `break`, etc. automatically.
+
+### Ctrl+C to Interrupt
 
-## Available Tools
+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 IRB context |
+| `evaluate_code` | Execute Ruby code in current 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 |
-| `continue_analysis` | Request context refresh for autonomous investigation |
+| `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 |
 
-### Additional Tools in Rails Environment
+### Example: Variable Tracking
 
-| Tool | Description |
-|------|-------------|
-| `query_model` | Execute queries on ActiveRecord models |
-| `model_info` | Get model schema information |
+```
+(rdbg) qq Track all values of x through this loop and report when done
 
-### Additional Tools in Debug Mode (rdbg)
+[AI sets breakpoints, runs continue, collects values]
 
-| Tool | Description |
-|------|-------------|
-| `run_debug_command` | Execute debugger commands (step, next, continue, break, etc.) |
+Tracked values of x: [7, 66, 85, 11, 53, 42, 99, 23]
+Loop completed.
+```
+
+---
 
 ## Custom Providers
 
@@ -234,61 +386,26 @@ class MyProvider < Girb::Providers::Base
     @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: {...} }
-
-    # Call your LLM API here
+  def chat(messages:, system_prompt:, tools:, binding: nil)
+    # Call your LLM API
     response = call_my_llm(messages, system_prompt, tools)
 
-    # 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
 end
-
-Girb.configure do |c|
-  c.provider = MyProvider.new(api_key: ENV['MY_API_KEY'])
-end
 ```
 
-## Examples
-
-### Debugging Assistance
-
-```
-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.
-```
-
-### Code Understanding
-
-```
-irb(main):001> Where is the User model defined in this project?[Ctrl+Space]
-It's defined in app/models/user.rb.
-```
-
-### Pattern Recognition
-
-```
-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.
-```
+---
 
 ## 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
 
@@ -296,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).