feat(web-search): provider interface + brave key rename + typed schemas

Author: czyt

README.md

@@ -195,7 +195,7 @@ nekobot/
 - **write_file**: Write content to files
 - **list_dir**: List directory contents
 - **exec**: Execute shell commands
-- **web_search**: Search the web using Brave Search API
+- **web_search**: Search the web using Brave Search (with DuckDuckGo fallback)
 - **web_fetch**: Fetch and extract content from URLs
 - **message**: Send messages to user
 

docs/ARCHITECTURE.md

@@ -69,7 +69,7 @@
 **Built-in Tools**:
 - **file.go** - Read, write, list, edit, append files
 - **exec.go** - Shell command execution
-- **web_search.go** - Brave Search API integration
+- **web_search.go** - Brave Search + DuckDuckGo fallback integration
 - **web_fetch.go** - URL content fetching with HTML parsing
 - **browser.go** - Chrome CDP automation (navigate, screenshot, click, type, execute JS)
 - **message.go** - Direct user communication via bus

docs/PROGRESS.md

@@ -75,7 +75,7 @@
 - ✅ Tool registry and discovery
 - ✅ File operations (read, write, edit, append, list)
 - ✅ Shell execution (exec with safety guards)
-- ✅ Web search (Brave API)
+- ✅ Web search (Brave API + DuckDuckGo fallback)
 - ✅ Web fetch (HTTP content)
 - ✅ Message tool (user communication)
 - ✅ Spawn/subagent (async tasks)

docs/WEB_TOOLS.md

@@ -6,16 +6,22 @@ Nekobot includes web tools that enable the agent to search the internet and fetc
 
 ### 1. web_search
 
-Search the web for current information using Brave Search API.
+Search the web for current information.
+
+Provider behavior:
+- If `brave_api_key` is configured, use **Brave Search API**
+- If Brave fails (or key is missing), fallback/use **DuckDuckGo HTML search**
 
 **Configuration:**
 ```json
 {
   "tools": {
     "web": {
       "search": {
-        "api_key": "your-brave-search-api-key",
-        "max_results": 5
+        "brave_api_key": "your-brave-search-api-key",
+        "max_results": 5,
+        "duckduckgo_enabled": true,
+        "duckduckgo_max_results": 5
       }
     }
   }
@@ -30,7 +36,7 @@ Search the web for current information using Brave Search API.
 
 **Environment Variable:**
 ```bash
-export NEKOBOT_TOOLS_WEB_SEARCH_API_KEY="your-brave-api-key"
+export NEKOBOT_TOOLS_WEB_SEARCH_BRAVE_API_KEY="your-brave-api-key"
 ```
 
 **Usage Example:**
@@ -200,26 +206,13 @@ The agent automatically decides when to use these tools based on the conversatio
 
 ## Troubleshooting
 
-### web_search Not Available
+### web_search Results Are Weak/Empty
 
-**Issue:** "web search API key not configured"
+**Issue:** DuckDuckGo fallback returns low-quality/limited results in some regions.
 
-**Solution:**
+**Solution:** configure Brave API key for better relevance and stability.
 ```bash
-export NEKOBOT_TOOLS_WEB_SEARCH_API_KEY="your-api-key"
-```
-
-Or add to config.json:
-```json
-{
-  "tools": {
-    "web": {
-      "search": {
-        "api_key": "your-api-key"
-      }
-    }
-  }
-}
+export NEKOBOT_TOOLS_WEB_SEARCH_BRAVE_API_KEY="your-api-key"
 ```
 
 ### web_fetch Fails
@@ -257,7 +250,7 @@ Or add to config.json:
 2. **URL Validation**: Only http:// and https:// URLs are allowed
 3. **Content Filtering**: HTML is sanitized during extraction
 4. **Rate Limiting**: Respect API rate limits
-5. **Privacy**: Web requests are logged by Brave Search
+5. **Privacy**: Web requests may be logged by upstream search providers (Brave/DuckDuckGo)
 
 ## Cost
 
@@ -274,7 +267,7 @@ Or add to config.json:
 ## Future Enhancements
 
 Planned improvements:
-- [ ] Support for alternative search providers (Google, DuckDuckGo)
+- [ ] Support for additional providers (Google, Bing, etc.)
 - [ ] Image search and fetch
 - [ ] PDF content extraction
 - [ ] Markdown output option

pkg/agent/agent.go

@@ -72,13 +72,15 @@ func New(cfg *config.Config, log *logger.Logger, providerClient *providers.Clien
 	toolRegistry.MustRegister(tools.NewProcessTool(processMgr))
 	log.Info("PTY process management enabled")
 
-	// Register web tools if configured
-	if cfg.Tools.Web.Search.APIKey != "" {
-		toolRegistry.MustRegister(tools.NewWebSearchTool(
-			cfg.Tools.Web.Search.APIKey,
-			cfg.Tools.Web.Search.MaxResults,
-		))
-		log.Info("Web search tool enabled")
+	// Register web search tool (Brave first, optional DuckDuckGo fallback)
+	if webSearch := tools.NewWebSearchTool(tools.WebSearchToolOptions{
+		BraveAPIKey:          cfg.Tools.Web.Search.GetBraveAPIKey(),
+		BraveMaxResults:      cfg.Tools.Web.Search.MaxResults,
+		DuckDuckGoEnabled:    cfg.Tools.Web.Search.DuckDuckGoEnabled,
+		DuckDuckGoMaxResults: cfg.Tools.Web.Search.DuckDuckGoMaxResults,
+	}); webSearch != nil {
+		toolRegistry.MustRegister(webSearch)
+		log.Info("Web search tool enabled", zap.String("providers", webSearch.ProviderSummary()))
 	}
 
 	// Web fetch tool (always available)

pkg/config/config.example.json

@@ -258,8 +258,10 @@
     },
     "web": {
       "search": {
-        "api_key": "",
-        "max_results": 5
+        "brave_api_key": "",
+        "max_results": 5,
+        "duckduckgo_enabled": true,
+        "duckduckgo_max_results": 5
       },
       "fetch": {
         "max_chars": 50000

pkg/config/config.go

@@ -8,6 +8,7 @@ package config
 
 import (
 	"os"
+	"strings"
 	"sync"
 )
 
@@ -259,8 +260,11 @@ type WebToolsConfig struct {
 
 // WebSearchConfig for web search tool.
 type WebSearchConfig struct {
-	APIKey     string `mapstructure:"api_key" json:"api_key"`
-	MaxResults int    `mapstructure:"max_results" json:"max_results"`
+	BraveAPIKey          string `mapstructure:"brave_api_key" json:"brave_api_key"`
+	LegacyAPIKey         string `mapstructure:"api_key" json:"-"`
+	MaxResults           int    `mapstructure:"max_results" json:"max_results"`
+	DuckDuckGoEnabled    bool   `mapstructure:"duckduckgo_enabled" json:"duckduckgo_enabled"`
+	DuckDuckGoMaxResults int    `mapstructure:"duckduckgo_max_results" json:"duckduckgo_max_results"`
 }
 
 // WebFetchConfig for web fetch tool.
@@ -383,7 +387,9 @@ func DefaultConfig() *Config {
 		Tools: ToolsConfig{
 			Web: WebToolsConfig{
 				Search: WebSearchConfig{
-					MaxResults: 5,
+					MaxResults:           5,
+					DuckDuckGoEnabled:    true,
+					DuckDuckGoMaxResults: 5,
 				},
 				Fetch: WebFetchConfig{
 					MaxChars: 50000,
@@ -478,6 +484,14 @@ func (p *ProviderProfile) GetTimeout() int {
 	return 30 // Default 30 seconds
 }
 
+// GetBraveAPIKey returns the Brave search API key with backward compatibility.
+func (w WebSearchConfig) GetBraveAPIKey() string {
+	if strings.TrimSpace(w.BraveAPIKey) != "" {
+		return strings.TrimSpace(w.BraveAPIKey)
+	}
+	return strings.TrimSpace(w.LegacyAPIKey)
+}
+
 // expandPath expands ~ to home directory.
 func expandPath(path string) string {
 	if path == "" {

pkg/config/loader.go

@@ -70,6 +70,11 @@ func (l *Loader) Load(configPath string) (*Config, error) {
 		return nil, fmt.Errorf("unmarshaling config: %w", err)
 	}
 
+	// Backward compatibility: migrate tools.web.search.api_key -> brave_api_key in-memory.
+	if cfg.Tools.Web.Search.BraveAPIKey == "" {
+		cfg.Tools.Web.Search.BraveAPIKey = cfg.Tools.Web.Search.LegacyAPIKey
+	}
+
 	return cfg, nil
 }
 

pkg/config/loader_env_test.go

@@ -1,6 +1,7 @@
 package config
 
 import (
+	"os"
 	"path/filepath"
 	"testing"
 )
@@ -27,3 +28,35 @@ func TestLoad_UsesConfigPathEnvWhenPathEmpty(t *testing.T) {
 		t.Fatalf("expected gateway port 29999, got %d", got.Gateway.Port)
 	}
 }
+
+func TestLoad_MigratesLegacySearchAPIKey(t *testing.T) {
+	tmpDir := t.TempDir()
+	cfgPath := filepath.Join(tmpDir, "legacy-search-key.json")
+
+	content := `{
+  "tools": {
+    "web": {
+      "search": {
+        "api_key": "legacy-key",
+        "max_results": 5,
+        "duckduckgo_enabled": true,
+        "duckduckgo_max_results": 5
+      }
+    }
+  }
+}`
+	if err := os.WriteFile(cfgPath, []byte(content), 0644); err != nil {
+		t.Fatalf("write config: %v", err)
+	}
+
+	got, err := NewLoader().Load(cfgPath)
+	if err != nil {
+		t.Fatalf("load config: %v", err)
+	}
+	if got.Tools.Web.Search.GetBraveAPIKey() != "legacy-key" {
+		t.Fatalf("expected migrated brave key, got %q", got.Tools.Web.Search.GetBraveAPIKey())
+	}
+	if got.Tools.Web.Search.BraveAPIKey != "legacy-key" {
+		t.Fatalf("expected brave_api_key field to be normalized, got %q", got.Tools.Web.Search.BraveAPIKey)
+	}
+}

pkg/config/validator.go

@@ -247,6 +247,9 @@ func (v *Validator) validateTools(cfg *ToolsConfig) {
 	if cfg.Web.Search.MaxResults < 1 {
 		v.addError("tools.web.search.max_results", "max_results must be at least 1")
 	}
+	if cfg.Web.Search.DuckDuckGoEnabled && cfg.Web.Search.DuckDuckGoMaxResults < 1 {
+		v.addError("tools.web.search.duckduckgo_max_results", "duckduckgo_max_results must be at least 1 when duckduckgo is enabled")
+	}
 	if cfg.Exec.TimeoutSeconds < 1 {
 		v.addError("tools.exec.timeout_seconds", "timeout_seconds must be at least 1")
 	}