coderio 0.4.0__py3-none-any.whl

coderio/tools/permission.py

@@ -0,0 +1,214 @@
+from __future__ import annotations
+
+from enum import StrEnum
+from typing import Any, Callable
+
+from coderio.tools.base import DESTRUCTIVE_TOOLS, FILE_EDIT_TOOLS
+
+# Heuristic keywords for classifying MCP tool risk by NAME. MCP tools arrive
+# with server-prefixed names (e.g. "filesystem_write_file", "github_create_pr")
+# that PermissionGate's DESTRUCTIVE_TOOLS set doesn't recognize — without this
+# classification, a PLAN-mode agent could freely call an MCP server's write/exec
+# tools because they fall through to the "not in DESTRUCTIVE_TOOLS → allow" path.
+#
+# This is a NAME-HEURISTIC, not a capability check: a server could expose a
+# destructive tool under a benign name. The goal is to catch the obvious cases
+# (write/create/delete/execute in the tool name) so the tier gate engages, same
+# as for coderio's built-in tools. False negatives are possible; false positives
+# only trigger a confirm prompt (safe direction).
+_MCP_DESTRUCTIVE_KEYWORDS = frozenset(
+    {
+        "write",
+        "create",
+        "delete",
+        "remove",
+        "execute",
+        "exec",
+        "run",
+        "shell",
+        "fetch",  # network egress
+        "request",
+        "post",  # HTTP POST
+        "put",  # HTTP PUT
+        "patch",  # HTTP PATCH
+    }
+)
+
+# Built-in tool names that CONTAIN a destructive keyword but must NOT be
+# classified destructive by the heuristic — they're handled explicitly by the
+# mode logic (or are read-only despite the name). Without this exclusion,
+# write_todos (deepagents' planning tool) would match "write" and be blocked in
+# PLAN mode, preventing the agent from ever creating a todo list.
+_HEURISTIC_EXCLUDE = frozenset({"write_todos"})
+
+
+def _is_mcp_destructive(tool_name: str) -> bool:
+    """Heuristic: does this tool name suggest a destructive/network action?
+
+    Used for MCP tools whose names aren't in the static DESTRUCTIVE_TOOLS set.
+    Matches any keyword as a substring (case-insensitive) — "filesystem_write",
+    "github_create_pr", "db_delete_row" all match.
+
+    Excludes built-in names in _HEURISTIC_EXCLUDE that happen to contain a
+    keyword but have their own explicit handling (e.g. write_todos is a
+    planning tool, not a file write).
+    """
+    if tool_name in _HEURISTIC_EXCLUDE:
+        return False
+    lower = tool_name.lower()
+    return any(kw in lower for kw in _MCP_DESTRUCTIVE_KEYWORDS)
+
+
+class PermissionMode(StrEnum):
+    """Four permission levels (industry-standard tiered access).
+
+    StrEnum so members ARE strings (== works with raw str), but invalid values
+    raise ValueError at construction — catching config typos early.
+
+    Levels (least → most permissive):
+      PLAN      — read-only, blocks ALL writes/shell (safe exploration)
+      CONFIRM   — prompts before each destructive action
+      AUTO_EDIT — auto-allow file edits, but shell/web/note still need confirm
+      FULL      — auto-allow everything (no prompts)
+
+    Backward compat: the old "auto" string maps to FULL via normalize().
+
+    Security model: file path isolation is handled by deepagents' backend
+    virtual_mode (not by WorkspacePolicy — which was deleted because it
+    couldn't handle virtual paths). Permission gates only control WHICH tools
+    may execute, not WHERE they can write.
+    """
+
+    PLAN = "plan"
+    CONFIRM = "confirm"
+    AUTO_EDIT = "auto_edit"
+    FULL = "full"
+
+    @classmethod
+    def normalize(cls, raw: str) -> "PermissionMode":
+        """Map a raw config string to a PermissionMode, with backward compat.
+
+        Old configs may have permission_mode = "auto" (the pre-v0.2 name for
+        FULL). This silently upgrades it so users don't get a ValueError on
+        existing configs.
+        """
+        if raw == "auto":
+            return cls.FULL
+        return cls(raw)
+
+
+class PermissionGate:
+    """Permission gate based on tool type + mode (no path checking).
+
+    Path isolation is delegated to deepagents' backend virtual_mode, which
+    maps virtual paths (e.g. /foo.py) to the workspace root and enforces
+    that all file operations stay inside it. This gate only decides whether
+    a tool TYPE is allowed in the current MODE — it does NOT inspect paths.
+    """
+
+    def __init__(self, mode: str, auto_allow_execute: bool = False):
+        """Initialize the gate.
+
+        Args:
+            mode: permission tier (plan/confirm/auto_edit/full).
+            auto_allow_execute: when True, the ``execute`` (shell) tool is
+                auto-allowed in CONFIRM/AUTO_EDIT modes without prompting —
+                this is the "sandbox 消除问题" design from Claude Code
+                (``autoAllowBashIfSandboxed``). Intended for use when
+                ``sandbox_mode != "off"``: the sandbox provides the real
+                isolation boundary, so the per-command prompt becomes noise.
+                PLAN mode is unaffected (always read-only — sandbox doesn't
+                change that semantics). The command blacklist still applies
+                (via CommandReviewMiddleware, which runs after this gate).
+        """
+        self._mode = PermissionMode.normalize(mode)
+        self._auto_allow_execute = auto_allow_execute
+
+    @property
+    def mode(self) -> str:
+        return self._mode
+
+    @property
+    def auto_allow_execute(self) -> bool:
+        return self._auto_allow_execute
+
+    def check(self, tool_name: str, args: dict[str, Any]) -> bool | str:
+        # note tool: only WRITE/APPEND/DELETE are destructive. read/list are
+        # read-only and shouldn't prompt (same as read_file/ls).
+        if tool_name == "note":
+            action = str(args.get("action", "")).lower()
+            if action in ("read", "list"):
+                return True
+        if tool_name in DESTRUCTIVE_TOOLS:
+            pass  # fall through to mode-based decision below
+        elif _is_mcp_destructive(tool_name):
+            # MCP tool with a destructive-sounding name (write/create/delete/execute/...).
+            # Treat it like a built-in destructive tool so the tier gate engages.
+            # This prevents a PLAN-mode agent from calling an MCP server's write
+            # tool just because "filesystem_write_file" isn't in DESTRUCTIVE_TOOLS.
+            pass
+        else:
+            # Read-only tool (built-in or MCP) — allow regardless of mode.
+            return True
+        # FULL: auto-allow everything.
+        if self._mode == PermissionMode.FULL:
+            return True
+        # auto_allow_execute: the "sandbox 消除问题" path. When a sandbox is
+        # active, the OS provides the real isolation boundary, so prompting
+        # the user for every shell command becomes noise. Skip the prompt for
+        # the execute tool specifically. PLAN mode is excluded — PLAN is always
+        # read-only, and sandbox doesn't change that contract.
+        if tool_name == "execute" and self._auto_allow_execute and self._mode != PermissionMode.PLAN:
+            return True
+        # AUTO_EDIT: auto-allow file edits, shell/web/note still confirm.
+        # MCP destructive tools always confirm in AUTO_EDIT (we can't reliably
+        # tell an MCP write from an MCP execute, so be conservative).
+        if self._mode == PermissionMode.AUTO_EDIT:
+            if tool_name in FILE_EDIT_TOOLS:
+                return True
+            return self._ask(tool_name, args)
+        if self._mode == PermissionMode.PLAN:
+            return False
+        # CONFIRM: prompt for all destructive tools.
+        return self._ask(tool_name, args)
+
+    def _ask(self, tool_name: str, args: dict[str, Any]) -> bool | str:
+        raise NotImplementedError
+
+
+def _default_prompt(tool_name: str, args) -> bool:
+    """Console prompt used when no custom prompter is supplied."""
+    confirm = input(f"Allow {tool_name}({args})? [y/N] ").strip().lower()
+    return confirm in {"yes", "y"}
+
+
+class RichPromptPermissionGate(PermissionGate):
+    """Concrete confirm-mode gate using a Rich console.
+
+    `prompt_fn` is injectable so tests can answer without a real TTY.
+    """
+
+    def __init__(
+        self,
+        console=None,
+        prompt_fn: Callable[[str, dict[str, Any]], bool] | None = None,
+        auto_allow_execute: bool = False,
+    ):
+        super().__init__(PermissionMode.CONFIRM, auto_allow_execute=auto_allow_execute)
+        self._console = console
+        self._prompt_fn = prompt_fn or _default_prompt
+
+    def _ask(self, tool_name: str, args: dict[str, Any]) -> bool:
+        if self._console:
+            self._console.print(f"[yellow]permission:[/yellow] {tool_name}({args})")
+        return self._prompt_fn(tool_name, args)
+
+
+class AutoPermissionGate(PermissionGate):
+    """Auto-approve everything (FULL mode). For tests / explicit trust."""
+
+    def __init__(self):
+        super().__init__(PermissionMode.FULL)
+
+    def _ask(self, tool_name: str, args: dict[str, Any]) -> bool:
+        return True

coderio/tools/read_file.py

@@ -0,0 +1,51 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+from pydantic import BaseModel, Field
+
+
+class ReadFileArgs(BaseModel):
+    path: str = Field(
+        description="Path to the file. Relative paths resolve from the project root (cwd), "
+        "NOT from the file's own directory. If unsure of the exact path, use glob or "
+        "grep to locate it first."
+    )
+    offset: int = Field(default=0, description="1-based first line number to show (0=start).")
+    limit: int = Field(default=2000, description="Maximum number of lines to return.")
+
+
+class ReadFileTool:
+    name = "read_file"
+    description = (
+        "Read a file from the local filesystem. Returns content with line numbers "
+        "(cat -n style). Supports offset and limit.\n\n"
+        "PATH RESOLUTION: relative paths resolve from the project root (cwd), not from "
+        "the file's own directory. For example, if you saw 'store.py' under 'session/' "
+        "in list_dir('src/coderio'), the correct path is 'src/coderio/session/store.py', "
+        "NOT 'session/store.py'. When a read returns 'file not found', use glob to find "
+        "the actual location: glob('**/store.py')."
+    )
+    args_schema = ReadFileArgs
+
+    def run(self, path: str, offset: int = 0, limit: int = 2000) -> str:
+        p = Path(path)
+        if not p.exists():
+            return f"Error: file not found: {path}"
+        if p.is_dir():
+            return f"Error: path is a directory: {path}"
+        try:
+            text = p.read_text(encoding="utf-8", errors="replace")
+        except OSError as e:
+            return f"Error reading file: {e}"
+        lines = text.splitlines()
+        if offset > 0:
+            start_idx = max(0, offset - 1)
+        else:
+            start_idx = 0
+        if limit:
+            end_idx = start_idx + limit
+        else:
+            end_idx = len(lines)
+        numbered = [f"{i}\t{line}" for i, line in enumerate(lines[start_idx:end_idx], start_idx + 1)]
+        return "\n".join(numbered)

coderio/tools/sandbox_runner.py

@@ -0,0 +1,113 @@
+"""Cross-platform sandbox dispatcher.
+
+Selects the appropriate OS-level sandbox based on platform + mode:
+  - Windows: win_sandbox.py (Restricted Token + Job Object)
+  - Linux:   linux_sandbox.py (bubblewrap)
+  - macOS:   linux_sandbox.py fallback (bubblewrap if available, else off)
+
+Modes (match config ToolsConfig.sandbox_mode):
+  - "off":   no sandbox — caller should use plain subprocess (we return -1
+             so the caller falls back to its own subprocess path).
+  - "job":   Windows Job Object (resource limits + process-tree kill only).
+             On Linux, equivalent to plain run (POSIX process groups already
+             provide reliable kill; resource limits need cgroups — future work).
+  - "write": Windows Restricted Token (file-write isolation). On Linux,
+             bubblewrap (read-only /, write to workspace only).
+
+This module is the single import point for the shell backend — it keeps the
+platform branching out of deep_loop.py so the backend stays readable.
+"""
+
+from __future__ import annotations
+
+import logging
+import sys
+
+_log = logging.getLogger(__name__)
+
+
+def run_with_sandbox(
+    command: str,
+    cwd: str,
+    *,
+    mode: str = "job",
+    timeout: int = 120,
+    env: dict | None = None,
+    max_output_bytes: int = 100_000,
+    network_allowed: bool = True,
+    fs_config=None,
+) -> tuple[int, str]:
+    """Run a command with the requested sandbox mode.
+
+    Returns (exit_code, combined_output). On any sandbox failure, degrades to
+    plain subprocess.run (returns -1 only if even the fallback fails — callers
+    should treat -1 as "retry without sandbox").
+
+    The caller (shell backend's execute) passes mode through from config. If
+    the sandbox isn't available on this platform (e.g. "write" on a Linux
+    without bubblewrap), we log + fall back to subprocess — never block work.
+
+    Args:
+        network_allowed: forwarded to bubblewrap as ``--unshare-net`` when
+            False. REGRESSION GUARD: this was previously not forwarded (the
+            ``run_bwrap`` call omitted it), so ``network_allowed=false`` had
+            zero effect on Linux sandbox mode — a silent security gap.
+        fs_config: optional SandboxFsConfig for filesystem allow/deny lists
+            (bubblewrap only; Windows ignores it — token is a no-op there).
+    """
+    if mode == "off":
+        # Shouldn't reach here (caller checks mode before calling), but handle
+        # it defensively by signalling "use your own subprocess path".
+        return (-1, "sandbox mode is off")
+
+    if sys.platform == "win32":
+        from coderio.tools.win_sandbox import run_sandboxed
+
+        # Windows: fs_config not yet applied (token is no-op; ACL is TODO).
+        return run_sandboxed(command, cwd, timeout=timeout, env=env, max_output_bytes=max_output_bytes)
+
+    # POSIX: try bubblewrap (linux_sandbox module) for "write" mode; for "job"
+    # mode there's no POSIX equivalent of Job Object resource limits without
+    # cgroups, so we fall through to plain subprocess (with start_new_session
+    # for at least reliable process-group kill).
+    if mode == "write":
+        try:
+            from coderio.tools.linux_sandbox import bwrap_available, run_bwrap
+
+            if bwrap_available():
+                return run_bwrap(
+                    command,
+                    cwd,
+                    timeout=timeout,
+                    env=env,
+                    max_output_bytes=max_output_bytes,
+                    network_allowed=network_allowed,
+                    fs_config=fs_config,
+                )
+            _log.warning("sandbox_mode=write but bubblewrap not installed — falling back to plain run")
+        except ImportError:
+            _log.warning("linux_sandbox not available — falling back to plain run")
+
+    # Fallback: plain subprocess with start_new_session (for POSIX process-group kill).
+    import subprocess
+
+    try:
+        kwargs: dict = {"shell": True, "capture_output": True, "cwd": cwd, "timeout": timeout, "text": False}
+        if sys.platform != "win32":
+            kwargs["start_new_session"] = True  # own process group → killpg works
+        if env is not None:
+            kwargs["env"] = env
+        kwargs["stdin"] = subprocess.DEVNULL
+        proc = subprocess.run(command, **kwargs)
+        stdout = proc.stdout.decode("utf-8", errors="replace") if proc.stdout else ""
+        stderr = proc.stderr.decode("utf-8", errors="replace") if proc.stderr else ""
+        output = stdout
+        if stderr:
+            output += f"\n[stderr]\n{stderr}"
+        if len(output) > max_output_bytes:
+            output = output[:max_output_bytes] + f"\n\n... Output truncated at {max_output_bytes} bytes."
+        return (proc.returncode, output)
+    except subprocess.TimeoutExpired:
+        return (124, f"Command timed out after {timeout}s")
+    except Exception as e:  # noqa: BLE001
+        return (1, f"Execution error: {e}")

coderio/tools/todo.py

@@ -0,0 +1,71 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from pydantic import BaseModel, Field
+
+
+class TodoArgs(BaseModel):
+    action: str = Field(description="One of: list, add, update, delete.")
+    content: str = Field(default="", description="Todo text (for 'add').")
+    priority: str = Field(default="medium", description="high | medium | low (for 'add').")
+    index: int = Field(default=-1, description="Todo index (for 'update'/'delete').")
+    status: str = Field(default="", description="New status (for 'update').")
+
+
+@dataclass
+class Todo:
+    content: str
+    status: str = "pending"
+    priority: str = "medium"
+
+
+@dataclass
+class TodoStore:
+    todos: list[Todo] = field(default_factory=list)
+
+
+class TodoTool:
+    name = "todo"
+    description = "Manage a task list. actions: list, add, update, delete."
+    args_schema = TodoArgs
+
+    def __init__(self, store: TodoStore):
+        self.store = store
+
+    def run(
+        self,
+        action: str,
+        content: str = "",
+        priority: str = "medium",
+        index: int = -1,
+        status: str = "",
+    ) -> str:
+        if action == "list":
+            if not self.store.todos:
+                return "No todos."
+            lines = []
+            for i, t in enumerate(self.store.todos):
+                if t.status == "completed":
+                    mark = "✓"
+                elif t.status == "in_progress":
+                    mark = "→"
+                else:
+                    mark = " "
+                lines.append(f"[{i}] {mark} ({t.priority}) {t.content}")
+            return "\n".join(lines)
+        elif action == "add":
+            self.store.todos.append(Todo(content=content, priority=priority))
+            return f"Added todo: {content}"
+        elif action == "update":
+            if not (0 <= index < len(self.store.todos)):
+                return f"Error: index {index} out of range"
+            if status:
+                self.store.todos[index].status = status
+            return f"Updated todo {index}"
+        elif action == "delete":
+            if not (0 <= index < len(self.store.todos)):
+                return f"Error: index {index} out of range"
+            self.store.todos.pop(index)
+            return f"Deleted todo {index}"
+        return f"Error: unknown action {action!r}"

coderio/tools/web_fetch.py

@@ -0,0 +1,188 @@
+"""Web fetch tool with SSRF (Server-Side Request Forgery) protection.
+
+SECURITY (2026-08-14 report P0-3): the original implementation did a bare
+``httpx.get(url, follow_redirects=True)`` with no validation. A prompt-injected
+model could point it at:
+
+  - ``http://127.0.0.1:*`` — local services (databases, admin panels)
+  - ``http://169.254.169.254/latest/meta-data/`` — cloud metadata (AWS/GCP/Azure
+    credential exfiltration; this is the classic SSRF payout)
+  - ``http://[::1]``, ``http://10.x.x.x``, ``http://192.168.x.x`` — internal networks
+
+Protections applied here (defense in depth):
+
+1. Scheme allowlist: only ``http`` / ``https`` (blocks ``file://``, ``ftp://``...).
+2. IP-based blocking at CONNECT time: the hostname is resolved and every
+   resolved address is checked against private / loopback / link-local /
+   reserved ranges BEFORE the request is sent. DNS-rebinding is mitigated by
+   checking at connect time via a custom transport, not just at parse time.
+3. Redirect policy: redirects are followed MANUALLY (max 3 hops), and each hop's
+   URL goes through the same validation. ``follow_redirects=False`` on the
+   client — an allowlisted URL redirecting to 169.254.169.254 is still blocked.
+4. Response size cap: stream up to 1 MB, not ``resp.text`` unbounded into memory.
+5. Content-Type sniff: binary payloads are rejected early.
+
+This is prompt-injection defense, not a hard boundary — a determined attacker
+with a DNS name that resolves to a public-but-malicious host still gets
+fetched. The goal is to close the internal-network/metadata-exfiltration
+class, which is the realistic damage path for a local coding agent.
+"""
+
+from __future__ import annotations
+
+import ipaddress
+import re
+import socket
+
+import httpx
+from pydantic import BaseModel, Field
+
+_TAG_RE = re.compile(r"<[^>]+>")
+_WS_RE = re.compile(r"\s+")
+
+_MAX_RESPONSE_BYTES = 1_000_000  # 1 MB cap — resp.text unbounded was an OOM vector
+_MAX_REDIRECTS = 3
+
+_SSRF_ERROR_TEMPLATE = (
+    "Error fetching {url}: blocked by SSRF protection — {reason}. "
+    "coderio's web_fetch may only reach public internet hosts over http/https; "
+    "private networks, loopback, and link-local addresses (including cloud "
+    "metadata services) are not fetchable."
+)
+
+
+def _extract_text(html: str) -> str:
+    for tag in ("article", "main", "body"):
+        m = re.search(f"<{tag}[^>]*>(.*?)</{tag}>", html, re.DOTALL | re.IGNORECASE)
+        if m:
+            html = m.group(1)
+            break
+    text = _TAG_RE.sub(" ", html)
+    return _WS_RE.sub(" ", text).strip()
+
+
+def _is_blocked_address(ip: ipaddress.IPv4Address | ipaddress.IPv6Address) -> str | None:
+    """Return a human-readable reason if the address must not be fetched, else None."""
+    if ip.is_loopback:
+        return f"loopback address {ip} is not allowed"
+    if ip.is_private:
+        return f"private address {ip} is not allowed"
+    if ip.is_link_local:
+        return f"link-local address {ip} is not allowed (cloud metadata lives here)"
+    if ip.is_reserved or ip.is_unspecified or ip.is_multicast:
+        return f"reserved address {ip} is not allowed"
+    return None
+
+
+def _validate_url_host(url: str) -> str | None:
+    """Validate scheme + resolved host addresses. Returns an error reason or None.
+
+    Resolution happens HERE (per request / per redirect hop), so a DNS name
+    that flips to an internal IP between checks is still caught.
+    """
+    try:
+        parsed = httpx.URL(url)
+    except Exception as e:  # noqa: BLE001 — malformed URL is a user error, not a crash
+        return f"invalid URL: {e}"
+
+    if parsed.scheme not in ("http", "https"):
+        return f"scheme {parsed.scheme!r} is not allowed (only http/https)"
+
+    host = parsed.host
+    if not host:
+        return "URL has no host"
+
+    # Bracketed IPv6 literal: httpx.URL.host strips the brackets.
+    try:
+        # Try to parse the host as a literal IP first (fast path, no DNS).
+        addr = ipaddress.ip_address(host)
+        return _is_blocked_address(addr)
+    except ValueError:
+        pass  # Not an IP literal — resolve as a hostname below.
+
+    try:
+        infos = socket.getaddrinfo(host, None)
+    except socket.gaierror as e:
+        return f"DNS resolution failed: {e}"
+
+    for info in infos:
+        sockaddr = info[4]
+        ip_str = sockaddr[0]
+        try:
+            addr = ipaddress.ip_address(ip_str)
+        except ValueError:
+            continue
+        reason = _is_blocked_address(addr)
+        if reason:
+            return reason
+    return None
+
+
+class WebFetchArgs(BaseModel):
+    url: str = Field(description="URL to fetch (public internet, http/https only).")
+    timeout: int = Field(default=20, description="Request timeout in seconds.")
+
+
+class WebFetchTool:
+    name = "web_fetch"
+    description = (
+        "Fetch a public-internet URL and return extracted text content. "
+        "Private/loopback/link-local addresses are blocked (SSRF protection). "
+        "Requires permission."
+    )
+    args_schema = WebFetchArgs
+
+    def run(self, url: str, timeout: int = 20) -> str:
+        # Validate the initial URL before any request is made.
+        reason = _validate_url_host(url)
+        if reason:
+            return _SSRF_ERROR_TEMPLATE.format(url=url, reason=reason)
+
+        # follow_redirects=False — we hop manually so EACH redirect target
+        # passes validation. A public URL redirecting to 169.254.169.254
+        # (the metadata-service exfil pattern) is caught at the hop.
+        try:
+            with httpx.Client(
+                timeout=timeout,
+                follow_redirects=False,
+                headers={"User-Agent": "coderio/0.1"},
+            ) as client:
+                current_url = url
+                for _hop in range(_MAX_REDIRECTS + 1):
+                    resp = client.get(current_url)
+                    if resp.is_redirect:
+                        # Validate the redirect target with the same rules.
+                        next_url = str(resp.headers.get("location", ""))
+                        if not next_url:
+                            return f"Error fetching {url}: redirect without Location header"
+                        # Relative redirect — resolve against the current URL.
+                        next_url = str(httpx.URL(current_url).join(next_url))
+                        reason = _validate_url_host(next_url)
+                        if reason:
+                            return _SSRF_ERROR_TEMPLATE.format(url=next_url, reason=reason)
+                        current_url = next_url
+                        continue
+                    resp.raise_for_status()
+
+                    # Binary sniff: reading a 1MB of gzip'd binary as text is
+                    # useless to the model and wastes the context budget.
+                    ctype = resp.headers.get("content-type", "").lower()
+                    if any(
+                        t in ctype
+                        for t in ("image/", "audio/", "video/", "application/octet-stream", "application/pdf")
+                    ):
+                        return f"Error fetching {url}: unsupported content type {ctype!r} (text/HTML only)"
+
+                    # Size cap via streamed read (Content-Length may lie/absent).
+                    chunks: list[bytes] = []
+                    total = 0
+                    for chunk in resp.iter_bytes():
+                        chunks.append(chunk)
+                        total += len(chunk)
+                        if total > _MAX_RESPONSE_BYTES:
+                            break
+                    body = b"".join(chunks)[:_MAX_RESPONSE_BYTES]
+                    return _extract_text(body.decode("utf-8", errors="replace"))[:8000]
+                return f"Error fetching {url}: too many redirects (max {_MAX_REDIRECTS})"
+        except Exception as e:  # noqa: BLE001 — surface fetch errors to the model
+            return f"Error fetching {url}: {e}"