Skip to content

Your lightweight open-source personal agent.

fix(web): propagate web_fetch failures as structured tool errors

Kail Tian4f7479ca64ea
diff --git a/nanobot/agent/tools/web.py b/nanobot/agent/tools/web.py
index 087acf04c..0fc75297b 100644
--- a/nanobot/agent/tools/web.py
+++ b/nanobot/agent/tools/web.py
@@ -1166,7 +1166,7 @@ class WebFetchTool(Tool):
max_chars = cast(int, kwargs.pop("maxChars", max_chars) or self.max_chars)
is_valid, error_msg = _validate_url_safe(url)
if not is_valid:
- return json.dumps({"error": f"URL validation failed: {error_msg}", "url": url}, ensure_ascii=False)
+ return ToolResult.error(json.dumps({"error": f"URL validation failed: {error_msg}", "url": url}, ensure_ascii=False))
# Detect and fetch images directly to avoid Jina's textual image captioning.
# This local preflight also proves that no credential-bearing URL occurs
@@ -1184,9 +1184,9 @@ class WebFetchTool(Tool):
)
)
if redirect_error:
- return json.dumps({"error": redirect_error, "url": url}, ensure_ascii=False)
+ return ToolResult.error(json.dumps({"error": redirect_error, "url": url}, ensure_ascii=False))
if r is None:
- return json.dumps({"error": "Fetch failed", "url": url}, ensure_ascii=False)
+ return ToolResult.error(json.dumps({"error": "Fetch failed", "url": url}, ensure_ascii=False))
jina_remote_safe = not chain_carries_credentials
try:
@@ -1201,7 +1201,7 @@ class WebFetchTool(Tool):
except Exception as e:
unsafe_error = _unsafe_url_request_error(e)
if unsafe_error is not None:
- return json.dumps({"error": f"URL validation failed: {unsafe_error}", "url": url}, ensure_ascii=False)
+ return ToolResult.error(json.dumps({"error": f"URL validation failed: {unsafe_error}", "url": url}, ensure_ascii=False))
logger.debug(
"Pre-fetch image detection failed for {} ({})",
_redact_url_for_log(url),
@@ -1277,9 +1277,9 @@ class WebFetchTool(Tool):
headers={"User-Agent": self.user_agent},
)
if redirect_error:
- return json.dumps({"error": redirect_error, "url": url}, ensure_ascii=False)
+ return ToolResult.error(json.dumps({"error": redirect_error, "url": url}, ensure_ascii=False))
if r is None:
- return json.dumps({"error": "Fetch failed", "url": url}, ensure_ascii=False)
+ return ToolResult.error(json.dumps({"error": "Fetch failed", "url": url}, ensure_ascii=False))
r.raise_for_status()
ctype = r.headers.get("content-type", "")
@@ -1318,14 +1318,14 @@ class WebFetchTool(Tool):
_redact_url_for_log(url),
type(e).__name__,
)
- return json.dumps({"error": f"Proxy error: {e}", "url": url}, ensure_ascii=False)
+ return ToolResult.error(json.dumps({"error": f"Proxy error: {e}", "url": url}, ensure_ascii=False))
except Exception as e:
logger.warning(
"WebFetch error for {} ({})",
_redact_url_for_log(url),
type(e).__name__,
)
- return json.dumps({"error": str(e), "url": url}, ensure_ascii=False)
+ return ToolResult.error(json.dumps({"error": str(e), "url": url}, ensure_ascii=False))
def _extract_readable_html(self, html_content: str, extract_mode: str) -> str:
from readability import Document # pyright: ignore[reportMissingTypeStubs]
diff --git a/tests/agent/test_runner_errors.py b/tests/agent/test_runner_errors.py
index 3211014f7..de2c8b981 100644
--- a/tests/agent/test_runner_errors.py
+++ b/tests/agent/test_runner_errors.py
@@ -3,6 +3,8 @@ session message isolation, and tool result preservation."""
from __future__ import annotations
+import json
+import socket
from types import SimpleNamespace
from unittest.mock import AsyncMock, MagicMock
@@ -12,6 +14,8 @@ from agent.runner_helpers import make_run_spec
from nanobot.agent.hook import AgentHook, AgentHookContext
from nanobot.agent.tools import ToolResult
from nanobot.agent.tools.execution import execute_tool_calls
+from nanobot.agent.tools.registry import ToolRegistry
+from nanobot.agent.tools.web import WebFetchTool
from nanobot.config.schema import AgentDefaults
from nanobot.providers.base import LLMProvider, LLMResponse, ToolCallRequest
@@ -237,6 +241,76 @@ async def test_runner_returns_structured_tool_error_to_model_for_recovery():
]
[email protected]("url,ssrf", [
+ pytest.param("not-a-url", False, id="invalid-url"),
+ pytest.param("http://127.0.0.1/admin", True, id="blocked-loopback"),
+])
+async def test_runner_recognizes_web_fetch_errors(monkeypatch, url, ssrf):
+ from nanobot.agent.runner import AgentRunner
+
+ monkeypatch.setattr("nanobot.security.network._allowed_networks", [])
+ monkeypatch.setattr("nanobot.security.network.socket.getaddrinfo", MagicMock(
+ return_value=[(socket.AF_INET, socket.SOCK_STREAM, 0, "", ("127.0.0.1", 0))],
+ ))
+ http_client = MagicMock(side_effect=AssertionError("Rejected URLs must not reach HTTP"))
+ monkeypatch.setattr("nanobot.agent.tools.web.httpx.AsyncClient", http_client)
+ tools = ToolRegistry()
+ tools.register(WebFetchTool())
+ hook = AgentHook()
+ error_hook = AsyncMock()
+ success_hook = AsyncMock()
+ monkeypatch.setattr(hook, "on_execute_tool_error", error_hook)
+ monkeypatch.setattr(hook, "after_execute_tool", success_hook)
+ provider = MagicMock(spec=LLMProvider)
+ provider.chat_stream_with_retry = AsyncMock(side_effect=[
+ LLMResponse(content="fetching", tool_calls=[
+ ToolCallRequest(id="fetch_1", name="web_fetch", arguments={"url": url}),
+ ]),
+ LLMResponse(content="Unable to fetch this URL."),
+ ])
+
+ result = await AgentRunner().run(make_run_spec(provider,
+ initial_messages=[{"role": "user", "content": f"Read {url}"}],
+ tools=tools,
+ model="test-model",
+ max_iterations=2,
+ max_tool_result_chars=_MAX_TOOL_RESULT_CHARS,
+ hook=hook,
+ ))
+
+ assert result.stop_reason == "completed"
+ assert result.final_content == "Unable to fetch this URL."
+ assert len(result.tool_events) == 1
+ assert result.tool_events[0]["status"] == "error"
+ assert result.tools_used == []
+ error_hook.assert_awaited_once()
+ success_hook.assert_not_awaited()
+ http_client.assert_not_called()
+ raw_error = error_hook.await_args.args[-1]
+ assert isinstance(raw_error, ToolResult) and raw_error.is_error
+ raw_payload = json.loads(raw_error)
+ assert raw_payload["url"] == url
+ assert raw_payload["error"].startswith("URL validation failed:")
+
+ assert provider.chat_stream_with_retry.await_count == 2
+ next_request = provider.chat_stream_with_retry.await_args_list[1].kwargs["messages"]
+ tool_message = next(message for message in next_request if message.get("role") == "tool")
+ assert tool_message["tool_call_id"] == "fetch_1"
+ content = tool_message["content"]
+ assert content.startswith(str(raw_error) + "\n\n")
+ assert json.JSONDecoder().raw_decode(content)[0] == raw_payload
+ retry_hint = "[Analyze the error above and try a different approach.]"
+ if ssrf:
+ assert result.tool_events[0]["detail"].startswith("ssrf_violation:")
+ assert "non-bypassable security boundary" in content
+ assert "Do not retry" in content
+ assert "tools.ssrfWhitelist" in content
+ assert retry_hint not in content
+ else:
+ assert content.count(retry_hint) == 1
+
+
@pytest.mark.asyncio
async def test_runner_preserves_successful_exec_output_that_starts_with_error():
from nanobot.agent.runner import AgentRunner
diff --git a/tests/tools/test_web_fetch_security.py b/tests/tools/test_web_fetch_security.py
index 9d57e70a7..63097d4d0 100644
--- a/tests/tools/test_web_fetch_security.py
+++ b/tests/tools/test_web_fetch_security.py
@@ -5,13 +5,14 @@ from __future__ import annotations
import asyncio
import json
import socket
-from unittest.mock import patch
+from unittest.mock import AsyncMock, patch
from urllib.request import getproxies_environment
import httpx
import pytest
from nanobot.agent.tools import web as web_module
+from nanobot.agent.tools.registry import is_tool_error_result
from nanobot.agent.tools.web import WebFetchTool, _get_with_safe_redirects
from nanobot.config.schema import WebFetchConfig
from nanobot.security.network import PinnedDNSAsyncTransport
@@ -96,6 +97,7 @@ async def test_web_fetch_blocks_private_ip():
with patch("nanobot.security.network.socket.getaddrinfo", _fake_resolve_private):
result = await tool.execute(url="http://169.254.169.254/computeMetadata/v1/")
data = json.loads(result)
+ assert is_tool_error_result(result)
assert "error" in data
assert "private" in data["error"].lower() or "blocked" in data["error"].lower()
@@ -108,6 +110,7 @@ async def test_web_fetch_blocks_localhost():
with patch("nanobot.security.network.socket.getaddrinfo", _resolve_localhost):
result = await tool.execute(url="http://localhost/admin")
data = json.loads(result)
+ assert is_tool_error_result(result)
assert "error" in data
@@ -126,6 +129,7 @@ async def test_web_fetch_blocks_localhost_even_in_full_workspace_scope(tmp_path)
finally:
reset_workspace_scope(token)
data = json.loads(result)
+ assert is_tool_error_result(result)
assert "error" in data
@@ -139,6 +143,7 @@ async def test_web_fetch_result_contains_untrusted_flag(monkeypatch: pytest.Monk
result = await tool.execute(url="https://example.com/page")
data = json.loads(result)
+ assert not is_tool_error_result(result)
assert data.get("untrusted") is True
assert "[External content" in data.get("text", "")
@@ -278,6 +283,7 @@ async def test_web_fetch_does_not_fallback_after_pinned_dns_rebind_rejection(mon
result = await tool.execute(url="http://evil.example/page")
data = json.loads(result)
+ assert is_tool_error_result(result)
assert "error" in data
assert "blocked" in data["error"].lower()
assert calls["evil.example"] == 3
@@ -452,6 +458,7 @@ async def test_web_fetch_blocks_private_redirect_before_readability_request(monk
result = await tool.execute(url="https://attacker.example/start")
data = json.loads(result)
+ assert is_tool_error_result(result)
assert "error" in data
assert "redirect blocked" in data["error"].lower()
assert requested == ["https://attacker.example/start"]
@@ -498,6 +505,7 @@ async def test_web_fetch_blocks_private_redirect_before_returning_image(monkeypa
result = await tool.execute(url="https://example.com/image.png")
data = json.loads(result)
+ assert is_tool_error_result(result)
assert "error" in data
assert "redirect blocked" in data["error"].lower()
@@ -539,6 +547,55 @@ async def test_web_fetch_does_not_request_private_redirect_target(monkeypatch):
result = await tool.execute(url="https://attacker.example/start")
data = json.loads(result)
+ assert is_tool_error_result(result)
assert "error" in data
assert "redirect blocked" in data["error"].lower()
assert requested == ["https://attacker.example/start"]
+
+
+ ("failure", "error_text"),
+ [("http", "404"), ("timeout", "request timed out"), ("proxy", "Proxy error: proxy unavailable")],
+)
+async def test_web_fetch_marks_terminal_fetch_failures_as_errors(monkeypatch, failure, error_text):
+ url = "https://93.184.216.34/page"
+ tool = WebFetchTool(config=WebFetchConfig(use_jina_reader=False))
+
+ def handler(request: httpx.Request) -> httpx.Response:
+ if failure == "timeout":
+ raise httpx.ReadTimeout("request timed out", request=request)
+ if failure == "proxy":
+ raise httpx.ProxyError("proxy unavailable", request=request)
+ return httpx.Response(404, request=request)
+
+ monkeypatch.setattr(web_module, "_pinned_dns_transport", lambda: httpx.MockTransport(handler))
+
+ result = await tool.execute(url=url)
+
+ assert is_tool_error_result(result)
+ data = json.loads(result)
+ assert data["url"] == url
+ assert error_text in data["error"]
+
+
+async def test_web_fetch_jina_fallback_keeps_json_error_content_successful(monkeypatch):
+ url = "https://93.184.216.34/page"
+ tool = WebFetchTool()
+ jina = AsyncMock(return_value=None)
+ source = {"error": "This is fetched document content, not a tool failure."}
+
+ def handler(request: httpx.Request) -> httpx.Response:
+ return httpx.Response(200, json=source, request=request)
+
+ monkeypatch.setattr(web_module, "_pinned_dns_transport", lambda: httpx.MockTransport(handler))
+ monkeypatch.setattr(tool, "_fetch_jina", jina)
+
+ result = await tool.execute(url=url)
+
+ jina.assert_awaited_once()
+ assert not is_tool_error_result(result)
+ data = json.loads(result)
+ assert data["status"] == 200
+ assert data["extractor"] == "json"
+ assert data["untrusted"] is True
+ assert json.dumps(source, indent=2) in data["text"]