ripperdoc 0.2.6__py3-none-any.whl

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/exit_code_handlers.py

@@ -0,0 +1,241 @@
+"""Smart exit code handlers for common shell commands and related helpers.
+
+Provides intelligent interpretation of exit codes for commands like grep, diff, test, etc.
+where non-zero exit codes don't necessarily indicate errors. Also includes small utilities
+shared by bash tooling such as command classification, preview sizing, and lightweight
+command/result schemas.
+"""
+
+import shlex
+from typing import Callable, Optional
+from pydantic import BaseModel, Field
+from dataclasses import dataclass
+
+
+@dataclass
+class ExitCodeResult:
+    """Result of exit code interpretation."""
+
+    is_error: bool
+    message: Optional[str] = None
+    semantic_meaning: Optional[str] = None
+
+
+ExitCodeHandler = Callable[[int, str, str], ExitCodeResult]
+
+
+# Default/max timeouts exposed for bash tooling (keep aligned with BashTool).
+DEFAULT_BASH_TIMEOUT_MS = 120000
+MAX_BASH_TIMEOUT_MS = 600000
+
+# Commands we intentionally ignore in certain contexts (e.g., background-safety checks).
+IGNORED_COMMANDS: tuple[str, ...] = ("sleep",)
+
+# Preview limits for rendering long commands compactly.
+MAX_PREVIEW_LINES = 2
+MAX_PREVIEW_CHARS = 160
+
+# Heuristic command classification list (mirrors the reference set).
+COMMON_COMMANDS: tuple[str, ...] = (
+    "npm",
+    "yarn",
+    "pnpm",
+    "node",
+    "python",
+    "python3",
+    "go",
+    "cargo",
+    "make",
+    "docker",
+    "terraform",
+    "webpack",
+    "vite",
+    "jest",
+    "pytest",
+    "curl",
+    "wget",
+    "build",
+    "test",
+    "serve",
+    "watch",
+    "dev",
+)
+
+
+class BashCommandSchema(BaseModel):
+    """Schema describing a bash command request."""
+
+    command: str = Field(description="The command to execute")
+    timeout: Optional[int] = Field(
+        default=None, description=f"Optional timeout in milliseconds (max {MAX_BASH_TIMEOUT_MS})"
+    )
+    description: Optional[str] = Field(
+        default=None,
+        description="Clear, concise description of what this command does in 5-10 words.",
+    )
+    run_in_background: bool = Field(
+        default=False, description="Set to true to run this command in the background."
+    )
+
+
+class ExtendedBashCommandSchema(BashCommandSchema):
+    """Schema describing an extended bash command request."""
+
+    sandbox: Optional[bool] = Field(
+        default=None, description="Whether to request sandboxed execution (read-only)."
+    )
+    shell_executable: Optional[str] = Field(
+        default=None, description="Optional shell path to use instead of the default shell."
+    )
+
+
+class CommandResultSchema(BaseModel):
+    """Schema describing the shape of a command result."""
+
+    stdout: str = Field(description="The standard output of the command")
+    stderr: str = Field(description="The standard error output of the command")
+    summary: Optional[str] = Field(default=None, description="Summarized output when available")
+    interrupted: bool = Field(default=False, description="Whether the command was interrupted")
+    is_image: Optional[bool] = Field(
+        default=None, description="Flag to indicate if stdout contains image data"
+    )
+    background_task_id: Optional[str] = Field(
+        default=None, description="ID of the background task if command is running in background"
+    )
+    sandbox: Optional[bool] = Field(
+        default=None, description="Flag to indicate if the command was run in sandbox mode"
+    )
+    return_code_interpretation: Optional[str] = Field(
+        default=None,
+        description="Semantic interpretation for non-error exit codes with special meaning",
+    )
+
+
+def default_handler(exit_code: int, stdout: str, stderr: str) -> ExitCodeResult:
+    """Default exit code handler - non-zero is error."""
+    return ExitCodeResult(
+        is_error=exit_code != 0,
+        message=f"Command failed with exit code {exit_code}" if exit_code != 0 else None,
+    )
+
+
+def grep_handler(exit_code: int, stdout: str, stderr: str) -> ExitCodeResult:
+    """Handle grep/rg exit codes: 0=found, 1=not found, 2+=error."""
+    if exit_code == 0:
+        return ExitCodeResult(is_error=False)
+    elif exit_code == 1:
+        return ExitCodeResult(is_error=False, semantic_meaning="No matches found")
+    else:
+        return ExitCodeResult(is_error=True, message=f"grep failed with exit code {exit_code}")
+
+
+def diff_handler(exit_code: int, stdout: str, stderr: str) -> ExitCodeResult:
+    """Handle diff exit codes: 0=same, 1=different, 2+=error."""
+    if exit_code == 0:
+        return ExitCodeResult(is_error=False, semantic_meaning="Files are identical")
+    elif exit_code == 1:
+        return ExitCodeResult(is_error=False, semantic_meaning="Files differ")
+    else:
+        return ExitCodeResult(is_error=True, message=f"diff failed with exit code {exit_code}")
+
+
+def test_handler(exit_code: int, stdout: str, stderr: str) -> ExitCodeResult:
+    """Handle test/[ exit codes: 0=true, 1=false, 2+=error."""
+    if exit_code == 0:
+        return ExitCodeResult(is_error=False, semantic_meaning="Condition is true")
+    elif exit_code == 1:
+        return ExitCodeResult(is_error=False, semantic_meaning="Condition is false")
+    else:
+        return ExitCodeResult(
+            is_error=True, message=f"test command failed with exit code {exit_code}"
+        )
+
+
+def find_handler(exit_code: int, stdout: str, stderr: str) -> ExitCodeResult:
+    """Handle find exit codes: 0=ok, 1=partial, 2+=error."""
+    if exit_code == 0:
+        return ExitCodeResult(is_error=False)
+    elif exit_code == 1:
+        return ExitCodeResult(is_error=False, semantic_meaning="Some directories were inaccessible")
+    else:
+        return ExitCodeResult(is_error=True, message=f"find failed with exit code {exit_code}")
+
+
+# Command-specific handlers
+COMMAND_HANDLERS: dict[str, ExitCodeHandler] = {
+    "grep": grep_handler,
+    "rg": grep_handler,
+    "ripgrep": grep_handler,
+    "diff": diff_handler,
+    "test": test_handler,
+    "[": test_handler,
+    "find": find_handler,
+}
+
+
+def normalize_command(command: str) -> str:
+    """Extract the base command from a command string.
+
+    Handles pipes, command chains, and extracts the final command.
+    Examples:
+        'git status' -> 'git'
+        'cat file | grep pattern' -> 'grep'
+        'ls -la' -> 'ls'
+    """
+    # Get the last command in a pipe chain
+    if "|" in command:
+        command = command.split("|")[-1].strip()
+
+    # Get the first word (the actual command)
+    command = command.strip().split()[0] if command.strip() else ""
+
+    return command
+
+
+def classify_command(command: str) -> str:
+    """Classify a shell command into a known category or 'other'."""
+    try:
+        tokens = shlex.split(command)
+    except ValueError:
+        tokens = command.split()
+
+    if not tokens:
+        return "other"
+
+    for token in tokens:
+        cleaned = token.strip()
+        if not cleaned or cleaned in {"&&", "||", ";", "|"}:
+            continue
+
+        first_word = cleaned.split()[0].lower()
+        if first_word in COMMON_COMMANDS:
+            return first_word
+
+    return "other"
+
+
+def get_exit_code_handler(command: str) -> ExitCodeHandler:
+    """Get the appropriate exit code handler for a command."""
+    normalized = normalize_command(command)
+    return COMMAND_HANDLERS.get(normalized, default_handler)
+
+
+def interpret_exit_code(command: str, exit_code: int, stdout: str, stderr: str) -> ExitCodeResult:
+    """Interpret an exit code in the context of the command.
+
+    Args:
+        command: The shell command that was executed
+        exit_code: The exit code returned
+        stdout: Standard output from the command
+        stderr: Standard error from the command
+
+    Returns:
+        ExitCodeResult with interpretation
+    """
+    handler = get_exit_code_handler(command)
+    return handler(exit_code, stdout, stderr)
+
+
+def create_exit_result(command: str, exit_code: int, stdout: str, stderr: str) -> ExitCodeResult:
+    """Convenience wrapper to mirror reference API naming."""
+    return interpret_exit_code(command, exit_code, stdout, stderr)

ripperdoc/utils/file_watch.py

@@ -0,0 +1,135 @@
+"""Lightweight file-change tracking for notifying the model about user edits."""
+
+from __future__ import annotations
+
+import difflib
+import os
+from dataclasses import dataclass
+from typing import Dict, List, Optional
+
+from ripperdoc.utils.log import get_logger
+
+logger = get_logger()
+
+
+@dataclass
+class FileSnapshot:
+    """Snapshot of a file read by the agent."""
+
+    content: str
+    timestamp: float
+    offset: int = 0
+    limit: Optional[int] = None
+
+
+@dataclass
+class ChangedFileNotice:
+    """Information about a file that changed after it was read."""
+
+    file_path: str
+    summary: str
+
+
+def record_snapshot(
+    file_path: str,
+    content: str,
+    cache: Dict[str, FileSnapshot],
+    *,
+    offset: int = 0,
+    limit: Optional[int] = None,
+) -> None:
+    """Store the current contents and mtime for a file."""
+    try:
+        timestamp = os.path.getmtime(file_path)
+    except OSError:
+        timestamp = 0.0
+    cache[file_path] = FileSnapshot(
+        content=content, timestamp=timestamp, offset=offset, limit=limit
+    )
+
+
+def _read_portion(file_path: str, offset: int, limit: Optional[int]) -> str:
+    with open(file_path, "r", encoding="utf-8", errors="replace") as handle:
+        lines = handle.readlines()
+    start = max(offset, 0)
+    if limit is None:
+        selected = lines[start:]
+    else:
+        selected = lines[start : start + limit]
+    return "".join(selected)
+
+
+def _build_diff_summary(old_content: str, new_content: str, file_path: str, max_lines: int) -> str:
+    diff = list(
+        difflib.unified_diff(
+            old_content.splitlines(),
+            new_content.splitlines(),
+            fromfile=file_path,
+            tofile=file_path,
+            lineterm="",
+        )
+    )
+    if not diff:
+        return "File was modified but contents appear unchanged."
+
+    # Keep the diff short to avoid flooding the model.
+    if len(diff) > max_lines:
+        diff = diff[:max_lines] + ["... (diff truncated)"]
+    return "\n".join(diff)
+
+
+def detect_changed_files(
+    cache: Dict[str, FileSnapshot], *, max_diff_lines: int = 80
+) -> List[ChangedFileNotice]:
+    """Return notices for files whose mtime increased since they were read."""
+    notices: List[ChangedFileNotice] = []
+
+    # Iterate over a static list so we can mutate cache safely.
+    for file_path, snapshot in list(cache.items()):
+        try:
+            current_mtime = os.path.getmtime(file_path)
+        except OSError:
+            notices.append(
+                ChangedFileNotice(
+                    file_path=file_path, summary="File was deleted or is no longer accessible."
+                )
+            )
+            cache.pop(file_path, None)
+            continue
+
+        if current_mtime <= snapshot.timestamp:
+            continue
+
+        try:
+            new_content = _read_portion(file_path, snapshot.offset, snapshot.limit)
+        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(
+                    file_path=file_path,
+                    summary=f"File changed but could not be read: {exc}",
+                )
+            )
+            # Avoid spamming repeated errors by updating timestamp.
+            snapshot.timestamp = current_mtime
+            cache[file_path] = snapshot
+            continue
+
+        diff_summary = _build_diff_summary(
+            snapshot.content, new_content, file_path, max_lines=max_diff_lines
+        )
+        notices.append(ChangedFileNotice(file_path=file_path, summary=diff_summary))
+        # Update snapshot so we only notify on subsequent changes.
+        record_snapshot(
+            file_path,
+            new_content,
+            cache,
+            offset=snapshot.offset,
+            limit=snapshot.limit,
+        )
+
+    return notices