ripperdoc 0.1.0__py3-none-any.whl

ripperdoc/utils/messages.py

@@ -0,0 +1,399 @@
+"""Message handling and formatting for Ripperdoc.
+
+This module provides utilities for creating and normalizing messages
+for communication with AI models.
+"""
+
+from typing import Any, Dict, List, Optional, Union
+from pydantic import BaseModel, ConfigDict
+from uuid import uuid4
+from enum import Enum
+from ripperdoc.utils.log import get_logger
+
+logger = get_logger()
+
+
+class MessageRole(str, Enum):
+    """Message roles in a conversation."""
+
+    USER = "user"
+    ASSISTANT = "assistant"
+    SYSTEM = "system"
+
+
+class MessageContent(BaseModel):
+    """Content of a message."""
+
+    type: str
+    text: Optional[str] = None
+    # Some providers return tool_use IDs as "id", others as "tool_use_id"
+    id: Optional[str] = None
+    tool_use_id: Optional[str] = None
+    name: Optional[str] = None
+    input: Optional[Dict[str, Any]] = None
+    is_error: Optional[bool] = None
+
+
+def _content_block_to_api(block: MessageContent) -> Dict[str, Any]:
+    """Convert a MessageContent block to API-ready dict for tool protocols."""
+    block_type = getattr(block, "type", None)
+    if block_type == "tool_use":
+        return {
+            "type": "tool_use",
+            "id": getattr(block, "id", None) or getattr(block, "tool_use_id", "") or "",
+            "name": getattr(block, "name", None) or "",
+            "input": getattr(block, "input", None) or {},
+        }
+    if block_type == "tool_result":
+        result: Dict[str, Any] = {
+            "type": "tool_result",
+            "tool_use_id": getattr(block, "tool_use_id", None) or getattr(block, "id", None) or "",
+            "content": [
+                {
+                    "type": "text",
+                    "text": getattr(block, "text", None) or getattr(block, "content", None) or "",
+                }
+            ],
+        }
+        if getattr(block, "is_error", None) is not None:
+            result["is_error"] = block.is_error
+        return result
+    # Default to text block
+    return {
+        "type": "text",
+        "text": getattr(block, "text", None) or getattr(block, "content", None) or str(block),
+    }
+
+
+def _content_block_to_openai(block: MessageContent) -> Dict[str, Any]:
+    """Convert a MessageContent block to OpenAI chat-completions tool call format."""
+    block_type = getattr(block, "type", None)
+    if block_type == "tool_use":
+        import json
+
+        args = getattr(block, "input", None) or {}
+        try:
+            args_str = json.dumps(args)
+        except Exception:
+            args_str = "{}"
+        tool_call_id = (
+            getattr(block, "id", None) or getattr(block, "tool_use_id", "") or str(uuid4())
+        )
+        return {
+            "role": "assistant",
+            "content": None,
+            "tool_calls": [
+                {
+                    "id": tool_call_id,
+                    "type": "function",
+                    "function": {
+                        "name": getattr(block, "name", None) or "",
+                        "arguments": args_str,
+                    },
+                }
+            ],
+        }
+    if block_type == "tool_result":
+        # OpenAI expects role=tool messages after a tool call
+        tool_call_id = getattr(block, "tool_use_id", None) or getattr(block, "id", None) or ""
+        if not tool_call_id:
+            logger.debug("[_content_block_to_openai] Skipping tool_result without tool_call_id")
+            return {}
+        return {
+            "role": "tool",
+            "tool_call_id": tool_call_id,
+            "content": getattr(block, "text", None) or getattr(block, "content", None) or "",
+        }
+    # Fallback text message
+    return {
+        "role": "assistant",
+        "content": getattr(block, "text", None) or getattr(block, "content", None) or str(block),
+    }
+
+
+class Message(BaseModel):
+    """A message in a conversation."""
+
+    role: MessageRole
+    content: Union[str, List[MessageContent]]
+    uuid: str = ""
+
+    def __init__(self, **data: Any) -> None:
+        if "uuid" not in data or not data["uuid"]:
+            data["uuid"] = str(uuid4())
+        super().__init__(**data)
+
+
+class UserMessage(BaseModel):
+    """User message with tool results."""
+
+    type: str = "user"
+    message: Message
+    uuid: str = ""
+    tool_use_result: Optional[Any] = None
+
+    def __init__(self, **data: Any) -> None:
+        if "uuid" not in data or not data["uuid"]:
+            data["uuid"] = str(uuid4())
+        super().__init__(**data)
+
+
+class AssistantMessage(BaseModel):
+    """Assistant message with metadata."""
+
+    type: str = "assistant"
+    message: Message
+    uuid: str = ""
+    cost_usd: float = 0.0
+    duration_ms: float = 0.0
+    is_api_error_message: bool = False
+
+    def __init__(self, **data: Any) -> None:
+        if "uuid" not in data or not data["uuid"]:
+            data["uuid"] = str(uuid4())
+        super().__init__(**data)
+
+
+class ProgressMessage(BaseModel):
+    """Progress message during tool execution."""
+
+    type: str = "progress"
+    uuid: str = ""
+    tool_use_id: str
+    content: Any
+    normalized_messages: List[Message] = []
+    sibling_tool_use_ids: set[str] = set()
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    def __init__(self, **data: Any) -> None:
+        if "uuid" not in data or not data["uuid"]:
+            data["uuid"] = str(uuid4())
+        super().__init__(**data)
+
+
+def create_user_message(
+    content: Union[str, List[Dict[str, Any]]], tool_use_result: Optional[Any] = None
+) -> UserMessage:
+    """Create a user message."""
+    if isinstance(content, str):
+        message_content: Union[str, List[MessageContent]] = content
+    else:
+        message_content = [MessageContent(**item) for item in content]
+
+    # Normalize tool_use_result to a dict if it's a Pydantic model
+    if tool_use_result is not None:
+        try:
+            if hasattr(tool_use_result, "model_dump"):
+                tool_use_result = tool_use_result.model_dump()
+        except Exception:
+            # Fallback: keep as-is if conversion fails
+            pass
+
+    message = Message(role=MessageRole.USER, content=message_content)
+
+    # Debug: record tool_result shaping
+    if isinstance(message_content, list):
+        tool_result_blocks = [
+            blk for blk in message_content if getattr(blk, "type", None) == "tool_result"
+        ]
+        if tool_result_blocks:
+            logger.debug(
+                f"[create_user_message] tool_result blocks={len(tool_result_blocks)} "
+                f"ids={[getattr(b, 'tool_use_id', None) for b in tool_result_blocks]}"
+            )
+
+    return UserMessage(message=message, tool_use_result=tool_use_result)
+
+
+def create_assistant_message(
+    content: Union[str, List[Dict[str, Any]]], cost_usd: float = 0.0, duration_ms: float = 0.0
+) -> AssistantMessage:
+    """Create an assistant message."""
+    if isinstance(content, str):
+        message_content: Union[str, List[MessageContent]] = content
+    else:
+        message_content = [MessageContent(**item) for item in content]
+
+    message = Message(role=MessageRole.ASSISTANT, content=message_content)
+
+    return AssistantMessage(message=message, cost_usd=cost_usd, duration_ms=duration_ms)
+
+
+def create_progress_message(
+    tool_use_id: str,
+    sibling_tool_use_ids: set[str],
+    content: Any,
+    normalized_messages: Optional[List[Message]] = None,
+) -> ProgressMessage:
+    """Create a progress message."""
+    return ProgressMessage(
+        tool_use_id=tool_use_id,
+        sibling_tool_use_ids=sibling_tool_use_ids,
+        content=content,
+        normalized_messages=normalized_messages or [],
+    )
+
+
+def normalize_messages_for_api(
+    messages: List[Union[UserMessage, AssistantMessage, ProgressMessage]],
+    protocol: str = "anthropic",
+) -> List[Dict[str, Any]]:
+    """Normalize messages for API submission.
+
+    Progress messages are filtered out as they are not sent to the API.
+    """
+
+    def _msg_type(msg: Any) -> Optional[str]:
+        if hasattr(msg, "type"):
+            return getattr(msg, "type", None)
+        if isinstance(msg, dict):
+            return msg.get("type")
+        return None
+
+    def _msg_content(msg: Any) -> Any:
+        if hasattr(msg, "message"):
+            return getattr(getattr(msg, "message", None), "content", None)
+        if isinstance(msg, dict):
+            message_payload = msg.get("message")
+            if isinstance(message_payload, dict):
+                return message_payload.get("content")
+            if "content" in msg:
+                return msg.get("content")
+        return None
+
+    normalized: List[Dict[str, Any]] = []
+    tool_results_seen = 0
+    tool_uses_seen = 0
+
+    # Precompute tool_result positions so we can drop dangling tool_calls that
+    # lack a following tool response (which OpenAI rejects).
+    tool_result_positions: Dict[str, int] = {}
+    skipped_tool_uses_no_result = 0
+    skipped_tool_uses_no_id = 0
+    if protocol == "openai":
+        for idx, msg in enumerate(messages):
+            if _msg_type(msg) != "user":
+                continue
+            content = _msg_content(msg)
+            if not isinstance(content, list):
+                continue
+            for block in content:
+                if getattr(block, "type", None) == "tool_result":
+                    tool_id = getattr(block, "tool_use_id", None) or getattr(block, "id", None)
+                    if tool_id and tool_id not in tool_result_positions:
+                        tool_result_positions[tool_id] = idx
+
+    for msg_index, msg in enumerate(messages):
+        msg_type = _msg_type(msg)
+        if msg_type == "progress":
+            # Skip progress messages
+            continue
+        if msg_type is None:
+            continue
+
+        if msg_type == "user":
+            user_content = _msg_content(msg)
+            if isinstance(user_content, list):
+                if protocol == "openai":
+                    # Map each block to an OpenAI-style message
+                    openai_msgs: List[Dict[str, Any]] = []
+                    for block in user_content:
+                        if getattr(block, "type", None) == "tool_result":
+                            tool_results_seen += 1
+                        mapped = _content_block_to_openai(block)
+                        if mapped:
+                            openai_msgs.append(mapped)
+                    normalized.extend(openai_msgs)
+                    continue
+                api_blocks = []
+                for block in user_content:
+                    if getattr(block, "type", None) == "tool_result":
+                        tool_results_seen += 1
+                    api_blocks.append(_content_block_to_api(block))
+                normalized.append({"role": "user", "content": api_blocks})
+            else:
+                normalized.append(
+                    {"role": "user", "content": user_content}  # type: ignore
+                )
+        elif msg_type == "assistant":
+            asst_content = _msg_content(msg)
+            if isinstance(asst_content, list):
+                if protocol == "openai":
+                    assistant_openai_msgs: List[Dict[str, Any]] = []
+                    tool_calls: List[Dict[str, Any]] = []
+                    text_parts: List[str] = []
+                    for block in asst_content:
+                        if getattr(block, "type", None) == "tool_use":
+                            tool_uses_seen += 1
+                            tool_id = getattr(block, "tool_use_id", None) or getattr(
+                                block, "id", None
+                            )
+                            if not tool_id:
+                                skipped_tool_uses_no_id += 1
+                                continue
+                            # Skip tool_use blocks that are not followed by a tool_result
+                            result_pos = tool_result_positions.get(tool_id)
+                            if result_pos is None:
+                                skipped_tool_uses_no_result += 1
+                                continue
+                            if result_pos <= msg_index:
+                                skipped_tool_uses_no_result += 1
+                                continue
+                            mapped = _content_block_to_openai(block)
+                            if mapped.get("tool_calls"):
+                                tool_calls.extend(mapped["tool_calls"])
+                        elif getattr(block, "type", None) == "text":
+                            text_parts.append(getattr(block, "text", "") or "")
+                        else:
+                            mapped = _content_block_to_openai(block)
+                            if mapped:
+                                assistant_openai_msgs.append(mapped)
+                    if text_parts:
+                        assistant_openai_msgs.append(
+                            {"role": "assistant", "content": "\n".join(text_parts)}
+                        )
+                    if tool_calls:
+                        assistant_openai_msgs.append(
+                            {
+                                "role": "assistant",
+                                "content": None,
+                                "tool_calls": tool_calls,
+                            }
+                        )
+                    normalized.extend(assistant_openai_msgs)
+                    continue
+                api_blocks = []
+                for block in asst_content:
+                    if getattr(block, "type", None) == "tool_use":
+                        tool_uses_seen += 1
+                    api_blocks.append(_content_block_to_api(block))
+                normalized.append({"role": "assistant", "content": api_blocks})
+            else:
+                normalized.append(
+                    {"role": "assistant", "content": asst_content}  # type: ignore
+                )
+
+    logger.debug(
+        f"[normalize_messages_for_api] protocol={protocol} input_msgs={len(messages)} "
+        f"normalized={len(normalized)} tool_results_seen={tool_results_seen} "
+        f"tool_uses_seen={tool_uses_seen} "
+        f"tool_result_positions={len(tool_result_positions)} "
+        f"skipped_tool_uses_no_result={skipped_tool_uses_no_result} "
+        f"skipped_tool_uses_no_id={skipped_tool_uses_no_id}"
+    )
+    return normalized
+
+
+# Special interrupt messages
+INTERRUPT_MESSAGE = "Request was interrupted by user."
+INTERRUPT_MESSAGE_FOR_TOOL_USE = "Tool execution was interrupted by user."
+
+
+def create_tool_result_stop_message(tool_use_id: str) -> Dict[str, Any]:
+    """Create a tool result message for interruption."""
+    return {
+        "type": "tool_result",
+        "tool_use_id": tool_use_id,
+        "text": INTERRUPT_MESSAGE_FOR_TOOL_USE,
+        "is_error": True,
+    }

ripperdoc/utils/output_utils.py

@@ -0,0 +1,233 @@
+"""Utilities for processing and truncating command output."""
+
+import re
+from typing import Any
+
+
+# Maximum output length to prevent token overflow
+MAX_OUTPUT_CHARS = 30000
+
+# Threshold for considering output "large"
+LARGE_OUTPUT_THRESHOLD = 5000
+
+# When truncating, keep this many chars from start and end
+TRUNCATE_KEEP_START = 15000
+TRUNCATE_KEEP_END = 10000
+
+
+def trim_blank_lines(text: str) -> str:
+    """Remove leading and trailing blank lines while preserving internal spacing.
+
+    Args:
+        text: Input text
+
+    Returns:
+        Text with leading/trailing blank lines removed
+    """
+    lines = text.split("\n")
+
+    # Remove leading blank lines
+    start = 0
+    while start < len(lines) and not lines[start].strip():
+        start += 1
+
+    # Remove trailing blank lines
+    end = len(lines)
+    while end > start and not lines[end - 1].strip():
+        end -= 1
+
+    return "\n".join(lines[start:end])
+
+
+def is_image_data(text: str) -> bool:
+    """Check if text appears to be base64 encoded image data.
+
+    Args:
+        text: Text to check
+
+    Returns:
+        True if text looks like image data
+    """
+    if not text:
+        return False
+
+    stripped = text.strip()
+
+    # Check for data URI scheme (most reliable indicator)
+    if stripped.startswith("data:image/"):
+        return True
+
+    # Don't treat arbitrary long text as base64 unless it has image indicators
+    # Base64 images are typically very long AND have specific characteristics
+    if len(stripped) < 1000:
+        return False
+
+    # Check for common image base64 patterns
+    # Real base64 images usually have variety of characters and padding
+    base64_chars = set("ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/=")
+    text_chars = set(stripped)
+
+    # If text only uses a small subset of base64 chars, it's probably not base64
+    # Real base64 uses a variety of characters
+    if len(text_chars) < 10:
+        return False
+
+    # Must be valid base64 characters
+    if not text_chars.issubset(base64_chars):
+        return False
+
+    # Must end with proper base64 padding or no padding
+    if not (
+        stripped.endswith("==")
+        or stripped.endswith("=")
+        or stripped[-1] in "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/"
+    ):
+        return False
+
+    # If all checks pass and it's very long, might be base64 image
+    return len(stripped) > 10000
+
+
+def truncate_output(text: str, max_chars: int = MAX_OUTPUT_CHARS) -> dict[str, Any]:
+    """Truncate output if it exceeds max length.
+
+    Keeps both the beginning and end of output to preserve context.
+
+    Args:
+        text: Output text to truncate
+        max_chars: Maximum character limit
+
+    Returns:
+        Dict with:
+            - truncated_content: Potentially truncated text
+            - is_truncated: Whether truncation occurred
+            - original_length: Original text length
+            - is_image: Whether content appears to be image data
+    """
+    if not text:
+        return {
+            "truncated_content": text,
+            "is_truncated": False,
+            "original_length": 0,
+            "is_image": False,
+        }
+
+    # Check if it's image data
+    if is_image_data(text):
+        return {
+            "truncated_content": text,
+            "is_truncated": False,
+            "original_length": len(text),
+            "is_image": True,
+        }
+
+    original_length = len(text)
+
+    if original_length <= max_chars:
+        return {
+            "truncated_content": text,
+            "is_truncated": False,
+            "original_length": original_length,
+            "is_image": False,
+        }
+
+    # Truncate: keep start and end
+    start_chars = min(TRUNCATE_KEEP_START, max_chars // 2)
+    end_chars = min(TRUNCATE_KEEP_END, max_chars - start_chars - 100)
+
+    truncated = (
+        text[:start_chars]
+        + f"\n\n... [Output truncated: {original_length - start_chars - end_chars} characters omitted] ...\n\n"
+        + text[-end_chars:]
+    )
+
+    return {
+        "truncated_content": truncated,
+        "is_truncated": True,
+        "original_length": original_length,
+        "is_image": False,
+    }
+
+
+def format_duration(duration_ms: float) -> str:
+    """Format duration in milliseconds to human-readable string.
+
+    Args:
+        duration_ms: Duration in milliseconds
+
+    Returns:
+        Formatted duration string (e.g., "1.23s", "45.6ms")
+    """
+    if duration_ms < 1000:
+        return f"{duration_ms:.0f}ms"
+    else:
+        return f"{duration_ms / 1000:.2f}s"
+
+
+def is_output_large(text: str) -> bool:
+    """Check if output is considered large.
+
+    Args:
+        text: Output text
+
+    Returns:
+        True if output exceeds large threshold
+    """
+    return len(text) > LARGE_OUTPUT_THRESHOLD
+
+
+def count_lines(text: str) -> int:
+    """Count number of lines in text.
+
+    Args:
+        text: Text to count
+
+    Returns:
+        Number of lines
+    """
+    if not text:
+        return 0
+    return text.count("\n") + 1
+
+
+def get_last_n_lines(text: str, n: int) -> str:
+    """Get the last N lines from text.
+
+    Args:
+        text: Input text
+        n: Number of lines to keep
+
+    Returns:
+        Last N lines
+    """
+    if not text:
+        return text
+
+    lines = text.split("\n")
+    if len(lines) <= n:
+        return text
+
+    return "\n".join(lines[-n:])
+
+
+def sanitize_output(text: str) -> str:
+    """Sanitize output by removing control/escape sequences and ensuring UTF-8."""
+    # ANSI/VT escape patterns, including charset selection (e.g., ESC(B) and OSC)
+    ansi_escape = re.compile(
+        r"""
+        \x1B
+        (?:
+            [@-Z\\-_]                      # 7-bit C1 control
+          | \[ [0-?]* [ -/]* [@-~]         # CSI (colors, cursor moves, etc.)
+          | [()][0-9A-Za-z]                # Charset selection like ESC(B
+          | \] (?: [^\x07\x1B]* \x07 | [^\x1B]* \x1B\\ )  # OSC to BEL or ST
+        )
+        """,
+        re.VERBOSE,
+    )
+    text = ansi_escape.sub("", text)
+
+    # Remove remaining control characters except newline, tab, carriage return
+    text = re.sub(r"[\x00-\x08\x0B\x0C\x0E-\x1F\x7F]", "", text)
+
+    return text

ripperdoc/utils/path_utils.py

@@ -0,0 +1,46 @@
+"""Filesystem path helpers."""
+
+from __future__ import annotations
+
+import hashlib
+import re
+from pathlib import Path
+
+
+def _legacy_sanitize_project_path(project_path: Path) -> str:
+    """Legacy sanitizer that strips non-alphanumeric characters."""
+    normalized = str(project_path.resolve())
+    return re.sub(r"[^a-zA-Z0-9]+", "-", normalized).strip("-") or "project"
+
+
+def sanitize_project_path(project_path: Path) -> str:
+    """Make a project path safe for directory names and avoid collisions.
+
+    Non-alphanumeric characters (including non-ASCII) are replaced with "-".
+    A short hash of the full resolved path is appended to prevent collisions
+    between different paths that would otherwise sanitize to the same string.
+    """
+    normalized = str(project_path.resolve())
+    safe = _legacy_sanitize_project_path(project_path)
+    digest = hashlib.sha1(normalized.encode("utf-8")).hexdigest()[:8]
+    return f"{safe}-{digest}"
+
+
+def project_storage_dir(base_dir: Path, project_path: Path, ensure: bool = False) -> Path:
+    """Return a storage directory path for a project, with legacy fallback.
+
+    Prefers a hashed, collision-safe name but will reuse an existing legacy
+    directory (pre-hash) to avoid stranding older data.
+    """
+    hashed_name = sanitize_project_path(project_path)
+    legacy_name = _legacy_sanitize_project_path(project_path)
+
+    hashed_dir = base_dir / hashed_name
+    legacy_dir = base_dir / legacy_name
+
+    chosen = hashed_dir if hashed_dir.exists() or not legacy_dir.exists() else legacy_dir
+
+    if ensure:
+        chosen.mkdir(parents=True, exist_ok=True)
+
+    return chosen

ripperdoc/utils/permissions/__init__.py

@@ -0,0 +1,21 @@
+"""Permission utilities."""
+
+from .path_validation_utils import validate_shell_command_paths
+from .shell_command_validation import validate_shell_command
+from .tool_permission_utils import (
+    PermissionDecision,
+    ToolRule,
+    evaluate_shell_command_permissions,
+    extract_rule_prefix,
+    match_rule,
+)
+
+__all__ = [
+    "PermissionDecision",
+    "ToolRule",
+    "evaluate_shell_command_permissions",
+    "extract_rule_prefix",
+    "match_rule",
+    "validate_shell_command_paths",
+    "validate_shell_command",
+]