Skip to content

Use Claude Code, Codex, VSCode, Pi, and OpenCode (and 6 other harnesses) for free (1.3B+ free tokens) from your terminal, app, IDE, or phone, and now from the browser with native browser sessions (multi-harness + multi-model) like OpenClaw (voice supported + ToS friendly)

Python

Separate server-tool orchestration from HTTP (#1800)

Ali Khokhar7cdfd7313008
diff --git a/e2e/conftest.py b/e2e/conftest.py
index 7a543534..f2e32db1 100644
--- a/e2e/conftest.py
+++ b/e2e/conftest.py
@@ -34,6 +34,7 @@ from free_claude_code.runtime.asgi import RuntimeASGIApp
from free_claude_code.runtime.configuration import ConfigurationService
from free_claude_code.runtime.folder_picker import NativeFolderPicker
from free_claude_code.runtime.provider_manager import ProviderRuntimeManager
+from tests.web_tools_support import StubWebToolsClient
class _ModelListingProvider(BaseProvider):
@@ -212,6 +213,7 @@ def admin_base_url(
requests=manager,
admin=runtime,
tasks=runtime,
+ web_tools=StubWebToolsClient(),
code=code_control.service,
)
),
diff --git a/pyproject.toml b/pyproject.toml
index 9ae8ec07..aab7b242 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
[project]
name = "free-claude-code"
-version = "6.2.28"
+version = "6.2.29"
description = "Local proxy connecting coding agents to OpenAI-compatible AI providers"
readme = "README.md"
requires-python = ">=3.14.0"
diff --git a/src/free_claude_code/api/handlers/messages.py b/src/free_claude_code/api/handlers/messages.py
index a7a08002..2dfd9e5f 100644
--- a/src/free_claude_code/api/handlers/messages.py
+++ b/src/free_claude_code/api/handlers/messages.py
@@ -1,7 +1,7 @@
"""Claude Messages API product flow."""
import asyncio
-from collections.abc import AsyncIterator, Callable, Mapping
+from collections.abc import AsyncIterator, Mapping
from dataclasses import dataclass, replace
from fastapi.responses import JSONResponse, Response
@@ -23,23 +23,12 @@ from free_claude_code.api.response_streams import (
terminal_execution_error_response,
trace_terminal_execution_error,
)
-from free_claude_code.api.web_tools.automatic_search import (
- stream_automatic_web_search_response,
-)
-from free_claude_code.api.web_tools.egress import (
- WebFetchEgressPolicy,
- web_fetch_allowed_scheme_set,
-)
-from free_claude_code.api.web_tools.request import (
- is_web_server_tool_request,
- plan_automatic_web_search,
- unsupported_server_tool_error,
-)
-from free_claude_code.api.web_tools.streaming import stream_web_server_tool_response
-from free_claude_code.application.errors import ApplicationError, InvalidRequestError
+from free_claude_code.application.errors import ApplicationError
from free_claude_code.application.execution import ProviderExecutor, TokenCounter
from free_claude_code.application.ports import ModelInfoLookup, ProviderResolver
from free_claude_code.application.routing import ModelRouter, RoutedMessagesRequest
+from free_claude_code.application.web_tools.ports import WebToolsPort
+from free_claude_code.application.web_tools.service import WebToolService
from free_claude_code.config.settings import Settings
from free_claude_code.core.anthropic import (
MessagesRequest,
@@ -69,7 +58,6 @@ class _MessagesCompleteResult:
_MessagesResult = _MessagesStreamResult | _MessagesCompleteResult
-MessageIntercept = Callable[[RoutedMessagesRequest], _MessagesResult | None]
class MessagesHandler:
@@ -80,6 +68,7 @@ class MessagesHandler:
settings: Settings,
provider_resolver: ProviderResolver,
*,
+ web_tools: WebToolsPort,
model_router: ModelRouter | None = None,
token_counter: TokenCounter = get_token_count,
provider_executor: ProviderExecutor | None = None,
@@ -89,7 +78,6 @@ class MessagesHandler:
) -> None:
self._settings = settings
self._model_router = model_router or ModelRouter(settings)
- self._token_counter = token_counter
self._provider_executor = provider_executor or ProviderExecutor(
provider_resolver,
progress_timeout_seconds=settings.provider_progress_timeout,
@@ -99,9 +87,11 @@ class MessagesHandler:
request_headers=request_headers,
model_info_lookup=model_info_lookup,
)
- self._message_intercepts: tuple[MessageIntercept, ...] = (
- self._intercept_web_server_tool,
- self._intercept_local_optimization,
+ self._web_tools = WebToolService(
+ settings=settings,
+ client=web_tools,
+ executor=self._provider_executor,
+ token_counter=token_counter,
)
async def create(
@@ -113,29 +103,14 @@ class MessagesHandler:
require_non_empty_messages(request_data.messages)
routed = self._model_router.resolve_messages_request(request_data)
routed = self._apply_message_routing_policies(routed)
- automatic_search = plan_automatic_web_search(
- routed.request,
- web_tools_enabled=self._settings.enable_web_server_tools,
+ tool_body = self._web_tools.try_stream_messages(
+ routed, request_id=request_id
+ )
+ result = (
+ _MessagesStreamResult(tool_body)
+ if tool_body is not None
+ else self._intercept_local_optimization(routed)
)
- if automatic_search is None:
- self._reject_unsupported_server_tools(routed)
- result = self._run_message_intercepts(routed)
- else:
- input_tokens = self._token_counter(
- routed.request.messages,
- routed.request.system,
- routed.request.tools,
- )
- result = _MessagesStreamResult(
- stream_automatic_web_search_response(
- self._provider_executor,
- routed,
- automatic_search,
- request_id=request_id,
- fallback_input_tokens=input_tokens,
- verbose_client_errors=self._settings.log_api_error_tracebacks,
- )
- )
if result is None:
logger.debug("No optimization matched, routing to provider")
result = _MessagesStreamResult(
@@ -303,14 +278,6 @@ class MessagesHandler:
),
)
- def _reject_unsupported_server_tools(self, routed: RoutedMessagesRequest) -> None:
- tool_err = unsupported_server_tool_error(
- routed.request,
- web_tools_enabled=self._settings.enable_web_server_tools,
- )
- if tool_err is not None:
- raise InvalidRequestError(tool_err)
-
def _apply_message_routing_policies(
self, routed: RoutedMessagesRequest
) -> RoutedMessagesRequest:
@@ -357,48 +324,6 @@ class MessagesHandler:
),
)
- def _run_message_intercepts(
- self, routed: RoutedMessagesRequest
- ) -> _MessagesResult | None:
- for intercept in self._message_intercepts:
- result = intercept(routed)
- if result is not None:
- return result
- return None
-
- def _intercept_web_server_tool(
- self, routed: RoutedMessagesRequest
- ) -> _MessagesResult | None:
- if not self._settings.enable_web_server_tools:
- return None
- if not is_web_server_tool_request(routed.request):
- return None
-
- input_tokens = self._token_counter(
- routed.request.messages, routed.request.system, routed.request.tools
- )
- trace_event(
- stage="routing",
- event="free_claude_code.api.optimization.web_server_tool",
- source="api",
- model=routed.resolved.original_model,
- )
- egress = WebFetchEgressPolicy(
- allow_private_network_targets=self._settings.web_fetch_allow_private_networks,
- allowed_schemes=web_fetch_allowed_scheme_set(
- self._settings.web_fetch_allowed_schemes
- ),
- )
- return _MessagesStreamResult(
- stream_web_server_tool_response(
- routed.request,
- input_tokens=input_tokens,
- web_fetch_egress=egress,
- response_model=routed.resolved.original_model,
- verbose_client_errors=self._settings.log_api_error_tracebacks,
- ),
- )
-
def _intercept_local_optimization(
self, routed: RoutedMessagesRequest
) -> _MessagesResult | None:
diff --git a/src/free_claude_code/api/ports.py b/src/free_claude_code/api/ports.py
index a09f696f..5c2fbfe6 100644
--- a/src/free_claude_code/api/ports.py
+++ b/src/free_claude_code/api/ports.py
@@ -11,6 +11,7 @@ from free_claude_code.application.connected_accounts import (
)
from free_claude_code.application.model_metadata import ProviderModelRefreshResult
from free_claude_code.application.ports import RequestRuntimePort, TaskController
+from free_claude_code.application.web_tools.ports import WebToolsPort
from free_claude_code.config.admin.state import ConfigInputValue, ValueState
from free_claude_code.core.json_types import JsonObject
@@ -72,4 +73,5 @@ class ApiServices:
requests: RequestRuntimePort
admin: AdminRuntimePort
tasks: TaskController
+ web_tools: WebToolsPort
code: CodeApplicationPort | None = None
diff --git a/src/free_claude_code/api/routes.py b/src/free_claude_code/api/routes.py
index 7af7b1ae..47f6640b 100644
--- a/src/free_claude_code/api/routes.py
+++ b/src/free_claude_code/api/routes.py
@@ -56,6 +56,7 @@ async def _create_messages_response(
await lease.wait_for_token_estimation()
handler = MessagesHandler(
lease.settings,
+ web_tools=services.web_tools,
provider_resolver=_provider_resolver(lease),
token_counter=get_token_count,
generation_id=lease.generation_id,
diff --git a/src/free_claude_code/api/web_tools/__init__.py b/src/free_claude_code/api/web_tools/__init__.py
deleted file mode 100644
index e0fd14c4..00000000
--- a/src/free_claude_code/api/web_tools/__init__.py
+++ /dev/null
@@ -1,17 +0,0 @@
-"""Submodules for Anthropic web server tool handling (search/fetch, egress, streaming)."""
-
-from .egress import (
- WebFetchEgressPolicy,
- WebFetchEgressViolation,
- enforce_web_fetch_egress,
-)
-from .request import is_web_server_tool_request
-from .streaming import stream_web_server_tool_response
-
-__all__ = [
- "WebFetchEgressPolicy",
- "WebFetchEgressViolation",
- "enforce_web_fetch_egress",
- "is_web_server_tool_request",
- "stream_web_server_tool_response",
-]
diff --git a/src/free_claude_code/api/web_tools/automatic_search.py b/src/free_claude_code/api/web_tools/automatic_search.py
deleted file mode 100644
index 170bc552..00000000
--- a/src/free_claude_code/api/web_tools/automatic_search.py
+++ /dev/null
@@ -1,232 +0,0 @@
-"""One provider decision for Claude Code's automatic WebSearch request."""
-
-import sys
-from collections.abc import AsyncIterator, Mapping
-from dataclasses import replace
-from urllib.parse import urlsplit
-
-from free_claude_code.application.execution import ProviderExecutor
-from free_claude_code.application.routing import RoutedMessagesRequest
-from free_claude_code.core.anthropic import (
- aggregate_anthropic_sse_to_message,
- anthropic_status_for_error_type,
-)
-from free_claude_code.core.failures import ExecutionFailure, FailureKind
-from free_claude_code.core.trace import close_stream_input, trace_event
-
-from .request import (
- HIDDEN_WEB_SEARCH_NAME,
- AutomaticWebSearchPlan,
- WebSearchDomainFilter,
-)
-from .streaming import stream_selected_web_search_response
-
-
-async def stream_automatic_web_search_response(
- provider_executor: ProviderExecutor,
- routed: RoutedMessagesRequest,
- plan: AutomaticWebSearchPlan,
- *,
- request_id: str,
- fallback_input_tokens: int,
- verbose_client_errors: bool,
-) -> AsyncIterator[str]:
- """Buffer one model decision, then replay it or execute one local search."""
- translated = replace(routed, request=plan.request)
- trace_event(
- stage="routing",
- event="free_claude_code.api.web_search.automatic_recognized",
- source="api",
- request_id=request_id,
- model=routed.resolved.original_model,
- )
- provider_stream = provider_executor.stream_messages(
- translated,
- raw_log_payload=plan.request.model_dump(),
- request_id=request_id,
- )
- chunks: list[str] = []
- try:
- chunks.extend([chunk async for chunk in provider_stream])
- finally:
- await close_stream_input(
- provider_stream,
- owner="automatic_web_search",
- source="api",
- preserved_error=sys.exception(),
- )
-
- message, stream_error, _complete = await aggregate_anthropic_sse_to_message(
- _iterate_chunks(chunks)
- )
- if stream_error is not None:
- raise _execution_failure_from_stream_error(stream_error)
-
- tool_calls = _tool_calls(message)
- if not tool_calls:
- trace_event(
- stage="execution",
- event="free_claude_code.api.web_search.automatic_declined",
- source="api",
- request_id=request_id,
- model=routed.resolved.original_model,
- )
- for chunk in chunks:
- yield chunk
- return
- if len(tool_calls) != 1:
- raise _protocol_failure(
- "Upstream model returned multiple tool calls for automatic WebSearch.",
- request_id=request_id,
- )
-
- call = tool_calls[0]
- if call.get("name") != HIDDEN_WEB_SEARCH_NAME:
- raise _protocol_failure(
- "Upstream model returned an unexpected tool for automatic WebSearch.",
- request_id=request_id,
- )
- arguments = call.get("input")
- if not isinstance(arguments, dict) or set(arguments) != {"query"}:
- raise _protocol_failure(
- "Upstream model returned malformed arguments for automatic WebSearch.",
- request_id=request_id,
- )
- raw_query = arguments.get("query")
- if not isinstance(raw_query, str) or not raw_query.strip():
- raise _protocol_failure(
- "Upstream model returned an empty query for automatic WebSearch.",
- request_id=request_id,
- )
- query = raw_query.strip()
- provider_usage = _provider_usage(message)
- input_tokens = _integer_field(provider_usage, "input_tokens")
- if input_tokens is None:
- input_tokens = fallback_input_tokens
-
- trace_event(
- stage="execution",
- event="free_claude_code.api.web_search.automatic_selected",
- source="api",
- request_id=request_id,
- model=routed.resolved.original_model,
- )
- async for frame in stream_selected_web_search_response(
- query,
- input_tokens=input_tokens,
- response_model=routed.resolved.original_model,
- provider_usage=provider_usage,
- result_filter=lambda results: _filter_results(results, plan.domains),
- verbose_client_errors=verbose_client_errors,
- ):
- yield frame
- trace_event(
- stage="execution",
- event="free_claude_code.api.web_search.automatic_completed",
- source="api",
- request_id=request_id,
- model=routed.resolved.original_model,
- )
-
-
-async def _iterate_chunks(chunks: list[str]) -> AsyncIterator[str]:
- for chunk in chunks:
- yield chunk
-
-
-def _tool_calls(message: Mapping[str, object]) -> list[dict[str, object]]:
- content = message.get("content")
- if not isinstance(content, list):
- return []
- calls: list[dict[str, object]] = []
- for block in content:
- if not isinstance(block, dict) or block.get("type") != "tool_use":
- continue
- calls.append({str(key): value for key, value in block.items()})
- return calls
-
-
-def _provider_usage(message: Mapping[str, object]) -> dict[str, object]:
- usage = message.get("usage")
- if not isinstance(usage, dict):
- return {}
- return {str(key): value for key, value in usage.items()}
-
-
-def _integer_field(values: Mapping[str, object], key: str) -> int | None:
- value = values.get(key)
- return value if isinstance(value, int) and not isinstance(value, bool) else None
-
-
-def _filter_results(
- results: list[dict[str, str]],
- domains: WebSearchDomainFilter,
-) -> list[dict[str, str]]:
- if not domains.allowed and not domains.blocked:
- return results
- return [
- result
- for result in results
- if _hostname_is_allowed(result.get("url", ""), domains)
- ]
-
-
-def _hostname_is_allowed(url: str, domains: WebSearchDomainFilter) -> bool:
- hostname = urlsplit(url).hostname
- if hostname is None:
- return False
- try:
- normalized = hostname.encode("idna").decode("ascii").lower()
- except UnicodeError:
- return False
- if domains.allowed and not any(
- _is_hostname_or_subdomain(normalized, domain) for domain in domains.allowed
- ):
- return False
- return not any(
- _is_hostname_or_subdomain(normalized, domain) for domain in domains.blocked
- )
-
-
-def _is_hostname_or_subdomain(hostname: str, domain: str) -> bool:
- return hostname == domain or hostname.endswith(f".{domain}")
-
-
-def _execution_failure_from_stream_error(
- error: Mapping[str, object],
-) -> ExecutionFailure:
- raw_type = error.get("type")
- error_type = raw_type if isinstance(raw_type, str) else "api_error"
- raw_message = error.get("message")
- message = (
- raw_message
- if isinstance(raw_message, str) and raw_message.strip()
- else "Provider request failed unexpectedly."
- )
- status = anthropic_status_for_error_type(error_type)
- kind = {
- 400: FailureKind.INVALID_REQUEST,
- 401: FailureKind.AUTHENTICATION,
- 402: FailureKind.PERMISSION,
- 403: FailureKind.PERMISSION,
- 404: FailureKind.INVALID_REQUEST,
- 413: FailureKind.INVALID_REQUEST,
- 429: FailureKind.RATE_LIMIT,
- 504: FailureKind.TIMEOUT,
- 529: FailureKind.OVERLOADED,
- }.get(status, FailureKind.UPSTREAM)
- return ExecutionFailure(
- kind=kind,
- status_code=status,
- message=message,
- retryable=False,
- )
-
-
-def _protocol_failure(message: str, *, request_id: str) -> ExecutionFailure:
- return ExecutionFailure(
- kind=FailureKind.UPSTREAM,
- status_code=500,
- message=f"{message}\n\nRequest ID: {request_id}",
- retryable=False,
- )
diff --git a/src/free_claude_code/api/web_tools/outbound.py b/src/free_claude_code/api/web_tools/outbound.py
deleted file mode 100644
index d0435611..00000000
--- a/src/free_claude_code/api/web_tools/outbound.py
+++ /dev/null
@@ -1,276 +0,0 @@
-"""Outbound HTTP for web_search / web_fetch (client, body caps, logging)."""
-
-import asyncio
-import socket
-from collections.abc import AsyncIterator
-from urllib.parse import urljoin, urlparse
-
-import aiohttp
-import httpx
-from aiohttp import ClientSession, ClientTimeout, TCPConnector
-from aiohttp.abc import AbstractResolver, ResolveResult
-from loguru import logger
-
-from . import constants
-from .constants import (
- _MAX_FETCH_CHARS,
- _MAX_SEARCH_RESULTS,
- _REDIRECT_RESPONSE_BODY_CAP_BYTES,
- _REQUEST_TIMEOUT_S,
- _WEB_FETCH_REDIRECT_STATUSES,
- _WEB_TOOL_HTTP_HEADERS,
-)
-from .egress import (
- WebFetchEgressPolicy,
- WebFetchEgressViolation,
- get_validated_stream_addrinfos_for_egress,
-)
-from .parsers import HTMLTextParser, SearchResultParser
-
-
-def _safe_public_host_for_logs(url: str) -> str:
- host = urlparse(url).hostname or ""
- return host[:253]
-
-
-def _log_web_tool_failure(
- tool_name: str,
- error: BaseException,
- *,
- fetch_url: str | None = None,
-) -> None:
- exc_type = type(error).__name__
- if isinstance(error, WebFetchEgressViolation):
- host = _safe_public_host_for_logs(fetch_url) if fetch_url else ""
- logger.warning(
- "web_tool_egress_rejected tool={} exc_type={} host={!r}",
- tool_name,
- exc_type,
- host,
- )
- return
- if tool_name == "web_fetch" and fetch_url:
- logger.warning(
- "web_tool_failure tool={} exc_type={} host={!r}",
- tool_name,
- exc_type,
- _safe_public_host_for_logs(fetch_url),
- )
- else:
- logger.warning("web_tool_failure tool={} exc_type={}", tool_name, exc_type)
-
-
-def _web_tool_client_error_summary(
- tool_name: str,
- error: BaseException,
- *,
- verbose: bool,
-) -> str:
- if verbose:
- return f"{tool_name} failed: {type(error).__name__}"
- return "Web tool request failed."
-
-
-async def _iter_response_body_under_cap(
- response: httpx.Response, max_bytes: int
-) -> AsyncIterator[bytes]:
- if max_bytes <= 0:
- return
- received = 0
- async for chunk in response.aiter_bytes(chunk_size=65_536):
- if received >= max_bytes:
- break
- remaining = max_bytes - received
- if len(chunk) <= remaining:
- received += len(chunk)
- yield chunk
- if received >= max_bytes:
- break
- else:
- yield chunk[:remaining]
- break
-
-
-async def _drain_response_body_capped(response: httpx.Response, max_bytes: int) -> None:
- async for _ in _iter_response_body_under_cap(response, max_bytes):
- pass
-
-
-async def _read_response_body_capped(response: httpx.Response, max_bytes: int) -> bytes:
- return b"".join(
- [piece async for piece in _iter_response_body_under_cap(response, max_bytes)]
- )
-
-
-_NUMERIC_RESOLVE_FLAGS = socket.AI_NUMERICHOST | socket.AI_NUMERICSERV
-_NAME_RESOLVE_FLAGS = socket.NI_NUMERICHOST | socket.NI_NUMERICSERV
-
-
-def getaddrinfo_rows_to_resolve_results(
- host: str, addrinfos: list[tuple]
-) -> list[ResolveResult]:
- """Map :func:`socket.getaddrinfo` rows to aiohttp :class:`ResolveResult` (ThreadedResolver logic)."""
- out: list[ResolveResult] = []
- for family, _type, proto, _canon, sockaddr in addrinfos:
- if family == socket.AF_INET6:
- if len(sockaddr) < 3:
- continue
- if sockaddr[3]:
- resolved_host, port = socket.getnameinfo(sockaddr, _NAME_RESOLVE_FLAGS)
- else:
- resolved_host, port = sockaddr[:2]
- else:
- assert family == socket.AF_INET, family
- resolved_host, port = sockaddr[0], sockaddr[1]
- resolved_host = str(resolved_host)
- port = int(port)
- out.append(
- ResolveResult(
- hostname=host,
- host=resolved_host,
- port=int(port),
- family=family,
- proto=proto,
- flags=_NUMERIC_RESOLVE_FLAGS,
- )
- )
- return out
-
-
-class _PinnedEgressStaticResolver(AbstractResolver):
- """Return only pre-validated :class:`ResolveResult` for the outbound request."""
-
- def __init__(self, results: list[ResolveResult]) -> None:
- self._results = results
-
- async def resolve(
- self, host: str, port: int = 0, family: int = socket.AF_INET
- ) -> list[ResolveResult]:
- return self._results
-
- async def close(self) -> None: # pragma: no cover - aiohttp contract
- return
-
-
-async def _read_aiohttp_body_capped(
- response: aiohttp.ClientResponse, max_bytes: int
-) -> bytes:
- received = 0
- parts: list[bytes] = []
- async for chunk in response.content.iter_chunked(65_536):
- if received >= max_bytes:
- break
- remaining = max_bytes - received
- if len(chunk) <= remaining:
- received += len(chunk)
- parts.append(chunk)
- else:
- parts.append(chunk[:remaining])
- break
- return b"".join(parts)
-
-
-async def _drain_aiohttp_body_capped(
- response: aiohttp.ClientResponse, max_bytes: int
-) -> None:
- if max_bytes <= 0:
- return
- received = 0
- async for chunk in response.content.iter_chunked(65_536):
- received += len(chunk)
- if received >= max_bytes:
- break
-
-
-async def _run_web_search(query: str) -> list[dict[str, str]]:
- async with (
- httpx.AsyncClient(
- timeout=_REQUEST_TIMEOUT_S,
- follow_redirects=True,
- headers=_WEB_TOOL_HTTP_HEADERS,
- ) as client,
- client.stream(
- "GET",
- "https://lite.duckduckgo.com/lite/",
- params={"q": query},
- ) as response,
- ):
- response.raise_for_status()
- body_bytes = await _read_response_body_capped(
- response, constants._MAX_WEB_FETCH_RESPONSE_BYTES
- )
- text = body_bytes.decode("utf-8", errors="replace")
- parser = SearchResultParser()
- parser.feed(text)
- return parser.results[:_MAX_SEARCH_RESULTS]
-
-
-async def _run_web_fetch(url: str, egress: WebFetchEgressPolicy) -> dict[str, str]:
- """Fetch URL with manual redirects; each hop is DNS-pinned to validated addresses."""
- current_url = url
- redirect_hops = 0
- timeout = ClientTimeout(total=_REQUEST_TIMEOUT_S)
-
- while True:
- addr_infos = await asyncio.to_thread(
- get_validated_stream_addrinfos_for_egress, current_url, egress
- )
- host = urlparse(current_url).hostname or ""
- results = getaddrinfo_rows_to_resolve_results(host, addr_infos)
- resolver = _PinnedEgressStaticResolver(results)
- connector = TCPConnector(
- resolver=resolver,
- force_close=True,
- )
- try:
- async with (
- ClientSession(
- timeout=timeout,
- headers=_WEB_TOOL_HTTP_HEADERS,
- connector=connector,
- ) as session,
- session.get(current_url, allow_redirects=False) as response,
- ):
- if response.status in _WEB_FETCH_REDIRECT_STATUSES:
- await _drain_aiohttp_body_capped(
- response, _REDIRECT_RESPONSE_BODY_CAP_BYTES
- )
- if redirect_hops >= constants._MAX_WEB_FETCH_REDIRECTS:
- raise WebFetchEgressViolation(
- "web_fetch exceeded maximum redirects "
- f"({constants._MAX_WEB_FETCH_REDIRECTS})"
- )
- location = response.headers.get("location")
- if not location or not location.strip():
- raise WebFetchEgressViolation(
- "web_fetch redirect response missing Location header"
- )
- current_url = urljoin(str(response.url), location.strip())
- redirect_hops += 1
- continue
- response.raise_for_status()
- content_type = response.headers.get("content-type", "text/plain")
- final_url = str(response.url)
- encoding = response.get_encoding() or "utf-8"
- body_bytes = await _read_aiohttp_body_capped(
- response, constants._MAX_WEB_FETCH_RESPONSE_BYTES
- )
- finally:
- await connector.close()
-
- break
-
- text = body_bytes.decode(encoding, errors="replace")
- title = final_url
- data = text
- if "html" in content_type.lower():
- parser = HTMLTextParser()
- parser.feed(text)
- title = parser.title or final_url
- data = "\n".join(parser.text_parts)
- return {
- "url": final_url,
- "title": title,
- "media_type": "text/plain",
- "data": data[:_MAX_FETCH_CHARS],
- }
diff --git a/src/free_claude_code/api/web_tools/streaming.py b/src/free_claude_code/api/web_tools/streaming.py
deleted file mode 100644
index fa1cc3bd..00000000
--- a/src/free_claude_code/api/web_tools/streaming.py
+++ /dev/null
@@ -1,286 +0,0 @@
-"""SSE streaming for local web_search / web_fetch server-tool results."""
-
-import uuid
-from collections.abc import AsyncIterator, Callable, Mapping
-from datetime import UTC, datetime
-
-from free_claude_code.core.anthropic import MessagesRequest
-from free_claude_code.core.anthropic.server_tool_sse import (
- SERVER_TOOL_USE,
- WEB_FETCH_TOOL_ERROR,
- WEB_FETCH_TOOL_RESULT,
- WEB_SEARCH_TOOL_RESULT,
- WEB_SEARCH_TOOL_RESULT_ERROR,
-)
-from free_claude_code.core.anthropic.streaming import format_sse_event
-from free_claude_code.core.json_types import JsonValue
-
-from . import outbound
-from .constants import _MAX_FETCH_CHARS
-from .egress import WebFetchEgressPolicy
-from .parsers import extract_query, extract_url
-from .request import forced_server_tool_name, forced_tool_turn_text, has_tool_named
-
-type SearchResultFilter = Callable[
- [list[dict[str, str]]],
- list[dict[str, str]],
-]
-
-
-def _search_summary(query: str, results: list[dict[str, str]]) -> str:
- if not results:
- return f"No web search results found for: {query}"
- lines = [f"Search results for: {query}"]
- for index, result in enumerate(results, start=1):
- lines.append(f"{index}. {result['title']}\n{result['url']}")
- return "\n\n".join(lines)
-
-
-async def stream_web_server_tool_response(
- request: MessagesRequest,
- input_tokens: int,
- *,
- web_fetch_egress: WebFetchEgressPolicy,
- response_model: str | None = None,
- verbose_client_errors: bool = False,
-) -> AsyncIterator[str]:
- """Stream the existing forced `web_search` / `web_fetch` local fallback."""
- tool_name = forced_server_tool_name(request)
- if tool_name is None or not has_tool_named(request, tool_name):
- return
-
- text = forced_tool_turn_text(request)
- tool_input = (
- {"query": extract_query(text)}
- if tool_name == "web_search"
- else {"url": extract_url(text)}
- )
- async for frame in _stream_local_web_tool_response(
- tool_name=tool_name,
- tool_input=tool_input,
- input_tokens=input_tokens,
- web_fetch_egress=web_fetch_egress,
- response_model=request.model if response_model is None else response_model,
- verbose_client_errors=verbose_client_errors,
- ):
- yield frame
-
-
-async def stream_selected_web_search_response(
- query: str,
- *,
- input_tokens: int,
- response_model: str,
- provider_usage: Mapping[str, object],
- result_filter: SearchResultFilter,
- verbose_client_errors: bool = False,
-) -> AsyncIterator[str]:
- """Stream the existing local result shape for one provider-selected query."""
- async for frame in _stream_local_web_tool_response(
- tool_name="web_search",
- tool_input={"query": query},
- input_tokens=input_tokens,
- web_fetch_egress=None,
- response_model=response_model,
- verbose_client_errors=verbose_client_errors,
- provider_usage=provider_usage,
- search_result_filter=result_filter,
- ):
- yield frame
-
-
-async def _stream_local_web_tool_response(
- *,
- tool_name: str,
- tool_input: dict[str, str],
- input_tokens: int,
- web_fetch_egress: WebFetchEgressPolicy | None,
- response_model: str,
- verbose_client_errors: bool,
- provider_usage: Mapping[str, object] | None = None,
- search_result_filter: SearchResultFilter | None = None,
-) -> AsyncIterator[str]:
- message_id = f"msg_{uuid.uuid4()}"
- tool_id = f"srvtoolu_{uuid.uuid4().hex}"
- usage_key = (
- "web_search_requests" if tool_name == "web_search" else "web_fetch_requests"
- )
- result_block_for_tool = {
- "web_search": WEB_SEARCH_TOOL_RESULT,
- "web_fetch": WEB_FETCH_TOOL_RESULT,
- }
- error_payload_type_for_tool = {
- "web_search": WEB_SEARCH_TOOL_RESULT_ERROR,
- "web_fetch": WEB_FETCH_TOOL_ERROR,
- }
-
- yield format_sse_event(
- "message_start",
- {
- "type": "message_start",
- "message": {
- "id": message_id,
- "type": "message",
- "role": "assistant",
- "content": [],
- "model": response_model,
- "stop_reason": None,
- "stop_sequence": None,
- "usage": _message_start_usage(input_tokens, provider_usage),
- },
- },
- )
- yield format_sse_event(
- "content_block_start",
- {
- "type": "content_block_start",
- "index": 0,
- "content_block": {
- "type": SERVER_TOOL_USE,
- "id": tool_id,
- "name": tool_name,
- "input": tool_input,
- },
- },
- )
- yield format_sse_event(
- "content_block_stop", {"type": "content_block_stop", "index": 0}
- )
-
- try:
- if tool_name == "web_search":
- query = tool_input["query"]
- results = await outbound._run_web_search(query)
- if search_result_filter is not None:
- results = search_result_filter(results)
- result_content: JsonValue = [
- {
- "type": "web_search_result",
- "title": result["title"],
- "url": result["url"],
- }
- for result in results
- ]
- summary = _search_summary(query, results)
- result_block_type = WEB_SEARCH_TOOL_RESULT
- else:
- if web_fetch_egress is None:
- raise RuntimeError("web_fetch requires an egress policy")
- fetched = await outbound._run_web_fetch(tool_input["url"], web_fetch_egress)
- result_content = {
- "type": "web_fetch_result",
- "url": fetched["url"],
- "content": {
- "type": "document",
- "source": {
- "type": "text",
- "media_type": fetched["media_type"],
- "data": fetched["data"],
- },
- "title": fetched["title"],
- "citations": {"enabled": True},
- },
- "retrieved_at": datetime.now(UTC).isoformat(),
- }
- summary = fetched["data"][:_MAX_FETCH_CHARS]
- result_block_type = WEB_FETCH_TOOL_RESULT
- except Exception as error:
- fetch_url = tool_input.get("url") if tool_name == "web_fetch" else None
- outbound._log_web_tool_failure(tool_name, error, fetch_url=fetch_url)
- result_block_type = result_block_for_tool[tool_name]
- result_content = {
- "type": error_payload_type_for_tool[tool_name],
- "error_code": "unavailable",
- }
- summary = outbound._web_tool_client_error_summary(
- tool_name, error, verbose=verbose_client_errors
- )
-
- yield format_sse_event(
- "content_block_start",
- {
- "type": "content_block_start",
- "index": 1,
- "content_block": {
- "type": result_block_type,
- "tool_use_id": tool_id,
- "content": result_content,
- },
- },
- )
- yield format_sse_event(
- "content_block_stop", {"type": "content_block_stop", "index": 1}
- )
- yield format_sse_event(
- "content_block_start",
- {
- "type": "content_block_start",
- "index": 2,
- "content_block": {"type": "text", "text": ""},
- },
- )
- yield format_sse_event(
- "content_block_delta",
- {
- "type": "content_block_delta",
- "index": 2,
- "delta": {"type": "text_delta", "text": summary},
- },
- )
- yield format_sse_event(
- "content_block_stop", {"type": "content_block_stop", "index": 2}
- )
- yield format_sse_event(
- "message_delta",
- {
- "type": "message_delta",
- "delta": {"stop_reason": "end_turn", "stop_sequence": None},
- "usage": _completion_usage(
- input_tokens,
- summary,
- provider_usage,
- usage_key=usage_key,
- ),
- },
- )
- yield format_sse_event("message_stop", {"type": "message_stop"})
-
-
-def _message_start_usage(
- input_tokens: int,
- provider_usage: Mapping[str, object] | None,
-) -> dict[str, object]:
- if provider_usage is None:
- return {"input_tokens": input_tokens, "output_tokens": 1}
- usage = _integer_usage(provider_usage)
- usage.setdefault("input_tokens", input_tokens)
- usage["output_tokens"] = 1
- return usage
-
-
-def _completion_usage(
- input_tokens: int,
- summary: str,
- provider_usage: Mapping[str, object] | None,
- *,
- usage_key: str,
-) -> dict[str, object]:
- if provider_usage is None:
- usage: dict[str, object] = {
- "input_tokens": input_tokens,
- "output_tokens": max(1, len(summary) // 4),
- }
- else:
- usage = _integer_usage(provider_usage)
- usage.setdefault("input_tokens", input_tokens)
- usage.setdefault("output_tokens", max(1, len(summary) // 4))
- usage["server_tool_use"] = {usage_key: 1}
- return usage
-
-
-def _integer_usage(usage: Mapping[str, object]) -> dict[str, object]:
- return {
- key: value
- for key, value in usage.items()
- if isinstance(value, int) and not isinstance(value, bool)
- }
diff --git a/src/free_claude_code/application/web_tools/__init__.py b/src/free_claude_code/application/web_tools/__init__.py
new file mode 100644
index 00000000..478fae02
--- /dev/null
+++ b/src/free_claude_code/application/web_tools/__init__.py
@@ -0,0 +1 @@
+"""Application policy and execution for local web tools."""
diff --git a/src/free_claude_code/application/web_tools/ports.py b/src/free_claude_code/application/web_tools/ports.py
new file mode 100644
index 00000000..2ce923a5
--- /dev/null
+++ b/src/free_claude_code/application/web_tools/ports.py
@@ -0,0 +1,35 @@
+"""Outbound capabilities consumed by the local web-tool workflow."""
+
+from dataclasses import dataclass
+from typing import Protocol
+
+from free_claude_code.core.web_tools import WebFetchResult, WebSearchResult
+
+
+@dataclass(frozen=True, slots=True)
+class WebFetchEgressPolicy:
+ """Egress rules for user-influenced web_fetch URLs."""
+
+ allow_private_network_targets: bool
+ allowed_schemes: frozenset[str]
+
+
+class WebFetchEgressViolation(ValueError):
+ """Raised when a web_fetch URL is rejected by egress policy (SSRF guard)."""
+
+
+def web_fetch_allowed_scheme_set(raw_schemes: str) -> frozenset[str]:
+ """Return normalized schemes allowed for web_fetch."""
+ return frozenset(
+ part.strip().lower() for part in raw_schemes.split(",") if part.strip()
+ )
+
+
+class WebToolsPort(Protocol):
+ """Complete each operation before returning data, retaining no response resource."""
+
+ async def search(self, query: str) -> list[WebSearchResult]: ...
+
+ async def fetch(
+ self, url: str, *, egress: WebFetchEgressPolicy
+ ) -> WebFetchResult: ...
diff --git a/src/free_claude_code/api/web_tools/request.py b/src/free_claude_code/application/web_tools/request.py
similarity index 91%
rename from src/free_claude_code/api/web_tools/request.py
rename to src/free_claude_code/application/web_tools/request.py
index d961f56d..8f96fb8e 100644
--- a/src/free_claude_code/api/web_tools/request.py
+++ b/src/free_claude_code/application/web_tools/request.py
@@ -6,8 +6,6 @@ from dataclasses import dataclass
from free_claude_code.application.errors import InvalidRequestError
from free_claude_code.core.anthropic import MessagesRequest, Tool
-from .parsers import content_text
-
WEB_SEARCH_TYPE = "web_search_20250305"
WEB_FETCH_TYPE = "web_fetch_20250910"
HIDDEN_WEB_SEARCH_NAME = "fcc_web_search"
@@ -239,3 +237,29 @@ def _parse_domains(value: object, *, field: str) -> tuple[str, ...]:
if len(domains) != len(set(domains)):
raise InvalidRequestError(f"{field} must not contain duplicate hostnames.")
return tuple(domains)
+
+
+def content_text(content: object) -> str:
+ if isinstance(content, str):
+ return content
+ if isinstance(content, list):
+ parts = []
+ for item in content:
+ if isinstance(item, dict):
+ parts.append(str(item.get("text", "")))
+ else:
+ parts.append(str(getattr(item, "text", "")))
+ return "\n".join(part for part in parts if part)
+ return str(content)
+
+
+def extract_query(text: str) -> str:
+ match = re.search(r"query:\s*(.+)", text, flags=re.IGNORECASE | re.DOTALL)
+ if match:
+ return match.group(1).strip().strip("\"'")
+ return text.strip()
+
+
+def extract_url(text: str) -> str:
+ match = re.search(r"https?://\S+", text)
+ return match.group(0).rstrip(").,]") if match else text.strip()
diff --git a/src/free_claude_code/application/web_tools/service.py b/src/free_claude_code/application/web_tools/service.py
new file mode 100644
index 00000000..28a22055
--- /dev/null
+++ b/src/free_claude_code/application/web_tools/service.py
@@ -0,0 +1,428 @@
+"""Application workflow for supported local Anthropic web-tool requests."""
+
+import sys
+import uuid
+from collections.abc import AsyncIterator, Mapping
+from dataclasses import replace
+from datetime import UTC, datetime
+from urllib.parse import urlparse, urlsplit
+
+from loguru import logger
+
+from free_claude_code.application.errors import InvalidRequestError
+from free_claude_code.application.execution import ProviderExecutor, TokenCounter
+from free_claude_code.application.routing import RoutedMessagesRequest
+from free_claude_code.config.settings import Settings
+from free_claude_code.core.anthropic import (
+ aggregate_anthropic_sse_to_message,
+ anthropic_status_for_error_type,
+)
+from free_claude_code.core.anthropic.server_tool_sse import (
+ ServerToolResponseContext,
+ server_tool_completion_frames,
+ server_tool_start_frames,
+ web_fetch_result_block,
+ web_search_result_block,
+ web_tool_error_block,
+)
+from free_claude_code.core.failures import ExecutionFailure, FailureKind
+from free_claude_code.core.trace import close_stream_input, trace_event
+from free_claude_code.core.web_tools import WebSearchResult
+
+from .ports import (
+ WebFetchEgressPolicy,
+ WebFetchEgressViolation,
+ WebToolsPort,
+ web_fetch_allowed_scheme_set,
+)
+from .request import (
+ HIDDEN_WEB_SEARCH_NAME,
+ AutomaticWebSearchPlan,
+ WebSearchDomainFilter,
+ extract_query,
+ extract_url,
+ forced_server_tool_name,
+ forced_tool_turn_text,
+ plan_automatic_web_search,
+ unsupported_server_tool_error,
+)
+
+
+class WebToolService:
+ """Coordinate one tool request using the originating settings and executor."""
+
+ def __init__(
+ self,
+ *,
+ settings: Settings,
+ client: WebToolsPort,
+ executor: ProviderExecutor,
+ token_counter: TokenCounter,
+ ) -> None:
+ self._client = client
+ self._executor = executor
+ self._token_counter = token_counter
+ self._enabled = settings.enable_web_server_tools
+ self._verbose_client_errors = settings.log_api_error_tracebacks
+ self._egress = WebFetchEgressPolicy(
+ allow_private_network_targets=settings.web_fetch_allow_private_networks,
+ allowed_schemes=web_fetch_allowed_scheme_set(
+ settings.web_fetch_allowed_schemes
+ ),
+ )
+
+ def try_stream_messages(
+ self, routed: RoutedMessagesRequest, *, request_id: str
+ ) -> AsyncIterator[str] | None:
+ """Validate synchronously; return a lazy body only for handled requests."""
+ request = routed.request
+ plan = plan_automatic_web_search(request, web_tools_enabled=self._enabled)
+ if plan is None:
+ error = unsupported_server_tool_error(
+ request, web_tools_enabled=self._enabled
+ )
+ if error is not None:
+ raise InvalidRequestError(error)
+ tool_name = forced_server_tool_name(request)
+ if plan is None and tool_name is None:
+ return None
+ input_tokens = self._token_counter(
+ request.messages, request.system, request.tools
+ )
+ if plan is not None:
+ return self._stream_automatic_search(
+ routed, plan, request_id=request_id, fallback_input_tokens=input_tokens
+ )
+ assert tool_name is not None
+ trace_event(
+ stage="routing",
+ event="free_claude_code.api.optimization.web_server_tool",
+ source="api",
+ model=routed.resolved.original_model,
+ )
+ text = forced_tool_turn_text(request)
+ tool_input = (
+ {"query": extract_query(text)}
+ if tool_name == "web_search"
+ else {"url": extract_url(text)}
+ )
+ return self._stream_local_tool(
+ tool_name=tool_name,
+ tool_input=tool_input,
+ input_tokens=input_tokens,
+ response_model=routed.resolved.original_model,
+ )
+
+ async def _stream_automatic_search(
+ self,
+ routed: RoutedMessagesRequest,
+ plan: AutomaticWebSearchPlan,
+ *,
+ request_id: str,
+ fallback_input_tokens: int,
+ ) -> AsyncIterator[str]:
+ """Keep one provider decision private, then replay it or execute search."""
+ translated = replace(routed, request=plan.request)
+ trace_event(
+ stage="routing",
+ event="free_claude_code.api.web_search.automatic_recognized",
+ source="api",
+ request_id=request_id,
+ model=routed.resolved.original_model,
+ )
+ provider_stream = self._executor.stream_messages(
+ translated,
+ raw_log_payload=plan.request.model_dump(),
+ request_id=request_id,
+ )
+ chunks: list[str] = []
+ try:
+ chunks.extend([chunk async for chunk in provider_stream])
+ finally:
+ await close_stream_input(
+ provider_stream,
+ owner="automatic_web_search",
+ source="api",
+ preserved_error=sys.exception(),
+ )
+
+ message, stream_error, _complete = await aggregate_anthropic_sse_to_message(
+ _iterate_chunks(chunks)
+ )
+ if stream_error is not None:
+ raise _execution_failure_from_stream_error(stream_error)
+ tool_calls = _tool_calls(message)
+ if not tool_calls:
+ trace_event(
+ stage="execution",
+ event="free_claude_code.api.web_search.automatic_declined",
+ source="api",
+ request_id=request_id,
+ model=routed.resolved.original_model,
+ )
+ for chunk in chunks:
+ yield chunk
+ return
+ if len(tool_calls) != 1:
+ raise _protocol_failure(
+ "Upstream model returned multiple tool calls for automatic WebSearch.",
+ request_id=request_id,
+ )
+ call = tool_calls[0]
+ if call.get("name") != HIDDEN_WEB_SEARCH_NAME:
+ raise _protocol_failure(
+ "Upstream model returned an unexpected tool for automatic WebSearch.",
+ request_id=request_id,
+ )
+ arguments = call.get("input")
+ if not isinstance(arguments, dict) or set(arguments) != {"query"}:
+ raise _protocol_failure(
+ "Upstream model returned malformed arguments for automatic WebSearch.",
+ request_id=request_id,
+ )
+ raw_query = arguments.get("query")
+ if not isinstance(raw_query, str) or not raw_query.strip():
+ raise _protocol_failure(
+ "Upstream model returned an empty query for automatic WebSearch.",
+ request_id=request_id,
+ )
+ query = raw_query.strip()
+ provider_usage = _provider_usage(message)
+ input_tokens = _integer_field(provider_usage, "input_tokens")
+ if input_tokens is None:
+ input_tokens = fallback_input_tokens
+
+ trace_event(
+ stage="execution",
+ event="free_claude_code.api.web_search.automatic_selected",
+ source="api",
+ request_id=request_id,
+ model=routed.resolved.original_model,
+ )
+ local_stream = self._stream_local_tool(
+ tool_name="web_search",
+ tool_input={"query": query},
+ input_tokens=input_tokens,
+ response_model=routed.resolved.original_model,
+ provider_usage=provider_usage,
+ domains=plan.domains,
+ )
+ try:
+ async for frame in local_stream:
+ yield frame
+ finally:
+ await close_stream_input(
+ local_stream,
+ owner="automatic_web_search",
+ source="api",
+ preserved_error=sys.exception(),
+ )
+ trace_event(
+ stage="execution",
+ event="free_claude_code.api.web_search.automatic_completed",
+ source="api",
+ request_id=request_id,
+ model=routed.resolved.original_model,
+ )
+
+ async def _stream_local_tool(
+ self,
+ *,
+ tool_name: str,
+ tool_input: dict[str, str],
+ input_tokens: int,
+ response_model: str,
+ provider_usage: Mapping[str, object] | None = None,
+ domains: WebSearchDomainFilter | None = None,
+ ) -> AsyncIterator[str]:
+ context = ServerToolResponseContext(
+ message_id=f"msg_{uuid.uuid4()}",
+ tool_id=f"srvtoolu_{uuid.uuid4().hex}",
+ model=response_model,
+ tool_name=tool_name,
+ tool_input=tool_input,
+ input_tokens=input_tokens,
+ provider_usage=provider_usage,
+ )
+ for frame in server_tool_start_frames(context):
+ yield frame
+
+ try:
+ if tool_name == "web_search":
+ query = tool_input["query"]
+ results = await self._client.search(query)
+ if domains is not None:
+ results = _filter_results(results, domains)
+ result_block = web_search_result_block(context, results)
+ summary = _search_summary(query, results)
+ else:
+ fetched = await self._client.fetch(
+ tool_input["url"], egress=self._egress
+ )
+ result_block = web_fetch_result_block(
+ context, fetched, retrieved_at=datetime.now(UTC).isoformat()
+ )
+ summary = fetched.data
+ except Exception as error:
+ fetch_url = tool_input.get("url") if tool_name == "web_fetch" else None
+ _log_web_tool_failure(tool_name, error, fetch_url=fetch_url)
+ result_block = web_tool_error_block(context)
+ summary = _web_tool_client_error_summary(
+ tool_name, error, verbose=self._verbose_client_errors
+ )
+
+ for frame in server_tool_completion_frames(
+ context, result_block, summary=summary
+ ):
+ yield frame
+
+
+def _search_summary(query: str, results: list[WebSearchResult]) -> str:
+ if not results:
+ return f"No web search results found for: {query}"
+ lines = [f"Search results for: {query}"]
+ for index, result in enumerate(results, start=1):
+ lines.append(f"{index}. {result.title}\n{result.url}")
+ return "\n\n".join(lines)
+
+
+async def _iterate_chunks(chunks: list[str]) -> AsyncIterator[str]:
+ for chunk in chunks:
+ yield chunk
+
+
+def _tool_calls(message: Mapping[str, object]) -> list[dict[str, object]]:
+ content = message.get("content")
+ if not isinstance(content, list):
+ return []
+ calls: list[dict[str, object]] = []
+ for block in content:
+ if not isinstance(block, dict) or block.get("type") != "tool_use":
+ continue
+ calls.append({str(key): value for key, value in block.items()})
+ return calls
+
+
+def _provider_usage(message: Mapping[str, object]) -> dict[str, object]:
+ usage = message.get("usage")
+ if not isinstance(usage, dict):
+ return {}
+ return {str(key): value for key, value in usage.items()}
+
+
+def _integer_field(values: Mapping[str, object], key: str) -> int | None:
+ value = values.get(key)
+ return value if isinstance(value, int) and not isinstance(value, bool) else None
+
+
+def _filter_results(
+ results: list[WebSearchResult],
+ domains: WebSearchDomainFilter,
+) -> list[WebSearchResult]:
+ if not domains.allowed and not domains.blocked:
+ return results
+ return [result for result in results if _hostname_is_allowed(result.url, domains)]
+
+
+def _hostname_is_allowed(url: str, domains: WebSearchDomainFilter) -> bool:
+ hostname = urlsplit(url).hostname
+ if hostname is None:
+ return False
+ try:
+ normalized = hostname.encode("idna").decode("ascii").lower()
+ except UnicodeError:
+ return False
+ if domains.allowed and not any(
+ _is_hostname_or_subdomain(normalized, domain) for domain in domains.allowed
+ ):
+ return False
+ return not any(
+ _is_hostname_or_subdomain(normalized, domain) for domain in domains.blocked
+ )
+
+
+def _is_hostname_or_subdomain(hostname: str, domain: str) -> bool:
+ return hostname == domain or hostname.endswith(f".{domain}")
+
+
+def _execution_failure_from_stream_error(
+ error: Mapping[str, object],
+) -> ExecutionFailure:
+ raw_type = error.get("type")
+ error_type = raw_type if isinstance(raw_type, str) else "api_error"
+ raw_message = error.get("message")
+ message = (
+ raw_message
+ if isinstance(raw_message, str) and raw_message.strip()
+ else "Provider request failed unexpectedly."
+ )
+ status = anthropic_status_for_error_type(error_type)
+ kind = {
+ 400: FailureKind.INVALID_REQUEST,
+ 401: FailureKind.AUTHENTICATION,
+ 402: FailureKind.PERMISSION,
+ 403: FailureKind.PERMISSION,
+ 404: FailureKind.INVALID_REQUEST,
+ 413: FailureKind.INVALID_REQUEST,
+ 429: FailureKind.RATE_LIMIT,
+ 504: FailureKind.TIMEOUT,
+ 529: FailureKind.OVERLOADED,
+ }.get(status, FailureKind.UPSTREAM)
+ return ExecutionFailure(
+ kind=kind,
+ status_code=status,
+ message=message,
+ retryable=False,
+ )
+
+
+def _protocol_failure(message: str, *, request_id: str) -> ExecutionFailure:
+ return ExecutionFailure(
+ kind=FailureKind.UPSTREAM,
+ status_code=500,
+ message=f"{message}\n\nRequest ID: {request_id}",
+ retryable=False,
+ )
+
+
+def _safe_public_host_for_logs(url: str) -> str:
+ host = urlparse(url).hostname or ""
+ return host[:253]
+
+
+def _log_web_tool_failure(
+ tool_name: str,
+ error: BaseException,
+ *,
+ fetch_url: str | None = None,
+) -> None:
+ exc_type = type(error).__name__
+ if isinstance(error, WebFetchEgressViolation):
+ host = _safe_public_host_for_logs(fetch_url) if fetch_url else ""
+ logger.warning(
+ "web_tool_egress_rejected tool={} exc_type={} host={!r}",
+ tool_name,
+ exc_type,
+ host,
+ )
+ return
+ if tool_name == "web_fetch" and fetch_url:
+ logger.warning(
+ "web_tool_failure tool={} exc_type={} host={!r}",
+ tool_name,
+ exc_type,
+ _safe_public_host_for_logs(fetch_url),
+ )
+ else:
+ logger.warning("web_tool_failure tool={} exc_type={}", tool_name, exc_type)
+
+
+def _web_tool_client_error_summary(
+ tool_name: str,
+ error: BaseException,
+ *,
+ verbose: bool,
+) -> str:
+ if verbose:
+ return f"{tool_name} failed: {type(error).__name__}"
+ return "Web tool request failed."
diff --git a/src/free_claude_code/core/anthropic/server_tool_sse.py b/src/free_claude_code/core/anthropic/server_tool_sse.py
index 2de1a82d..db9e7aa5 100644
--- a/src/free_claude_code/core/anthropic/server_tool_sse.py
+++ b/src/free_claude_code/core/anthropic/server_tool_sse.py
@@ -1,12 +1,204 @@
-"""SSE content_block ``type`` values for Anthropic web server tools (local handlers).
+"""Anthropic representation of completed local web-tool operations."""
-Shared by :mod:`api.web_tools` and stream contract tests to avoid drift.
-"""
+from collections.abc import Iterator, Mapping, Sequence
+from dataclasses import dataclass
-from typing import Final
+from free_claude_code.core.json_types import JsonObject
+from free_claude_code.core.web_tools import WebFetchResult, WebSearchResult
-SERVER_TOOL_USE: Final = "server_tool_use"
-WEB_SEARCH_TOOL_RESULT: Final = "web_search_tool_result"
-WEB_FETCH_TOOL_RESULT: Final = "web_fetch_tool_result"
-WEB_SEARCH_TOOL_RESULT_ERROR: Final = "web_search_tool_result_error"
-WEB_FETCH_TOOL_ERROR: Final = "web_fetch_tool_error"
+from .server_tool_types import (
+ SERVER_TOOL_USE,
+ WEB_FETCH_TOOL_ERROR,
+ WEB_FETCH_TOOL_RESULT,
+ WEB_SEARCH_TOOL_RESULT,
+ WEB_SEARCH_TOOL_RESULT_ERROR,
+)
+from .streaming import format_sse_event
+
+
+@dataclass(frozen=True, slots=True)
+class ServerToolResponseContext:
+ message_id: str
+ tool_id: str
+ model: str
+ tool_name: str
+ tool_input: Mapping[str, str]
+ input_tokens: int
+ provider_usage: Mapping[str, object] | None = None
+
+
+def server_tool_start_frames(context: ServerToolResponseContext) -> Iterator[str]:
+ yield format_sse_event(
+ "message_start",
+ {
+ "type": "message_start",
+ "message": {
+ "id": context.message_id,
+ "type": "message",
+ "role": "assistant",
+ "content": [],
+ "model": context.model,
+ "stop_reason": None,
+ "stop_sequence": None,
+ "usage": _message_start_usage(
+ context.input_tokens, context.provider_usage
+ ),
+ },
+ },
+ )
+ yield format_sse_event(
+ "content_block_start",
+ {
+ "type": "content_block_start",
+ "index": 0,
+ "content_block": {
+ "type": SERVER_TOOL_USE,
+ "id": context.tool_id,
+ "name": context.tool_name,
+ "input": context.tool_input,
+ },
+ },
+ )
+ yield format_sse_event(
+ "content_block_stop", {"type": "content_block_stop", "index": 0}
+ )
+
+
+def web_search_result_block(
+ context: ServerToolResponseContext, results: Sequence[WebSearchResult]
+) -> JsonObject:
+ return {
+ "type": WEB_SEARCH_TOOL_RESULT,
+ "tool_use_id": context.tool_id,
+ "content": [
+ {"type": "web_search_result", "title": result.title, "url": result.url}
+ for result in results
+ ],
+ }
+
+
+def web_fetch_result_block(
+ context: ServerToolResponseContext,
+ result: WebFetchResult,
+ *,
+ retrieved_at: str,
+) -> JsonObject:
+ return {
+ "type": WEB_FETCH_TOOL_RESULT,
+ "tool_use_id": context.tool_id,
+ "content": {
+ "type": "web_fetch_result",
+ "url": result.url,
+ "content": {
+ "type": "document",
+ "source": {
+ "type": "text",
+ "media_type": result.media_type,
+ "data": result.data,
+ },
+ "title": result.title,
+ "citations": {"enabled": True},
+ },
+ "retrieved_at": retrieved_at,
+ },
+ }
+
+
+def web_tool_error_block(context: ServerToolResponseContext) -> JsonObject:
+ search = context.tool_name == "web_search"
+ return {
+ "type": WEB_SEARCH_TOOL_RESULT if search else WEB_FETCH_TOOL_RESULT,
+ "tool_use_id": context.tool_id,
+ "content": {
+ "type": WEB_SEARCH_TOOL_RESULT_ERROR if search else WEB_FETCH_TOOL_ERROR,
+ "error_code": "unavailable",
+ },
+ }
+
+
+def server_tool_completion_frames(
+ context: ServerToolResponseContext,
+ result_block: JsonObject,
+ *,
+ summary: str,
+) -> Iterator[str]:
+ yield format_sse_event(
+ "content_block_start",
+ {"type": "content_block_start", "index": 1, "content_block": result_block},
+ )
+ yield format_sse_event(
+ "content_block_stop", {"type": "content_block_stop", "index": 1}
+ )
+ yield format_sse_event(
+ "content_block_start",
+ {
+ "type": "content_block_start",
+ "index": 2,
+ "content_block": {"type": "text", "text": ""},
+ },
+ )
+ yield format_sse_event(
+ "content_block_delta",
+ {
+ "type": "content_block_delta",
+ "index": 2,
+ "delta": {"type": "text_delta", "text": summary},
+ },
+ )
+ yield format_sse_event(
+ "content_block_stop", {"type": "content_block_stop", "index": 2}
+ )
+ yield format_sse_event(
+ "message_delta",
+ {
+ "type": "message_delta",
+ "delta": {"stop_reason": "end_turn", "stop_sequence": None},
+ "usage": _completion_usage(
+ context.input_tokens,
+ summary,
+ context.provider_usage,
+ usage_key=f"{context.tool_name}_requests",
+ ),
+ },
+ )
+ yield format_sse_event("message_stop", {"type": "message_stop"})
+
+
+def _message_start_usage(
+ input_tokens: int,
+ provider_usage: Mapping[str, object] | None,
+) -> dict[str, object]:
+ if provider_usage is None:
+ return {"input_tokens": input_tokens, "output_tokens": 1}
+ usage = _integer_usage(provider_usage)
+ usage.setdefault("input_tokens", input_tokens)
+ usage["output_tokens"] = 1
+ return usage
+
+
+def _completion_usage(
+ input_tokens: int,
+ summary: str,
+ provider_usage: Mapping[str, object] | None,
+ *,
+ usage_key: str,
+) -> dict[str, object]:
+ if provider_usage is None:
+ usage: dict[str, object] = {
+ "input_tokens": input_tokens,
+ "output_tokens": max(1, len(summary) // 4),
+ }
+ else:
+ usage = _integer_usage(provider_usage)
+ usage.setdefault("input_tokens", input_tokens)
+ usage.setdefault("output_tokens", max(1, len(summary) // 4))
+ usage["server_tool_use"] = {usage_key: 1}
+ return usage
+
+
+def _integer_usage(usage: Mapping[str, object]) -> dict[str, object]:
+ return {
+ key: value
+ for key, value in usage.items()
+ if isinstance(value, int) and not isinstance(value, bool)
+ }
diff --git a/src/free_claude_code/core/anthropic/server_tool_types.py b/src/free_claude_code/core/anthropic/server_tool_types.py
new file mode 100644
index 00000000..45f49294
--- /dev/null
+++ b/src/free_claude_code/core/anthropic/server_tool_types.py
@@ -0,0 +1,9 @@
+"""Anthropic server-tool block types shared by decoders and formatters."""
+
+from typing import Final
+
+SERVER_TOOL_USE: Final = "server_tool_use"
+WEB_SEARCH_TOOL_RESULT: Final = "web_search_tool_result"
+WEB_FETCH_TOOL_RESULT: Final = "web_fetch_tool_result"
+WEB_SEARCH_TOOL_RESULT_ERROR: Final = "web_search_tool_result_error"
+WEB_FETCH_TOOL_ERROR: Final = "web_fetch_tool_error"
diff --git a/src/free_claude_code/core/anthropic/stream_contracts.py b/src/free_claude_code/core/anthropic/stream_contracts.py
index 49422ba3..a5aa76d3 100644
--- a/src/free_claude_code/core/anthropic/stream_contracts.py
+++ b/src/free_claude_code/core/anthropic/stream_contracts.py
@@ -9,7 +9,7 @@ from collections.abc import Iterable
from dataclasses import dataclass
from typing import Any
-from .server_tool_sse import (
+from .server_tool_types import (
SERVER_TOOL_USE,
WEB_FETCH_TOOL_RESULT,
WEB_SEARCH_TOOL_RESULT,
diff --git a/src/free_claude_code/core/web_tools.py b/src/free_claude_code/core/web_tools.py
new file mode 100644
index 00000000..2d26bbb3
--- /dev/null
+++ b/src/free_claude_code/core/web_tools.py
@@ -0,0 +1,17 @@
+"""Completed web results shared by application operations and wire formatters."""
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True, slots=True)
+class WebSearchResult:
+ title: str
+ url: str
+
+
+@dataclass(frozen=True, slots=True)
+class WebFetchResult:
+ url: str
+ title: str
+ media_type: str
+ data: str
diff --git a/src/free_claude_code/runtime/bootstrap.py b/src/free_claude_code/runtime/bootstrap.py
index 806be20b..3972ee20 100644
--- a/src/free_claude_code/runtime/bootstrap.py
+++ b/src/free_claude_code/runtime/bootstrap.py
@@ -34,6 +34,7 @@ from .codex_app_server import CodexHarnessFactory
from .codex_catalog import CodexModelCatalogPublisher
from .configuration import ConfigurationService
from .provider_manager import ProviderRuntimeManager
+from .web_tools.client import HTTPWebToolsClient
def build_asgi_app(
@@ -88,6 +89,7 @@ def build_asgi_app(
requests=provider_manager,
admin=runtime,
tasks=runtime,
+ web_tools=HTTPWebToolsClient(),
code=code_service,
)
return RuntimeASGIApp(create_app(services), runtime)
diff --git a/src/free_claude_code/runtime/web_tools/__init__.py b/src/free_claude_code/runtime/web_tools/__init__.py
new file mode 100644
index 00000000..86e69f0a
--- /dev/null
+++ b/src/free_claude_code/runtime/web_tools/__init__.py
@@ -0,0 +1 @@
+"""Outbound HTTP implementation for local web tools."""
diff --git a/src/free_claude_code/runtime/web_tools/client.py b/src/free_claude_code/runtime/web_tools/client.py
new file mode 100644
index 00000000..abc9cd14
--- /dev/null
+++ b/src/free_claude_code/runtime/web_tools/client.py
@@ -0,0 +1,238 @@
+"""Outbound HTTP for web_search / web_fetch with operation-scoped resources."""
+
+import asyncio
+import socket
+from collections.abc import AsyncIterator
+from urllib.parse import urljoin, urlparse
+
+import aiohttp
+import httpx
+from aiohttp import ClientSession, ClientTimeout, TCPConnector
+from aiohttp.abc import AbstractResolver, ResolveResult
+
+from free_claude_code.application.web_tools.ports import (
+ WebFetchEgressPolicy,
+ WebFetchEgressViolation,
+)
+from free_claude_code.core.web_tools import WebFetchResult, WebSearchResult
+
+from . import constants
+from .constants import (
+ _MAX_FETCH_CHARS,
+ _MAX_SEARCH_RESULTS,
+ _REDIRECT_RESPONSE_BODY_CAP_BYTES,
+ _REQUEST_TIMEOUT_S,
+ _WEB_FETCH_REDIRECT_STATUSES,
+ _WEB_TOOL_HTTP_HEADERS,
+)
+from .egress import (
+ get_validated_stream_addrinfos_for_egress,
+)
+from .parsers import HTMLTextParser, SearchResultParser
+
+
+async def _iter_response_body_under_cap(
+ response: httpx.Response, max_bytes: int
+) -> AsyncIterator[bytes]:
+ if max_bytes <= 0:
+ return
+ received = 0
+ async for chunk in response.aiter_bytes(chunk_size=65_536):
+ if received >= max_bytes:
+ break
+ remaining = max_bytes - received
+ if len(chunk) <= remaining:
+ received += len(chunk)
+ yield chunk
+ if received >= max_bytes:
+ break
+ else:
+ yield chunk[:remaining]
+ break
+
+
+async def _drain_response_body_capped(response: httpx.Response, max_bytes: int) -> None:
+ async for _ in _iter_response_body_under_cap(response, max_bytes):
+ pass
+
+
+async def _read_response_body_capped(response: httpx.Response, max_bytes: int) -> bytes:
+ return b"".join(
+ [piece async for piece in _iter_response_body_under_cap(response, max_bytes)]
+ )
+
+
+_NUMERIC_RESOLVE_FLAGS = socket.AI_NUMERICHOST | socket.AI_NUMERICSERV
+_NAME_RESOLVE_FLAGS = socket.NI_NUMERICHOST | socket.NI_NUMERICSERV
+
+
+def getaddrinfo_rows_to_resolve_results(
+ host: str, addrinfos: list[tuple]
+) -> list[ResolveResult]:
+ """Map :func:`socket.getaddrinfo` rows to aiohttp :class:`ResolveResult` (ThreadedResolver logic)."""
+ out: list[ResolveResult] = []
+ for family, _type, proto, _canon, sockaddr in addrinfos:
+ if family == socket.AF_INET6:
+ if len(sockaddr) < 3:
+ continue
+ if sockaddr[3]:
+ resolved_host, port = socket.getnameinfo(sockaddr, _NAME_RESOLVE_FLAGS)
+ else:
+ resolved_host, port = sockaddr[:2]
+ else:
+ assert family == socket.AF_INET, family
+ resolved_host, port = sockaddr[0], sockaddr[1]
+ resolved_host = str(resolved_host)
+ port = int(port)
+ out.append(
+ ResolveResult(
+ hostname=host,
+ host=resolved_host,
+ port=int(port),
+ family=family,
+ proto=proto,
+ flags=_NUMERIC_RESOLVE_FLAGS,
+ )
+ )
+ return out
+
+
+class _PinnedEgressStaticResolver(AbstractResolver):
+ """Return only pre-validated :class:`ResolveResult` for the outbound request."""
+
+ def __init__(self, results: list[ResolveResult]) -> None:
+ self._results = results
+
+ async def resolve(
+ self, host: str, port: int = 0, family: int = socket.AF_INET
+ ) -> list[ResolveResult]:
+ return self._results
+
+ async def close(self) -> None: # pragma: no cover - aiohttp contract
+ return
+
+
+async def _read_aiohttp_body_capped(
+ response: aiohttp.ClientResponse, max_bytes: int
+) -> bytes:
+ received = 0
+ parts: list[bytes] = []
+ async for chunk in response.content.iter_chunked(65_536):
+ if received >= max_bytes:
+ break
+ remaining = max_bytes - received
+ if len(chunk) <= remaining:
+ received += len(chunk)
+ parts.append(chunk)
+ else:
+ parts.append(chunk[:remaining])
+ break
+ return b"".join(parts)
+
+
+async def _drain_aiohttp_body_capped(
+ response: aiohttp.ClientResponse, max_bytes: int
+) -> None:
+ if max_bytes <= 0:
+ return
+ received = 0
+ async for chunk in response.content.iter_chunked(65_536):
+ received += len(chunk)
+ if received >= max_bytes:
+ break
+
+
+class HTTPWebToolsClient:
+ """Stateless adapter; each call owns its HTTP resources until completion."""
+
+ async def search(self, query: str) -> list[WebSearchResult]:
+ async with (
+ httpx.AsyncClient(
+ timeout=_REQUEST_TIMEOUT_S,
+ follow_redirects=True,
+ headers=_WEB_TOOL_HTTP_HEADERS,
+ ) as client,
+ client.stream(
+ "GET",
+ "https://lite.duckduckgo.com/lite/",
+ params={"q": query},
+ ) as response,
+ ):
+ response.raise_for_status()
+ body_bytes = await _read_response_body_capped(
+ response, constants._MAX_WEB_FETCH_RESPONSE_BYTES
+ )
+ text = body_bytes.decode("utf-8", errors="replace")
+ parser = SearchResultParser()
+ parser.feed(text)
+ return parser.results[:_MAX_SEARCH_RESULTS]
+
+ async def fetch(self, url: str, *, egress: WebFetchEgressPolicy) -> WebFetchResult:
+ """Fetch URL with manual redirects; each hop is DNS-pinned to validated addresses."""
+ current_url = url
+ redirect_hops = 0
+ timeout = ClientTimeout(total=_REQUEST_TIMEOUT_S)
+
+ while True:
+ addr_infos = await asyncio.to_thread(
+ get_validated_stream_addrinfos_for_egress, current_url, egress
+ )
+ host = urlparse(current_url).hostname or ""
+ results = getaddrinfo_rows_to_resolve_results(host, addr_infos)
+ resolver = _PinnedEgressStaticResolver(results)
+ connector = TCPConnector(
+ resolver=resolver,
+ force_close=True,
+ )
+ try:
+ async with (
+ ClientSession(
+ timeout=timeout,
+ headers=_WEB_TOOL_HTTP_HEADERS,
+ connector=connector,
+ ) as session,
+ session.get(current_url, allow_redirects=False) as response,
+ ):
+ if response.status in _WEB_FETCH_REDIRECT_STATUSES:
+ await _drain_aiohttp_body_capped(
+ response, _REDIRECT_RESPONSE_BODY_CAP_BYTES
+ )
+ if redirect_hops >= constants._MAX_WEB_FETCH_REDIRECTS:
+ raise WebFetchEgressViolation(
+ "web_fetch exceeded maximum redirects "
+ f"({constants._MAX_WEB_FETCH_REDIRECTS})"
+ )
+ location = response.headers.get("location")
+ if not location or not location.strip():
+ raise WebFetchEgressViolation(
+ "web_fetch redirect response missing Location header"
+ )
+ current_url = urljoin(str(response.url), location.strip())
+ redirect_hops += 1
+ continue
+ response.raise_for_status()
+ content_type = response.headers.get("content-type", "text/plain")
+ final_url = str(response.url)
+ encoding = response.get_encoding() or "utf-8"
+ body_bytes = await _read_aiohttp_body_capped(
+ response, constants._MAX_WEB_FETCH_RESPONSE_BYTES
+ )
+ finally:
+ await connector.close()
+
+ break
+
+ text = body_bytes.decode(encoding, errors="replace")
+ title = final_url
+ data = text
+ if "html" in content_type.lower():
+ parser = HTMLTextParser()
+ parser.feed(text)
+ title = parser.title or final_url
+ data = "\n".join(parser.text_parts)
+ return WebFetchResult(
+ url=final_url,
+ title=title,
+ media_type="text/plain",
+ data=data[:_MAX_FETCH_CHARS],
+ )
diff --git a/src/free_claude_code/api/web_tools/constants.py b/src/free_claude_code/runtime/web_tools/constants.py
similarity index 100%
rename from src/free_claude_code/api/web_tools/constants.py
rename to src/free_claude_code/runtime/web_tools/constants.py
diff --git a/src/free_claude_code/api/web_tools/egress.py b/src/free_claude_code/runtime/web_tools/egress.py
similarity index 80%
rename from src/free_claude_code/api/web_tools/egress.py
rename to src/free_claude_code/runtime/web_tools/egress.py
index 1aec7223..63bef009 100644
--- a/src/free_claude_code/api/web_tools/egress.py
+++ b/src/free_claude_code/runtime/web_tools/egress.py
@@ -2,28 +2,12 @@
import ipaddress
import socket
-from dataclasses import dataclass
from urllib.parse import urlparse
-
-@dataclass(frozen=True, slots=True)
-class WebFetchEgressPolicy:
- """Egress rules for user-influenced web_fetch URLs."""
-
- allow_private_network_targets: bool
- allowed_schemes: frozenset[str]
-
-
-class WebFetchEgressViolation(ValueError):
- """Raised when a web_fetch URL is rejected by egress policy (SSRF guard)."""
-
-
-def web_fetch_allowed_scheme_set(raw_schemes: str) -> frozenset[str]:
- """Return normalized schemes allowed for web_fetch."""
-
- return frozenset(
- part.strip().lower() for part in raw_schemes.split(",") if part.strip()
- )
+from free_claude_code.application.web_tools.ports import (
+ WebFetchEgressPolicy,
+ WebFetchEgressViolation,
+)
def _port_for_url(parsed) -> int:
@@ -50,7 +34,7 @@ def get_validated_stream_addrinfos_for_egress(
Each HTTP connect pins to only these `getaddrinfo` results so a malicious DNS
server cannot rebind to a disallowed address between resolution and the TCP
- connect (used by :func:`api.web_tools.outbound._run_web_fetch`).
+ connect (used by :meth:`runtime.web_tools.client.HTTPWebToolsClient.fetch`).
"""
parsed = urlparse(url)
scheme = (parsed.scheme or "").lower()
diff --git a/src/free_claude_code/api/web_tools/parsers.py b/src/free_claude_code/runtime/web_tools/parsers.py
similarity index 68%
rename from src/free_claude_code/api/web_tools/parsers.py
rename to src/free_claude_code/runtime/web_tools/parsers.py
index 929538ac..06d2ed7d 100644
--- a/src/free_claude_code/api/web_tools/parsers.py
+++ b/src/free_claude_code/runtime/web_tools/parsers.py
@@ -1,17 +1,18 @@
"""HTML parsing for web_search / web_fetch."""
import html
-import re
from html.parser import HTMLParser
from urllib.parse import parse_qs, unquote, urlparse
+from free_claude_code.core.web_tools import WebSearchResult
+
class SearchResultParser(HTMLParser):
"""DuckDuckGo lite HTML: extract result links and titles."""
def __init__(self) -> None:
super().__init__()
- self.results: list[dict[str, str]] = []
+ self.results: list[WebSearchResult] = []
self._href: str | None = None
self._title_parts: list[str] = []
@@ -37,8 +38,10 @@ class SearchResultParser(HTMLParser):
if tag != "a" or self._href is None:
return
title = " ".join("".join(self._title_parts).split())
- if title and not any(result["url"] == self._href for result in self.results):
- self.results.append({"title": html.unescape(title), "url": self._href})
+ if title and not any(result.url == self._href for result in self.results):
+ self.results.append(
+ WebSearchResult(title=html.unescape(title), url=self._href)
+ )
self._href = None
self._title_parts = []
@@ -73,29 +76,3 @@ class HTMLTextParser(HTMLParser):
self.title = f"{self.title} {text}".strip()
elif not self._skip_depth:
self.text_parts.append(text)
-
-
-def content_text(content: object) -> str:
- if isinstance(content, str):
- return content
- if isinstance(content, list):
- parts = []
- for item in content:
- if isinstance(item, dict):
- parts.append(str(item.get("text", "")))
- else:
- parts.append(str(getattr(item, "text", "")))
- return "\n".join(part for part in parts if part)
- return str(content)
-
-
-def extract_query(text: str) -> str:
- match = re.search(r"query:\s*(.+)", text, flags=re.IGNORECASE | re.DOTALL)
- if match:
- return match.group(1).strip().strip("\"'")
- return text.strip()
-
-
-def extract_url(text: str) -> str:
- match = re.search(r"https?://\S+", text)
- return match.group(0).rstrip(").,]") if match else text.strip()
diff --git a/tests/api/support.py b/tests/api/support.py
index 9cd7594f..ff7494da 100644
--- a/tests/api/support.py
+++ b/tests/api/support.py
@@ -17,6 +17,7 @@ from free_claude_code.providers.runtime import ProviderRuntime
from free_claude_code.runtime.application import ApplicationRuntime, RestartCallback
from free_claude_code.runtime.configuration import ConfigurationService
from free_claude_code.runtime.provider_manager import ProviderRuntimeManager
+from tests.web_tools_support import StubWebToolsClient
class ApiTestRuntime(ProviderRuntimeManager):
@@ -85,6 +86,7 @@ def create_test_app(
admin=runtime,
tasks=runtime,
code=code,
+ web_tools=StubWebToolsClient(),
)
)
diff --git a/tests/api/test_api_handlers.py b/tests/api/test_api_handlers.py
index 374c75d7..44919bee 100644
--- a/tests/api/test_api_handlers.py
+++ b/tests/api/test_api_handlers.py
@@ -23,6 +23,7 @@ from free_claude_code.core.anthropic.streaming import format_sse_event
from free_claude_code.core.failures import ExecutionFailure, FailureKind
from free_claude_code.core.openai_responses import OpenAIResponsesRequest
from free_claude_code.core.reasoning import ReasoningPolicy
+from tests.web_tools_support import StubWebToolsClient
_LEGACY_CLASSIFIER_SYSTEM = (
"You are a security monitor. Respond with <block>yes</block> or <block>no</block>."
@@ -126,7 +127,9 @@ def _trace_events(trace_mock: MagicMock, event: str) -> list[dict[str, Any]]:
async def test_messages_handler_passes_routed_request_and_stream_metadata() -> None:
provider = FakeProvider()
handler = MessagesHandler(
- Settings(), provider_resolver=AsyncMock(side_effect=lambda _: provider)
+ Settings(),
+ provider_resolver=AsyncMock(side_effect=lambda _: provider),
+ web_tools=StubWebToolsClient(),
)
request = MessagesRequest(
model="nvidia_nim/test-model",
@@ -167,7 +170,9 @@ async def test_messages_handler_startup_invalid_request_stays_http_error(
provider = RejectStartupProvider()
handler = MessagesHandler(
- Settings(), provider_resolver=AsyncMock(side_effect=lambda _: provider)
+ Settings(),
+ provider_resolver=AsyncMock(side_effect=lambda _: provider),
+ web_tools=StubWebToolsClient(),
)
request = MessagesRequest(
model="nvidia_nim/test-model",
@@ -241,7 +246,9 @@ async def test_messages_handler_aggregates_provider_stream_when_stream_false() -
]
)
handler = MessagesHandler(
- Settings(), provider_resolver=AsyncMock(side_effect=lambda _: provider)
+ Settings(),
+ provider_resolver=AsyncMock(side_effect=lambda _: provider),
+ web_tools=StubWebToolsClient(),
)
request = MessagesRequest(
model="nvidia_nim/test-model",
@@ -282,7 +289,9 @@ async def test_messages_handler_returns_error_json_for_stream_false_sse_error()
]
)
handler = MessagesHandler(
- Settings(), provider_resolver=AsyncMock(side_effect=lambda _: provider)
+ Settings(),
+ provider_resolver=AsyncMock(side_effect=lambda _: provider),
+ web_tools=StubWebToolsClient(),
)
request = MessagesRequest(
model="nvidia_nim/test-model",
@@ -351,7 +360,9 @@ async def test_messages_handler_discards_partial_stream_false_output_on_error()
]
)
handler = MessagesHandler(
- Settings(), provider_resolver=AsyncMock(side_effect=lambda _: provider)
+ Settings(),
+ provider_resolver=AsyncMock(side_effect=lambda _: provider),
+ web_tools=StubWebToolsClient(),
)
request = MessagesRequest(
model="nvidia_nim/test-model",
@@ -406,7 +417,9 @@ async def test_messages_handler_stream_false_provider_exception_keeps_status() -
provider = FailingProvider()
handler = MessagesHandler(
- Settings(), provider_resolver=AsyncMock(side_effect=lambda _: provider)
+ Settings(),
+ provider_resolver=AsyncMock(side_effect=lambda _: provider),
+ web_tools=StubWebToolsClient(),
)
request = MessagesRequest(
model="nvidia_nim/test-model",
@@ -441,7 +454,9 @@ async def test_messages_handler_normalizes_safety_classifier_policy(
) -> None:
provider = FakeProvider()
handler = MessagesHandler(
- Settings(), provider_resolver=AsyncMock(side_effect=lambda _: provider)
+ Settings(),
+ provider_resolver=AsyncMock(side_effect=lambda _: provider),
+ web_tools=StubWebToolsClient(),
)
request = MessagesRequest(
model="nvidia_nim/test-model",
@@ -483,7 +498,9 @@ async def test_messages_handler_normalizes_safety_classifier_policy(
async def test_messages_handler_preserves_thinking_for_non_classifier() -> None:
provider = FakeProvider()
handler = MessagesHandler(
- Settings(), provider_resolver=AsyncMock(side_effect=lambda _: provider)
+ Settings(),
+ provider_resolver=AsyncMock(side_effect=lambda _: provider),
+ web_tools=StubWebToolsClient(),
)
request = MessagesRequest(
model="nvidia_nim/test-model",
@@ -523,7 +540,9 @@ async def test_messages_handler_preserves_thinking_for_non_classifier() -> None:
async def test_messages_handler_tolerates_required_thinking_for_classifier() -> None:
provider = FakeProvider()
handler = MessagesHandler(
- Settings(), provider_resolver=AsyncMock(side_effect=lambda _: provider)
+ Settings(),
+ provider_resolver=AsyncMock(side_effect=lambda _: provider),
+ web_tools=StubWebToolsClient(),
)
request = MessagesRequest(
model="claude-3-freecc-no-thinking/nvidia_nim/test-model",
@@ -564,7 +583,9 @@ async def test_messages_handler_prefers_no_thinking_without_classifier_stop_hint
):
provider = FakeProvider()
handler = MessagesHandler(
- Settings(), provider_resolver=AsyncMock(side_effect=lambda _: provider)
+ Settings(),
+ provider_resolver=AsyncMock(side_effect=lambda _: provider),
+ web_tools=StubWebToolsClient(),
)
request = MessagesRequest(
model="nvidia_nim/test-model",
@@ -600,7 +621,9 @@ async def test_messages_handler_prefers_no_thinking_without_classifier_stop_hint
async def test_messages_handler_preserves_unowned_classifier_stop_sequences() -> None:
provider = FakeProvider()
handler = MessagesHandler(
- Settings(), provider_resolver=AsyncMock(side_effect=lambda _: provider)
+ Settings(),
+ provider_resolver=AsyncMock(side_effect=lambda _: provider),
+ web_tools=StubWebToolsClient(),
)
original_stops = ["custom", "</severity>", "custom", "</severity>", "tail"]
request = MessagesRequest(
@@ -631,7 +654,9 @@ async def test_messages_handler_optimization_intercepts_before_provider_executio
None
):
provider_resolver = AsyncMock()
- handler = MessagesHandler(Settings(), provider_resolver=provider_resolver)
+ handler = MessagesHandler(
+ Settings(), provider_resolver=provider_resolver, web_tools=StubWebToolsClient()
+ )
request = MessagesRequest(
model="nvidia_nim/test-model",
max_tokens=100,
diff --git a/tests/api/test_classifier_provider_compatibility.py b/tests/api/test_classifier_provider_compatibility.py
index 940ac989..6c73f21d 100644
--- a/tests/api/test_classifier_provider_compatibility.py
+++ b/tests/api/test_classifier_provider_compatibility.py
@@ -22,6 +22,7 @@ from free_claude_code.core.anthropic.stream_contracts import (
from free_claude_code.core.reasoning import ReasoningCapability
from free_claude_code.providers.open_router import OpenRouterProvider
from tests.providers.support import immediate_admission, make_provider_config
+from tests.web_tools_support import StubWebToolsClient
class ClassifierStream:
@@ -145,7 +146,9 @@ async def test_openrouter_numeric_sse_rejection_uses_classifier_correction(
)
try:
response = await MessagesHandler(
- Settings(), provider_resolver=AsyncMock(side_effect=lambda _: provider)
+ Settings(),
+ provider_resolver=AsyncMock(side_effect=lambda _: provider),
+ web_tools=StubWebToolsClient(),
).create(classifier_request())
assert isinstance(response, JSONResponse)
assert len(bodies) == (2 if corrects else 1)
@@ -219,7 +222,9 @@ async def test_classifier_mandatory_reasoning_still_returns_verdict(reject_off,
try:
handler = MessagesHandler(
- Settings(), provider_resolver=AsyncMock(side_effect=lambda _: provider)
+ Settings(),
+ provider_resolver=AsyncMock(side_effect=lambda _: provider),
+ web_tools=StubWebToolsClient(),
)
with patch.object(
provider._client.chat.completions,
@@ -292,6 +297,7 @@ async def test_handler_uses_cached_capabilities_for_the_selected_provider(
),
None,
),
+ web_tools=StubWebToolsClient(),
)
with patch.object(
provider._client.chat.completions,
diff --git a/tests/api/test_request_lifetime.py b/tests/api/test_request_lifetime.py
index 2f790b44..98019b4c 100644
--- a/tests/api/test_request_lifetime.py
+++ b/tests/api/test_request_lifetime.py
@@ -25,6 +25,7 @@ from free_claude_code.core.anthropic import MessagesRequest
from free_claude_code.core.anthropic.streaming import format_sse_event
from free_claude_code.core.openai_responses import OpenAIResponsesRequest
from free_claude_code.core.reasoning import ReasoningPolicy
+from tests.web_tools_support import StubWebToolsClient
def _http_scope(
@@ -561,6 +562,7 @@ async def _disconnect_real_app(
requests=cast(RequestRuntimePort, requests),
admin=cast(AdminRuntimePort, object()),
tasks=cast(TaskController, object()),
+ web_tools=StubWebToolsClient(),
)
)
body = json.dumps(payload).encode()
diff --git a/tests/api/test_routes_optimizations.py b/tests/api/test_routes_optimizations.py
index 38fe351a..dafb210a 100644
--- a/tests/api/test_routes_optimizations.py
+++ b/tests/api/test_routes_optimizations.py
@@ -8,6 +8,7 @@ from free_claude_code.api.ports import ApiServices
from free_claude_code.application.ports import StopResult
from free_claude_code.config.settings import Settings
from tests.api.support import create_test_app
+from tests.web_tools_support import StubWebToolsClient
@pytest.fixture
@@ -190,6 +191,7 @@ def test_stop_cli_with_messaging_workflow(app, client):
requests=services.requests,
admin=services.admin,
tasks=session_control,
+ web_tools=StubWebToolsClient(),
)
response = client.post("/stop")
@@ -207,6 +209,7 @@ def test_stop_cli_fallback_to_manager(app, client):
requests=services.requests,
admin=services.admin,
tasks=session_control,
+ web_tools=StubWebToolsClient(),
)
response = client.post("/stop")
diff --git a/tests/api/test_safe_logging.py b/tests/api/test_safe_logging.py
index f9710f54..73eb6cfc 100644
--- a/tests/api/test_safe_logging.py
+++ b/tests/api/test_safe_logging.py
@@ -12,6 +12,7 @@ from free_claude_code.application import execution
from free_claude_code.config.settings import Settings
from free_claude_code.core.anthropic import AnthropicStreamLedger
from free_claude_code.core.anthropic.models import Message, MessagesRequest
+from tests.web_tools_support import StubWebToolsClient
@pytest.mark.asyncio
@@ -25,7 +26,9 @@ async def test_create_message_skips_full_payload_debug_log_by_default():
mock_provider.stream_messages = fake_stream
service = MessagesHandler(
- settings, provider_resolver=AsyncMock(side_effect=lambda _: mock_provider)
+ settings,
+ provider_resolver=AsyncMock(side_effect=lambda _: mock_provider),
+ web_tools=StubWebToolsClient(),
)
request = MessagesRequest(
@@ -56,7 +59,9 @@ async def test_create_message_logs_full_payload_when_opt_in():
mock_provider.stream_messages = fake_stream
service = MessagesHandler(
- settings, provider_resolver=AsyncMock(side_effect=lambda _: mock_provider)
+ settings,
+ provider_resolver=AsyncMock(side_effect=lambda _: mock_provider),
+ web_tools=StubWebToolsClient(),
)
request = MessagesRequest(
model="claude-3-haiku-20240307",
@@ -115,7 +120,9 @@ async def test_create_message_unexpected_error_default_logs_exclude_exception_te
mock_provider.stream_messages = stream_boom
service = MessagesHandler(
- settings, provider_resolver=AsyncMock(side_effect=lambda _: mock_provider)
+ settings,
+ provider_resolver=AsyncMock(side_effect=lambda _: mock_provider),
+ web_tools=StubWebToolsClient(),
)
request = MessagesRequest(
model="claude-3-haiku-20240307",
@@ -150,7 +157,9 @@ async def test_create_message_unexpected_error_terminal_json_ignores_status_code
mock_provider.stream_messages = stream_boom
service = MessagesHandler(
- settings, provider_resolver=AsyncMock(side_effect=lambda _: mock_provider)
+ settings,
+ provider_resolver=AsyncMock(side_effect=lambda _: mock_provider),
+ web_tools=StubWebToolsClient(),
)
request = MessagesRequest(
model="claude-3-haiku-20240307",
diff --git a/tests/api/test_web_server_tools.py b/tests/api/test_web_server_tools.py
index 6db6b149..8abb0310 100644
--- a/tests/api/test_web_server_tools.py
+++ b/tests/api/test_web_server_tools.py
@@ -1,6 +1,7 @@
import asyncio
import json
-from collections.abc import AsyncIterator, Mapping
+import socket
+from collections.abc import AsyncGenerator, AsyncIterator, Mapping
from typing import Any
from unittest.mock import AsyncMock, MagicMock, patch
@@ -8,27 +9,10 @@ import httpx
import pytest
from fastapi.responses import JSONResponse, StreamingResponse
-import free_claude_code.api.web_tools.constants as web_tool_constants
+import free_claude_code.runtime.web_tools.constants as web_tool_constants
from free_claude_code.api.handlers import MessagesHandler
-from free_claude_code.api.web_tools import egress as web_egress
-from free_claude_code.api.web_tools.egress import (
- WebFetchEgressPolicy,
- WebFetchEgressViolation,
- enforce_web_fetch_egress,
-)
-from free_claude_code.api.web_tools.outbound import (
- _drain_response_body_capped,
- _read_response_body_capped,
- _run_web_fetch,
-)
-from free_claude_code.api.web_tools.request import (
- HIDDEN_WEB_SEARCH_NAME,
- is_web_server_tool_request,
- plan_automatic_web_search,
- unsupported_server_tool_error,
-)
-from free_claude_code.api.web_tools.streaming import stream_web_server_tool_response
from free_claude_code.application.errors import InvalidRequestError
+from free_claude_code.application.execution import ProviderExecutor
from free_claude_code.application.model_metadata import ProviderModelInfo
from free_claude_code.application.routing import (
ModelRouter,
@@ -36,6 +20,17 @@ from free_claude_code.application.routing import (
ResolvedModelRoute,
RoutedMessagesRequest,
)
+from free_claude_code.application.web_tools.ports import (
+ WebFetchEgressPolicy,
+ WebFetchEgressViolation,
+)
+from free_claude_code.application.web_tools.request import (
+ HIDDEN_WEB_SEARCH_NAME,
+ is_web_server_tool_request,
+ plan_automatic_web_search,
+ unsupported_server_tool_error,
+)
+from free_claude_code.application.web_tools.service import WebToolService
from free_claude_code.config.provider_catalog import PROVIDER_CATALOG
from free_claude_code.config.reasoning import ReasoningPreference
from free_claude_code.config.settings import Settings
@@ -55,7 +50,16 @@ from free_claude_code.core.failures import ExecutionFailure, FailureKind
from free_claude_code.core.openai_responses import OpenAIResponsesRequest
from free_claude_code.core.reasoning import ReasoningPolicy
from free_claude_code.core.version import package_version
+from free_claude_code.core.web_tools import WebFetchResult, WebSearchResult
from free_claude_code.messaging.event_parser import parse_cli_event
+from free_claude_code.runtime.web_tools import egress as web_egress
+from free_claude_code.runtime.web_tools.client import (
+ HTTPWebToolsClient,
+ _drain_response_body_capped,
+ _read_response_body_capped,
+)
+from free_claude_code.runtime.web_tools.egress import enforce_web_fetch_egress
+from tests.web_tools_support import StubWebToolsClient
_STRICT_EGRESS = WebFetchEgressPolicy(
allow_private_network_targets=False,
@@ -108,6 +112,41 @@ class FixedProviderModelRouter(ModelRouter):
)
+def _local_tool_body(
+ request: MessagesRequest,
+ input_tokens: int,
+ *,
+ web_fetch_egress: WebFetchEgressPolicy,
+ verbose_client_errors: bool = False,
+) -> AsyncGenerator[str]:
+ settings = Settings().model_copy(
+ update={
+ "enable_web_server_tools": True,
+ "web_fetch_allow_private_networks": web_fetch_egress.allow_private_network_targets,
+ "web_fetch_allowed_schemes": ",".join(
+ sorted(web_fetch_egress.allowed_schemes)
+ ),
+ "log_api_error_tracebacks": verbose_client_errors,
+ }
+ )
+
+ async def unexpected_provider(_provider_id: str):
+ pytest.fail("Forced local tools must not resolve a provider")
+
+ service = WebToolService(
+ settings=settings,
+ client=StubWebToolsClient(),
+ executor=ProviderExecutor(unexpected_provider, progress_timeout_seconds=30),
+ token_counter=lambda *_: input_tokens,
+ )
+ routed = FixedProviderModelRouter(
+ settings, _PROVIDER_IDS[0]
+ ).resolve_messages_request(request)
+ body = service.try_stream_messages(routed, request_id="req_local_tool")
+ assert isinstance(body, AsyncGenerator)
+ return body
+
+
class ScriptedSelectionProvider:
"""One-stream provider double for the automatic WebSearch decision."""
@@ -337,6 +376,7 @@ def _automatic_search_service(
_PROVIDER_IDS[0],
provider_model="upstream-model",
),
+ web_tools=StubWebToolsClient(),
)
@@ -556,6 +596,7 @@ async def test_service_rejects_forced_server_tool_when_local_handler_is_disabled
settings,
provider_resolver=AsyncMock(side_effect=lambda _: MagicMock()),
model_router=FixedProviderModelRouter(settings, provider_id),
+ web_tools=StubWebToolsClient(),
)
request = MessagesRequest(
model="claude-haiku-4-5-20251001",
@@ -580,9 +621,7 @@ async def test_automatic_web_search_replays_provider_response_when_declined(
events = _provider_text_events("No search needed")
provider = ScriptedSelectionProvider(events)
search = AsyncMock()
- monkeypatch.setattr(
- "free_claude_code.api.web_tools.outbound._run_web_search", search
- )
+ monkeypatch.setattr("tests.web_tools_support.StubWebToolsClient.search", search)
service = _automatic_search_service(provider)
response = await service.create(
@@ -627,15 +666,15 @@ async def test_automatic_web_search_uses_model_query_and_filters_domains(
)
seen_queries: list[str] = []
- async def fake_search(query: str) -> list[dict[str, str]]:
+ async def fake_search(self, query: str) -> list[WebSearchResult]:
seen_queries.append(query)
return [
- {"title": "Allowed", "url": "https://docs.example.com/page"},
- {"title": "Filtered", "url": "https://unrelated.test/page"},
+ WebSearchResult(title="Allowed", url="https://docs.example.com/page"),
+ WebSearchResult(title="Filtered", url="https://unrelated.test/page"),
]
monkeypatch.setattr(
- "free_claude_code.api.web_tools.outbound._run_web_search", fake_search
+ "tests.web_tools_support.StubWebToolsClient.search", fake_search
)
service = _automatic_search_service(provider)
request = _automatic_search_request(
@@ -699,11 +738,11 @@ async def test_automatic_web_search_aggregates_when_stream_false(
_provider_tool_events(arguments={"query": "json query"})
)
- async def fake_search(_query: str) -> list[dict[str, str]]:
- return [{"title": "JSON result", "url": "https://example.com/json"}]
+ async def fake_search(self, _query: str) -> list[WebSearchResult]:
+ return [WebSearchResult(title="JSON result", url="https://example.com/json")]
monkeypatch.setattr(
- "free_claude_code.api.web_tools.outbound._run_web_search", fake_search
+ "tests.web_tools_support.StubWebToolsClient.search", fake_search
)
service = _automatic_search_service(provider)
@@ -740,9 +779,7 @@ async def test_automatic_web_search_rejects_malformed_provider_selection(
) -> None:
provider = ScriptedSelectionProvider(events)
search = AsyncMock()
- monkeypatch.setattr(
- "free_claude_code.api.web_tools.outbound._run_web_search", search
- )
+ monkeypatch.setattr("tests.web_tools_support.StubWebToolsClient.search", search)
service = _automatic_search_service(provider)
response = await service.create(
@@ -772,9 +809,7 @@ async def test_automatic_web_search_preserves_provider_failure_before_public_com
),
)
search = AsyncMock()
- monkeypatch.setattr(
- "free_claude_code.api.web_tools.outbound._run_web_search", search
- )
+ monkeypatch.setattr("tests.web_tools_support.StubWebToolsClient.search", search)
service = _automatic_search_service(provider)
response = await service.create(
@@ -804,9 +839,7 @@ async def test_automatic_web_search_converts_internal_post_start_failure_to_json
failure_after_events=True,
)
search = AsyncMock()
- monkeypatch.setattr(
- "free_claude_code.api.web_tools.outbound._run_web_search", search
- )
+ monkeypatch.setattr("tests.web_tools_support.StubWebToolsClient.search", search)
service = _automatic_search_service(provider)
response = await service.create(
@@ -956,16 +989,59 @@ def _aiohttp_client_session_patch(
return client_cm, session
-def test_enforce_web_fetch_egress_documents_connect_time_pinning():
- assert enforce_web_fetch_egress.__doc__ and "resolved addresses" in (
- enforce_web_fetch_egress.__doc__ or ""
- )
- assert (
- web_egress.get_validated_stream_addrinfos_for_egress.__doc__
- and "pinning"
- in (web_egress.get_validated_stream_addrinfos_for_egress.__doc__ or "")
+async def test_web_fetch_pins_validated_addresses_for_every_redirect(monkeypatch):
+ addresses = iter(["8.8.8.8", "1.1.1.1"])
+ resolved_hosts = []
+
+ def resolve(host, port, **kwargs):
+ resolved_hosts.append(host)
+ return [
+ (
+ socket.AF_INET,
+ socket.SOCK_STREAM,
+ socket.IPPROTO_TCP,
+ "",
+ (next(addresses), port),
+ )
+ ]
+
+ monkeypatch.setattr(web_egress.socket, "getaddrinfo", resolve)
+ redirect = _aiohttp_response(
+ 302, url="https://first.example/", location="https://next.example/", body=b""
)
- assert "DNS-pinned" in (_run_web_fetch.__doc__ or "")
+ final = _aiohttp_response(200, url="https://next.example/", body=b"done")
+ client_cm, _ = _aiohttp_client_session_patch(redirect, final)
+ connectors = []
+
+ def connector(**kwargs):
+ value = MagicMock()
+ value.close = AsyncMock()
+ connectors.append((kwargs["resolver"], value))
+ return value
+
+ with (
+ patch(
+ "free_claude_code.runtime.web_tools.client.ClientSession",
+ return_value=client_cm,
+ ),
+ patch(
+ "free_claude_code.runtime.web_tools.client.TCPConnector",
+ side_effect=connector,
+ ),
+ ):
+ result = await HTTPWebToolsClient().fetch(
+ "https://first.example/", egress=_STRICT_EGRESS
+ )
+
+ assert result.data == "done"
+ assert resolved_hosts == ["first.example", "next.example"]
+ for (resolver, value), expected in zip(
+ connectors, ["8.8.8.8", "1.1.1.1"], strict=True
+ ):
+ pinned = await resolver.resolve("ignored.example", 443)
+ assert [row["host"] for row in pinned] == [expected]
+ value.close.assert_awaited_once()
@pytest.mark.asyncio
@@ -976,11 +1052,14 @@ async def test_run_web_fetch_follows_redirect_when_each_hop_is_allowed():
res_ok = _aiohttp_response(200, url="http://8.8.8.8/final", body=b"hello world")
client_cm, session = _aiohttp_client_session_patch(res_redirect, res_ok)
with patch(
- "free_claude_code.api.web_tools.outbound.ClientSession", return_value=client_cm
+ "free_claude_code.runtime.web_tools.client.ClientSession",
+ return_value=client_cm,
):
- out = await _run_web_fetch("http://8.8.8.8/start", _STRICT_EGRESS)
+ out = await HTTPWebToolsClient().fetch(
+ "http://8.8.8.8/start", egress=_STRICT_EGRESS
+ )
- assert out["data"] == "hello world"
+ assert out.data == "hello world"
assert session.get.call_count == 2
@@ -991,12 +1070,15 @@ async def test_run_web_fetch_truncates_large_body_to_byte_cap(monkeypatch):
client_cm, _ = _aiohttp_client_session_patch(res_ok)
monkeypatch.setattr(web_tool_constants, "_MAX_WEB_FETCH_RESPONSE_BYTES", 100)
with patch(
- "free_claude_code.api.web_tools.outbound.ClientSession", return_value=client_cm
+ "free_claude_code.runtime.web_tools.client.ClientSession",
+ return_value=client_cm,
):
- out = await _run_web_fetch("http://8.8.8.8/big", _STRICT_EGRESS)
+ out = await HTTPWebToolsClient().fetch(
+ "http://8.8.8.8/big", egress=_STRICT_EGRESS
+ )
- assert len(out["data"]) <= 100
- assert out["data"] == "x" * 100
+ assert len(out.data) <= 100
+ assert out.data == "x" * 100
@pytest.mark.asyncio
@@ -1010,12 +1092,12 @@ async def test_run_web_fetch_redirect_to_blocked_host_raises():
client_cm, session = _aiohttp_client_session_patch(res_redirect)
with (
patch(
- "free_claude_code.api.web_tools.outbound.ClientSession",
+ "free_claude_code.runtime.web_tools.client.ClientSession",
return_value=client_cm,
),
pytest.raises(WebFetchEgressViolation),
):
- await _run_web_fetch("http://8.8.8.8/start", _STRICT_EGRESS)
+ await HTTPWebToolsClient().fetch("http://8.8.8.8/start", egress=_STRICT_EGRESS)
session.get.assert_called_once()
@@ -1026,12 +1108,12 @@ async def test_run_web_fetch_redirect_without_location_raises():
client_cm, _ = _aiohttp_client_session_patch(res_bad)
with (
patch(
- "free_claude_code.api.web_tools.outbound.ClientSession",
+ "free_claude_code.runtime.web_tools.client.ClientSession",
return_value=client_cm,
),
pytest.raises(WebFetchEgressViolation, match="missing Location"),
):
- await _run_web_fetch("http://8.8.8.8/here", _STRICT_EGRESS)
+ await HTTPWebToolsClient().fetch("http://8.8.8.8/here", egress=_STRICT_EGRESS)
@pytest.mark.asyncio
@@ -1040,24 +1122,28 @@ async def test_run_web_fetch_excess_redirects_raises():
res2 = _aiohttp_response(302, url="http://8.8.8.8/b", location="/c", body=b"")
client_cm, _ = _aiohttp_client_session_patch(res1, res2)
with (
- patch("free_claude_code.api.web_tools.constants._MAX_WEB_FETCH_REDIRECTS", 1),
patch(
- "free_claude_code.api.web_tools.outbound.ClientSession",
+ "free_claude_code.runtime.web_tools.constants._MAX_WEB_FETCH_REDIRECTS", 1
+ ),
+ patch(
+ "free_claude_code.runtime.web_tools.client.ClientSession",
return_value=client_cm,
),
pytest.raises(WebFetchEgressViolation, match="exceeded maximum redirects"),
):
- await _run_web_fetch("http://8.8.8.8/a", _STRICT_EGRESS)
+ await HTTPWebToolsClient().fetch("http://8.8.8.8/a", egress=_STRICT_EGRESS)
@pytest.mark.asyncio
async def test_streams_web_search_server_tool_result(monkeypatch):
- async def fake_search(query: str) -> list[dict[str, str]]:
+ async def fake_search(self, query: str) -> list[WebSearchResult]:
assert query == "DeepSeek V4 model release 2026"
- return [{"title": "DeepSeek V4 Released", "url": "https://example.com/v4"}]
+ return [
+ WebSearchResult(title="DeepSeek V4 Released", url="https://example.com/v4")
+ ]
monkeypatch.setattr(
- "free_claude_code.api.web_tools.outbound._run_web_search", fake_search
+ "tests.web_tools_support.StubWebToolsClient.search", fake_search
)
request = MessagesRequest(
model="claude-haiku-4-5-20251001",
@@ -1077,7 +1163,7 @@ async def test_streams_web_search_server_tool_result(monkeypatch):
raw = "".join(
[
event
- async for event in stream_web_server_tool_response(
+ async for event in _local_tool_body(
request, input_tokens=42, web_fetch_egress=_STRICT_EGRESS
)
]
@@ -1115,11 +1201,13 @@ async def test_streams_web_search_server_tool_result(monkeypatch):
@pytest.mark.asyncio
async def test_service_streams_forced_web_search_by_default(monkeypatch):
- async def fake_search(_query: str) -> list[dict[str, str]]:
- return [{"title": "DeepSeek V4 Released", "url": "https://example.com/v4"}]
+ async def fake_search(self, _query: str) -> list[WebSearchResult]:
+ return [
+ WebSearchResult(title="DeepSeek V4 Released", url="https://example.com/v4")
+ ]
monkeypatch.setattr(
- "free_claude_code.api.web_tools.outbound._run_web_search", fake_search
+ "tests.web_tools_support.StubWebToolsClient.search", fake_search
)
settings = Settings.model_validate({"ENABLE_WEB_SERVER_TOOLS": True})
provider_resolver = AsyncMock()
@@ -1131,6 +1219,7 @@ async def test_service_streams_forced_web_search_by_default(monkeypatch):
_PROVIDER_IDS[0],
provider_model="upstream-model",
),
+ web_tools=StubWebToolsClient(),
)
request = MessagesRequest(
model="claude-haiku-4-5-20251001",
@@ -1159,11 +1248,13 @@ async def test_service_streams_forced_web_search_by_default(monkeypatch):
@pytest.mark.asyncio
async def test_service_aggregates_forced_web_search_when_stream_false(monkeypatch):
- async def fake_search(_query: str) -> list[dict[str, str]]:
- return [{"title": "DeepSeek V4 Released", "url": "https://example.com/v4"}]
+ async def fake_search(self, _query: str) -> list[WebSearchResult]:
+ return [
+ WebSearchResult(title="DeepSeek V4 Released", url="https://example.com/v4")
+ ]
monkeypatch.setattr(
- "free_claude_code.api.web_tools.outbound._run_web_search", fake_search
+ "tests.web_tools_support.StubWebToolsClient.search", fake_search
)
settings = Settings.model_validate({"ENABLE_WEB_SERVER_TOOLS": True})
provider_resolver = AsyncMock()
@@ -1171,6 +1262,7 @@ async def test_service_aggregates_forced_web_search_when_stream_false(monkeypatc
settings,
provider_resolver=provider_resolver,
model_router=FixedProviderModelRouter(settings, _PROVIDER_IDS[0]),
+ web_tools=StubWebToolsClient(),
)
request = MessagesRequest(
model="claude-haiku-4-5-20251001",
@@ -1202,18 +1294,13 @@ async def test_forced_web_fetch_ignores_stale_url_from_prior_user_turns(monkeypa
"""Only the latest user message supplies the URL (not earlier transcript text)."""
target = "https://new-only.example.com/page"
- async def fake_fetch(url: str, _egress: WebFetchEgressPolicy) -> dict[str, str]:
+ async def fake_fetch(
+ self, url: str, *, egress: WebFetchEgressPolicy
+ ) -> WebFetchResult:
assert url == target
- return {
- "url": url,
- "title": "T",
- "media_type": "text/plain",
- "data": "x",
- }
+ return WebFetchResult(url=url, title="T", media_type="text/plain", data="x")
- monkeypatch.setattr(
- "free_claude_code.api.web_tools.outbound._run_web_fetch", fake_fetch
- )
+ monkeypatch.setattr("tests.web_tools_support.StubWebToolsClient.fetch", fake_fetch)
request = MessagesRequest(
model="claude-haiku-4-5-20251001",
max_tokens=100,
@@ -1235,7 +1322,7 @@ async def test_forced_web_fetch_ignores_stale_url_from_prior_user_turns(monkeypa
raw = "".join(
[
event
- async for event in stream_web_server_tool_response(
+ async for event in _local_tool_body(
request, input_tokens=1, web_fetch_egress=_STRICT_EGRESS
)
]
@@ -1245,23 +1332,24 @@ async def test_forced_web_fetch_ignores_stale_url_from_prior_user_turns(monkeypa
@pytest.mark.asyncio
async def test_service_aggregates_forced_web_fetch_when_stream_false(monkeypatch):
- async def fake_fetch(url: str, _egress: WebFetchEgressPolicy) -> dict[str, str]:
- return {
- "url": url,
- "title": "Example Article",
- "media_type": "text/plain",
- "data": "Article body",
- }
+ async def fake_fetch(
+ self, url: str, *, egress: WebFetchEgressPolicy
+ ) -> WebFetchResult:
+ return WebFetchResult(
+ url=url,
+ title="Example Article",
+ media_type="text/plain",
+ data="Article body",
+ )
- monkeypatch.setattr(
- "free_claude_code.api.web_tools.outbound._run_web_fetch", fake_fetch
- )
+ monkeypatch.setattr("tests.web_tools_support.StubWebToolsClient.fetch", fake_fetch)
settings = Settings.model_validate({"ENABLE_WEB_SERVER_TOOLS": True})
provider_resolver = AsyncMock()
service = MessagesHandler(
settings,
provider_resolver=provider_resolver,
model_router=FixedProviderModelRouter(settings, _PROVIDER_IDS[0]),
+ web_tools=StubWebToolsClient(),
)
request = MessagesRequest(
model="claude-haiku-4-5-20251001",
@@ -1290,18 +1378,18 @@ async def test_service_aggregates_forced_web_fetch_when_stream_false(monkeypatch
@pytest.mark.asyncio
async def test_streams_web_fetch_server_tool_result(monkeypatch):
- async def fake_fetch(url: str, _egress: WebFetchEgressPolicy) -> dict[str, str]:
+ async def fake_fetch(
+ self, url: str, *, egress: WebFetchEgressPolicy
+ ) -> WebFetchResult:
assert url == "https://example.com/article"
- return {
- "url": url,
- "title": "Example Article",
- "media_type": "text/plain",
- "data": "Article body",
- }
+ return WebFetchResult(
+ url=url,
+ title="Example Article",
+ media_type="text/plain",
+ data="Article body",
+ )
- monkeypatch.setattr(
- "free_claude_code.api.web_tools.outbound._run_web_fetch", fake_fetch
- )
+ monkeypatch.setattr("tests.web_tools_support.StubWebToolsClient.fetch", fake_fetch)
request = MessagesRequest(
model="claude-haiku-4-5-20251001",
max_tokens=100,
@@ -1315,7 +1403,7 @@ async def test_streams_web_fetch_server_tool_result(monkeypatch):
raw = "".join(
[
event
- async for event in stream_web_server_tool_response(
+ async for event in _local_tool_body(
request, input_tokens=42, web_fetch_egress=_STRICT_EGRESS
)
]
@@ -1352,10 +1440,10 @@ async def test_streams_web_fetch_server_tool_result(monkeypatch):
async def test_streams_web_fetch_error_summary_generic_by_default(monkeypatch):
secret = "sensitive-upstream-token"
- async def boom(_url: str, _egress: WebFetchEgressPolicy) -> dict[str, str]:
+ async def boom(self, _url: str, *, egress: WebFetchEgressPolicy) -> WebFetchResult:
raise ValueError(secret)
- monkeypatch.setattr("free_claude_code.api.web_tools.outbound._run_web_fetch", boom)
+ monkeypatch.setattr("tests.web_tools_support.StubWebToolsClient.fetch", boom)
request = MessagesRequest(
model="claude-haiku-4-5-20251001",
max_tokens=100,
@@ -1369,11 +1457,13 @@ async def test_streams_web_fetch_error_summary_generic_by_default(monkeypatch):
tool_choice={"type": "tool", "name": "web_fetch"},
)
- with patch("free_claude_code.api.web_tools.outbound.logger.warning") as log_warn:
+ with patch(
+ "free_claude_code.application.web_tools.service.logger.warning"
+ ) as log_warn:
raw = "".join(
[
event
- async for event in stream_web_server_tool_response(
+ async for event in _local_tool_body(
request,
input_tokens=1,
web_fetch_egress=_STRICT_EGRESS,
@@ -1410,10 +1500,10 @@ async def test_streams_web_fetch_error_summary_generic_by_default(monkeypatch):
async def test_streams_web_fetch_error_summary_verbose_includes_exception_class(
monkeypatch,
):
- async def boom(_url: str, _egress: WebFetchEgressPolicy) -> dict[str, str]:
+ async def boom(self, _url: str, *, egress: WebFetchEgressPolicy) -> WebFetchResult:
raise OSError(5, "oops")
- monkeypatch.setattr("free_claude_code.api.web_tools.outbound._run_web_fetch", boom)
+ monkeypatch.setattr("tests.web_tools_support.StubWebToolsClient.fetch", boom)
request = MessagesRequest(
model="claude-haiku-4-5-20251001",
max_tokens=100,
@@ -1425,7 +1515,7 @@ async def test_streams_web_fetch_error_summary_verbose_includes_exception_class(
raw = "".join(
[
event
- async for event in stream_web_server_tool_response(
+ async for event in _local_tool_body(
request,
input_tokens=1,
web_fetch_egress=_STRICT_EGRESS,
@@ -1477,6 +1567,7 @@ async def test_service_rejects_listed_server_tools_for_every_provider(
settings,
provider_resolver=AsyncMock(side_effect=lambda _: MagicMock()),
model_router=FixedProviderModelRouter(settings, provider_id),
+ web_tools=StubWebToolsClient(),
)
request = MessagesRequest(
model="m",
@@ -1486,3 +1577,174 @@ async def test_service_rejects_listed_server_tools_for_every_provider(
)
with pytest.raises(InvalidRequestError, match="ENABLE_WEB_SERVER_TOOLS=false"):
await service.create(request)
+
+
+async def test_automatic_selection_stays_private_until_provider_finishes() -> None:
+ release = asyncio.Event()
+ provider = ScriptedSelectionProvider(
+ _provider_text_events("declined"), wait_for=release
+ )
+ task = asyncio.create_task(
+ _automatic_search_service(provider).create(_automatic_search_request())
+ )
+ try:
+ await asyncio.wait_for(provider.started.wait(), 1)
+ assert not task.done()
+ release.set()
+ response = await asyncio.wait_for(task, 1)
+ assert isinstance(response, StreamingResponse)
+ assert await _streaming_body_text(response) == "".join(provider.events)
+ assert provider.close_count == 1
+ finally:
+ release.set()
+ if not task.done():
+ task.cancel()
+ await asyncio.gather(task, return_exceptions=True)
+
+
[email protected]("tool_name", ["web_search", "web_fetch"])
[email protected]("close_before_outbound", [False, True])
+async def test_local_tool_start_precedes_outbound_and_cancellation_closes_operation(
+ monkeypatch, tool_name: str, close_before_outbound: bool
+) -> None:
+ entered, closed = asyncio.Event(), asyncio.Event()
+
+ async def blocked(*_args, **_kwargs):
+ entered.set()
+ try:
+ await asyncio.Event().wait()
+ finally:
+ closed.set()
+
+ monkeypatch.setattr(
+ f"tests.web_tools_support.StubWebToolsClient.{tool_name.removeprefix('web_')}",
+ blocked,
+ )
+ tool_type = (
+ "web_search_20250305" if tool_name == "web_search" else "web_fetch_20250910"
+ )
+ request = MessagesRequest(
+ model="public-model",
+ messages=[Message(role="user", content="https://example.com/")],
+ tools=[Tool(name=tool_name, type=tool_type)],
+ tool_choice={"type": "tool", "name": tool_name},
+ )
+ body = _local_tool_body(request, 7, web_fetch_egress=_STRICT_EGRESS)
+ pending = None
+ try:
+ prefix = [await anext(body) for _ in range(3)]
+ assert [event.event for event in parse_sse_text("".join(prefix))] == [
+ "message_start",
+ "content_block_start",
+ "content_block_stop",
+ ]
+ assert not entered.is_set()
+ if close_before_outbound:
+ await body.aclose()
+ assert not entered.is_set()
+ return
+ pending = asyncio.create_task(anext(body))
+ await asyncio.wait_for(entered.wait(), 1)
+ pending.cancel()
+ with pytest.raises(asyncio.CancelledError):
+ await pending
+ assert closed.is_set()
+ finally:
+ if pending is not None and not pending.done():
+ pending.cancel()
+ await asyncio.gather(pending, return_exceptions=True)
+ await body.aclose()
+
+
+ ("tool_name", "automatic"),
+ [("web_search", False), ("web_fetch", False), ("web_search", True)],
+)
[email protected]("stream", [False, True])
+async def test_local_failures_remain_completed_tool_results(
+ monkeypatch, tool_name: str, automatic: bool, stream: bool
+) -> None:
+ async def fail(*_args, **_kwargs):
+ raise OSError("private upstream detail")
+
+ monkeypatch.setattr(
+ f"tests.web_tools_support.StubWebToolsClient.{tool_name.removeprefix('web_')}",
+ fail,
+ )
+ provider = ScriptedSelectionProvider(
+ _provider_tool_events(arguments={"query": "query"})
+ )
+ handler = _automatic_search_service(provider)
+ request = _automatic_search_request().model_copy(update={"stream": stream})
+ if not automatic:
+ tool_type = (
+ "web_search_20250305" if tool_name == "web_search" else "web_fetch_20250910"
+ )
+ request = request.model_copy(
+ update={
+ "tools": [Tool(name=tool_name, type=tool_type)],
+ "tool_choice": {"type": "tool", "name": tool_name},
+ }
+ )
+ response = await handler.create(request)
+ if stream:
+ assert isinstance(response, StreamingResponse)
+ raw = await _streaming_body_text(response)
+ events = parse_sse_text(raw)
+ assert_anthropic_stream_contract(events)
+ assert not any(event.event == "error" for event in events)
+ result = next(
+ event.data["content_block"]
+ for event in events
+ if event.event == "content_block_start" and event.data["index"] == 1
+ )
+ usage = next(
+ event.data["usage"] for event in events if event.event == "message_delta"
+ )
+ assert events[-1].event == "message_stop"
+ else:
+ assert isinstance(response, JSONResponse)
+ assert response.status_code == 200
+ message = _json_body(response)
+ result, usage = message["content"][1], message["usage"]
+ assert message["stop_reason"] == "end_turn"
+ assert result["type"] == f"{tool_name}_tool_result"
+ expected_error = (
+ "web_search_tool_result_error"
+ if tool_name == "web_search"
+ else "web_fetch_tool_error"
+ )
+ assert result["content"] == {"type": expected_error, "error_code": "unavailable"}
+ assert usage["server_tool_use"] == {f"{tool_name}_requests": 1}
+ assert len(provider.requests) == int(automatic)
+
+
[email protected]("tool_name", ["web_search", "web_fetch"])
+def test_forced_tools_keep_permissive_matching(tool_name: str) -> None:
+ tool_type = (
+ "web_search_20250305" if tool_name == "web_search" else "web_fetch_20250910"
+ )
+ request = MessagesRequest(
+ model="model",
+ messages=[
+ Message(
+ role="assistant",
+ content=[
+ ContentBlockServerToolUse(
+ type="server_tool_use", id="old", name=tool_name, input={}
+ )
+ ],
+ )
+ ],
+ tools=[
+ Tool(name=tool_name, type=tool_type, max_uses=0, unsupported_option=True),
+ Tool(name="client_tool", input_schema={"type": "object"}),
+ ],
+ tool_choice={"type": "tool", "name": tool_name, "extra": True},
+ )
+ assert is_web_server_tool_request(request)
+ assert plan_automatic_web_search(request, web_tools_enabled=True) is None
+ assert unsupported_server_tool_error(request, web_tools_enabled=True) is None
diff --git a/tests/application/test_web_tools.py b/tests/application/test_web_tools.py
new file mode 100644
index 00000000..db910c60
--- /dev/null
+++ b/tests/application/test_web_tools.py
@@ -0,0 +1,131 @@
+"""Application web-tool behavior through its explicit outbound capability."""
+
+import asyncio
+from collections.abc import AsyncIterator
+
+import pytest
+
+from free_claude_code.application.errors import InvalidRequestError
+from free_claude_code.application.execution import ProviderExecutor
+from free_claude_code.application.routing import ModelRouter
+from free_claude_code.application.web_tools.ports import WebFetchEgressPolicy
+from free_claude_code.application.web_tools.service import WebToolService
+from free_claude_code.config.settings import Settings
+from free_claude_code.core.anthropic.models import Message, MessagesRequest, Tool
+from free_claude_code.core.web_tools import WebFetchResult
+from tests.web_tools_support import StubWebToolsClient
+
+
+async def _no_provider(_provider_id):
+ pytest.fail("This request must not resolve a provider")
+
+
+def _service(settings, client, *, token_counter=lambda *_: 5):
+ return WebToolService(
+ settings=settings,
+ client=client,
+ executor=ProviderExecutor(_no_provider, progress_timeout_seconds=30),
+ token_counter=token_counter,
+ )
+
+
+def _request(tool, *, typed=True):
+ return MessagesRequest(
+ model="claude-sonnet",
+ messages=[Message(role="user", content="https://example.com/")],
+ tools=[
+ Tool(
+ name=tool,
+ type=(
+ "web_fetch_20250910"
+ if tool == "web_fetch"
+ else "web_search_20250305"
+ )
+ if typed
+ else None,
+ )
+ ],
+ tool_choice={"type": "tool", "name": tool},
+ )
+
+
+async def _drain(body: AsyncIterator[str]) -> str:
+ return "".join([chunk async for chunk in body])
+
+
+def test_ordinary_client_tool_needs_no_web_or_token_work():
+ settings = Settings()
+ service = _service(
+ settings,
+ StubWebToolsClient(),
+ token_counter=lambda *_: pytest.fail("Unhandled request counted tokens"),
+ )
+ routed = ModelRouter(settings).resolve_messages_request(
+ _request("web_search", typed=False)
+ )
+ assert service.try_stream_messages(routed, request_id="req_unhandled") is None
+
+
+def test_disabled_tool_fails_during_preparation():
+ settings = Settings().model_copy(update={"enable_web_server_tools": False})
+ service = _service(settings, StubWebToolsClient())
+ routed = ModelRouter(settings).resolve_messages_request(_request("web_fetch"))
+ with pytest.raises(InvalidRequestError, match="disabled"):
+ service.try_stream_messages(routed, request_id="req_disabled")
+
+
+async def test_concurrent_requests_keep_their_own_egress_policy():
+ entered, release = asyncio.Event(), asyncio.Event()
+
+ class Client(StubWebToolsClient):
+ def __init__(self):
+ self.policies = []
+
+ async def fetch(
+ self, url: str, *, egress: WebFetchEgressPolicy
+ ) -> WebFetchResult:
+ self.policies.append(egress)
+ if len(self.policies) == 2:
+ entered.set()
+ await release.wait()
+ return WebFetchResult(
+ url=url, title="page", media_type="text/plain", data="text"
+ )
+
+ client = Client()
+ settings = [
+ Settings().model_copy(
+ update={
+ "web_fetch_allow_private_networks": False,
+ "web_fetch_allowed_schemes": "https",
+ }
+ ),
+ Settings().model_copy(
+ update={
+ "web_fetch_allow_private_networks": True,
+ "web_fetch_allowed_schemes": "http, https",
+ }
+ ),
+ ]
+ tasks = []
+ try:
+ for index, snapshot in enumerate(settings):
+ service = _service(snapshot, client)
+ body = service.try_stream_messages(
+ ModelRouter(snapshot).resolve_messages_request(_request("web_fetch")),
+ request_id=f"req_{index}",
+ )
+ assert body is not None
+ tasks.append(asyncio.create_task(_drain(body)))
+ await asyncio.wait_for(entered.wait(), 1)
+ assert client.policies == [
+ WebFetchEgressPolicy(False, frozenset({"https"})),
+ WebFetchEgressPolicy(True, frozenset({"http", "https"})),
+ ]
+ release.set()
+ outputs = await asyncio.gather(*tasks)
+ assert all("web_fetch_tool_result" in output for output in outputs)
+ finally:
+ release.set()
+ await asyncio.gather(*tasks, return_exceptions=True)
diff --git a/tests/cli/test_config_restart_lifecycle.py b/tests/cli/test_config_restart_lifecycle.py
index 2a618285..404a58a3 100644
--- a/tests/cli/test_config_restart_lifecycle.py
+++ b/tests/cli/test_config_restart_lifecycle.py
@@ -17,6 +17,7 @@ from free_claude_code.runtime.application import ApplicationRuntime
from free_claude_code.runtime.asgi import RuntimeASGIApp
from free_claude_code.runtime.configuration import ConfigurationService
from free_claude_code.runtime.provider_manager import ProviderRuntimeManager
+from tests.web_tools_support import StubWebToolsClient
@pytest.mark.parametrize("stop_during_commit", [False, True])
@@ -46,7 +47,14 @@ def test_supervised_http_apply_finishes_and_reconnects(monkeypatch, stop_during_
)
runtimes.append(runtime)
return RuntimeASGIApp(
- create_app(ApiServices(requests=manager, admin=runtime, tasks=runtime)),
+ create_app(
+ ApiServices(
+ requests=manager,
+ admin=runtime,
+ tasks=runtime,
+ web_tools=StubWebToolsClient(),
+ )
+ ),
runtime,
)
diff --git a/tests/contracts/test_import_boundaries.py b/tests/contracts/test_import_boundaries.py
index 3aac1097..5ac769b7 100644
--- a/tests/contracts/test_import_boundaries.py
+++ b/tests/contracts/test_import_boundaries.py
@@ -565,6 +565,25 @@ def test_core_does_not_import_provider_transport_sdks() -> None:
assert sorted(offenders) == []
+def test_web_tool_workflow_has_no_http_adapter_owner() -> None:
+ former_owner = "free_claude_code.api.web_tools"
+ application_owner = "free_claude_code.application.web_tools"
+ forbidden_clients = {"aiohttp", "httpx", "requests", "socket"}
+ offenders = [
+ record.describe()
+ for record in _scan_imports(_PACKAGE_ROOT)
+ if record.imported.startswith(former_owner)
+ or (
+ record.importer.startswith(application_owner)
+ and record.imported.split(".", 1)[0] in forbidden_clients
+ )
+ ]
+ remaining = list((_PACKAGE_ROOT / "api" / "web_tools").glob("*.py"))
+ assert not offenders and not remaining, "\n".join(
+ [*offenders, *(str(path.relative_to(_REPO_ROOT)) for path in remaining)]
+ )
+
+
def test_providers_do_not_own_wire_error_type_literals() -> None:
wire_types = {
"api_error",
diff --git a/tests/core/anthropic/test_server_tool_sse.py b/tests/core/anthropic/test_server_tool_sse.py
new file mode 100644
index 00000000..ae62ee38
--- /dev/null
+++ b/tests/core/anthropic/test_server_tool_sse.py
@@ -0,0 +1,136 @@
+"""Local tool wire contracts independent of application and network execution."""
+
+import pytest
+
+from free_claude_code.core.anthropic.server_tool_sse import (
+ ServerToolResponseContext,
+ server_tool_completion_frames,
+ server_tool_start_frames,
+ web_fetch_result_block,
+ web_search_result_block,
+ web_tool_error_block,
+)
+from free_claude_code.core.anthropic.stream_contracts import parse_sse_text
+from free_claude_code.core.web_tools import WebFetchResult, WebSearchResult
+
+
+ ("usage", "expected_start", "expected_end"),
+ [
+ (
+ None,
+ {"input_tokens": 7, "output_tokens": 1},
+ {"input_tokens": 7, "output_tokens": 2},
+ ),
+ (
+ {},
+ {"input_tokens": 7, "output_tokens": 1},
+ {"input_tokens": 7, "output_tokens": 2},
+ ),
+ (
+ {
+ "input_tokens": 17,
+ "output_tokens": 9,
+ "cache_read_input_tokens": 5,
+ "bool": True,
+ "text": "ignore",
+ },
+ {"input_tokens": 17, "output_tokens": 1, "cache_read_input_tokens": 5},
+ {"input_tokens": 17, "output_tokens": 9, "cache_read_input_tokens": 5},
+ ),
+ ],
+)
[email protected]("tool_name", ["web_search", "web_fetch"])
[email protected]("failed", [False, True])
+def test_local_tool_event_order_linked_results_and_usage(
+ usage, expected_start, expected_end, tool_name, failed
+):
+ context = ServerToolResponseContext(
+ message_id="msg_local",
+ tool_id="srvtoolu_local",
+ model="public/model",
+ tool_name=tool_name,
+ tool_input={"query": "q"}
+ if tool_name == "web_search"
+ else {"url": "https://example.com/"},
+ input_tokens=7,
+ provider_usage=usage,
+ )
+ if failed:
+ block = web_tool_error_block(context)
+ elif tool_name == "web_search":
+ block = web_search_result_block(
+ context, [WebSearchResult(title="Result", url="https://example.com/")]
+ )
+ else:
+ block = web_fetch_result_block(
+ context,
+ WebFetchResult(
+ url="https://example.com/final",
+ title="Page",
+ media_type="text/plain",
+ data="contents",
+ ),
+ retrieved_at="2026-09-15T00:00:00+00:00",
+ )
+ events = parse_sse_text(
+ "".join(
+ [
+ *server_tool_start_frames(context),
+ *server_tool_completion_frames(context, block, summary="12345678"),
+ ]
+ )
+ )
+ assert [event.event for event in events] == [
+ "message_start",
+ "content_block_start",
+ "content_block_stop",
+ "content_block_start",
+ "content_block_stop",
+ "content_block_start",
+ "content_block_delta",
+ "content_block_stop",
+ "message_delta",
+ "message_stop",
+ ]
+ assert events[0].data["message"]["model"] == "public/model"
+ assert events[0].data["message"]["usage"] == expected_start
+ assert events[1].data["content_block"]["id"] == "srvtoolu_local"
+ assert events[3].data["content_block"]["tool_use_id"] == "srvtoolu_local"
+ assert [events[index].data["index"] for index in (1, 3, 5)] == [0, 1, 2]
+ assert events[-2].data["usage"] == {
+ **expected_end,
+ "server_tool_use": {f"{tool_name}_requests": 1},
+ }
+ assert events[-2].data["delta"]["stop_reason"] == "end_turn"
+ if failed:
+ assert block["content"] == {
+ "type": "web_search_tool_result_error"
+ if tool_name == "web_search"
+ else "web_fetch_tool_error",
+ "error_code": "unavailable",
+ }
+ elif tool_name == "web_search":
+ assert block["content"] == [
+ {
+ "type": "web_search_result",
+ "title": "Result",
+ "url": "https://example.com/",
+ }
+ ]
+ else:
+ assert block["content"] == {
+ "type": "web_fetch_result",
+ "url": "https://example.com/final",
+ "content": {
+ "type": "document",
+ "source": {
+ "type": "text",
+ "media_type": "text/plain",
+ "data": "contents",
+ },
+ "title": "Page",
+ "citations": {"enabled": True},
+ },
+ "retrieved_at": "2026-09-15T00:00:00+00:00",
+ }
diff --git a/tests/runtime/test_progressive_startup.py b/tests/runtime/test_progressive_startup.py
index 5ac804cf..c166ca0c 100644
--- a/tests/runtime/test_progressive_startup.py
+++ b/tests/runtime/test_progressive_startup.py
@@ -21,6 +21,7 @@ from free_claude_code.runtime.application import ApplicationRuntime
from free_claude_code.runtime.codex_catalog import CodexModelCatalogPublisher
from free_claude_code.runtime.configuration import ConfigurationService
from free_claude_code.runtime.provider_manager import ProviderRuntimeManager
+from tests.web_tools_support import StubWebToolsClient
def _settings():
@@ -60,7 +61,9 @@ async def test_http_and_admin_serve_while_selected_catalog_is_held():
configuration=ConfigurationService(ManagedConfigStore()),
transcriber=None,
)
- app = create_app(ApiServices(manager, runtime, runtime))
+ app = create_app(
+ ApiServices(manager, runtime, runtime, web_tools=StubWebToolsClient())
+ )
try:
await asyncio.wait_for(runtime.start(), 1)
await asyncio.wait_for(entered.wait(), 1)
diff --git a/tests/runtime/test_web_tools_client.py b/tests/runtime/test_web_tools_client.py
new file mode 100644
index 00000000..bdc2a078
--- /dev/null
+++ b/tests/runtime/test_web_tools_client.py
@@ -0,0 +1,153 @@
+"""Outbound request, parsing, and resource ownership with no network access."""
+
+import asyncio
+
+import httpx
+import pytest
+
+from free_claude_code.core.web_tools import WebSearchResult
+from free_claude_code.runtime.web_tools import client as web_client
+
+
+def _httpx_clients(monkeypatch, handler):
+ original_client = httpx.AsyncClient
+ clients = []
+
+ def construct(**kwargs):
+ client = original_client(transport=httpx.MockTransport(handler), **kwargs)
+ clients.append(client)
+ return client
+
+ monkeypatch.setattr(web_client.httpx, "AsyncClient", construct)
+ return clients
+
+
+async def test_search_request_parsing_limit_and_client_closure(monkeypatch):
+ def handle(request):
+ assert str(request.url).startswith("https://lite.duckduckgo.com/lite/")
+ assert request.url.params["q"] == "query & details"
+ assert "free-claude-code/" in request.headers["User-Agent"]
+ links = [
+ f'<a href="/l/?uddg=https%3A%2F%2Fexample.com%2F{index}">Title {index}</a>'
+ for index in range(12)
+ ]
+ links.insert(1, links[0])
+ return httpx.Response(200, text="".join(links))
+
+ clients = _httpx_clients(monkeypatch, handle)
+ result = await web_client.HTTPWebToolsClient().search("query & details")
+ assert result == [
+ WebSearchResult(title=f"Title {index}", url=f"https://example.com/{index}")
+ for index in range(10)
+ ]
+ assert len(clients) == 1 and clients[0].is_closed
+
+
[email protected]("cancel_during_body", [False, True])
+async def test_search_cancellation_closes_client_and_open_response(
+ monkeypatch, cancel_during_body
+):
+ entered = asyncio.Event()
+
+ class Body(httpx.AsyncByteStream):
+ closed = False
+
+ async def __aiter__(self):
+ entered.set()
+ await asyncio.Event().wait()
+ yield b""
+
+ async def aclose(self):
+ self.closed = True
+
+ body = Body()
+
+ async def handle(request):
+ if not cancel_during_body:
+ entered.set()
+ await asyncio.Event().wait()
+ return httpx.Response(200, stream=body)
+
+ clients = _httpx_clients(monkeypatch, handle)
+ task = asyncio.create_task(web_client.HTTPWebToolsClient().search("held"))
+ try:
+ await asyncio.wait_for(entered.wait(), 1)
+ task.cancel()
+ with pytest.raises(asyncio.CancelledError):
+ await task
+ assert len(clients) == 1 and clients[0].is_closed
+ assert body.closed is cancel_during_body
+ finally:
+ if not task.done():
+ task.cancel()
+ await asyncio.gather(task, return_exceptions=True)
+
+
+async def test_fetch_cancellation_closes_response_session_and_connector(monkeypatch):
+ from contextlib import asynccontextmanager
+ from types import SimpleNamespace
+
+ from free_claude_code.application.web_tools.ports import WebFetchEgressPolicy
+
+ entered = asyncio.Event()
+ response_closed, session_closed = [], []
+ connectors = []
+ original_connector = web_client.TCPConnector
+
+ def connector(**kwargs):
+ value = original_connector(**kwargs)
+ connectors.append(value)
+ return value
+
+ async def chunks(_size):
+ entered.set()
+ await asyncio.Event().wait()
+ yield b""
+
+ @asynccontextmanager
+ async def response(url, *, allow_redirects):
+ assert url == "https://8.8.8.8/"
+ assert allow_redirects is False
+ try:
+ yield SimpleNamespace(
+ status=200,
+ url=url,
+ headers={},
+ get_encoding=lambda: "utf-8",
+ raise_for_status=lambda: None,
+ content=SimpleNamespace(iter_chunked=chunks),
+ )
+ finally:
+ response_closed.append(True)
+
+ @asynccontextmanager
+ async def session(**kwargs):
+ assert kwargs["connector"] is connectors[-1]
+ try:
+ yield SimpleNamespace(get=response)
+ finally:
+ session_closed.append(True)
+
+ monkeypatch.setattr(web_client, "TCPConnector", connector)
+ monkeypatch.setattr(web_client, "ClientSession", session)
+ task = asyncio.create_task(
+ web_client.HTTPWebToolsClient().fetch(
+ "https://8.8.8.8/",
+ egress=WebFetchEgressPolicy(False, frozenset({"https"})),
+ )
+ )
+ try:
+ await asyncio.wait_for(entered.wait(), 1)
+ task.cancel()
+ with pytest.raises(asyncio.CancelledError):
+ await task
+ assert response_closed == [True]
+ assert session_closed == [True]
+ assert len(connectors) == 1 and connectors[0].closed
+ finally:
+ if not task.done():
+ task.cancel()
+ await asyncio.gather(task, return_exceptions=True)
diff --git a/tests/web_tools_support.py b/tests/web_tools_support.py
new file mode 100644
index 00000000..7c19e69e
--- /dev/null
+++ b/tests/web_tools_support.py
@@ -0,0 +1,14 @@
+"""Explicit web-client double for tests that do not perform outbound requests."""
+
+import pytest
+
+from free_claude_code.application.web_tools.ports import WebFetchEgressPolicy
+from free_claude_code.core.web_tools import WebFetchResult, WebSearchResult
+
+
+class StubWebToolsClient:
+ async def search(self, query: str) -> list[WebSearchResult]:
+ pytest.fail(f"Unexpected web search: {query!r}")
+
+ async def fetch(self, url: str, *, egress: WebFetchEgressPolicy) -> WebFetchResult:
+ pytest.fail(f"Unexpected web fetch: {url!r}")
diff --git a/uv.lock b/uv.lock
index 581fa256..59db4e58 100644
--- a/uv.lock
+++ b/uv.lock
@@ -598,7 +598,7 @@ wheels = [
[[package]]
name = "free-claude-code"
-version = "6.2.28"
+version = "6.2.29"
source = { editable = "." }
dependencies = [
{ name = "aiohttp" },