kolega-code 0.6.0__tar.gz → 0.7.0__tar.gz

{kolega_code-0.6.0 → kolega_code-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kolega-code
-Version: 0.6.0
+Version: 0.7.0
 Summary: Local-first AI coding agent for the terminal
 Project-URL: Homepage, https://kolega-ai.github.io/kolega-code/
 Project-URL: Documentation, https://kolega-ai.github.io/kolega-code/
@@ -43,9 +43,13 @@ Classifier: Topic :: Utilities
 Requires-Python: >=3.11
 Requires-Dist: anthropic==0.101.0
 Requires-Dist: beautifulsoup4==4.14.3
+Requires-Dist: ddgs==9.14.4
+Requires-Dist: firecrawl-py==4.28.2
 Requires-Dist: google-genai==2.0.1
+Requires-Dist: httpx==0.28.1
 Requires-Dist: jinja2==3.1.6
 Requires-Dist: langfuse==3.14.5
+Requires-Dist: lxml-html-clean==0.4.4
 Requires-Dist: nest-asyncio==1.6.0
 Requires-Dist: openai==1.109.1
 Requires-Dist: packaging==25.0
@@ -55,6 +59,7 @@ Requires-Dist: psutil==7.2.2
 Requires-Dist: pydantic==2.13.4
 Requires-Dist: python-dotenv==1.2.2
 Requires-Dist: pyyaml==6.0.3
+Requires-Dist: tavily-python==0.7.26
 Requires-Dist: tenacity==9.1.4
 Requires-Dist: textual==8.2.5
 Requires-Dist: tiktoken==0.12.0
@@ -103,8 +108,9 @@ sessions, settings, and API keys stay on your own machine.
   and applies precise edits.
 - **Runs commands.** Executes shell commands and watches their output in a dedicated terminal view.
 - **Plans before it builds.** Plan mode investigates and proposes; Build mode executes.
-- **Browses the web.** A built-in browser agent (powered by Playwright) fetches pages and
-  interacts with sites when a task needs it.
+- **Searches and browses the web.** The agent can search for relevant pages, fetch URLs
+  directly, or use the built-in browser agent (powered by Playwright) when a task needs
+  site interaction.
 - **Dispatches sub-agents.** Hands work off to specialized agents and tracks their activity live.
 - **Orchestrates workflows.** With [gigacode](https://kolega-ai.github.io/kolega-code/gigacode/),
   it fans out many sub-agents in parallel.
@@ -187,6 +193,10 @@ Settings. Local session state lives under your platform's state directory unless
 [Configuration docs](https://kolega-ai.github.io/kolega-code/configuration/settings-and-api-keys/)
 for the full story.
 
+The `web_search` tool uses DuckDuckGo by default without a key. To choose another backend,
+set it in **Settings** or export `KOLEGA_CODE_WEB_SEARCH_BACKEND` as `firecrawl`, `tavily`,
+or `searxng`; use `FIRECRAWL_API_KEY`, `TAVILY_API_KEY`, or `SEARXNG_BASE_URL` as needed.
+
 ## Requirements
 
 - **Python 3.11+**

{kolega_code-0.6.0 → kolega_code-0.7.0}/README.md

@@ -35,8 +35,9 @@ sessions, settings, and API keys stay on your own machine.
   and applies precise edits.
 - **Runs commands.** Executes shell commands and watches their output in a dedicated terminal view.
 - **Plans before it builds.** Plan mode investigates and proposes; Build mode executes.
-- **Browses the web.** A built-in browser agent (powered by Playwright) fetches pages and
-  interacts with sites when a task needs it.
+- **Searches and browses the web.** The agent can search for relevant pages, fetch URLs
+  directly, or use the built-in browser agent (powered by Playwright) when a task needs
+  site interaction.
 - **Dispatches sub-agents.** Hands work off to specialized agents and tracks their activity live.
 - **Orchestrates workflows.** With [gigacode](https://kolega-ai.github.io/kolega-code/gigacode/),
   it fans out many sub-agents in parallel.
@@ -119,6 +120,10 @@ Settings. Local session state lives under your platform's state directory unless
 [Configuration docs](https://kolega-ai.github.io/kolega-code/configuration/settings-and-api-keys/)
 for the full story.
 
+The `web_search` tool uses DuckDuckGo by default without a key. To choose another backend,
+set it in **Settings** or export `KOLEGA_CODE_WEB_SEARCH_BACKEND` as `firecrawl`, `tavily`,
+or `searxng`; use `FIRECRAWL_API_KEY`, `TAVILY_API_KEY`, or `SEARXNG_BASE_URL` as needed.
+
 ## Requirements
 
 - **Python 3.11+**

{kolega_code-0.6.0 → kolega_code-0.7.0}/docs/src/content/docs/concepts/tools.md

@@ -38,8 +38,14 @@ the [TUI](../../cli/overview/) or [`ask`](../../cli/ask/).
 
 ### Web
 
+- `web_search` — search the web for relevant pages and return ranked results.
 - `web_fetch` — fetch and parse a web page without a full browser.
 
+Use `web_search` when you do not already know the right URL, then follow up with
+`web_fetch` to read a result in depth. The default backend is keyless DuckDuckGo;
+Firecrawl, Tavily, and self-hosted SearXNG can be selected in Settings or with
+environment variables.
+
 ### Reasoning & memory
 
 - `think_hard` — an extended-reasoning step that uses the
@@ -57,8 +63,8 @@ and `dispatch_general_agent`.
 Tools are gated by mode. In a read-only context — like [Plan mode](../../tui/modes/)
 or an investigation sub-agent — only non-mutating tools are available
 (`list_directory`, `read_entire_file`, `read_file_section`, `search_codebase`,
-`find_files_by_pattern`, `web_fetch`, `think_hard`, and reading memory). Editing
-files and running commands require Build mode's full toolset.
+`find_files_by_pattern`, `web_search`, `web_fetch`, `think_hard`, and reading
+memory). Editing files and running commands require Build mode's full toolset.
 
 This separation is what makes Plan mode safe to run against any codebase: the
 planning agent can look but not touch.

{kolega_code-0.6.0 → kolega_code-0.7.0}/docs/src/content/docs/configuration/environment-variables.md

@@ -87,6 +87,18 @@ section.
 | `KOLEGA_CODE_STATE_DIR` | Override where settings and sessions are stored |
 | `KOLEGA_CODE_ENVIRONMENT` | Environment label attached to tracing/metadata (default `development`) |
 
+## Web search
+
+The `web_search` tool defaults to the keyless DuckDuckGo backend. Set a backend
+explicitly when you want a cloud provider or a self-hosted SearXNG instance.
+
+| Variable | Purpose |
+| --- | --- |
+| `KOLEGA_CODE_WEB_SEARCH_BACKEND` | Backend for `web_search`: `duckduckgo`, `firecrawl`, `tavily`, or `searxng` |
+| `FIRECRAWL_API_KEY` | Optional Firecrawl key for higher rate limits |
+| `TAVILY_API_KEY` | Tavily API key |
+| `SEARXNG_BASE_URL` | Base URL for a self-hosted SearXNG instance |
+
 ## Telemetry (Langfuse)
 
 Optional [Langfuse](https://langfuse.com/) tracing of LLM usage.
@@ -113,6 +125,9 @@ KOLEGA_CODE_PROVIDER=moonshot
 KOLEGA_CODE_MODEL=kimi-k2.7-code
 KOLEGA_CODE_THINKING_EFFORT=auto
 
+# Optional: web search
+KOLEGA_CODE_WEB_SEARCH_BACKEND=duckduckgo
+
 # Optional: Langfuse tracing
 LANGFUSE_HOST=https://us.cloud.langfuse.com
 LANGFUSE_PUBLIC_KEY=

{kolega_code-0.6.0 → kolega_code-0.7.0}/docs/src/content/docs/configuration/settings-and-api-keys.mdx

@@ -32,6 +32,13 @@ agents (planning, building, investigation, general, browser) their own provider,
 model, and effort. Leave a role on **Default** to inherit the active model. See
 [Per-agent models](../providers-and-models/#per-agent-models).
 
+The **Web Search** section configures the `web_search` tool. DuckDuckGo is the
+default and needs no key. Firecrawl can also run without a key, with an optional
+key for higher rate limits. Tavily requires a key, and SearXNG requires the base
+URL of your self-hosted instance. The same settings can be supplied with
+[`KOLEGA_CODE_WEB_SEARCH_BACKEND`, `FIRECRAWL_API_KEY`, `TAVILY_API_KEY`, and
+`SEARXNG_BASE_URL`](../environment-variables/#web-search).
+
 ## Where settings live
 
 Settings are stored as JSON in your platform's state directory, in a file named
@@ -56,7 +63,8 @@ The file looks like this:
   "active_thinking_effort": "auto",
   "api_keys": {
     "moonshot": "sk-...",
-    "deepseek": "sk-..."
+    "deepseek": "sk-...",
+    "tavily": "tvly-..."
   },
   "agent_models": {
     "investigation": {
@@ -64,13 +72,17 @@ The file looks like this:
       "model": "deepseek-v4-flash",
       "thinking_effort": "high"
     }
-  }
+  },
+  "web_search_backend": "tavily",
+  "web_search_base_url": null
 }
 ```
 
 `agent_models` holds per-agent overrides keyed by role (`planning`, `building`,
 `investigation`, `general`, `browser`); a role that is absent inherits the active
 model. The field is optional and older `schema_version` files load unchanged.
+Cloud web-search keys are stored in `api_keys` under their backend names
+(`firecrawl` or `tavily`); `web_search_base_url` is used by SearXNG.
 
 <Aside type="caution" title="Keys are stored in plaintext">
 API keys are written to `settings.json` in plaintext, but the file is created with
@@ -83,7 +95,7 @@ store keys on disk at all, supply them via
 
 <FileTree>
 - kolega-code/
-  - settings.json   Provider, model, thinking effort, and API keys (0600)
+  - settings.json   Provider, model, web search, thinking effort, and API keys (0600)
   - sessions/
     - &lt;session-id&gt;.json   One file per saved session
 </FileTree>

{kolega_code-0.6.0 → kolega_code-0.7.0}/docs/src/content/docs/index.mdx

@@ -19,8 +19,9 @@ and your sessions, settings, and API keys are stored on your own machine.
   dedicated terminal view in the UI.
 - **Plans before it builds.** A read-only **Plan mode** produces a reviewable plan
   and a shared task list; **Build mode** implements it.
-- **Browses the web.** A built-in browser agent (powered by Playwright) can fetch
-  pages and interact with sites when a task needs it.
+- **Searches and browses the web.** The agent can search for relevant pages,
+  fetch URLs directly, or use the built-in browser agent (powered by Playwright)
+  when a task needs site interaction.
 - **Dispatches sub-agents.** For larger tasks, the main agent can hand off to
   specialized agents (investigation, browser, coding, general) and track their
   activity live.

{kolega_code-0.6.0 → kolega_code-0.7.0}/kolega_code/__init__.py

@@ -148,4 +148,4 @@ __all__ = [
     "parse_git_status_output",
 ]
 
-__version__ = "0.6.0"
+__version__ = "0.7.0"

{kolega_code-0.6.0 → kolega_code-0.7.0}/kolega_code/agent/__init__.py

@@ -39,4 +39,4 @@ __all__ = [
     "ToolExtension",
 ]
 
-__version__ = "0.6.0"
+__version__ = "0.7.0"

{kolega_code-0.6.0 → kolega_code-0.7.0}/kolega_code/agent/tests/test_agent_tools_inventory.py

@@ -104,6 +104,7 @@ def test_investigation_agent_tools(project_path, mock_connection_manager, agent_
         "sleep",
         "think_hard",
         "web_fetch",
+        "web_search",
     ]
 
     assert len(tools) == len(expected_tools)

kolega_code-0.7.0/kolega_code/agent/tests/tool_backend/test_web_search_tool.py

@@ -0,0 +1,366 @@
+from types import SimpleNamespace
+from unittest.mock import AsyncMock, Mock, patch
+
+import httpx
+import pytest
+
+from kolega_code.agent.tool_backend.search_backends import (
+    DEFAULT_BACKEND,
+    SearchBackendError,
+    SearchBackendNotConfigured,
+    SearchBackendRateLimited,
+    SearchBackendUnavailable,
+    SearchResponse,
+    SearchResult,
+    available_backends,
+    backend_names,
+    build_search_backend,
+    get_backend_class,
+)
+from kolega_code.agent.tool_backend.search_backends.base import clamp_results
+from kolega_code.agent.tool_backend.web_search_tool import WebSearchTool
+from kolega_code.config import AgentConfig, ModelConfig, ModelProvider
+
+_DUCK = "kolega_code.agent.tool_backend.search_backends.duckduckgo"
+_TAVILY = "kolega_code.agent.tool_backend.search_backends.tavily"
+_FIRE = "kolega_code.agent.tool_backend.search_backends.firecrawl"
+_SEARX = "kolega_code.agent.tool_backend.search_backends.searxng"
+
+
+# --------------------------------------------------------------------------- registry
+
+
+def test_registry_lists_all_backends() -> None:
+    assert set(backend_names()) == {"duckduckgo", "firecrawl", "tavily", "searxng"}
+    # Default backend is first in the TUI option list and is keyless.
+    labels = available_backends()
+    assert labels[0][1] == DEFAULT_BACKEND == "duckduckgo"
+    assert get_backend_class("duckduckgo").requires_api_key is False
+    # Optional-key model: Firecrawl is keyless-capable but accepts a key for higher limits;
+    # Tavily requires one; DuckDuckGo/SearXNG take no key.
+    assert get_backend_class("firecrawl").requires_api_key is False
+    assert get_backend_class("firecrawl").accepts_api_key is True
+    assert get_backend_class("tavily").requires_api_key is True
+    assert get_backend_class("tavily").accepts_api_key is True
+    assert get_backend_class("duckduckgo").accepts_api_key is False
+    assert get_backend_class("searxng").accepts_api_key is False
+
+
+def test_build_unknown_backend_raises_typed_error() -> None:
+    with pytest.raises(SearchBackendError, match="Unknown web_search backend"):
+        build_search_backend("nope")
+
+
+@pytest.mark.parametrize(("requested", "expected"), [(-3, 1), (0, 1), (5, 5), (50, 10), ("bad", 5)])
+def test_clamp_results(requested, expected) -> None:
+    assert clamp_results(requested) == expected
+
+
+# ------------------------------------------------------------------------- duckduckgo
+
+
+class _DummyDDGS:
+    def __init__(self, rows=None, exc=None):
+        self._rows = rows or []
+        self._exc = exc
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *args):
+        return False
+
+    def text(self, query, max_results=5):
+        if self._exc:
+            raise self._exc
+        return self._rows
+
+
+@pytest.mark.asyncio
+async def test_duckduckgo_maps_rows() -> None:
+    rows = [{"title": "T", "href": "https://a.test", "body": "snippet"}, {"title": "", "href": "", "body": "x"}]
+    with patch(f"{_DUCK}.DDGS", lambda: _DummyDDGS(rows=rows)):
+        response = await build_search_backend("duckduckgo").search("q", max_results=3)
+    assert response.backend == "duckduckgo"
+    # The second row has no href and is dropped.
+    assert [r.url for r in response.results] == ["https://a.test"]
+    assert response.results[0].snippet == "snippet"
+
+
+@pytest.mark.asyncio
+async def test_duckduckgo_rate_limit_mapped() -> None:
+    from ddgs.exceptions import RatelimitException
+
+    with patch(f"{_DUCK}.DDGS", lambda: _DummyDDGS(exc=RatelimitException("429"))):
+        with pytest.raises(SearchBackendRateLimited):
+            await build_search_backend("duckduckgo").search("q")
+
+
+@pytest.mark.asyncio
+async def test_duckduckgo_generic_error_unavailable() -> None:
+    with patch(f"{_DUCK}.DDGS", lambda: _DummyDDGS(exc=RuntimeError("boom"))):
+        with pytest.raises(SearchBackendUnavailable):
+            await build_search_backend("duckduckgo").search("q")
+
+
+# ----------------------------------------------------------------------------- tavily
+
+
+@pytest.mark.asyncio
+async def test_tavily_requires_key() -> None:
+    with pytest.raises(SearchBackendNotConfigured):
+        await build_search_backend("tavily", api_key=None).search("q")
+
+
+@pytest.mark.asyncio
+async def test_tavily_success_with_answer() -> None:
+    payload = {
+        "answer": "the answer",
+        "results": [{"title": "T", "url": "https://a.test", "content": "body"}, {"url": ""}],
+    }
+    client = Mock()
+    client.search.return_value = payload
+    with patch(f"{_TAVILY}.TavilyClient", return_value=client):
+        response = await build_search_backend("tavily", api_key="k").search("q", max_results=2)
+    assert response.answer == "the answer"
+    assert [r.url for r in response.results] == ["https://a.test"]
+    # Key + count are passed through.
+    _, kwargs = client.search.call_args
+    assert kwargs["max_results"] == 2 and kwargs["include_answer"] is True
+
+
+@pytest.mark.asyncio
+async def test_tavily_invalid_key_mapped_to_not_configured() -> None:
+    from tavily.errors import InvalidAPIKeyError
+
+    client = Mock()
+    client.search.side_effect = InvalidAPIKeyError("bad key")
+    with patch(f"{_TAVILY}.TavilyClient", return_value=client):
+        with pytest.raises(SearchBackendNotConfigured):
+            await build_search_backend("tavily", api_key="bad").search("q")
+
+
+# --------------------------------------------------------------------------- firecrawl
+
+
+@pytest.mark.asyncio
+async def test_firecrawl_keyless_uses_rest() -> None:
+    # No key -> direct REST (Firecrawl's free tier), no SDK involved.
+    payload = {
+        "success": True,
+        "data": {
+            "web": [
+                {"url": "https://a.test", "title": "T", "description": "desc"},
+                {"url": "", "title": "skip"},
+            ]
+        },
+    }
+    with patch(f"{_FIRE}.httpx.AsyncClient", _post_client(_DummyResponse(200, payload))):
+        response = await build_search_backend("firecrawl", api_key=None).search("q", max_results=3)
+    assert response.backend == "firecrawl"
+    assert [r.url for r in response.results] == ["https://a.test"]
+    assert response.results[0].snippet == "desc"
+
+
+@pytest.mark.asyncio
+async def test_firecrawl_keyless_429_rate_limited() -> None:
+    with patch(f"{_FIRE}.httpx.AsyncClient", _post_client(_DummyResponse(429))):
+        with pytest.raises(SearchBackendRateLimited):
+            await build_search_backend("firecrawl", api_key=None).search("q")
+
+
+@pytest.mark.asyncio
+async def test_firecrawl_keyed_uses_sdk() -> None:
+    data = SimpleNamespace(
+        web=[
+            SimpleNamespace(url="https://a.test", title="T", description="desc", markdown="full"),
+            SimpleNamespace(url=None, title="skip", description="", markdown=""),
+        ]
+    )
+    client = Mock()
+    client.search.return_value = data
+    with patch(f"{_FIRE}.Firecrawl", return_value=client):
+        response = await build_search_backend("firecrawl", api_key="fc").search("q", max_results=4)
+    assert [r.url for r in response.results] == ["https://a.test"]
+    assert response.results[0].snippet == "desc"
+    assert response.results[0].content == "full"
+    # limit is forwarded; firecrawl timeout is milliseconds.
+    _, kwargs = client.search.call_args
+    assert kwargs["limit"] == 4 and kwargs["timeout"] == int(WebSearchTool.SEARCH_TIMEOUT_SECONDS * 1000)
+
+
+@pytest.mark.asyncio
+async def test_firecrawl_401_mapped_to_not_configured() -> None:
+    client = Mock()
+    client.search.side_effect = RuntimeError("HTTP 401 Unauthorized")
+    with patch(f"{_FIRE}.Firecrawl", return_value=client):
+        with pytest.raises(SearchBackendNotConfigured):
+            await build_search_backend("firecrawl", api_key="fc").search("q")
+
+
+# ----------------------------------------------------------------------------- searxng
+
+
+class _DummyResponse:
+    def __init__(self, status_code=200, payload=None, json_error=False):
+        self.status_code = status_code
+        self._payload = payload or {}
+        self._json_error = json_error
+
+    def json(self):
+        if self._json_error:
+            raise ValueError("not json")
+        return self._payload
+
+
+def _searx_client(response=None, get_exc=None):
+    class _DummyAsyncClient:
+        def __init__(self, *args, **kwargs):
+            pass
+
+        async def __aenter__(self):
+            return self
+
+        async def __aexit__(self, *args):
+            return False
+
+        async def get(self, url, params=None):
+            if get_exc:
+                raise get_exc
+            return response
+
+    return _DummyAsyncClient
+
+
+def _post_client(response=None, post_exc=None):
+    class _DummyAsyncClient:
+        def __init__(self, *args, **kwargs):
+            pass
+
+        async def __aenter__(self):
+            return self
+
+        async def __aexit__(self, *args):
+            return False
+
+        async def post(self, url, json=None, headers=None):
+            if post_exc:
+                raise post_exc
+            return response
+
+    return _DummyAsyncClient
+
+
+@pytest.mark.asyncio
+async def test_searxng_requires_base_url() -> None:
+    with pytest.raises(SearchBackendNotConfigured):
+        await build_search_backend("searxng", base_url=None).search("q")
+
+
+@pytest.mark.asyncio
+async def test_searxng_success() -> None:
+    payload = {"results": [{"title": "T", "url": "https://a.test", "content": "c"}, {"url": ""}]}
+    with patch(f"{_SEARX}.httpx.AsyncClient", _searx_client(_DummyResponse(200, payload))):
+        response = await build_search_backend("searxng", base_url="https://s.test/").search("q", max_results=5)
+    assert [r.url for r in response.results] == ["https://a.test"]
+
+
+@pytest.mark.asyncio
+async def test_searxng_429_rate_limited() -> None:
+    with patch(f"{_SEARX}.httpx.AsyncClient", _searx_client(_DummyResponse(429))):
+        with pytest.raises(SearchBackendRateLimited):
+            await build_search_backend("searxng", base_url="https://s.test").search("q")
+
+
+@pytest.mark.asyncio
+async def test_searxng_http_error_unavailable() -> None:
+    with patch(f"{_SEARX}.httpx.AsyncClient", _searx_client(_DummyResponse(503))):
+        with pytest.raises(SearchBackendUnavailable):
+            await build_search_backend("searxng", base_url="https://s.test").search("q")
+
+
+@pytest.mark.asyncio
+async def test_searxng_timeout_unavailable() -> None:
+    with patch(f"{_SEARX}.httpx.AsyncClient", _searx_client(get_exc=httpx.TimeoutException("slow"))):
+        with pytest.raises(SearchBackendUnavailable):
+            await build_search_backend("searxng", base_url="https://s.test").search("q")
+
+
+# ------------------------------------------------------------------------- WebSearchTool
+
+
+@pytest.fixture
+def agent_config():
+    return AgentConfig(
+        anthropic_api_key="k",
+        long_context_config=ModelConfig(provider=ModelProvider.ANTHROPIC, model="m"),
+        fast_config=ModelConfig(provider=ModelProvider.ANTHROPIC, model="f"),
+        thinking_config=ModelConfig(provider=ModelProvider.ANTHROPIC, model="t"),
+    )
+
+
+@pytest.fixture
+def caller():
+    c = Mock()
+    c.agent_name = "coder"
+    c.current_tool_call_id = "call-1"
+    c.sub_agent = False
+    return c
+
+
+@pytest.fixture
+def tool(tmp_path, agent_config, caller):
+    return WebSearchTool(tmp_path, "ws", "th", AsyncMock(), agent_config, caller)
+
+
+@pytest.mark.asyncio
+async def test_tool_empty_query_guard(tool) -> None:
+    assert (await tool.web_search("   ")).startswith("Error: Provide a non-empty search query.")
+
+
+@pytest.mark.asyncio
+async def test_tool_formats_results_and_streams(tool) -> None:
+    response = SearchResponse(
+        query="cats",
+        backend="duckduckgo",
+        results=[SearchResult(title="Cats", url="https://cats.test", snippet="meow")],
+    )
+    backend = Mock()
+    backend.search = AsyncMock(return_value=response)
+    with patch("kolega_code.agent.tool_backend.web_search_tool.build_search_backend", return_value=backend):
+        result = await tool.web_search("cats", max_results=3)
+    # The URL appears as its own line (exact match, not a substring check).
+    assert any(line.strip() == "https://cats.test" for line in result.splitlines())
+    assert "Cats" in result
+    assert "meow" in result
+    # A final (is_complete) streaming update is emitted.
+    final = [c for c in tool.connection_manager.broadcast_event.call_args_list]
+    assert final, "expected streaming updates"
+
+
+@pytest.mark.asyncio
+async def test_tool_empty_results_message(tool) -> None:
+    response = SearchResponse(query="zzz", backend="duckduckgo", results=[])
+    backend = Mock()
+    backend.search = AsyncMock(return_value=response)
+    with patch("kolega_code.agent.tool_backend.web_search_tool.build_search_backend", return_value=backend):
+        result = await tool.web_search("zzz")
+    assert result == "No results found for: zzz"
+
+
+@pytest.mark.asyncio
+async def test_tool_not_configured_is_friendly(tool) -> None:
+    backend = Mock()
+    backend.search = AsyncMock(side_effect=SearchBackendNotConfigured("needs a key"))
+    with patch("kolega_code.agent.tool_backend.web_search_tool.build_search_backend", return_value=backend):
+        result = await tool.web_search("q")
+    assert result.startswith("Error:") and "Settings > Web Search" in result
+
+
+@pytest.mark.asyncio
+async def test_tool_never_raises_on_unexpected(tool) -> None:
+    backend = Mock()
+    backend.search = AsyncMock(side_effect=RuntimeError("kaboom"))
+    with patch("kolega_code.agent.tool_backend.web_search_tool.build_search_backend", return_value=backend):
+        result = await tool.web_search("q")
+    assert result.startswith("Error: web_search failed:")

kolega_code-0.7.0/kolega_code/agent/tool_backend/search_backends/__init__.py

@@ -0,0 +1,83 @@
+"""Pluggable web-search backends for the ``web_search`` tool.
+
+To add a backend: create a module with a ``SearchBackend`` subclass, import it below,
+and add it to ``_BACKENDS``. The TUI Select options and config validation derive from
+this registry, so no other wiring is needed.
+"""
+
+from __future__ import annotations
+
+from typing import Dict, List, Optional, Tuple, Type
+
+from .base import DEFAULT_RESULTS, DEFAULT_TIMEOUT_SECONDS, SearchBackend, clamp_results
+from .duckduckgo import DuckDuckGoBackend
+from .errors import (
+    SearchBackendError,
+    SearchBackendNotConfigured,
+    SearchBackendRateLimited,
+    SearchBackendUnavailable,
+)
+from .firecrawl import FirecrawlBackend
+from .models import SearchResponse, SearchResult
+from .searxng import SearxngBackend
+from .tavily import TavilyBackend
+
+DEFAULT_BACKEND = "duckduckgo"
+
+_BACKENDS: Dict[str, Type[SearchBackend]] = {
+    backend.name: backend
+    for backend in (DuckDuckGoBackend, FirecrawlBackend, TavilyBackend, SearxngBackend)
+}
+
+
+def backend_names() -> List[str]:
+    """All registered backend names."""
+    return list(_BACKENDS)
+
+
+def available_backends() -> List[Tuple[str, str]]:
+    """``(label, name)`` pairs for the TUI Select, with the default backend first."""
+    ordered = [_BACKENDS[DEFAULT_BACKEND]] + [
+        backend for name, backend in _BACKENDS.items() if name != DEFAULT_BACKEND
+    ]
+    return [(backend.label, backend.name) for backend in ordered]
+
+
+def get_backend_class(name: str) -> Type[SearchBackend]:
+    """Look up a backend class by name, or raise SearchBackendError for an unknown name."""
+    try:
+        return _BACKENDS[name]
+    except KeyError as exc:
+        valid = ", ".join(_BACKENDS)
+        raise SearchBackendError(f"Unknown web_search backend '{name}'. Valid: {valid}.") from exc
+
+
+def build_search_backend(
+    name: Optional[str],
+    *,
+    api_key: Optional[str] = None,
+    base_url: Optional[str] = None,
+    timeout: float = DEFAULT_TIMEOUT_SECONDS,
+) -> SearchBackend:
+    """Construct the configured backend instance."""
+    backend_cls = get_backend_class(name or DEFAULT_BACKEND)
+    return backend_cls(api_key=api_key, base_url=base_url, timeout=timeout)
+
+
+__all__ = [
+    "DEFAULT_BACKEND",
+    "DEFAULT_RESULTS",
+    "DEFAULT_TIMEOUT_SECONDS",
+    "SearchBackend",
+    "SearchBackendError",
+    "SearchBackendNotConfigured",
+    "SearchBackendRateLimited",
+    "SearchBackendUnavailable",
+    "SearchResponse",
+    "SearchResult",
+    "available_backends",
+    "backend_names",
+    "build_search_backend",
+    "clamp_results",
+    "get_backend_class",
+]