ripperdoc 0.2.3__py3-none-any.whl → 0.2.5__py3-none-any.whl

ripperdoc/tools/tool_search_tool.py

@@ -119,9 +119,7 @@ class ToolSearchTool(Tool[ToolSearchInput, ToolSearchOutput]):
     def is_concurrency_safe(self) -> bool:
         return True
 
-    def needs_permissions(
-        self, input_data: Optional[ToolSearchInput] = None
-    ) -> bool:  # noqa: ARG002
+    def needs_permissions(self, input_data: Optional[ToolSearchInput] = None) -> bool:  # noqa: ARG002
         return False
 
     async def validate_input(
@@ -191,10 +189,11 @@ class ToolSearchTool(Tool[ToolSearchInput, ToolSearchOutput]):
                 description = await build_tool_description(
                     tool, include_examples=include_examples, max_examples=2
                 )
-            except Exception:
+            except (OSError, RuntimeError, ValueError, TypeError, AttributeError, KeyError) as exc:
                 description = ""
-                logger.exception(
-                    "[tool_search] Failed to build tool description",
+                logger.warning(
+                    "[tool_search] Failed to build tool description: %s: %s",
+                    type(exc).__name__, exc,
                     extra={"tool_name": getattr(tool, "name", None)},
                 )
             doc_text = " ".join([name, tool.user_facing_name(), description])

ripperdoc/utils/coerce.py

@@ -0,0 +1,34 @@
+"""Lightweight parsing helpers for permissive type coercion."""
+
+from __future__ import annotations
+
+from typing import Optional
+
+
+def parse_boolish(value: object, default: bool = False) -> bool:
+    """Parse a truthy/falsey value from common representations."""
+    if value is None:
+        return default
+    if isinstance(value, bool):
+        return value
+    if isinstance(value, (int, float)):
+        return bool(value)
+    if isinstance(value, str):
+        normalized = value.strip().lower()
+        if normalized in {"1", "true", "yes", "on"}:
+            return True
+        if normalized in {"0", "false", "no", "off"}:
+            return False
+    return default
+
+
+def parse_optional_int(value: object) -> Optional[int]:
+    """Best-effort int parsing; returns None on failure."""
+    try:
+        if value is None:
+            return None
+        if isinstance(value, bool):
+            return int(value)
+        return int(str(value).strip())
+    except (ValueError, TypeError):
+        return None

ripperdoc/utils/context_length_errors.py

@@ -0,0 +1,252 @@
+"""Detection helpers for context-window overflow errors across providers.
+
+Observed provider responses when the request is too large:
+- OpenAI/OpenRouter style (400 BadRequestError): error.code/context_length_exceeded with
+  a message like "This model's maximum context length is 128000 tokens. However, you
+  requested 130000 tokens (... in the messages, ... in the completion)."
+- Anthropic (400 BadRequestError): invalid_request_error with a message such as
+  "prompt is too long for model claude-3-5-sonnet. max tokens: 200000 prompt tokens: 240000".
+- Gemini / google-genai (FAILED_PRECONDITION or INVALID_ARGUMENT): APIError message like
+  "The input to the model was too long. The requested input has X tokens, which exceeds
+  the maximum of Y tokens for models/gemini-...".
+
+These helpers allow callers to detect the condition and trigger auto-compaction.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, List, Optional, Set
+
+ContextLengthErrorCode = Optional[str]
+
+
+@dataclass
+class ContextLengthErrorInfo:
+    """Normalized metadata about a context-length error."""
+
+    provider: Optional[str]
+    message: str
+    error_code: ContextLengthErrorCode = None
+    status_code: Optional[int] = None
+
+
+_CONTEXT_PATTERNS = [
+    "context_length_exceeded",
+    "maximum context length",
+    "max context length",
+    "maximum context window",
+    "max context window",
+    "context length is",
+    "context length was exceeded",
+    "context window of",
+    "token limit exceeded",
+    "token length exceeded",
+    "prompt is too long",
+    "input is too long",
+    "request is too large",
+    "exceeds the maximum context",
+    "exceeds the model's context",
+    "requested input has",
+    "too many tokens",
+    "reduce the length of the messages",
+]
+
+
+def detect_context_length_error(error: Any) -> Optional[ContextLengthErrorInfo]:
+    """Return normalized context-length error info if the exception matches."""
+    if error is None:
+        return None
+
+    provider = _guess_provider(error)
+    status_code = _extract_status_code(error)
+    codes = _extract_codes(error)
+    messages = _collect_strings(error)
+
+    # Check explicit error codes first.
+    for code in codes:
+        normalized = code.lower()
+        if any(
+            keyword in normalized
+            for keyword in (
+                "context_length",
+                "max_tokens",
+                "token_length",
+                "prompt_too_long",
+                "input_too_large",
+                "token_limit",
+            )
+        ):
+            message = messages[0] if messages else code
+            return ContextLengthErrorInfo(
+                provider=provider,
+                message=message,
+                error_code=code,
+                status_code=status_code,
+            )
+
+    # Fall back to message-based detection.
+    for text in messages:
+        if _looks_like_context_length_message(text):
+            return ContextLengthErrorInfo(
+                provider=provider,
+                message=text,
+                error_code=codes[0] if codes else None,
+                status_code=status_code,
+            )
+
+    return None
+
+
+def _looks_like_context_length_message(text: str) -> bool:
+    lower = text.lower()
+    if any(pattern in lower for pattern in _CONTEXT_PATTERNS):
+        return True
+    if "too long" in lower and (
+        "prompt" in lower or "input" in lower or "context" in lower or "token" in lower
+    ):
+        return True
+    if "exceed" in lower and ("token" in lower or "context" in lower):
+        return True
+    if "max" in lower and "token" in lower and ("context" in lower or "limit" in lower):
+        return True
+    return False
+
+
+def _guess_provider(error: Any) -> Optional[str]:
+    module = getattr(getattr(error, "__class__", None), "__module__", "") or ""
+    name = getattr(getattr(error, "__class__", None), "__name__", "").lower()
+    if "openai" in module or "openai" in name:
+        return "openai"
+    if "anthropic" in module or "claude" in module:
+        return "anthropic"
+    if "google.genai" in module or "vertexai" in module:
+        return "gemini"
+    return None
+
+
+def _extract_status_code(error: Any) -> Optional[int]:
+    for attr in ("status_code", "http_status", "code"):
+        value = getattr(error, attr, None)
+        if isinstance(value, int):
+            return value
+        if isinstance(value, str) and value.isdigit():
+            return int(value)
+
+    for payload in (
+        _safe_getattr(error, "body"),
+        _safe_getattr(error, "details"),
+        _safe_getattr(error, "error"),
+    ):
+        if isinstance(payload, dict):
+            for key in ("status_code", "code"):
+                value = payload.get(key)
+                if isinstance(value, int):
+                    return value
+                if isinstance(value, str) and value.isdigit():
+                    return int(value)
+
+    return None
+
+
+def _extract_codes(error: Any) -> List[str]:
+    codes: List[str] = []
+    seen: Set[str] = set()
+
+    def _add(value: Any) -> None:
+        if value is None:
+            return
+        if isinstance(value, int):
+            value = str(value)
+        if not isinstance(value, str):
+            return
+        normalized = value.strip()
+        if not normalized or normalized in seen:
+            return
+        seen.add(normalized)
+        codes.append(normalized)
+
+    for attr in ("code", "error_code", "type", "status"):
+        _add(_safe_getattr(error, attr))
+
+    for payload in (
+        _safe_getattr(error, "body"),
+        _safe_getattr(error, "details"),
+        _safe_getattr(error, "error"),
+    ):
+        if isinstance(payload, dict):
+            for key in ("code", "type", "status"):
+                _add(payload.get(key))
+            nested = payload.get("error")
+            if isinstance(nested, dict):
+                for key in ("code", "type", "status"):
+                    _add(nested.get(key))
+
+    if isinstance(error, dict):
+        for key in ("code", "type", "status"):
+            _add(error.get(key))
+
+    return codes
+
+
+def _collect_strings(error: Any) -> List[str]:
+    """Collect human-readable strings from an exception/payload."""
+    texts: List[str] = []
+    seen_texts: Set[str] = set()
+    seen_objs: Set[int] = set()
+
+    def _add_text(value: Any) -> None:
+        if not isinstance(value, str):
+            return
+        normalized = value.strip()
+        if not normalized or normalized in seen_texts:
+            return
+        seen_texts.add(normalized)
+        texts.append(normalized)
+
+    def _walk(obj: Any) -> None:
+        if obj is None:
+            return
+        obj_id = id(obj)
+        if obj_id in seen_objs:
+            return
+        seen_objs.add(obj_id)
+
+        if isinstance(obj, str):
+            _add_text(obj)
+            return
+
+        if isinstance(obj, BaseException):
+            _add_text(_safe_getattr(obj, "message"))
+            for arg in getattr(obj, "args", ()):
+                _walk(arg)
+            for attr in ("body", "error", "details"):
+                _walk(_safe_getattr(obj, attr))
+            return
+
+        if isinstance(obj, dict):
+            for val in obj.values():
+                _walk(val)
+            return
+
+        if isinstance(obj, (list, tuple, set)):
+            for item in obj:
+                _walk(item)
+            return
+
+        _add_text(_safe_getattr(obj, "message"))
+
+    _walk(error)
+    try:
+        _add_text(str(error))
+    except (TypeError, ValueError):
+        pass
+
+    return texts
+
+
+def _safe_getattr(obj: Any, attr: str) -> Any:
+    try:
+        return getattr(obj, attr, None)
+    except (TypeError, AttributeError):
+        return None

ripperdoc/utils/file_watch.py

@@ -102,10 +102,11 @@ def detect_changed_files(
 
         try:
             new_content = _read_portion(file_path, snapshot.offset, snapshot.limit)
-        except Exception as exc:  # pragma: no cover - best-effort telemetry
-            logger.exception(
-                "[file_watch] Failed reading changed file",
-                extra={"file_path": file_path, "error": str(exc)},
+        except (OSError, IOError, UnicodeDecodeError, ValueError) as exc:  # pragma: no cover - best-effort telemetry
+            logger.warning(
+                "[file_watch] Failed reading changed file: %s: %s",
+                type(exc).__name__, exc,
+                extra={"file_path": file_path},
             )
             notices.append(
                 ChangedFileNotice(

ripperdoc/utils/json_utils.py

@@ -17,11 +17,11 @@ def safe_parse_json(json_text: Optional[str], log_error: bool = True) -> Optiona
         return None
     try:
         return json.loads(json_text)
-    except Exception as exc:
+    except (json.JSONDecodeError, TypeError, ValueError) as exc:
         if log_error:
             logger.debug(
-                "[json_utils] Failed to parse JSON",
-                extra={"error": str(exc), "length": len(json_text)},
-                exc_info=True,
+                "[json_utils] Failed to parse JSON: %s: %s",
+                type(exc).__name__, exc,
+                extra={"length": len(json_text)},
             )
         return None

ripperdoc/utils/log.py

@@ -55,7 +55,7 @@ class StructuredFormatter(logging.Formatter):
         if extras:
             try:
                 serialized = json.dumps(extras, sort_keys=True, ensure_ascii=True, default=str)
-            except Exception:
+            except (TypeError, ValueError):
                 serialized = str(extras)
             return f"{message} | {serialized}"
         return message
@@ -97,9 +97,9 @@ class RipperdocLogger:
         if self._file_handler:
             try:
                 self.logger.removeHandler(self._file_handler)
-            except Exception:
+            except (ValueError, RuntimeError):
                 # Swallow errors while rotating handlers; console logging should continue.
-                self.logger.exception("[logging] Failed to remove existing file handler")
+                pass
 
         # Use UTF-8 to avoid Windows code page encoding errors when logs contain non-ASCII text.
         file_handler = logging.FileHandler(log_file, encoding="utf-8")

ripperdoc/utils/mcp.py

@@ -5,6 +5,7 @@ from __future__ import annotations
 import asyncio
 import contextvars
 import json
+import shlex
 from contextlib import AsyncExitStack
 from dataclasses import dataclass, field, replace
 from pathlib import Path
@@ -12,23 +13,23 @@ from typing import Any, Dict, List, Optional
 
 from ripperdoc import __version__
 from ripperdoc.utils.log import get_logger
-from ripperdoc.utils.message_compaction import estimate_tokens_from_text
+from ripperdoc.utils.token_estimation import estimate_tokens
 
 logger = get_logger()
 
 try:
-    import mcp.types as mcp_types
-    from mcp.client.session import ClientSession
-    from mcp.client.sse import sse_client
-    from mcp.client.stdio import StdioServerParameters, stdio_client
-    from mcp.client.streamable_http import streamablehttp_client
+    import mcp.types as mcp_types  # type: ignore[import-not-found]
+    from mcp.client.session import ClientSession  # type: ignore[import-not-found]
+    from mcp.client.sse import sse_client  # type: ignore[import-not-found]
+    from mcp.client.stdio import StdioServerParameters, stdio_client  # type: ignore[import-not-found]
+    from mcp.client.streamable_http import streamablehttp_client  # type: ignore[import-not-found]
 
     MCP_AVAILABLE = True
-except Exception:  # pragma: no cover - handled gracefully at runtime
+except (ImportError, ModuleNotFoundError):  # pragma: no cover - handled gracefully at runtime
     MCP_AVAILABLE = False
     ClientSession = object  # type: ignore
     mcp_types = None  # type: ignore
-    logger.exception("[mcp] MCP SDK not available at import time")
+    logger.debug("[mcp] MCP SDK not available at import time")
 
 
 @dataclass
@@ -88,19 +89,56 @@ def _ensure_str_dict(raw: object) -> Dict[str, str]:
     for key, value in raw.items():
         try:
             result[str(key)] = str(value)
-        except Exception:
-            logger.exception(
-                "[mcp] Failed to coerce env/header value to string",
-                extra={"key": key, "value": value},
+        except (TypeError, ValueError) as exc:
+            logger.warning(
+                "[mcp] Failed to coerce env/header value to string: %s: %s",
+                type(exc).__name__, exc,
+                extra={"key": key},
             )
             continue
     return result
 
 
+def _normalize_command(raw_command: Any, raw_args: Any) -> tuple[Optional[str], List[str]]:
+    """Normalize MCP server command/args.
+
+    Supports:
+    - command as list -> first element is executable, rest are args
+    - command as string with spaces -> shlex.split into executable/args (when args empty)
+    - command as plain string -> used as-is
+    """
+    args: List[str] = []
+    if isinstance(raw_args, list):
+        args = [str(a) for a in raw_args]
+
+    # Command provided as list: treat first token as command.
+    if isinstance(raw_command, list):
+        tokens = [str(t) for t in raw_command if str(t)]
+        if not tokens:
+            return None, args
+        return tokens[0], tokens[1:] + args
+
+    if not isinstance(raw_command, str):
+        return None, args
+
+    command_str = raw_command.strip()
+    if not command_str:
+        return None, args
+
+    if not args and (" " in command_str or "\t" in command_str):
+        try:
+            tokens = shlex.split(command_str)
+        except ValueError:
+            tokens = [command_str]
+        if tokens:
+            return tokens[0], tokens[1:]
+
+    return command_str, args
+
+
 def _parse_server(name: str, raw: Dict[str, Any]) -> McpServerInfo:
     server_type = str(raw.get("type") or raw.get("transport") or "").strip().lower()
-    command = raw.get("command")
-    args = raw.get("args") if isinstance(raw.get("args"), list) else []
+    command, args = _normalize_command(raw.get("command"), raw.get("args"))
     url = str(raw.get("url") or raw.get("uri") or "").strip() or None
 
     if not server_type:
@@ -121,7 +159,7 @@ def _parse_server(name: str, raw: Dict[str, Any]) -> McpServerInfo:
         type=server_type,
         url=url,
         description=description,
-        command=str(command) if isinstance(command, str) else None,
+        command=command,
         args=[str(a) for a in args] if args else [],
         env=env,
         headers=headers,
@@ -327,10 +365,11 @@ class McpRuntime:
                     "capabilities": list(info.capabilities.keys()),
                 },
             )
-        except Exception as exc:  # pragma: no cover - network/process errors
-            logger.exception(
-                "Failed to connect to MCP server",
-                extra={"server": config.name, "error": str(exc)},
+        except (OSError, RuntimeError, ConnectionError, ValueError, TimeoutError) as exc:  # pragma: no cover - network/process errors
+            logger.warning(
+                "Failed to connect to MCP server: %s: %s",
+                type(exc).__name__, exc,
+                extra={"server": config.name},
             )
             info.status = "failed"
             info.error = str(exc)
@@ -347,6 +386,12 @@ class McpRuntime:
         )
         try:
             await self._exit_stack.aclose()
+        except BaseException as exc:  # pragma: no cover - defensive shutdown
+            # Swallow noisy ExceptionGroups from stdio_client cancel scopes during exit.
+            logger.debug(
+                "[mcp] Suppressed MCP shutdown error",
+                extra={"error": str(exc), "project_path": str(self.project_path)},
+            )
         finally:
             self.sessions.clear()
             self.servers.clear()
@@ -355,10 +400,16 @@ class McpRuntime:
 _runtime_var: contextvars.ContextVar[Optional[McpRuntime]] = contextvars.ContextVar(
     "ripperdoc_mcp_runtime", default=None
 )
+# Fallback for synchronous contexts (e.g., run_until_complete) where contextvars
+# don't propagate values back to the caller.
+_global_runtime: Optional[McpRuntime] = None
 
 
 def _get_runtime() -> Optional[McpRuntime]:
-    return _runtime_var.get()
+    runtime = _runtime_var.get()
+    if runtime:
+        return runtime
+    return _global_runtime
 
 
 def get_existing_mcp_runtime() -> Optional[McpRuntime]:
@@ -370,6 +421,7 @@ async def ensure_mcp_runtime(project_path: Optional[Path] = None) -> McpRuntime:
     runtime = _get_runtime()
     project_path = project_path or Path.cwd()
     if runtime and not runtime._closed and runtime.project_path == project_path:
+        _runtime_var.set(runtime)
         logger.debug(
             "[mcp] Reusing existing MCP runtime",
             extra={
@@ -390,6 +442,9 @@ async def ensure_mcp_runtime(project_path: Optional[Path] = None) -> McpRuntime:
     configs = _load_server_configs(project_path)
     await runtime.connect(configs)
     _runtime_var.set(runtime)
+    # Keep a module-level reference so sync callers that hop event loops can reuse it.
+    global _global_runtime
+    _global_runtime = runtime
     return runtime
 
 
@@ -397,8 +452,13 @@ async def shutdown_mcp_runtime() -> None:
     runtime = _get_runtime()
     if not runtime:
         return
-    await runtime.aclose()
+    try:
+        await runtime.aclose()
+    except BaseException as exc:  # pragma: no cover - defensive for ExceptionGroup
+        logger.debug("[mcp] Suppressed MCP runtime shutdown error", extra={"error": str(exc)})
     _runtime_var.set(None)
+    global _global_runtime
+    _global_runtime = None
 
 
 async def load_mcp_servers_async(project_path: Optional[Path] = None) -> List[McpServerInfo]:
@@ -482,7 +542,7 @@ def format_mcp_instructions(servers: List[McpServerInfo]) -> str:
 def estimate_mcp_tokens(servers: List[McpServerInfo]) -> int:
     """Estimate token usage for MCP instructions."""
     mcp_text = format_mcp_instructions(servers)
-    return estimate_tokens_from_text(mcp_text)
+    return estimate_tokens(mcp_text)
 
 
 __all__ = [

ripperdoc/utils/memory.py

@@ -45,9 +45,10 @@ def _is_path_under_directory(path: Path, directory: Path) -> bool:
     try:
         path.resolve().relative_to(directory.resolve())
         return True
-    except Exception:
-        logger.exception(
-            "[memory] Failed to compare path containment",
+    except (ValueError, OSError) as exc:
+        logger.warning(
+            "[memory] Failed to compare path containment: %s: %s",
+            type(exc).__name__, exc,
             extra={"path": str(path), "directory": str(directory)},
         )
         return False
@@ -122,9 +123,11 @@ def _collect_files(
     resolved_path = file_path.expanduser()
     try:
         resolved_path = resolved_path.resolve()
-    except Exception:
-        logger.exception(
-            "[memory] Failed to resolve memory file path", extra={"path": str(resolved_path)}
+    except (OSError, ValueError) as exc:
+        logger.warning(
+            "[memory] Failed to resolve memory file path: %s: %s",
+            type(exc).__name__, exc,
+            extra={"path": str(resolved_path)},
         )
 
     resolved_key = str(resolved_path)

ripperdoc/utils/message_compaction.py

@@ -3,13 +3,13 @@
 from __future__ import annotations
 
 import json
-import math
 import os
 from dataclasses import dataclass
 from typing import Any, Callable, Dict, List, Optional, Sequence, Set, Union
 
 from ripperdoc.core.config import GlobalConfig, ModelProfile, get_global_config
 from ripperdoc.utils.log import get_logger
+from ripperdoc.utils.token_estimation import estimate_tokens
 from ripperdoc.utils.messages import (
     AssistantMessage,
     MessageContent,
@@ -140,10 +140,8 @@ def _parse_truthy_env_value(value: Optional[str]) -> bool:
 
 
 def estimate_tokens_from_text(text: str) -> int:
-    """Rough token estimate using a 4-characters-per-token rule."""
-    if not text:
-        return 0
-    return max(1, math.ceil(len(text) / 4))
+    """Estimate token count using shared token estimation helper."""
+    return estimate_tokens(text)
 
 
 def _stringify_content(content: Union[str, List[MessageContent], None]) -> str:
@@ -171,9 +169,10 @@ def _stringify_content(content: Union[str, List[MessageContent], None]) -> str:
             if block_type == "tool_use" and part.get("input") is not None:
                 try:
                     parts.append(json.dumps(part.get("input"), ensure_ascii=False))
-                except Exception:
-                    logger.exception(
-                        "[message_compaction] Failed to serialize tool_use input for token estimate"
+                except (TypeError, ValueError) as exc:
+                    logger.warning(
+                        "[message_compaction] Failed to serialize tool_use input for token estimate: %s: %s",
+                        type(exc).__name__, exc,
                     )
                     parts.append(str(part.get("input")))
 
@@ -227,10 +226,11 @@ def _estimate_tool_schema_tokens(tools: Sequence[Any]) -> int:
             schema = tool.input_schema.model_json_schema()
             schema_text = json.dumps(schema, sort_keys=True)
             total += estimate_tokens_from_text(schema_text)
-        except Exception as exc:
-            logger.exception(
-                "Failed to estimate tokens for tool schema",
-                extra={"tool": getattr(tool, "name", None), "error": str(exc)},
+        except (AttributeError, TypeError, KeyError, ValueError) as exc:
+            logger.warning(
+                "Failed to estimate tokens for tool schema: %s: %s",
+                type(exc).__name__, exc,
+                extra={"tool": getattr(tool, "name", None)},
             )
             continue
     return total
@@ -401,8 +401,8 @@ def find_latest_assistant_usage_tokens(
                     tokens += int(value)
             if tokens > 0:
                 return tokens
-        except Exception:
-            logger.debug("[message_compaction] Failed to parse usage tokens", exc_info=True)
+        except (TypeError, ValueError, AttributeError):
+            logger.debug("[message_compaction] Failed to parse usage tokens")
             continue
     return 0
 
@@ -438,8 +438,11 @@ def _run_cleanup_callbacks() -> None:
     for callback in callbacks:
         try:
             callback()
-        except Exception as exc:
-            logger.debug(f"[message_compaction] Cleanup callback failed: {exc}", exc_info=True)
+        except (RuntimeError, TypeError, ValueError, AttributeError) as exc:
+            logger.debug(
+                "[message_compaction] Cleanup callback failed: %s: %s",
+                type(exc).__name__, exc,
+            )
 
 
 def _normalize_tool_use_id(block: Any) -> str: