alysis-code 0.13.0__py3-none-any.whl

alysis_code/llm_error_display.py

@@ -0,0 +1,315 @@
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass
+from typing import Any
+from urllib.parse import urlparse
+
+from .error_text import sanitize_error_text_for_output
+
+_NETWORK_MODEL_SIGNALS = (
+    "llm request failed",
+    "llm error",
+    "network",
+    "timeout",
+    "timed out",
+    "connection",
+    "dns",
+    "tls",
+    "certificate",
+    "api key",
+    "unauthorized",
+    "forbidden",
+    "rate limit",
+    "too many requests",
+    "base_url",
+    "can't reach",
+    "chat/completions",
+    "model provider",
+    "provider rejected",
+)
+
+_TOOL_TRANSCRIPT_SIGNAL_GROUPS = (
+    (
+        "assistant message with 'tool_calls' must be followed by tool messages",
+        'assistant message with "tool_calls" must be followed by tool messages',
+    ),
+    (
+        "tool_call_id",
+        "did not have response messages",
+    ),
+    (
+        "tool transcript",
+        "missing",
+    ),
+    (
+        "tool transcript",
+        "malformed",
+    ),
+    (
+        "tool transcript",
+        "incomplete",
+    ),
+)
+
+
+@dataclass(frozen=True)
+class LLMErrorDisplay:
+    title: str
+    guidance_lines: tuple[str, ...]
+
+
+def is_tool_transcript_error(text: str) -> bool:
+    lowered = str(text or "").lower()
+    if not lowered:
+        return False
+    return any(all(token in lowered for token in group) for group in _TOOL_TRANSCRIPT_SIGNAL_GROUPS)
+
+
+def is_network_or_model_error(text: str) -> bool:
+    lowered = str(text or "").lower()
+    if not lowered or is_tool_transcript_error(lowered):
+        return False
+    return any(token in lowered for token in _NETWORK_MODEL_SIGNALS)
+
+
+def friendly_llm_error_message(error: Any) -> str:
+    """Return user-facing provider error text without raw exception wrappers."""
+    try:
+        from .llm.openai_compat import alysis_trial_error_message
+
+        trial_message = alysis_trial_error_message(error)
+    except Exception:  # noqa: BLE001
+        trial_message = None
+    if trial_message:
+        return sanitize_error_text_for_output(trial_message)
+
+    text = sanitize_error_text_for_output(error).strip()
+    if not text:
+        return "The model provider returned an empty error."
+    if is_tool_transcript_error(text):
+        return text
+
+    status = _llm_error_status_code(text)
+    detail = _provider_error_detail(text)
+    lowered = f"{text}\n{detail}".casefold()
+    url = _first_url(detail)
+    url_suffix = f" See: {url}" if url else ""
+
+    if status in {401, 403} or _looks_like_auth_error(lowered):
+        status_suffix = f" ({status})" if status is not None else ""
+        return f"Your API key was rejected{status_suffix}. Update it with /config.{url_suffix}"
+
+    if _looks_like_connection_error(error, lowered):
+        host = _provider_host_from_error(error) or _provider_host_from_text(text)
+        host_suffix = f" at {host}" if host else ""
+        return (
+            f"Can't reach the model provider{host_suffix}. "
+            "Check the profile base URL in /config and try again."
+        )
+
+    if _looks_like_timeout_error(lowered):
+        return (
+            "The model provider did not respond before the request timed out. "
+            "Check the base URL/network, or increase the model timeout in /config."
+        )
+
+    if "tool_choice" in lowered:
+        status_suffix = f" ({status})" if status is not None else ""
+        return (
+            f"The provider rejected the tool_choice parameter{status_suffix}. "
+            "Use a tool-compatible model/provider, or retry with provider compatibility enabled."
+        )
+
+    unsupported_model = _unsupported_model_name(detail) or _unsupported_model_name(text)
+    if unsupported_model:
+        status_suffix = f" ({status})" if status is not None else ""
+        return (
+            f"The provider rejected model '{unsupported_model}' for this request"
+            f"{status_suffix}. Check the model id or provider profile in /config."
+        )
+
+    if status == 429 or "rate limit" in lowered or "too many requests" in lowered:
+        return "The model provider is rate-limiting this session (429). Wait a moment and retry."
+
+    if status is not None and detail and detail != text:
+        return f"The model provider rejected the request ({status}): {_single_line(detail)}"
+    return text
+
+
+def classify_llm_error_display(text: str) -> LLMErrorDisplay:
+    # Transcript integrity errors often arrive inside a generic "LLM error 400" wrapper,
+    # so classify them before broader network/model guidance.
+    if is_tool_transcript_error(text):
+        return LLMErrorDisplay(
+            title="Tool Transcript Error",
+            guidance_lines=(
+                "This session's tool transcript is incomplete or malformed.",
+                "Retry in a new session. If it repeats, inspect resume/compaction around missing tool responses.",
+            ),
+        )
+    if is_network_or_model_error(text):
+        return LLMErrorDisplay(
+            title="Network/Model Error",
+            guidance_lines=(
+                "Check base URL, API key, and network connectivity.",
+                "Retry when ready. Use /status for current session settings.",
+            ),
+        )
+    return LLMErrorDisplay(title="LLM Error", guidance_lines=())
+
+
+def _llm_error_status_code(text: str) -> int | None:
+    match = re.search(r"\bLLM\s+error\s+(\d{3})\b", str(text or ""), re.IGNORECASE)
+    if match is None:
+        return None
+    try:
+        return int(match.group(1))
+    except ValueError:
+        return None
+
+
+def _llm_error_body(text: str) -> str:
+    raw = str(text or "").strip()
+    match = re.search(r"\bLLM\s+error\s+\d{3}\s*:\s*", raw, re.IGNORECASE)
+    if match is None:
+        return raw
+    return raw[match.end() :].strip()
+
+
+def _json_error_payload(text: str) -> dict[str, Any]:
+    try:
+        payload = json.loads(str(text or "").strip())
+    except json.JSONDecodeError:
+        return {}
+    return payload if isinstance(payload, dict) else {}
+
+
+def _provider_error_detail(text: str) -> str:
+    body = _llm_error_body(text)
+    payload = _json_error_payload(body)
+    if not payload:
+        return _single_line(body)
+    raw_error = payload.get("error")
+    error = raw_error if isinstance(raw_error, dict) else payload
+    message = error.get("message") if isinstance(error, dict) else None
+    if isinstance(message, str) and message.strip():
+        return _single_line(message)
+    code = error.get("code") if isinstance(error, dict) else None
+    if isinstance(code, str) and code.strip():
+        return _single_line(code)
+    return _single_line(body)
+
+
+def _single_line(text: str) -> str:
+    return re.sub(r"\s+", " ", str(text or "").strip())
+
+
+def _first_url(text: str) -> str | None:
+    match = re.search(r"https?://[^\s)>\]}\"']+", str(text or ""))
+    if match is None:
+        return None
+    return match.group(0).rstrip(".,;:")
+
+
+def _looks_like_auth_error(lowered: str) -> bool:
+    return any(
+        token in lowered
+        for token in (
+            "api key",
+            "invalid_api_key",
+            "incorrect api key",
+            "unauthorized",
+            "authentication",
+            "forbidden",
+        )
+    )
+
+
+def _looks_like_connection_error(error: Any, lowered: str) -> bool:
+    for exc in _exception_chain(error):
+        type_name = type(exc).__name__.casefold()
+        if type_name in {"connecterror", "connecttimeout"}:
+            return True
+    return any(
+        token in lowered
+        for token in (
+            "connection refused",
+            "connect error",
+            "connect timeout",
+            "connecttimeout",
+            "dns",
+            "name resolution",
+            "network is unreachable",
+            "temporary failure in name resolution",
+        )
+    )
+
+
+def _looks_like_timeout_error(lowered: str) -> bool:
+    return any(
+        token in lowered
+        for token in (
+            "read timeout",
+            "readtimeout",
+            "timed out",
+            "timeout",
+        )
+    )
+
+
+def _provider_host_from_error(error: Any) -> str | None:
+    for exc in _exception_chain(error):
+        request = getattr(exc, "request", None)
+        url = getattr(request, "url", None)
+        host = getattr(url, "host", None)
+        if isinstance(host, str) and host:
+            port = getattr(url, "port", None)
+            return f"{host}:{port}" if port is not None else host
+    return None
+
+
+def _provider_host_from_text(text: str) -> str | None:
+    safe_label = re.search(
+        r"(?P<host>(?:\[[0-9a-f:]+\]|[A-Za-z0-9.-]+)(?::\d+)?)\s+"
+        r"\(endpoint\s+[0-9a-f]{12}\)",
+        str(text or ""),
+        re.IGNORECASE,
+    )
+    if safe_label is not None:
+        return safe_label.group("host")
+    url = _first_url(text)
+    if not url:
+        return None
+    try:
+        parsed = urlparse(url)
+    except ValueError:
+        return None
+    if not parsed.hostname:
+        return None
+    return f"{parsed.hostname}:{parsed.port}" if parsed.port is not None else parsed.hostname
+
+
+def _exception_chain(error: Any) -> list[Any]:
+    chain: list[Any] = []
+    seen: set[int] = set()
+    current = error
+    while current is not None and id(current) not in seen:
+        seen.add(id(current))
+        chain.append(current)
+        cause = getattr(current, "__cause__", None)
+        context = getattr(current, "__context__", None)
+        current = cause if cause is not None else context
+    return chain
+
+
+def _unsupported_model_name(text: str) -> str | None:
+    match = re.search(
+        r"(?:not\s+supported\s+model|unsupported\s+model|model\s+not\s+supported)\s+['\"]?([^'\"\s,.;}]+)",
+        str(text or ""),
+        re.IGNORECASE,
+    )
+    if match is None:
+        return None
+    return match.group(1).strip()

alysis_code/logging_redaction.py

@@ -0,0 +1,326 @@
+"""Write-path secret redaction for Alysis Code log and telemetry sinks.
+
+Background: a live ``ALYSIS_API_KEY`` value once reached a session JSONL file
+in cleartext. A tool call dumped the process environment and the tool output was
+logged verbatim. An archive-time scanner caught it after the fact, but by then
+the credential had already been written to disk. This module closes that gap at
+the write boundary: each Alysis Code log/telemetry sink funnels its final
+serialized string through :func:`redact_log_text` immediately before the write,
+so a captured secret value cannot reach disk in the first place.
+
+The archive-time scanner in ``feedback_report`` is deliberately left untouched
+and remains the second, independent layer.
+
+Design constraints:
+
+* Stdlib only, with no intra-package imports. Every sink module must be able to
+  import this one without creating a cycle and without dragging in heavy
+  third-party dependencies (httpx, pydantic, rich).
+* Deterministic and idempotent: ``redact(redact(t)) == redact(t)``.
+* Fast: one precompiled alternation covers every known spelling of every
+  captured value, and one further combined pass covers risky assignment
+  patterns, so a line costs two regex scans regardless of how many secrets are
+  known. Run ``python -m alysis_code.logging_redaction`` for a
+  micro-benchmark.
+
+What is captured
+----------------
+At construction the redactor snapshots the *values* of environment variables
+whose names end in ``_API_KEY``, ``_TOKEN``, ``_SECRET`` or ``_PASSWORD`` (or
+that are exactly ``API_KEY``/``TOKEN``/``SECRET``/``PASSWORD``), plus any
+``ALYSIS_*`` variable whose value looks credential-like. Values shorter than
+``MIN_VALUE_LENGTH`` are ignored: they collide with ordinary log prose far too
+often to be replaced safely.
+
+Known limitations (deliberate)
+------------------------------
+* Base64 is matched only for the exact UTF-8 bytes of the value at alignment 0
+  (standard and URL-safe, padded and unpadded). A secret base64-encoded as part
+  of a *larger* blob lands at a shifted alignment and is not detected; the
+  archive-time scanner remains the backstop for that case.
+* A secret deliberately split across two fields (for example the first half in
+  one JSON value and the second half in another) is not reassembled. Each half
+  is redacted only if it independently matches a captured value.
+* The risky-pattern pass requires a high-entropy payload, so a low-entropy
+  placeholder such as ``password=aaaaaaaaaaaaaaaa`` is left alone on purpose.
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+import math
+import os
+import re
+import threading
+from collections import Counter
+from collections.abc import Mapping
+from urllib.parse import quote, quote_plus
+
+__all__ = [
+    "MIN_CREDENTIAL_LENGTH",
+    "MIN_VALUE_LENGTH",
+    "SecretRedactor",
+    "default_redactor",
+    "redact_log_text",
+    "reset_default_redactor",
+]
+
+# Guillemets keep the marker visually distinct and, more importantly, outside the
+# payload character classes below, which is what makes redaction idempotent by
+# construction rather than by convention.
+_PLACEHOLDER_PREFIX = "«redacted:"
+_PLACEHOLDER_SUFFIX = "»"
+_PATTERN_PLACEHOLDER = f"{_PLACEHOLDER_PREFIX}pattern{_PLACEHOLDER_SUFFIX}"
+
+#: Values shorter than this are never captured: too collision-prone.
+MIN_VALUE_LENGTH = 8
+#: Length floor for the ``ALYSIS_*`` "looks like a credential" heuristic.
+MIN_CREDENTIAL_LENGTH = 16
+#: Shannon entropy floor, in bits per character.
+MIN_ENTROPY_BITS_PER_CHAR = 3.0
+#: Entropy floor for a payload found by the risky-pattern pass.
+MIN_PATTERN_ENTROPY_BITS_PER_CHAR = 3.0
+
+_SECRET_NAME_SUFFIXES = ("_API_KEY", "_TOKEN", "_SECRET", "_PASSWORD")
+_SECRET_NAME_EXACT = frozenset({"API_KEY", "TOKEN", "SECRET", "PASSWORD"})
+_HEURISTIC_NAME_PREFIX = "ALYSIS_"
+
+# Characters a credential may plausibly be made of. Excludes whitespace, quotes
+# and braces so that a JSON blob or an English sentence can never be mistaken
+# for one value.
+_TOKEN_CHARSET_RE = re.compile(r"[A-Za-z0-9._~+/=:-]+")
+_PATHISH_RE = re.compile(r"(?:\A[./~]|\A[A-Za-z]:[\\/]|://)")
+_HEXISH_RE = re.compile(r"[0-9a-fA-F]+")
+
+
+def _shannon_entropy_bits_per_char(value: str) -> float:
+    """Return Shannon entropy of ``value`` in bits per character."""
+    if not value:
+        return 0.0
+    total = len(value)
+    return -sum((count / total) * math.log2(count / total) for count in Counter(value).values())
+
+
+def _is_named_secret(name: str) -> bool:
+    upper = name.upper()
+    return upper in _SECRET_NAME_EXACT or upper.endswith(_SECRET_NAME_SUFFIXES)
+
+
+def _looks_credential_like(value: str) -> bool:
+    """Heuristic for ``ALYSIS_*`` values whose name does not give them away.
+
+    Deliberately conservative about *shape* rather than length alone, so that
+    ordinary configuration such as a model id or a file path is not swept up.
+    """
+    if len(value) < MIN_CREDENTIAL_LENGTH:
+        return False
+    if not _TOKEN_CHARSET_RE.fullmatch(value):
+        return False
+    if _PATHISH_RE.search(value):
+        return False
+    if _shannon_entropy_bits_per_char(value) < MIN_ENTROPY_BITS_PER_CHAR:
+        return False
+    has_lower = any(char.islower() for char in value)
+    has_upper = any(char.isupper() for char in value)
+    has_digit = any(char.isdigit() for char in value)
+    if has_lower and has_upper and has_digit:
+        return True
+    # Long single-case hex digests are credential-shaped even though they only
+    # use two character classes.
+    return len(value) >= 32 and _HEXISH_RE.fullmatch(value) is not None
+
+
+def _value_variants(value: str) -> list[str]:
+    """Every spelling of ``value`` that could plausibly be written to a log."""
+    variants = {value}
+    # JSON string escaping. Sinks serialize with ensure_ascii=True, but cover
+    # both settings so a non-ASCII secret is caught either way.
+    for ensure_ascii in (True, False):
+        variants.add(json.dumps(value, ensure_ascii=ensure_ascii)[1:-1])
+    # Percent-encoding, as seen in URLs and form bodies.
+    variants.add(quote(value, safe=""))
+    variants.add(quote_plus(value, safe=""))
+    # Base64 of the exact bytes at alignment 0 (see module docstring).
+    raw = value.encode("utf-8")
+    for encoded in (base64.b64encode(raw), base64.urlsafe_b64encode(raw)):
+        text = encoded.decode("ascii")
+        variants.add(text)
+        variants.add(text.rstrip("="))
+    return [variant for variant in variants if len(variant) >= MIN_VALUE_LENGTH]
+
+
+# Assignment-style and Authorization-header patterns whose payload is long and
+# high-entropy. The payload class excludes the guillemets used by the
+# placeholders, so an already-redacted string can never be re-matched.
+_RISKY_PATTERN_RE = re.compile(
+    r"""
+    (?:
+        \b(?:
+            api[-_]?key | access[-_]?key | secret[-_]?key | client[-_]?secret
+            | auth[-_]?token | access[-_]?token | refresh[-_]?token | api[-_]?token
+            | authorization | token | secret | password | passwd
+        )\b
+        \s* ["']? \s* [:=] \s* ["']? \s*
+        (?: (?: bearer | basic | token ) \s+ )?
+        (?P<assigned> [A-Za-z0-9._~+/=-]{16,})
+        |
+        \b bearer \s+ (?P<bearer> [A-Za-z0-9._~+/=-]{16,})
+    )
+    """,
+    re.VERBOSE | re.IGNORECASE,
+)
+
+
+def _replace_risky(match: re.Match) -> str:
+    assigned = match.group("assigned")
+    if assigned is not None:
+        payload, payload_start = assigned, match.start("assigned")
+    else:
+        payload, payload_start = match.group("bearer"), match.start("bearer")
+    if payload.startswith(_PLACEHOLDER_PREFIX):
+        return match.group(0)
+    if _shannon_entropy_bits_per_char(payload) < MIN_PATTERN_ENTROPY_BITS_PER_CHAR:
+        # A low-entropy payload is almost always a placeholder or an enum value;
+        # redacting it would only make real logs harder to read.
+        return match.group(0)
+    # The payload is always the tail of the match, so keeping everything before
+    # it preserves the surrounding syntax (including JSON quoting).
+    return match.group(0)[: payload_start - match.start()] + _PATTERN_PLACEHOLDER
+
+
+class SecretRedactor:
+    """An immutable snapshot of the secret values known at construction time.
+
+    Pass ``environ`` explicitly to get a deterministic redactor in tests; the
+    default reads :data:`os.environ`.
+    """
+
+    def __init__(self, environ: Mapping[str, str] | None = None) -> None:
+        source = os.environ if environ is None else environ
+        replacements: dict[str, str] = {}
+        names: list[str] = []
+        for name, value in sorted(source.items()):
+            if not isinstance(value, str) or len(value) < MIN_VALUE_LENGTH:
+                continue
+            if _is_named_secret(name):
+                pass
+            elif name.startswith(_HEURISTIC_NAME_PREFIX) and _looks_credential_like(value):
+                pass
+            else:
+                continue
+            names.append(name)
+            placeholder = f"{_PLACEHOLDER_PREFIX}{name}{_PLACEHOLDER_SUFFIX}"
+            for variant in _value_variants(value):
+                # Iteration is sorted by name, so if two variables share a value
+                # the alphabetically-first name wins. Deterministic either way.
+                replacements.setdefault(variant, placeholder)
+        self.secret_names: tuple[str, ...] = tuple(names)
+        self._replacements = replacements
+        self._exact_re = self._compile(replacements)
+
+    @staticmethod
+    def _compile(replacements: Mapping[str, str]) -> re.Pattern | None:
+        if not replacements:
+            return None
+        # Longest first, so that when one variant is a prefix of another the
+        # longer (more specific) spelling wins at any given position.
+        ordered = sorted(replacements, key=lambda variant: (-len(variant), variant))
+        return re.compile("|".join(re.escape(variant) for variant in ordered))
+
+    def _replace_exact(self, match: re.Match) -> str:
+        return self._replacements[match.group(0)]
+
+    def redact(self, text: str) -> str:
+        """Return ``text`` with every known secret value and risky payload masked."""
+        if not text:
+            return text
+        if self._exact_re is not None:
+            text = self._exact_re.sub(self._replace_exact, text)
+        return _RISKY_PATTERN_RE.sub(_replace_risky, text)
+
+
+_DEFAULT_LOCK = threading.Lock()
+_DEFAULT_REDACTOR: SecretRedactor | None = None
+_DEFAULT_SIGNATURE: tuple[tuple[str, str], ...] | None = None
+
+
+def _environ_signature(source: Mapping[str, str]) -> tuple[tuple[str, str], ...]:
+    """Cheap fingerprint of the secret-bearing part of the environment."""
+    matches = [
+        (name, value)
+        for name, value in source.items()
+        if isinstance(value, str)
+        and len(value) >= MIN_VALUE_LENGTH
+        and (_is_named_secret(name) or name.startswith(_HEURISTIC_NAME_PREFIX))
+    ]
+    matches.sort()
+    return tuple(matches)
+
+
+def default_redactor() -> SecretRedactor:
+    """Return the process-wide redactor, rebuilding it if the environment moved.
+
+    Credentials are often loaded into the environment after import, so a
+    build-once cache would miss exactly the value that matters. Comparing a
+    cheap signature keeps the compiled regex hot while staying correct.
+    """
+    global _DEFAULT_REDACTOR, _DEFAULT_SIGNATURE
+    signature = _environ_signature(os.environ)
+    with _DEFAULT_LOCK:
+        if _DEFAULT_REDACTOR is None or signature != _DEFAULT_SIGNATURE:
+            _DEFAULT_REDACTOR = SecretRedactor()
+            _DEFAULT_SIGNATURE = signature
+        return _DEFAULT_REDACTOR
+
+
+def reset_default_redactor() -> None:
+    """Drop the cached redactor. Intended for tests."""
+    global _DEFAULT_REDACTOR, _DEFAULT_SIGNATURE
+    with _DEFAULT_LOCK:
+        _DEFAULT_REDACTOR = None
+        _DEFAULT_SIGNATURE = None
+
+
+def redact_log_text(text: str) -> str:
+    """Redact ``text`` immediately before it is written to a log sink."""
+    if not text:
+        return text
+    return default_redactor().redact(text)
+
+
+def _benchmark(size_mb: float = 100.0) -> None:
+    """Micro-benchmark the redaction budget: 100MB in well under a minute."""
+    import time
+
+    secret = "sk-syl-" + ("A7bQ9zX2mK4pL8vN" * 2)
+    environ = {"ALYSIS_API_KEY": secret, "PATH": "/usr/bin:/bin"}
+    redactor = SecretRedactor(environ)
+    block = (
+        "2026-08-21T10:00:00Z level=info msg=tool_result "
+        'payload={"stdout": "HOME=/root\\nSHELL=/bin/bash\\n"} '
+        f"ALYSIS_API_KEY={secret} "
+        "Authorization: Bearer q1W2e3R4t5Y6u7I8o9P0a1S2d3F4g5H6 "
+        "ordinary log prose that must survive untouched\n"
+    )
+    repeats = max(1, int((size_mb * 1024 * 1024) / len(block)))
+    text = block * repeats
+    actual_mb = len(text) / (1024 * 1024)
+
+    start = time.perf_counter()
+    result = redactor.redact(text)
+    elapsed = time.perf_counter() - start
+
+    print(f"input        : {actual_mb:.1f} MB ({repeats} blocks)")
+    print(f"elapsed      : {elapsed:.3f} s")
+    print(f"throughput   : {actual_mb / elapsed:.1f} MB/s")
+    print(f"secret leaked: {secret in result}")
+    print(f"projected 100MB: {elapsed * (100.0 / actual_mb):.2f} s")
+
+    start = time.perf_counter()
+    again = redactor.redact(result)
+    print(f"idempotent   : {again == result} (second pass {time.perf_counter() - start:.3f} s)")
+
+
+if __name__ == "__main__":
+    _benchmark()