minimalcode 1.5.2__py3-none-any.whl

minimalcode/highlight/palette.py

@@ -0,0 +1,73 @@
+"""ANSI palettes and low-level color helpers."""
+
+from __future__ import annotations
+
+import re
+
+RESET = "\x1b[0m"
+ACTIVITY_TAG = "\x1b[38;5;114m"
+
+# Both palettes expose the same keys so renderers never branch on the theme.
+_PALETTES = {
+    "dark": {
+        "h1": "\x1b[1;38;5;51m",
+        "h2": "\x1b[1;38;5;45m",
+        "h3": "\x1b[1;38;5;48m",
+        "h4": "\x1b[1;38;5;111m",
+        "h5": "\x1b[1;38;5;249m",
+        "h6": "\x1b[2;38;5;245m",
+        "rule": "\x1b[38;5;238m",
+        "bold": "\x1b[1;38;5;229m",
+        "italic": "\x1b[3;38;5;250m",
+        "strike": "\x1b[9;38;5;245m",
+        "inline_code": "\x1b[38;5;222;48;5;236m",
+        "code_comment": "\x1b[3;38;5;244m",
+        "code_string": "\x1b[38;5;186m",
+        "code_number": "\x1b[38;5;141m",
+        "code_keyword": "\x1b[38;5;197m",
+        "code_name": "\x1b[38;5;81m",
+        "code_variable": "\x1b[38;5;114m",
+        "bullet": "\x1b[38;5;214m",
+        "quote": "\x1b[38;5;244m",
+        "link": "\x1b[4;38;5;75m",
+        "url": "\x1b[38;5;242m",
+    },
+    "light": {
+        "h1": "\x1b[1;38;5;25m",
+        "h2": "\x1b[1;38;5;24m",
+        "h3": "\x1b[1;38;5;29m",
+        "h4": "\x1b[1;38;5;55m",
+        "h5": "\x1b[1;38;5;238m",
+        "h6": "\x1b[2;38;5;240m",
+        "rule": "\x1b[38;5;250m",
+        "bold": "\x1b[1;38;5;130m",
+        "italic": "\x1b[3;38;5;238m",
+        "strike": "\x1b[9;38;5;240m",
+        "inline_code": "\x1b[38;5;166;48;5;254m",
+        "code_comment": "\x1b[3;38;5;244m",
+        "code_string": "\x1b[38;5;130m",
+        "code_number": "\x1b[38;5;91m",
+        "code_keyword": "\x1b[38;5;161m",
+        "code_name": "\x1b[38;5;25m",
+        "code_variable": "\x1b[38;5;28m",
+        "bullet": "\x1b[38;5;166m",
+        "quote": "\x1b[38;5;243m",
+        "link": "\x1b[4;38;5;25m",
+        "url": "\x1b[38;5;242m",
+    },
+}
+
+_ANSI_RE = re.compile(r"\x1b\[[0-9;]*m")
+
+
+def strip_ansi(text: str) -> str:
+    """Return text without SGR color sequences."""
+    # Only SGR (``ESC[...m``) is removed, because that is all this renderer writes;
+    # arbitrary control sequences from model or shell output are handled by
+    # ``terminal sanitization`` instead.
+    return _ANSI_RE.sub("", text)
+
+
+def _styled(text: str, style: str) -> str:
+    """Wrap ``text`` in an SGR style and the reset sequence."""
+    return f"{style}{text}{RESET}"

minimalcode/highlight/sanitize.py

@@ -0,0 +1,175 @@
+"""Terminal control-sequence sanitization for untrusted streamed text."""
+
+from __future__ import annotations
+
+# Cap on the held tail. A real escape sequence is a few bytes, so anything larger
+# means the stream opened a sequence that never terminated; dropping it keeps a
+# hostile or broken stream from growing the buffer for the rest of the reply.
+_CONTROL_PENDING_LIMIT = 64_000
+
+
+def _csi_length(data: str, start: int) -> int | None:
+    """Return the length of a CSI sequence beginning at ``start``."""
+    index = start + 2
+    while index < len(data):
+        code = ord(data[index])
+        if 0x40 <= code <= 0x7E:
+            return index + 1 - start
+        if not 0x20 <= code <= 0x3F:
+            # Malformed CSI: consume only the ESC and '['.
+            return 2
+        index += 1
+    return None
+
+
+def _c1_csi_length(data: str, start: int) -> int | None:
+    """Return the length of a single-byte C1 CSI (0x9B) sequence."""
+    index = start + 1
+    while index < len(data):
+        code = ord(data[index])
+        if 0x40 <= code <= 0x7E:
+            return index + 1 - start
+        if not 0x20 <= code <= 0x3F:
+            return 1
+        index += 1
+    return None
+
+
+def _string_sequence_length(data: str, start: int, sequence_start: int) -> int | None:
+    """Return the length of an OSC/DCS-style string sequence."""
+    index = start
+    while index < len(data):
+        # OSC/DCS strings end with BEL (xterm) or ST (``ESC \``); both forms appear
+        # in the wild, so either terminates the sequence.
+        if data[index] == "\x07" or data[index] == "\x9c":
+            # BEL (xterm), ST (``ESC \``), and the single-byte C1 ST all
+            # terminate an OSC/DCS-style string.
+            return index + 1 - sequence_start
+        if data[index] == "\x1b":
+            if index + 1 >= len(data):
+                # A trailing ESC may be the first half of ST; hold the sequence.
+                return None
+            if data[index + 1] == "\\":
+                return index + 2 - sequence_start
+        index += 1
+    return None
+
+
+class TerminalSanitizer:
+    """Strip terminal control sequences before writing untrusted text.
+
+    Model output and shell output are untrusted, but they still reach a real
+    terminal. Keep newlines and tabs, drop every other C0/C1 control character,
+    and remove complete or partially streamed escape sequences. Splitting the
+    state across ``feed`` calls also covers sequences cut between stream deltas.
+    """
+
+    def __init__(self) -> None:
+        self._pending = ""
+
+    @staticmethod
+    def _escape_length(data: str, start: int) -> int | None:
+        if start + 1 >= len(data):
+            return None
+        marker = data[start + 1]
+        if marker == "[":
+            return _csi_length(data, start)
+        if marker == "]":
+            return _string_sequence_length(data, start + 2, start)
+        if marker in "PX^_":
+            # DCS (P), SOS (X), PM (^), and APC (_) all use the same
+            # terminator-terminated body as OSC.
+            return _string_sequence_length(data, start + 2, start)
+        # Anything else is a two-byte escape (``ESC 7``, ``ESC c``). Two is returned
+        # rather than one so the parameter byte is consumed too; leaving it would
+        # print a stray character where the sequence used to be. A control byte
+        # after ESC cannot be a two-byte final, so only the ESC is removed —
+        # otherwise an isolated ESC before a newline would join two lines.
+        code = ord(marker)
+        if 0x20 <= code <= 0x2F:
+            # ``ESC`` plus intermediate bytes runs up to a final byte in
+            # 0x30-0x7E (``ESC ( B`` from `tput sgr0`). Consuming only the
+            # intermediate byte printed that final byte as ordinary text.
+            index = start + 1
+            while index < len(data):
+                current = ord(data[index])
+                if 0x20 <= current <= 0x2F:
+                    index += 1
+                    continue
+                if 0x30 <= current <= 0x7E:
+                    return index + 1 - start
+                # A control byte cannot be a final byte: drop the prefix only.
+                return index - start
+            return None
+        return 2 if 0x20 <= code <= 0x7E else 1
+
+    def feed(self, text: str) -> str:
+        """Consume a delta and return the safe text that is complete so far."""
+        if not text:
+            return ""
+        data = self._pending + text
+        self._pending = ""
+        rendered: list[str] = []
+        index = 0
+        while index < len(data):
+            char = data[index]
+            if char == "\x1b":
+                length = self._escape_length(data, index)
+                if length is None:
+                    # Hold an incomplete escape until the next delta.
+                    self._pending = data[index:]
+                    break
+                index += length
+                continue
+            if char == "\r":
+                if index + 1 >= len(data):
+                    self._pending = "\r"
+                    break
+                if data[index + 1] == "\n":
+                    rendered.append("\r\n")
+                    index += 2
+                else:
+                    # A lone CR would move the cursor; drop it.
+                    index += 1
+                continue
+            code = ord(char)
+            if char in "\n\t":
+                rendered.append(char)
+            elif code < 0x20 or code == 0x7F:
+                pass
+            elif 0x80 <= code <= 0x9F:
+                # Single-byte C1 controls include complete CSI/OSC/DCS
+                # sequences. Dropping only the lead byte printed their payload
+                # as ordinary text, so consume the whole sequence.
+                if code == 0x9B:
+                    length = _c1_csi_length(data, index)
+                    if length is None:
+                        self._pending = data[index:]
+                        break
+                    index += length
+                    continue
+                if code in {0x90, 0x98, 0x9D, 0x9E, 0x9F}:
+                    length = _string_sequence_length(data, index + 1, index)
+                    if length is None:
+                        self._pending = data[index:]
+                        break
+                    index += length
+                    continue
+            else:
+                rendered.append(char)
+            index += 1
+        if len(self._pending) > _CONTROL_PENDING_LIMIT:
+            # A hostile stream must not grow the pending buffer without bound.
+            self._pending = ""
+        return "".join(rendered)
+
+    def finish(self) -> str:
+        """Discard a trailing lone CR or unterminated escape sequence."""
+        self._pending = ""
+        return ""
+
+
+def sanitize_terminal_text(text: str) -> str:
+    """Return ``text`` with all terminal escape/control sequences removed."""
+    sanitizer = TerminalSanitizer()
+    return sanitizer.feed(text) + sanitizer.finish()

minimalcode/highlight/thinking.py

@@ -0,0 +1,71 @@
+"""Render streamed reasoning text in the Markdown six-level heading style."""
+
+from __future__ import annotations
+
+from typing import TextIO
+
+from . import color
+from .palette import _PALETTES, _styled
+from .sanitize import TerminalSanitizer
+
+
+def _detect_color(stream: TextIO) -> bool:
+    """Delegate to the color module so a single patch target stays effective."""
+    return color._supports_color(stream)
+
+
+class ThinkingRenderer:
+    """Write reasoning deltas the way a ``######`` heading is styled.
+
+    Reasoning text is not Markdown, so it does not go through the parser: each
+    delta is sanitized and wrapped in the palette's ``h6`` sequence as one block.
+    Nothing is written when the stream cannot take ANSI, which keeps redirected
+    output and ``--json`` equal to the answer alone.
+    """
+
+    def __init__(
+        self,
+        stream: TextIO,
+        *,
+        theme: str = "dark",
+        color: bool | None = None,
+    ) -> None:
+        self.stream = stream
+        self.style = _PALETTES.get(theme, _PALETTES["dark"])["h6"]
+        self.enabled = _detect_color(stream) if color is None else color
+        self._sanitizer = TerminalSanitizer()
+        self._last_char = ""
+        self._open = False
+
+    def feed(self, delta: str) -> None:
+        """Write one reasoning delta in the heading style."""
+        if not self.enabled:
+            return
+        text = self._sanitizer.feed(delta)
+        if not text:
+            return
+        self.stream.write(_styled(text, self.style))
+        self.stream.flush()
+        self._last_char = text[-1]
+        self._open = True
+
+    def finish(self) -> bool:
+        """Close the reasoning block so the answer starts on its own line.
+
+        Returns True when a newline was written to the shared stream, so a
+        Markdown renderer drawing after this one can resynchronize its line
+        state.
+        """
+        # Reset even when no complete delta was written: a block whose entire
+        # content is still held as an incomplete escape sequence must not poison
+        # the next reasoning block with that pending state.
+        self._sanitizer.finish()
+        wrote_newline = False
+        if self.enabled and self._open and self._last_char != "\n":
+            self.stream.write("\n")
+            self.stream.flush()
+            wrote_newline = True
+        self._sanitizer = TerminalSanitizer()
+        self._last_char = ""
+        self._open = False
+        return wrote_newline

minimalcode/httpclient.py

@@ -0,0 +1,278 @@
+"""Shared HTTP client construction and connection-retry policy.
+
+The provider, web, and vision clients all speak HTTP to a configured endpoint,
+so they share two decisions: which proxy settings apply, and how a request that
+never produced a response is retried. Both used to be copied per client, which
+is how a proxy bug could exist in one copy and not the others.
+"""
+
+from __future__ import annotations
+
+import ipaddress
+import math
+import time
+from typing import Any
+from urllib.parse import urlsplit, urlunsplit
+
+import httpx2
+
+from . import __version__
+from .errors import ToolError
+
+# A request that never produced a response is safe to repeat: the provider did
+# not start a billable generation, so a dropped keep-alive or a proxy reset is
+# worth retrying. Failures after streaming starts are handled by the callers and
+# are never retried, because the answer may already have been shown or billed.
+CONNECTION_ATTEMPTS = 11  # the first try plus 10 retries
+CONNECTION_BACKOFF_SECONDS = 0.5
+CONNECTION_BACKOFF_CAP_SECONDS = 8.0
+RETRYABLE_CONNECTION_ERRORS = (
+    httpx2.ConnectError,
+    httpx2.ConnectTimeout,
+    httpx2.RemoteProtocolError,
+)
+
+
+def connection_backoff(attempt: int) -> float:
+    """Return capped exponential backoff for a zero-based retry attempt."""
+    delay = CONNECTION_BACKOFF_SECONDS * (2**attempt)
+    return min(delay, CONNECTION_BACKOFF_CAP_SECONDS)
+
+
+def join_url_path(base_url: str, path: str) -> str:
+    """Append a path segment before any query string or fragment."""
+    parsed = urlsplit(base_url)
+    base_path = parsed.path.rstrip("/")
+    suffix = path.strip("/")
+    joined = f"{base_path}/{suffix}" if suffix else base_path
+    return urlunsplit(
+        (parsed.scheme, parsed.netloc, joined, parsed.query, parsed.fragment)
+    )
+
+
+def is_loopback_url(url: str) -> bool:
+    """Return True when ``url`` targets this machine.
+
+    Environment proxies are routinely configured for remote traffic (Clash on
+    ``127.0.0.1:7897``, corporate MITM proxies, and so on). Sending a request for
+    ``http://127.0.0.1:11434`` to such a proxy cannot work: a stopped local proxy
+    turns every local-provider call into a 502, and a running one has no route to
+    the caller's loopback interface. Loopback endpoints therefore opt out of
+    environment proxies unconditionally, which is also why the network-failure
+    tests no longer depend on the host having no proxy configured.
+    """
+    try:
+        host = urlsplit(url).hostname
+    except ValueError:
+        return False
+    if not host:
+        return False
+    lowered = host.lower().rstrip(".")
+    if lowered == "localhost" or lowered.endswith(".localhost"):
+        return True
+    if lowered == "0.0.0.0":
+        # Connecting to the wildcard address reaches this machine on the
+        # platforms where it is accepted, so a proxy would break it the same
+        # way it breaks 127.0.0.1.
+        return True
+    try:
+        return ipaddress.ip_address(lowered).is_loopback
+    except ValueError:
+        return False
+
+
+def merge_headers(*sources: Any) -> dict[str, Any]:
+    """Merge header mappings left to right, letting later entries win."""
+    merged: dict[str, Any] = {}
+    for source in sources:
+        if isinstance(source, dict):
+            merged.update(source)
+    return merged
+
+
+def build_headers(api_key: str | None, custom: Any) -> dict[str, str]:
+    """Build request headers, honouring a caller-supplied Authorization."""
+    headers = {
+        "Content-Type": "application/json",
+        "User-Agent": f"MinimalCode/{__version__}",
+    }
+    if isinstance(custom, dict):
+        headers.update({str(key): str(value) for key, value in custom.items()})
+    if api_key and not any(key.lower() == "authorization" for key in headers):
+        headers["Authorization"] = f"Bearer {api_key}"
+    return headers
+
+
+def resolve_trust_env(
+    base_url: str,
+    *,
+    transport: httpx2.BaseTransport | None,
+    configured: Any,
+) -> bool:
+    """Decide whether environment proxy settings apply to this client.
+
+    An explicit transport means the caller injected the connection (tests and
+    embedders); proxy mounts would silently shadow it, so they stay off unless
+    asked for. Otherwise loopback targets ignore the environment, and everything
+    else keeps the previous default of honouring it.
+    """
+    if isinstance(configured, bool):
+        return configured
+    if transport is not None:
+        return False
+    return not is_loopback_url(base_url)
+
+
+def build_client(
+    *,
+    base_url: str,
+    headers: dict[str, str],
+    timeout: float,
+    transport: httpx2.BaseTransport | None = None,
+    trust_env: Any = None,
+) -> httpx2.Client:
+    """Build one pooled client with the shared timeout and proxy policy.
+
+    Redirects are never followed automatically for JSON API calls. A 307/308
+    replays the complete request body (conversation, tool output, image data)
+    at the new origin, and httpx2 only strips ``Authorization`` on a cross
+    origin redirect; ``x-api-key`` and custom credential headers survive.
+    Callers surface a 3xx response as a provider error instead.
+    """
+    # The scalar timeout bounds a whole generation; capping the connect phase
+    # keeps an unreachable host from spending that entire budget on a SYN.
+    return httpx2.Client(
+        timeout=httpx2.Timeout(timeout, connect=min(20.0, timeout)),
+        headers=headers,
+        transport=transport,
+        follow_redirects=False,
+        trust_env=resolve_trust_env(
+            base_url, transport=transport, configured=trust_env
+        ),
+    )
+
+
+def post_json(
+    client: httpx2.Client,
+    url: str,
+    payload: dict[str, Any],
+    *,
+    label: str,
+    timeout: float,
+    deadline: float | None = None,
+) -> dict[str, Any]:
+    """POST a JSON body and return the parsed object, retrying connect failures.
+
+    ``deadline`` is an absolute ``time.monotonic()`` value bounding the whole
+    call, including backoff sleeps; it defaults to one ``timeout`` window. Only
+    failures raised before a response arrives are retried.
+    """
+    budget_end = deadline if deadline is not None else time.monotonic() + timeout
+    attempts = 0
+    last_error: httpx2.HTTPError | None = None
+    last_status: int | None = None
+    status_retried = False
+    while attempts < CONNECTION_ATTEMPTS:
+        remaining = budget_end - time.monotonic()
+        if remaining <= 0:
+            break
+        attempts += 1
+        response: httpx2.Response | None = None
+        try:
+            response = client.post(
+                url,
+                json=payload,
+                timeout=httpx2.Timeout(remaining, connect=min(20.0, remaining)),
+            )
+            if response.status_code in {429, 503} and not status_retried:
+                status_retried = True
+                status_code = response.status_code
+                last_status = status_code
+                try:
+                    requested_delay = float(response.headers.get("Retry-After", "1"))
+                    if not math.isfinite(requested_delay):
+                        requested_delay = 1.0
+                    delay = min(max(requested_delay, 0.2), 5.0)
+                except ValueError:
+                    delay = 1.0
+                response.close()
+                response = None
+                remaining = budget_end - time.monotonic()
+                if remaining <= 0:
+                    # The single status retry needs time to run; without it the
+                    # final message would report a connection error that never
+                    # happened ("after 1 attempts: None") and drop the status.
+                    raise ToolError(
+                        f"provider {label} request failed with HTTP {status_code} "
+                        "and no time was left to retry"
+                    )
+                time.sleep(min(delay, remaining))
+                continue
+            if 300 <= response.status_code < 400:
+                location = response.headers.get("Location", "")
+                raise ToolError(
+                    f"provider {label} request was redirected to "
+                    f"{location or 'another location'}; refusing to forward "
+                    "credentials and request data"
+                )
+            if response.status_code >= 400:
+                detail = response.text[:2000]
+                raise ToolError(
+                    f"provider {label} request failed with HTTP "
+                    f"{response.status_code}: {detail}"
+                )
+            try:
+                data = response.json()
+            except ValueError as exc:
+                raise ToolError(
+                    f"provider {label} request returned invalid JSON"
+                ) from exc
+        except RETRYABLE_CONNECTION_ERRORS as exc:
+            last_error = exc
+            if attempts >= CONNECTION_ATTEMPTS:
+                break
+            remaining = budget_end - time.monotonic()
+            if remaining <= 0:
+                break
+            delay = min(connection_backoff(attempts - 1), remaining)
+            if delay > 0:
+                time.sleep(delay)
+            continue
+        except (httpx2.HTTPError, httpx2.InvalidURL) as exc:
+            raise ToolError(f"provider {label} request failed: {exc}") from exc
+        finally:
+            if response is not None:
+                response.close()
+        if not isinstance(data, dict):
+            raise ToolError(f"provider {label} request returned an invalid response")
+        return data
+    if attempts == 0:
+        # The budget was already spent before the first POST; reporting
+        # "after 0 attempts: None" hid that and printed a literal None.
+        raise ToolError(
+            f"provider {label} request timed out before the first attempt: "
+            "the request budget was already spent"
+        )
+    if last_error is None and last_status is not None:
+        raise ToolError(
+            f"provider {label} request failed with HTTP {last_status} "
+            "and no time was left to retry"
+        )
+    raise ToolError(
+        f"provider {label} request failed after {attempts} attempts: {last_error}"
+    ) from last_error
+
+
+__all__ = [
+    "CONNECTION_ATTEMPTS",
+    "CONNECTION_BACKOFF_CAP_SECONDS",
+    "CONNECTION_BACKOFF_SECONDS",
+    "RETRYABLE_CONNECTION_ERRORS",
+    "build_client",
+    "build_headers",
+    "connection_backoff",
+    "is_loopback_url",
+    "merge_headers",
+    "post_json",
+    "resolve_trust_env",
+]