rubycode 0.1.3 → 0.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b77afd8d1e1731bea1936ffad3ed3e572ce8d14088ebb8fd49570b11c1c7b0b5
-  data.tar.gz: 2c5abe4b384a4f1f0ef5a26ee4c173eb41124235cd3337147d3fc04a291043b5
+  metadata.gz: 38eb208124cc78e03b6a8fb2778309dc17999ed1ab50270fbbfc3635f5d144d2
+  data.tar.gz: c02ee8d739bf3162d2e3e2fb5e16adcd00d9a373b3223e6e3d2ae6694f75c22d
 SHA512:
-  metadata.gz: 7400478e459c00e8e6ce7889f4eb58667cbe203a30fe4bd64568b122b1d323acb7f08dea92be7b725e4c41547d420fb81c9520071b1c89be3b1a3b6048c4fd1f
-  data.tar.gz: a6559e94215bf89b6c6cc0ed8a065dce7bae23232e7d3bd7c203ea274644a045a8e003c8e922772575c86f1ea86e0ce56b6fdaed0603535d958c15cd3d35a464
+  metadata.gz: 29a2f388ff00077112e5f3697a1fbca342ba5a9974bf7b306c862f4b97f78585c3357366c6980ca5c71c21944e191243ac4e84e59f6451492e140fb711d15314
+  data.tar.gz: bc30616c062dd24865f4ec9d2c93cae55569dec5d17c0648d39d6c6aa3059ca91d736b7867e4f0b7015de514182d145b47a5b93e7b297832134f26e922e6e93b

data/.env.example

@@ -0,0 +1,38 @@
+# RubyCode Environment Variables
+# Copy this file to .env and fill in your API keys
+
+# ====================================
+# LLM Providers
+# ====================================
+
+# Ollama API Key (required if using Ollama adapter)
+# Get your key: https://ollama.ai/
+# OLLAMA_API_KEY=your_ollama_api_key_here
+
+# DeepSeek API Key (required if using DeepSeek adapter)
+# Get your key: https://platform.deepseek.com/api_keys
+# DEEPSEEK_API_KEY=your_deepseek_api_key_here
+
+# Gemini API Key (required if using Gemini adapter)
+# Get your key: https://makersuite.google.com/app/apikey
+# GEMINI_API_KEY=your_gemini_api_key_here
+
+# OpenAI API Key (required if using OpenAI adapter)
+# Get your key: https://platform.openai.com/api-keys
+# OPENAI_API_KEY=your_openai_api_key_here
+
+# OpenRouter API Key (required if using OpenRouter adapter)
+# Get your key: https://openrouter.ai/keys
+# OPENROUTER_API_KEY=your_openrouter_api_key_here
+
+# ====================================
+# Web Search Providers
+# ====================================
+
+# Exa.ai API Key (optional - enables AI-native web search)
+# Get your key: https://exa.ai/api
+# EXA_API_KEY=your_exa_api_key_here
+
+# Brave Search API Key (optional - alternative search provider)
+# Get your key: https://brave.com/search/api/
+# BRAVE_API_KEY=your_brave_api_key_here

data/.rubocop.yml

@@ -18,3 +18,7 @@ Metrics/ClassLength:
 
 Metrics/MethodLength:
   Max: 20
+
+Metrics/AbcSize:
+  Exclude:
+    - "test/**/*"

data/CHANGELOG.md

@@ -1,5 +1,57 @@
 ## [Unreleased]
 
+## [0.1.4] - 2026-03-07
+
+### Added
+- **Multiple Cloud LLM Adapters**: Support for 5 cloud providers (Ollama Cloud, DeepSeek, Gemini, OpenAI, OpenRouter)
+- **Web Search & Fetch Tools**: Internet search via DuckDuckGo, Brave, and Exa.ai with automatic fallback
+- **Interactive Setup Wizard**: First-time configuration with provider/model selection and API key management
+- **Encrypted API Key Storage**: Secure database storage for API keys with AES-256-GCM encryption
+- **Configuration Persistence**: Automatic saving and loading of user preferences
+- **Search Provider Architecture**: Base class with concerns for HTTP client, error handling, and debugging
+- **Adapter Architecture**: Refactored with base class and shared concerns (66% code reduction)
+- **Debug Mode**: Comprehensive request/response logging for adapters and search providers
+- **Rate Limit Handling**: Automatic detection and retry with 3-attempt limit for 429 errors
+
+### Changed
+- **Bash Tool**: Improved with real-time output streaming and non-interactive execution
+- **System Prompt**: Added web_search and fetch tool documentation for LLM awareness
+- **View Layer**: Enhanced web_search and fetch summaries with full URLs and metadata
+- **Search Providers**: Reduced code duplication from ~100 lines per provider to shared base class
+- **Adapters**: Reduced from ~900 lines to ~300 lines with shared concerns
+- **Memory Management**: Clear conversation history on session start to prevent payload size issues
+
+### Fixed
+- **Agent Loop Exit Bug**: Agent now properly stops when `done` tool is called, even if tool execution fails
+- **Bash Tool stdin_data Error**: Removed invalid stdin_data option from Open3.popen2e
+- **Search Provider Transparency**: Now displays which provider (DuckDuckGo/Brave/Exa) returned results
+- **RuboCop Compliance**: Reduced violations from 45 to 39 (all acceptable complexity metrics)
+- **Test Suite**: Expanded coverage to 141 tests (379 assertions) including adapter and agent loop tests
+
+## [0.1.3] - 2026-03-05
+
+### Added
+- **Write & Update Tools**: New file creation and editing capabilities with user approval workflow
+- **Persistent Memory**: SQLite-backed conversation history using Sequel ORM
+- **Network Resilience**: Automatic retry with exponential backoff for failed LLM requests (configurable timeouts and retries)
+- **Enhanced CLI**: TTY-based interface with formatted output, progress indicators, and approval prompts
+- **I18n Support**: Internationalized error messages and system prompts
+- **Comprehensive Test Suite**: Added test coverage for Database, Memory, and Models::Base classes
+- **Configuration Options**: HTTP timeout settings (read_timeout, open_timeout, max_retries, retry_base_delay)
+- **Cross-platform Support**: Added Linux platform support for CI/CD environments
+
+### Changed
+- Migrated from raw SQLite3 to Sequel ORM for better database abstraction
+- Separated database connection management from model classes
+- Refactored view layer with dedicated view classes for all UI components
+- Improved error handling with adapter-specific error classes
+- Updated gemspec description to be more comprehensive
+
+### Fixed
+- Approval prompt now properly waits for user input instead of auto-declining
+- Models::Base.last now properly orders by ID before retrieving
+- RuboCop compliance across entire codebase
+
 ## [0.1.0] - 2026-02-28
 
 - Initial release

data/README.md

@@ -16,19 +16,28 @@ A Ruby-native AI coding assistant with pluggable LLM adapters. RubyCode provides
 ## Features
 
 - **AI Agent Loop**: Autonomous task execution with tool calling
-- **Pluggable LLM Adapters**: Currently supports Ollama with configurable timeouts and retry logic
+- **Multiple Cloud LLM Adapters**: Support for Ollama Cloud, DeepSeek, Gemini, OpenAI, and OpenRouter
+- **Interactive Setup Wizard**: First-time configuration with provider selection and API key management
 - **Built-in Tools**:
   - `bash`: Execute safe bash commands for filesystem exploration
   - `search`: Search file contents using grep with regex support
   - `read`: Read files and directories with line numbers
   - `write`: Create new files with user approval
   - `update`: Edit existing files with user approval
+  - `web_search`: Search the internet with automatic provider fallback (DuckDuckGo/Brave/Exa)
+  - `fetch`: Fetch content from URLs
   - `done`: Signal task completion with final answer
 - **Persistent Memory**: SQLite-backed conversation history with Sequel ORM
+- **Encrypted API Key Storage**: Secure database storage with AES-256-GCM encryption
+- **Configuration Persistence**: Automatic saving and loading of preferences
 - **Enhanced CLI**: TTY-based interface with formatted output, progress indicators, and approval workflows
-- **Resilient Network**: Automatic retry with exponential backoff for LLM requests
+- **Resilient Network**: Automatic retry with exponential backoff and rate limit handling
+- **Debug Mode**: Comprehensive request/response logging for adapters and search providers
 - **I18n Support**: Internationalized error messages and UI text
-- **Environment Context**: Automatically provides Ruby version, platform, and working directory info
+
+## Requirements
+
+- Ruby 3.1 or higher
 
 ## Installation
 
@@ -54,16 +63,30 @@ bundle install
 
 ### Basic Usage
 
+#### Interactive CLI (Recommended)
+
+```bash
+rubycode
+```
+
+The first time you run RubyCode, an interactive setup wizard will guide you through:
+1. Selecting your LLM provider (Ollama Cloud, DeepSeek, Gemini, OpenAI, or OpenRouter)
+2. Choosing a model
+3. Entering API keys (saved securely with encryption)
+
+Your configuration is automatically saved and reloaded on subsequent runs.
+
+#### Programmatic Usage
+
 ```ruby
 require "rubycode"
 
 # Configure the LLM adapter
 RubyCode.configure do |config|
   config.adapter = :ollama
-  config.url = "http://localhost:11434"
-  config.model = "deepseek-v3.1:671b-cloud"
+  config.url = "https://api.ollama.com"
+  config.model = "qwen3-coder:480b-cloud"
   config.root_path = Dir.pwd
-  config.debug = false
 end
 
 # Create a client and ask a question
@@ -76,14 +99,13 @@ puts response
 
 ```ruby
 RubyCode.configure do |config|
-  config.adapter = :ollama                    # LLM adapter to use
-  config.url = "http://localhost:11434"       # Ollama server URL
-  config.model = "deepseek-v3.1:671b-cloud"   # Model name
+  # LLM Provider Settings
+  config.adapter = :ollama                    # :ollama, :deepseek, :gemini, :openai, :openrouter
+  config.url = "https://api.ollama.com"       # Provider API URL
+  config.model = "qwen3-coder:480b-cloud"     # Model name
   config.root_path = Dir.pwd                  # Project root directory
-  config.debug = false                        # Enable debug output
-  config.enable_tool_injection_workaround = true  # Force tool usage (enabled by default)
 
-  # HTTP timeout and retry settings (new in 0.1.3)
+  # HTTP timeout and retry settings
   config.http_read_timeout = 120              # Request timeout in seconds (default: 120)
   config.http_open_timeout = 10               # Connection timeout in seconds (default: 10)
   config.max_retries = 3                      # Number of retry attempts (default: 3)
@@ -91,9 +113,19 @@ RubyCode.configure do |config|
 end
 ```
 
+### Supported LLM Providers
+
+| Provider | Models | API Key Required | Notes |
+|----------|--------|------------------|-------|
+| **Ollama Cloud** | qwen3-coder, deepseek-v3.1, gpt-oss | Yes | Cloud-hosted Ollama models |
+| **DeepSeek** | deepseek-chat, deepseek-reasoner | Yes | Fast reasoning models |
+| **Google Gemini** | gemini-2.5-flash, gemini-2.5-pro, gemini-3-flash-preview | Yes | Multimodal support |
+| **OpenAI** | gpt-4o, gpt-4o-mini, o1 | Yes | GPT models with reasoning |
+| **OpenRouter** | claude-sonnet-4.5, claude-opus-4.6, gpt-4o | Yes | Access to multiple providers |
+
 ### Available Tools
 
-The agent has access to six built-in tools:
+The agent has access to several built-in tools:
 
 1. **bash**: Execute safe bash commands including:
    - Directory exploration: `ls`, `pwd`, `find`, `tree`
@@ -104,25 +136,71 @@ The agent has access to six built-in tools:
 3. **read**: Read files with line numbers or list directory contents
 4. **write**: Create new files (requires user approval)
 5. **update**: Edit existing files with exact string replacement (requires user approval)
-6. **done**: Signal completion and provide the final answer
+6. **web_search**: Search the internet with automatic provider fallback (requires user approval):
+   - Primary: Exa.ai (AI-native search, optional with API key)
+   - Fallback 1: DuckDuckGo Instant Answer API (free, no API key)
+   - Fallback 2: Brave Search API (optional, for better results)
+7. **fetch**: Fetch and extract text content from URLs (requires user approval)
+8. **done**: Signal completion and provide the final answer
 
 **Note**: Tool schemas are externalized in `config/tools/*.json` for easy customization.
 
-### New in 0.1.3
+#### Web Search Configuration
+
+**By default** (no setup needed):
+- Uses DuckDuckGo Instant Answer API (free, no CAPTCHA)
+- Good for factual queries and summaries
+
+**For AI-native search** (optional, recommended):
+```bash
+# Sign up at https://exa.ai/api
+export EXA_API_KEY=your_api_key_here
+```
 
-- **Persistent Memory**: Conversation history now stored in SQLite database using Sequel ORM
-- **Write & Update Tools**: Create and modify files with user approval workflow
-- **Network Resilience**: Automatic retry with exponential backoff for failed LLM requests
-- **Enhanced CLI**: Improved UI with TTY toolkit, formatted output, and progress indicators
-- **I18n Support**: Internationalized error messages and system prompts
-- **Improved Architecture**: Separated database connection management, view classes for all UI components
-- **Cross-platform Support**: Added Linux platform support for CI/CD environments
+**For better web results** (optional):
+```bash
+# Sign up at https://brave.com/search/api/
+export BRAVE_API_KEY=your_api_key_here
+```
+
+### New in 0.1.4
+
+- **Bug Fix**: Agent now properly stops when `done` tool is called, even if tool execution fails
+- **Multiple Cloud LLM Adapters**: Support for 5 providers (Ollama Cloud, DeepSeek, Gemini, OpenAI, OpenRouter)
+- **Web Search & Fetch Tools**: Internet search with automatic fallback (Exa/DuckDuckGo/Brave)
+- **Interactive Setup Wizard**: First-time configuration with guided setup
+- **Encrypted API Key Storage**: Secure database storage with AES-256-GCM
+- **Configuration Persistence**: Automatic saving/loading of preferences
+- **Search Provider Architecture**: Refactored with base class and shared concerns
+- **Adapter Architecture**: 66% code reduction with shared HTTP/error handling
+- **Debug Mode**: Comprehensive request/response logging
+- **Rate Limit Handling**: Automatic retry with 3-attempt limit for 429 errors
+- **Expanded Test Coverage**: 141 tests covering adapters, agent loop, configuration, and tools
+- **Memory Optimization**: Configurable memory window with tool result pruning
 
 ## Development
 
 After checking out the repo, run `bundle install` to install dependencies.
 
-To install this gem onto your local machine, run:
+### Running Tests
+
+```bash
+# Run all tests
+bundle exec rake test
+
+# Run tests without warnings
+bundle exec rake test 2>/dev/null
+
+# Run specific test file
+bundle exec rake test TEST=test/test_adapters.rb
+
+# Run with RuboCop
+bundle exec rake
+```
+
+### Installing Locally
+
+To install this gem onto your local machine:
 
 ```bash
 bundle exec rake install

data/USAGE.md

@@ -67,27 +67,5 @@ The agent autonomously decides which tools to use to:
 Built following OpenCode's design:
 - **Tools**: Controlled, safe operations with validation
 - **Agent Loop**: LLM calls tools, we execute, loop until done
-- **History**: Maintains conversation context
+- **History**: Maintains conversation context including tool calls
 - **JSON Visibility**: Full transparency in debug mode
-
-## Workaround for Weak Tool-Calling Models
-
-If you're testing with models that have poor tool-calling capabilities (like qwen3-coder), enable the injection workaround:
-
-```ruby
-Rubycode.configure do |config|
-  config.enable_tool_injection_workaround = true
-end
-```
-
-**What this does:**
-- When the model generates text instead of calling a tool, it injects a reminder message
-- Forces the model to keep calling tools until it finds the answer
-- **OpenCode does NOT use this** - they rely on strong tool-calling models (Claude, GPT-4)
-- This is ONLY for testing/development with weaker models
-
-**When to disable:**
-- When using Claude (Anthropic)
-- When using GPT-4 (OpenAI)  
-- When using Gemini (Google)
-- In production

data/config/locales/en.yml

@@ -11,7 +11,115 @@ en:
       subtitle: "AI Ruby/Rails Code Assistant"
       built_with: "Built with: %{stack}"
       stack: "Ollama + DeepSeek + TTY Toolkit"
-      commands: "Commands: exit, quit, clear"
+      commands: "Commands: exit, quit, clear, config"
+
+    setup:
+      title: "🔧 Configuration Setup"
+      first_time: "👋 First-time setup!"
+      adapter_prompt: "Select LLM provider:"
+      model_prompt: "Select model:"
+      custom_model_prompt: "Enter model name:"
+      url_prompt: "Ollama URL:"
+      api_key_prompt: "%{adapter} API Key:"
+      api_key_optional: "(press Enter to use environment variable)"
+      api_key_missing: "⚠️  %{adapter}_API_KEY not set!"
+      api_key_help: "Get your key: %{url}\nThen either:\n  1. Set environment variable: export %{env_var}='...'\n  2. Enter it when prompted during setup"
+      api_key_required: "API key is required to continue."
+      use_saved_api_key: "Use saved %{adapter} API key?"
+      save_env_key_to_db: "Save %{adapter} API key from environment to database?"
+      config_saved: "✓ Configuration saved to %{path}"
+      use_saved: "Use saved configuration (%{adapter}/%{model})?"
+      reconfigure: "Reconfigure?"
+      restart_message: "Restart rubycode to apply new configuration."
+      configure_exa: "Configure Exa.ai for web search? (Optional - AI-native search, requires API key)"
+
+    models:
+      ollama:
+        default: "qwen3-coder:480b-cloud"
+        powerful:
+          name: "qwen3-coder:480b-cloud"
+          label: "Qwen3 Coder 480B (Best for coding, cloud)"
+        advanced:
+          name: "gpt-oss:120b-cloud"
+          label: "GPT-OSS 120B (Reasoning, cloud)"
+        reasoning:
+          name: "deepseek-v3.1:671b-cloud"
+          label: "DeepSeek v3.1 671B (Advanced reasoning, cloud)"
+        fast:
+          name: "gpt-oss:20b-cloud"
+          label: "GPT-OSS 20B (Fast, cloud)"
+      deepseek:
+        default: "deepseek-chat"
+        fast:
+          name: "deepseek-chat"
+          label: "DeepSeek Chat (Fast, reasoning)"
+        reasoning:
+          name: "deepseek-reasoner"
+          label: "DeepSeek Reasoner (Advanced, chain-of-thought)"
+      gemini:
+        default: "gemini-2.5-flash"
+        fast:
+          name: "gemini-2.5-flash"
+          label: "Gemini 2.5 Flash (Fast, latest)"
+        lite:
+          name: "gemini-2.5-flash-lite"
+          label: "Gemini 2.5 Flash Lite (Fastest)"
+        powerful:
+          name: "gemini-2.5-pro"
+          label: "Gemini 2.5 Pro (Most capable)"
+        experimental:
+          name: "gemini-3-flash-preview"
+          label: "Gemini 3 Flash Preview (Experimental)"
+      openai:
+        default: "gpt-4o"
+        fast:
+          name: "gpt-4o-mini"
+          label: "GPT-4o Mini (Fast, cheap)"
+        balanced:
+          name: "gpt-4o"
+          label: "GPT-4o (Balanced)"
+        reasoning:
+          name: "o1"
+          label: "O1 (Advanced reasoning)"
+      openrouter:
+        default: "anthropic/claude-sonnet-4.5"
+        fast:
+          name: "anthropic/claude-haiku-4.5"
+          label: "Claude 4.5 Haiku (Fast, cheap)"
+        balanced:
+          name: "anthropic/claude-sonnet-4.5"
+          label: "Claude 4.5 Sonnet (Balanced)"
+        powerful:
+          name: "anthropic/claude-opus-4.6"
+          label: "Claude 4.6 Opus (Most capable)"
+        alternative:
+          name: "openai/gpt-4o"
+          label: "GPT-4o (OpenAI)"
+    adapters:
+      ollama:
+        name: "Ollama (Cloud)"
+        api_key_url: "https://ollama.ai/"
+        requires_key: true
+      deepseek:
+        name: "DeepSeek (Cloud - Reasoning Models)"
+        api_key_url: "https://platform.deepseek.com/api_keys"
+        requires_key: true
+      gemini:
+        name: "Google Gemini (Cloud - Multimodal)"
+        api_key_url: "https://makersuite.google.com/app/apikey"
+        requires_key: true
+      openai:
+        name: "OpenAI (Cloud - GPT Models)"
+        api_key_url: "https://platform.openai.com/api-keys"
+        requires_key: true
+      openrouter:
+        name: "OpenRouter (Cloud - Multiple Models)"
+        api_key_url: "https://openrouter.ai/keys"
+        requires_key: true
+      exa:
+        name: "Exa.ai (Web Search)"
+        api_key_url: "https://exa.ai/api"
+        requires_key: true
 
     approval:
       bash:
@@ -69,6 +177,16 @@ en:
       debug_prefix: "[DEBUG]"
       error_prefix: "[ERROR]"
 
+    debug:
+      request_title: "📤 REQUEST TO LLM"
+      request_title_adapter: "📤 REQUEST TO LLM (%{adapter})"
+      response_title: "📥 RESPONSE FROM LLM"
+      response_title_adapter: "📥 RESPONSE FROM LLM (%{adapter})"
+      url_label: "URL: %{url}"
+      model_label: "Model: %{model}"
+      payload_label: "Payload:"
+      separator: "================================================================================"
+
     errors:
       unknown_adapter: "Unknown Adapter"
       file_not_found: "File '%{path}' not found"
@@ -85,3 +203,92 @@ en:
       adapter_connection: "Cannot connect to LLM at %{url}: %{error}"
       adapter_retry: "Request failed: %{error}. Retrying in %{delay}s... (attempt %{attempt}/%{max_retries})"
       adapter_failed: "LLM adapter failed: %{error}"
+      adapter_retry_exhausted: "All retry attempts failed: %{error}\nPlease check your LLM server connection and try again."
+      rate_limit_exhausted: "Rate limit exceeded after %{max_attempts} consecutive attempts. Please wait a few minutes before trying again."
+      user_cancelled_search: "USER CANCELLED: The user declined web search for '%{query}'. Do not retry this search. Ask the user if they want to search for something else or call 'done' to finish."
+      network_error: "Network error: %{message}"
+      http_error: "HTTP %{code}: %{message}"
+      url_error: "Invalid URL: %{url}"
+      tools_not_supported: |
+        Model '%{model}' does not support tool calling.
+
+        RubyCode requires a model with function/tool calling capabilities.
+
+        Suggested models that support tools:
+        • qwen2.5-coder:7b    (pull with: ollama pull qwen2.5-coder:7b)
+        • llama3.1:8b         (pull with: ollama pull llama3.1:8b)
+        • mistral:7b          (pull with: ollama pull mistral:7b)
+
+        Update your configuration in lib/rubycode/configuration.rb to use a compatible model.
+
+      # Adapter-specific errors
+      adapter:
+        retry_failed: "Failed after %{max_retries} retries: %{error}"
+        invalid_json: "Invalid JSON response from server: %{error}"
+        unexpected_error: "Unexpected error: %{error}"
+        read_timeout: "Request timed out after %{timeout}s: %{error}"
+        open_timeout: "Connection timed out after %{timeout}s: %{error}"
+        connection_refused: "Connection refused to %{uri}: %{error}"
+        connection_timeout: "Connection timed out to %{uri}: %{error}"
+        host_unreachable: "Cannot resolve host %{hostname}: %{error}"
+        rate_limited: "Rate limited (%{code}): %{message}"
+        server_error: "Server error (%{code}): %{message}"
+        http_error: "HTTP error (%{code}): %{message}"
+        auth_failed: "Authentication failed (%{code}): Check your %{adapter_name}_API_KEY"
+        no_choices: "No choices in response"
+        no_message: "No message in choice"
+
+      # Gemini-specific errors
+      gemini:
+        api_key_missing: |
+          GEMINI_API_KEY environment variable not set.
+
+          Get your API key:
+            https://makersuite.google.com/app/apikey
+
+          Then set it:
+            export GEMINI_API_KEY='...'
+
+      # OpenAI-specific errors
+      openai:
+        api_key_missing: |
+          OPENAI_API_KEY environment variable not set.
+
+          Get your API key:
+            https://platform.openai.com/api-keys
+
+          Then set it:
+            export OPENAI_API_KEY='sk-...'
+
+      # OpenRouter-specific errors
+      openrouter:
+        api_key_missing: |
+          OPENROUTER_API_KEY environment variable not set.
+
+          Get your API key:
+            https://openrouter.ai/keys
+
+          Then set it:
+            export OPENROUTER_API_KEY='sk-or-v1-...'
+
+      # Ollama-specific errors
+      ollama:
+        api_key_missing: |
+          OLLAMA_API_KEY environment variable not set.
+
+          Get your API key:
+            https://ollama.ai/
+
+          Then set it:
+            export OLLAMA_API_KEY='your-api-key'
+
+      # DeepSeek-specific errors
+      deepseek:
+        api_key_missing: |
+          DEEPSEEK_API_KEY environment variable not set.
+
+          Get your API key:
+            https://platform.deepseek.com/api_keys
+
+          Then set it:
+            export DEEPSEEK_API_KEY='sk-...'

data/config/system_prompt.md

@@ -14,6 +14,8 @@ You MUST call a tool in EVERY response. You MUST NEVER respond with just text.
 - **read**: view file contents with line numbers
 - **write**: create new files (requires approval, errors if file exists)
 - **update**: modify existing files (auto-reads if needed, requires approval)
+- **web_search**: search the internet when you cannot find the answer in the codebase or need current information (requires approval)
+- **fetch**: fetch content from URLs to read documentation or resources (requires approval)
 - **done**: MUST call when task is complete (see below)
 
 ## Recommended workflow
@@ -22,7 +24,10 @@ You MUST call a tool in EVERY response. You MUST NEVER respond with just text.
 2. Use bash with find to locate files: `find . -name "*.rb"`
 3. Once found → use read to see the file
 4. Make changes with write/update if needed
-5. IMMEDIATELY call done when finished - do not continue exploring
+5. If you cannot find the answer in the codebase or need current/external information:
+   - Use web_search to find information on the internet
+   - Use fetch to read documentation from URLs
+6. IMMEDIATELY call done when finished - do not continue exploring
 
 ## CRITICAL: When to call 'done'
 

data/config/tools/bash.json

@@ -2,7 +2,7 @@
   "type": "function",
   "function": {
     "name": "bash",
-    "description": "Execute safe bash commands for exploring the filesystem and terminal operations.\n\nUse this for any command-line operations including:\n- Directory exploration: ls, find, tree\n- File inspection: cat, head, tail, wc, file\n- Content search: grep, rg (ripgrep)\n\nExamples:\n- grep -rn 'button' app/views\n- find . -name '*.rb' -type f\n- ls -la app/\n\nWhitelisted commands: ls, pwd, find, tree, cat, head, tail, wc, file, which, echo, grep, rg",
+    "description": "Execute bash commands and wait for completion. Commands run non-interactively (stdin is closed).\n\nUse this for:\n- Directory exploration: ls, find, tree\n- File inspection: cat, head, tail, wc, file\n- Content search: grep, rg\n- Development tools: bundle, rails, rake, ruby, gem, node, npm, yarn, git (requires approval)\n\nIMPORTANT: For Rails generators and similar tools, always use --force or --skip flags to avoid interactive prompts:\n- rails generate authentication --force (overwrites files)\n- rails generate model User --force\n- bundle install --quiet\n\nExamples:\n- grep -rn 'button' app/views\n- find . -name '*.rb' -type f\n- rails generate authentication --force\n- git status\n\nAuto-approved commands (no user confirmation needed): ls, pwd, find, tree, cat, head, tail, wc, file, which, echo, grep, rg",
     "parameters": {
       "type": "object",
       "properties": {

data/config/tools/fetch.json

@@ -0,0 +1,22 @@
+{
+  "type": "function",
+  "function": {
+    "name": "fetch",
+    "description": "Fetch HTML content from a URL.\n\n- Retrieves web page content via HTTP/HTTPS\n- Optionally extracts text-only content (strips HTML tags)\n- No user approval required\n- 30 second timeout for requests\n- Returns raw HTML or extracted text",
+    "parameters": {
+      "type": "object",
+      "properties": {
+        "url": {
+          "type": "string",
+          "description": "The URL to fetch (must be http:// or https://)"
+        },
+        "extract_text": {
+          "type": "boolean",
+          "description": "Extract only text content, removing HTML tags. Default: false",
+          "default": false
+        }
+      },
+      "required": ["url"]
+    }
+  }
+}

data/config/tools/websearch.json

@@ -0,0 +1,22 @@
+{
+  "type": "function",
+  "function": {
+    "name": "web_search",
+    "description": "Search the web for information and return relevant links.\n\n- Primary provider: DuckDuckGo Instant Answer API (free, no API key needed)\n- Fallback provider: Brave Search API (optional, for better results if BRAVE_API_KEY is set)\n- Verifies each link exists before returning (HEAD request)\n- Returns title, URL, and snippet for each result\n- Filters out dead or inaccessible links\n- Requires user approval before making web requests\n- No CAPTCHA issues with API-based providers",
+    "parameters": {
+      "type": "object",
+      "properties": {
+        "query": {
+          "type": "string",
+          "description": "The search query to look up on the web"
+        },
+        "max_results": {
+          "type": "integer",
+          "description": "Maximum number of verified results to return. Default: 5",
+          "default": 5
+        }
+      },
+      "required": ["query"]
+    }
+  }
+}