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.pyindex 7a543534..f2e32db1 100644--- a/e2e/conftest.py+++ b/e2e/conftest.py@@ -34,6 +34,7 @@ from free_claude_code.runtime.asgi import RuntimeASGIAppfrom free_claude_code.runtime.configuration import ConfigurationServicefrom free_claude_code.runtime.folder_picker import NativeFolderPickerfrom free_claude_code.runtime.provider_manager import ProviderRuntimeManager+from tests.web_tools_support import StubWebToolsClientclass _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.tomlindex 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.pyindex 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, Mappingfrom dataclasses import dataclass, replacefrom 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 ApplicationErrorfrom free_claude_code.application.execution import ProviderExecutor, TokenCounterfrom free_claude_code.application.ports import ModelInfoLookup, ProviderResolverfrom 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 WebToolServicefrom free_claude_code.config.settings import Settingsfrom 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 = settingsself._model_router = model_router or ModelRouter(settings)- self._token_counter = token_counterself._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.pyindex 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 ProviderModelRefreshResultfrom free_claude_code.application.ports import RequestRuntimePort, TaskController+from free_claude_code.application.web_tools.ports import WebToolsPortfrom free_claude_code.config.admin.state import ConfigInputValue, ValueStatefrom free_claude_code.core.json_types import JsonObject@@ -72,4 +73,5 @@ class ApiServices:requests: RequestRuntimePortadmin: AdminRuntimePorttasks: TaskController+ web_tools: WebToolsPortcode: CodeApplicationPort | None = Nonediff --git a/src/free_claude_code/api/routes.py b/src/free_claude_code/api/routes.pyindex 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__.pydeleted file mode 100644index 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.pydeleted file mode 100644index 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.pydeleted file mode 100644index 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.pydeleted file mode 100644index 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__.pynew file mode 100644index 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.pynew file mode 100644index 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.pysimilarity index 91%rename from src/free_claude_code/api/web_tools/request.pyrename to src/free_claude_code/application/web_tools/request.pyindex 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 dataclassfrom free_claude_code.application.errors import InvalidRequestErrorfrom 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.pynew file mode 100644index 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.pyindex 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.pynew file mode 100644index 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.pyindex 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 Iterablefrom dataclasses import dataclassfrom 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.pynew file mode 100644index 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: strdiff --git a/src/free_claude_code/runtime/bootstrap.py b/src/free_claude_code/runtime/bootstrap.pyindex 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 CodexHarnessFactoryfrom .codex_catalog import CodexModelCatalogPublisherfrom .configuration import ConfigurationServicefrom .provider_manager import ProviderRuntimeManager+from .web_tools.client import HTTPWebToolsClientdef 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__.pynew file mode 100644index 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.pynew file mode 100644index 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.pysimilarity index 100%rename from src/free_claude_code/api/web_tools/constants.pyrename to src/free_claude_code/runtime/web_tools/constants.pydiff --git a/src/free_claude_code/api/web_tools/egress.py b/src/free_claude_code/runtime/web_tools/egress.pysimilarity index 80%rename from src/free_claude_code/api/web_tools/egress.pyrename to src/free_claude_code/runtime/web_tools/egress.pyindex 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 ipaddressimport socket-from dataclasses import dataclassfrom 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 DNSserver 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.pysimilarity index 68%rename from src/free_claude_code/api/web_tools/parsers.pyrename to src/free_claude_code/runtime/web_tools/parsers.pyindex 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 refrom html.parser import HTMLParserfrom 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 = Noneself._title_parts: list[str] = []@@ -37,8 +38,10 @@ class SearchResultParser(HTMLParser):if tag != "a" or self._href is None:returntitle = " ".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 = Noneself._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.pyindex 9cd7594f..ff7494da 100644--- a/tests/api/support.py+++ b/tests/api/support.py@@ -17,6 +17,7 @@ from free_claude_code.providers.runtime import ProviderRuntimefrom free_claude_code.runtime.application import ApplicationRuntime, RestartCallbackfrom free_claude_code.runtime.configuration import ConfigurationServicefrom free_claude_code.runtime.provider_manager import ProviderRuntimeManager+from tests.web_tools_support import StubWebToolsClientclass 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.pyindex 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_eventfrom free_claude_code.core.failures import ExecutionFailure, FailureKindfrom free_claude_code.core.openai_responses import OpenAIResponsesRequestfrom 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_hintasync 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_executioNone):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.pyindex 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 ReasoningCapabilityfrom free_claude_code.providers.open_router import OpenRouterProviderfrom tests.providers.support import immediate_admission, make_provider_config+from tests.web_tools_support import StubWebToolsClientclass 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.pyindex 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 MessagesRequestfrom free_claude_code.core.anthropic.streaming import format_sse_eventfrom free_claude_code.core.openai_responses import OpenAIResponsesRequestfrom free_claude_code.core.reasoning import ReasoningPolicy+from tests.web_tools_support import StubWebToolsClientdef _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.pyindex 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 ApiServicesfrom free_claude_code.application.ports import StopResultfrom free_claude_code.config.settings import Settingsfrom 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.pyindex 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 executionfrom free_claude_code.config.settings import Settingsfrom free_claude_code.core.anthropic import AnthropicStreamLedgerfrom 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_streamservice = 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_streamservice = 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_temock_provider.stream_messages = stream_boomservice = 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_codemock_provider.stream_messages = stream_boomservice = 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.pyindex 6db6b149..8abb0310 100644--- a/tests/api/test_web_server_tools.py+++ b/tests/api/test_web_server_tools.py@@ -1,6 +1,7 @@import asyncioimport json-from collections.abc import AsyncIterator, Mapping+import socket+from collections.abc import AsyncGenerator, AsyncIterator, Mappingfrom typing import Anyfrom unittest.mock import AsyncMock, MagicMock, patch@@ -8,27 +9,10 @@ import httpximport pytestfrom 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_constantsfrom 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_responsefrom free_claude_code.application.errors import InvalidRequestError+from free_claude_code.application.execution import ProviderExecutorfrom free_claude_code.application.model_metadata import ProviderModelInfofrom 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 WebToolServicefrom free_claude_code.config.provider_catalog import PROVIDER_CATALOGfrom free_claude_code.config.reasoning import ReasoningPreferencefrom free_claude_code.config.settings import Settings@@ -55,7 +50,16 @@ from free_claude_code.core.failures import ExecutionFailure, FailureKindfrom free_claude_code.core.openai_responses import OpenAIResponsesRequestfrom free_claude_code.core.reasoning import ReasoningPolicyfrom free_claude_code.core.version import package_version+from free_claude_code.core.web_tools import WebFetchResult, WebSearchResultfrom 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_disabledsettings,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_jsonfailure_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.asyncioasync 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.asyncioasync 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.asyncioasync 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(monkeypatcsettings,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(monkeyparaw = "".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.asyncioasync 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.asyncioasync 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 Nonediff --git a/tests/application/test_web_tools.py b/tests/application/test_web_tools.pynew file mode 100644index 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.pyindex 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 ApplicationRuntimefrom free_claude_code.runtime.asgi import RuntimeASGIAppfrom free_claude_code.runtime.configuration import ConfigurationServicefrom 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.pyindex 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.pynew file mode 100644index 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.pyindex 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 ApplicationRuntimefrom free_claude_code.runtime.codex_catalog import CodexModelCatalogPublisherfrom free_claude_code.runtime.configuration import ConfigurationServicefrom free_claude_code.runtime.provider_manager import ProviderRuntimeManager+from tests.web_tools_support import StubWebToolsClientdef _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.pynew file mode 100644index 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.pynew file mode 100644index 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.lockindex 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" },