girb 0.2.0 → 0.3.1

data/README_ja.md

@@ -1,38 +1,75 @@
 # girb (Generative IRB)
 
-IRBセッションに組み込まれたAIアシスタント。実行中のコンテキストを理解し、デバッグや開発を支援します。
+Ruby開発のためのAIアシスタント。IRB、Rails console、debug gemで動作します。
 
 ## 特徴
 
-- **コンテキスト認識**: ローカル変数、インスタンス変数、selfオブジェクトなどを自動的に把握
-- **例外キャプチャ**: 直前の例外を自動キャプチャ - エラー後に「なぜ失敗した？」と聞くだけでOK
-- **セッション履歴の理解**: IRBでの入力履歴を追跡し、会話の流れを理解
-- **ツール実行**: コードの実行、オブジェクトの検査、ソースコードの取得などをAIが自律的に実行
-- **自律的な調査**: `continue_analysis`を使って、調査→実行→分析のサイクルをAIが自律的にループ可能
-- **debug gem統合**: Rubyのdebug gemと連携し、AIアシスタント付きのステップ実行デバッグが可能
-- **多言語対応**: ユーザーの言語を検出し、同じ言語で応答
-- **カスタマイズ可能**: 独自のプロンプトを追加して、プロジェクト固有の指示を設定可能
-- **プロバイダー非依存**: 任意のLLMプロバイダーを使用、または独自実装が可能
+- **コンテキスト認識**: ローカル変数、インスタンス変数、実行時の状態を理解
+- **ツール実行**: コード実行、オブジェクト検査、ファイル読み取りをAIが自律的に実行
+- **自律的な調査**: 調査→実行→分析のサイクルをAIがループ
+- **マルチ環境対応**: IRB、Rails console、debug gem (rdbg) で動作
+- **プロバイダー非依存**: 任意のLLM（OpenAI、Anthropic、Gemini、Ollama等）を使用可能
 
-## インストール
+## クイックスタート
 
-### Railsプロジェクトの場合
+```bash
+# 1. インストール
+gem install girb girb-ruby_llm
 
-Gemfileに追加:
+# 2. APIキーを設定
+export GEMINI_API_KEY="your-api-key"  # または OPENAI_API_KEY, ANTHROPIC_API_KEY
 
+# 3. ~/.girbrc を作成
 ```ruby
-group :development do
-  gem 'girb-ruby_llm'  # または girb-gemini
+require 'girb-ruby_llm'
+Girb.configure do |c|
+  c.provider = Girb::Providers::RubyLlm.new(model: 'gemini-2.5-flash')
 end
 ```
 
-そして実行:
+# 4. 実行
+girb
+```
+
+質問を入力して **Ctrl+Space** を押すか、`qq <質問>` を使用します。
+
+## 目次
+
+1. [設定](#1-設定) - 全環境共通のセットアップ
+2. [Rubyスクリプト (IRB)](#2-rubyスクリプト-irb) - 純粋なRubyでの使用
+3. [Rails](#3-rails) - Rails consoleでの使用
+4. [Debug Gem (rdbg)](#4-debug-gem-rdbg) - AIアシスタント付きステップ実行デバッグ
+
+---
+
+## 1. 設定
+
+### インストール
 
 ```bash
-bundle install
+gem install girb girb-ruby_llm
+```
+
+利用可能なプロバイダーgem:
+- [girb-ruby_llm](https://github.com/rira100000000/girb-ruby_llm) - OpenAI、Anthropic、Gemini、Ollama等（推奨）
+- [girb-gemini](https://github.com/rira100000000/girb-gemini) - Google Geminiのみ
+
+### APIキー
+
+使用するLLMプロバイダーのAPIキーを環境変数に設定:
+
+```bash
+export GEMINI_API_KEY="your-api-key"
+# または OPENAI_API_KEY, ANTHROPIC_API_KEY など
 ```
 
-プロジェクトルートに `.girbrc` ファイルを作成:
+詳細な設定方法（Ollama、その他のプロバイダー、高度なオプション）は、プロバイダーgemのドキュメントを参照してください:
+- [girb-ruby_llm](https://github.com/rira100000000/girb-ruby_llm)
+- [girb-gemini](https://github.com/rira100000000/girb-gemini)
+
+### .girbrcの作成
+
+プロジェクトルート（またはホームディレクトリ）に `.girbrc` ファイルを作成:
 
 ```ruby
 # .girbrc
@@ -43,70 +80,104 @@ Girb.configure do |c|
 end
 ```
 
-これで `rails console` が自動的にgirbを読み込みます！
+girbは以下の順序で `.girbrc` を探します:
+1. カレントディレクトリ → 親ディレクトリ（ルートまで）
+2. `~/.girbrc` にフォールバック
 
-### 非Railsプロジェクトの場合
+### モデルの例
 
-グローバルにインストール:
+```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')
 ```
 
-プロジェクトディレクトリに `.girbrc` ファイルを作成:
+### 設定オプション
 
 ```ruby
-# .girbrc
-require 'girb-ruby_llm'
-
 Girb.configure do |c|
+  # 必須: LLMプロバイダー
   c.provider = Girb::Providers::RubyLlm.new(model: 'gemini-2.5-flash')
+
+  # オプション: デバッグ出力
+  c.debug = true
+
+  # オプション: カスタムシステムプロンプト
+  c.custom_prompt = <<~PROMPT
+    破壊的操作の前に必ず確認してください。
+  PROMPT
 end
 ```
 
-`irb` の代わりに `girb` コマンドを使用します。
+### 環境変数（フォールバック）
 
-## .girbrc の仕組み
+`.girbrc` に設定がない場合に使用:
 
-girbは以下の順序で `.girbrc` を探します:
+| 変数 | 説明 |
+|------|------|
+| `GIRB_PROVIDER` | プロバイダーgem（例: `girb-ruby_llm`） |
+| `GIRB_MODEL` | モデル名（例: `gemini-2.5-flash`） |
+| `GIRB_DEBUG` | `1` でデバッグ出力有効化 |
 
-1. カレントディレクトリから親ディレクトリを遡って探索（ルートまで）
-2. `~/.girbrc` にフォールバック
+### セッション永続化（オプション）
 
-これにより:
+AIとの会話履歴をセッション間で保持できます。明示的にセッションIDを指定した場合のみ有効になります。
 
-- **プロジェクト固有の設定**: プロジェクトルートに `.girbrc` を配置
-- **共有設定**: 親ディレクトリに `.girbrc` を配置（例: `~/work/.girbrc` で仕事用プロジェクト全体に適用）
-- **グローバルデフォルト**: ホームディレクトリに `.girbrc` を配置
+#### 有効化
 
-## プロバイダー
+`.girbrc` でセッションIDを設定:
 
-現在利用可能なプロバイダー:
+```ruby
+Girb.configure do |c|
+  c.provider = Girb::Providers::RubyLlm.new(model: 'gemini-2.5-flash')
+end
 
-- [girb-ruby_llm](https://github.com/rira100000000/girb-ruby_llm) - RubyLLM経由で複数プロバイダー対応（OpenAI、Anthropic、Gemini、Ollama等）
-- [girb-gemini](https://github.com/rira100000000/girb-gemini) - Google Gemini
+# セッション永続化を有効化（オプション）
+Girb.debug_session = "my-project"
+```
 
-[独自プロバイダーの作成](#カスタムプロバイダー)も可能です。
+または、コード内で動的に設定:
 
-## 使い方
+```ruby
+Girb.debug_session = "debug-user-auth"
+debugger  # このセッションの会話が保存される
+```
 
-### Railsプロジェクトの場合
+#### セッション管理コマンド
+
+IRBまたはデバッグモードで使用:
 
-```bash
-rails console
 ```
+qq session status  # 現在のセッション状態を表示
+qq session list    # 保存されたセッション一覧
+qq session clear   # 現在のセッションをクリア
+```
+
+#### 動作
+
+- セッションは `.girb/sessions/<session_id>.json` に保存
+- 7日以上アクセスのないセッションは自動削除
+- 同じセッションIDで再開すると、過去の会話を引き継ぎ
+- `get_session_history` ツールで過去の会話を参照可能
+
+---
+
+## 2. Rubyスクリプト (IRB)
 
-Railtieにより自動的にgirbが読み込まれます。
+### 使い方
 
-### 非Railsプロジェクトの場合
+`irb` の代わりに `girb` コマンドを使用:
 
 ```bash
 girb
 ```
 
-### binding.girbでデバッグ
-
-コード内に `binding.girb` を挿入:
+または、コード内に `binding.girb` を挿入:
 
 ```ruby
 def problematic_method
@@ -116,111 +187,192 @@ def problematic_method
 end
 ```
 
-### debug gem (rdbg) でデバッグ
+### AIへの質問方法
 
-AIアシスタント付きのステップ実行デバッグを行うには、スクリプトに `require "girb"` を追加:
+**Ctrl+Space**: 質問を入力した後に押す
 
-```ruby
-require "girb"
+```
+irb(main):001> なぜ失敗したの？[Ctrl+Space]
+```
 
-def problematic_method
-  result = some_calculation
-  result
-end
+**qqコマンド**: qqメソッドを使用
 
-problematic_method
 ```
+irb(main):001> qq このメソッドの使い方を教えて
+```
+
+### 利用可能なツール (IRB)
+
+| ツール | 説明 |
+|--------|------|
+| `evaluate_code` | Rubyコードを実行 |
+| `inspect_object` | オブジェクトの詳細を検査 |
+| `get_source` | メソッド/クラスのソースコードを取得 |
+| `list_methods` | オブジェクトのメソッド一覧を取得 |
+| `find_file` | ファイルを検索 |
+| `read_file` | ファイル内容を読み取り |
+| `get_session_history` | IRBセッション履歴を取得 |
+| `continue_analysis` | 自律調査のためのコンテキスト更新をリクエスト |
+
+### 使用例
+
+```
+irb(main):001> x = [1, 2, 3]
+irb(main):002> 合計を求めるメソッドは？[Ctrl+Space]
+`x.sum` で合計6が得られます。他にも `x.reduce(:+)` や `x.inject(0, :+)` が使えます。
+```
+
+---
+
+## 3. Rails
+
+### インストール
+
+Gemfileに追加:
 
-rdbgで起動:
+```ruby
+group :development do
+  gem 'girb'
+  gem 'girb-ruby_llm'
+end
+```
 
 ```bash
-rdbg your_script.rb
+bundle install
 ```
 
-デバッガ内では以下の方法でAIに質問できます:
-- `ai <質問>` - AIに質問
-- `Ctrl+Space` - 入力内容をAIに送信
-- 日本語（非ASCII文字）の入力は自動的にAIにルーティング
+### 設定
 
-AIは `step`、`next`、`continue` などのデバッガコマンドを実行したり、ブレークポイントを設定することもできます。
+Railsプロジェクトルートに `.girbrc` を作成。詳細は[設定](#1-設定)を参照。
 
-### AIへの質問方法
+### 使い方
+
+`rails console` を実行するだけ - Railtieで自動的にgirbが読み込まれます:
 
-#### 方法1: Ctrl+Space
+```bash
+rails console
+```
 
-入力後に `Ctrl+Space` を押すと、その入力がAIへの質問として送信されます。
+### 追加ツール (Rails)
+
+| ツール | 説明 |
+|--------|------|
+| `query_model` | ActiveRecordクエリを実行 |
+| `model_info` | モデルのスキーマ情報を取得 |
+
+### 使用例
 
 ```
-irb(main):001> このエラーの原因は？[Ctrl+Space]
+irb(main):001> user = User.find(1)
+irb(main):002> user.update(name: "test")
+=> false
+irb(main):003> なぜ更新に失敗したの？[Ctrl+Space]
+`user.errors.full_messages` を確認したところ:
+- "Email can't be blank"
+更新時にemail属性が空になっています。
 ```
 
-#### 方法2: qqコマンド
+---
 
+## 4. Debug Gem (rdbg)
+
+AIアシスタント付きのステップ実行デバッグ。
+
+### 設定
+
+上記と同じ `.girbrc` を使用。
+
+### Rubyスクリプトの場合
+
+`require "debug"` と `require "girb"` を追加し、`debugger`ステートメントを使用:
+
+**注意:** `require "debug"` は必ず `require "girb"` より先に記述してください。
+
+```ruby
+require "debug"
+require "girb"
+
+def calculate(x)
+  result = x * 2
+  debugger  # ここでAIアシスタント付きで停止
+  result + 1
+end
+
+calculate(5)
 ```
-irb(main):001> qq "このメソッドの使い方を教えて"
+
+rubyで実行:
+
+```bash
+ruby your_script.rb
 ```
 
-## 設定オプション
+### Railsの場合
 
-`.girbrc` に追加:
+debug gemより後にgirbを読み込むためinitializerを作成:
 
 ```ruby
-require 'girb-ruby_llm'
+# config/initializers/girb.rb
+require "girb" if Rails.env.development? || Rails.env.test?
+```
 
-Girb.configure do |c|
-  # デバッグ出力（デフォルト: false）
-  c.debug = true
+コード内で`debugger`ステートメントを使用:
 
-  # カスタムプロンプト（オプション）
-  c.custom_prompt = <<~PROMPT
-    本番環境です。破壊的操作の前に必ず確認してください。
-  PROMPT
+```ruby
+def show
+  @user = User.find(params[:id])
+  debugger  # ここでAIアシスタント付きで停止
 end
 ```
 
-### コマンドラインオプション
+### AIへの質問方法 (デバッグモード)
+
+- **`qq <質問>`** - AIに質問
+- **Ctrl+Space** - 現在の入力をAIに送信
+- **日本語入力** - 非ASCII文字は自動的にAIにルーティング
 
-```bash
-girb --debug    # デバッグ出力を有効化
-girb -d         # 同上
-girb --help     # ヘルプを表示
+```
+(rdbg) qq ここでのresultの値は？
+(rdbg) 次の行に進んで[Ctrl+Space]
 ```
 
-### 環境変数
+### AIがデバッガコマンドを実行
 
-`girb` コマンドでは、`.girbrc` が見つからない場合に環境変数で設定することもできます:
+AIがデバッガコマンドを自動で実行できます:
 
-| 変数 | 説明 |
-|------|------|
-| `GIRB_PROVIDER` | 読み込むプロバイダーgem（例: `girb-ruby_llm`、`girb-gemini`） |
-| `GIRB_MODEL` | 使用するモデル（例: `gemini-2.5-flash`、`gpt-4o`） |
-| `GIRB_DEBUG` | `1`に設定するとデバッグ出力を有効化 |
+```
+(rdbg) qq このループを実行して、xが1になるタイミングを教えて
+```
+
+AIは `step`、`next`、`continue`、`break` などを自動的に使用します。
+
+### Ctrl+Cで中断
+
+Ctrl+Cで長時間実行中のAI操作を中断できます。AIは進捗を要約します。
 
-## AIが使用できるツール
+### 利用可能なツール (デバッグモード)
 
 | ツール | 説明 |
 |--------|------|
-| `evaluate_code` | IRBのコンテキストでRubyコードを実行 |
+| `evaluate_code` | 現在のコンテキストでRubyコードを実行 |
 | `inspect_object` | オブジェクトの詳細を検査 |
-| `get_source` | メソッドやクラスのソースコードを取得 |
-| `list_methods` | オブジェクトのメソッド一覧を取得 |
-| `find_file` | プロジェクト内のファイルを検索 |
-| `read_file` | ファイルの内容を読み取り |
-| `session_history` | IRBセッションの履歴を取得 |
-| `continue_analysis` | 自律調査のためのコンテキスト更新をリクエスト |
+| `get_source` | メソッド/クラスのソースコードを取得 |
+| `read_file` | ソースファイルを読み取り |
+| `run_debug_command` | デバッガコマンドを実行 |
+| `get_session_history` | デバッグセッション履歴を取得 |
 
-### Rails環境での追加ツール
+### 使用例: 変数の追跡
 
-| ツール | 説明 |
-|--------|------|
-| `query_model` | ActiveRecordモデルへのクエリ実行 |
-| `model_info` | モデルのスキーマ情報を取得 |
+```
+(rdbg) qq このループでxの全ての値を追跡して、完了したら報告して
 
-### デバッグモード (rdbg) での追加ツール
+[AIがブレークポイントを設定、continueを実行、値を収集]
 
-| ツール | 説明 |
-|--------|------|
-| `run_debug_command` | デバッガコマンドを実行（step、next、continue、breakなど） |
+追跡したxの値: [7, 66, 85, 11, 53, 42, 99, 23]
+ループが完了しました。
+```
+
+---
 
 ## カスタムプロバイダー
 
@@ -232,61 +384,26 @@ class MyProvider < Girb::Providers::Base
     @api_key = api_key
   end
 
-  def chat(messages:, system_prompt:, tools:)
-    # messages: { role: :user/:assistant/:tool_call/:tool_result, content: "..." } の配列
-    # tools: { name: "...", description: "...", parameters: {...} } の配列
-
+  def chat(messages:, system_prompt:, tools:, binding: nil)
     # LLM APIを呼び出す
     response = call_my_llm(messages, system_prompt, tools)
 
-    # Responseオブジェクトを返す
     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
 ```
 
-## 使用例
-
-### デバッグ支援
-
-```
-irb(main):001> user = User.find(1)
-irb(main):002> user.update(name: "test")
-=> false
-irb(main):003> なぜ更新に失敗したの？[Ctrl+Space]
-`user.errors.full_messages` を確認したところ、バリデーションエラーが発生しています:
-- "Email can't be blank"
-nameの更新時にemailが空になっている可能性があります。
-```
-
-### コードの理解
-
-```
-irb(main):001> このプロジェクトでUserモデルはどこで定義されてる？[Ctrl+Space]
-app/models/user.rb で定義されています。
-```
-
-### パターン認識
-
-```
-irb(main):001> a = 1
-irb(main):002> b = 2
-irb(main):003> c = 3以降も続けるとzはいくつ？[Ctrl+Space]
-パターン a=1, b=2, c=3... を続けると、z=26 になります。
-```
+---
 
 ## 動作要件
 
 - Ruby 3.2.0以上
-- IRB 1.6.0以上
-- LLMプロバイダーgem（girb-ruby_llm または girb-gemini）
+- IRB 1.6.0以上（IRB/Rails使用時）
+- debug gem（rdbg使用時）
+- LLMプロバイダーgem
 
 ## ライセンス
 

data/lib/girb/ai_client.rb

@@ -2,6 +2,7 @@
 
 require_relative "auto_continue"
 require_relative "conversation_history"
+require_relative "session_persistence"
 require_relative "providers/base"
 require_relative "debug_context_builder"
 require_relative "debug_prompt_builder"
@@ -35,6 +36,7 @@ module Girb
       else
         auto_continue_count = 0
         original_int_handler = setup_interrupt_handler
+        @debug_command_queued = false
 
         begin
           loop do
@@ -47,6 +49,12 @@ module Girb
 
             process_with_tools(tools)
 
+            # If a debug command was queued, exit immediately
+            # The command needs to be executed by IRB first, then DebugIntegration handles auto-continue
+            if @debug_command_queued
+              break
+            end
+
             # Check for interrupt after API call (Ctrl+C during request)
             if Girb::AutoContinue.interrupted?
               Girb::AutoContinue.clear_interrupt!
@@ -73,10 +81,17 @@ module Girb
           end
         ensure
           restore_interrupt_handler(original_int_handler)
-          Girb::AutoContinue.reset!
+          # Only reset AutoContinue if no debug command was queued
+          # (it will be transferred to DebugIntegration in IrbDebugHook)
+          unless @debug_command_queued
+            Girb::AutoContinue.reset!
+          end
           Girb::AutoContinue.clear_interrupt!
         end
       end
+    ensure
+      # 毎ターン会話履歴を保存（クラッシュやexitでの消失を防止）
+      SessionPersistence.save_session
     end
 
     private
@@ -190,16 +205,19 @@ module Girb
               result: result
             }
 
-            ConversationHistory.add_tool_call(tool_name, tool_args, result, id: tool_id)
+            ConversationHistory.add_tool_call(tool_name, tool_args, result, id: tool_id, metadata: function_call[:metadata])
 
             if Girb.configuration.debug && result.is_a?(Hash) && result[:error]
               puts "[girb] Tool error: #{result[:error]}"
             end
 
-            # In debug mode, if run_debug_command was called, we need to exit
-            # the tool loop so the debugger can execute the pending commands
-            if @debug_mode && tool_name == "run_debug_command"
+            # If run_debug_command was called, we need to exit the tool loop
+            # so the debugger/IRB can execute the pending commands
+            if tool_name == "run_debug_command"
               debug_command_called = true
+              # In IRB mode, mark that we've queued a debug command
+              # This will prevent the auto-continue loop from continuing
+              @debug_command_queued = true unless @debug_mode
             end
           end
 

data/lib/girb/auto_continue.rb

@@ -2,7 +2,7 @@
 
 module Girb
   module AutoContinue
-    MAX_ITERATIONS = 2
+    MAX_ITERATIONS = 20
 
     class << self
       def active?

data/lib/girb/conversation_history.rb

@@ -22,8 +22,8 @@ module Girb
         instance.add_assistant_message(content)
       end
 
-      def add_tool_call(tool_name, args, result, id: nil)
-        instance.add_tool_call(tool_name, args, result, id: id)
+      def add_tool_call(tool_name, args, result, id: nil, metadata: nil)
+        instance.add_tool_call(tool_name, args, result, id: id, metadata: metadata)
       end
 
       def to_contents
@@ -72,13 +72,14 @@ module Girb
       end
     end
 
-    def add_tool_call(tool_name, args, result, id: nil)
+    def add_tool_call(tool_name, args, result, id: nil, metadata: nil)
       @pending_tool_calls << {
         id: id || "call_#{SecureRandom.hex(12)}",
         name: tool_name,
         args: args,
-        result: result
-      }
+        result: result,
+        metadata: metadata
+      }.compact
     end
 
     def clear!
@@ -106,14 +107,18 @@ module Girb
 
         # Add tool calls and results if present
         msg.tool_calls&.each do |tc|
-          result << { role: :tool_call, id: tc[:id], name: tc[:name], args: tc[:args] }
+          tool_call = { role: :tool_call, id: tc[:id], name: tc[:name], args: tc[:args] }
+          tool_call[:metadata] = tc[:metadata] if tc[:metadata]
+          result << tool_call
           result << { role: :tool_result, id: tc[:id], name: tc[:name], result: tc[:result] }
         end
       end
 
       # Add pending tool calls
       @pending_tool_calls.each do |tc|
-        result << { role: :tool_call, id: tc[:id], name: tc[:name], args: tc[:args] }
+        tool_call = { role: :tool_call, id: tc[:id], name: tc[:name], args: tc[:args] }
+        tool_call[:metadata] = tc[:metadata] if tc[:metadata]
+        result << tool_call
         result << { role: :tool_result, id: tc[:id], name: tc[:name], result: tc[:result] }
       end