ripperdoc 0.2.10__py3-none-any.whl → 0.3.1__py3-none-any.whl

ripperdoc/core/query_utils.py

@@ -125,20 +125,23 @@ def estimate_cost_usd(model_profile: ModelProfile, usage_tokens: Dict[str, int])
 
 
 def resolve_model_profile(model: str) -> ModelProfile:
-    """Resolve a model pointer to a concrete profile, falling back to a safe default."""
-    config = get_global_config()
-    profile_name = getattr(config.model_pointers, model, None) or model
-    model_profile = config.model_profiles.get(profile_name)
-    if model_profile is None:
-        fallback_profile = getattr(config.model_pointers, "main", "default")
-        model_profile = config.model_profiles.get(fallback_profile)
-    if not model_profile:
-        logger.warning(
-            "[config] No model profile found; using built-in default profile",
-            extra={"model_pointer": model},
-        )
-        return ModelProfile(provider=ProviderType.OPENAI_COMPATIBLE, model="gpt-4o-mini")
-    return model_profile
+    """Resolve a model pointer to a concrete profile, falling back to a safe default.
+
+    此函数现在尊重 RIPPERDOC_* 环境变量的覆盖。
+    """
+    from ripperdoc.core.config import get_effective_model_profile
+
+    # 首先尝试使用 get_effective_model_profile 来应用环境变量覆盖
+    model_profile = get_effective_model_profile(model)
+    if model_profile:
+        return model_profile
+
+    # 如果仍然没有找到，使用默认配置
+    logger.warning(
+        "[config] No model profile found; using built-in default profile",
+        extra={"model_pointer": model},
+    )
+    return ModelProfile(provider=ProviderType.OPENAI_COMPATIBLE, model="gpt-4o-mini")
 
 
 def determine_tool_mode(model_profile: ModelProfile) -> str:

ripperdoc/core/skills.py

@@ -278,6 +278,7 @@ def build_skill_summary(skills: Sequence[SkillDefinition]) -> str:
     lines = [
         "# Skills",
         "Skills extend your capabilities with reusable instructions stored in SKILL.md files.",
+        "IMPORTANT: To use a skill, you MUST call the Skill tool. Do NOT read SKILL.md files directly with Read, Glob, Grep, or Bash commands.",
         'Call the Skill tool with {"skill": "<name>"} to load a skill when it matches the user request.',
         "Available skills:",
     ]

ripperdoc/core/theme.py

@@ -0,0 +1,298 @@
+"""Theme system for Ripperdoc CLI.
+
+Provides color theming support with predefined themes and runtime switching.
+"""
+
+from dataclasses import dataclass, field
+from typing import Callable, Dict, List, Optional
+
+
+@dataclass
+class ThemeColors:
+    """Theme color definitions - all semantic color slots."""
+
+    # === Brand/Primary colors ===
+    primary: str = "cyan"  # Main accent (brand, borders, spinner)
+    secondary: str = "green"  # Secondary accent (success, ready status)
+
+    # === Semantic colors ===
+    success: str = "green"
+    warning: str = "yellow"
+    error: str = "red"
+    info: str = "blue"
+
+    # === Text colors ===
+    text_primary: str = "white"
+    text_secondary: str = "dim"  # dim/grey for secondary text
+    text_muted: str = "grey50"
+
+    # === UI elements ===
+    border: str = "cyan"
+    spinner: str = "cyan"
+    prompt: str = "bold green"
+
+    # === Tool output ===
+    tool_call: str = "dim cyan"
+    tool_result: str = "dim"
+
+    # === Message senders ===
+    sender_user: str = "bold green"
+    sender_assistant: str = "white"
+    sender_system: str = "dim cyan"
+
+    # === Context visualization ===
+    ctx_system_prompt: str = "grey58"
+    ctx_mcp: str = "cyan"
+    ctx_tools: str = "green3"
+    ctx_memory: str = "dark_orange3"
+    ctx_messages: str = "medium_purple"
+    ctx_free: str = "grey46"
+    ctx_reserved: str = "yellow3"
+
+    # === Thinking mode ===
+    thinking_on: str = "ansicyan bold"
+    thinking_off: str = "ansibrightblack"
+    thinking_content: str = "dim italic"
+
+    # === Headings and emphasis ===
+    heading: str = "bold"
+    emphasis: str = "bold cyan"
+
+
+@dataclass
+class Theme:
+    """Complete theme definition."""
+
+    name: str
+    display_name: str
+    description: str
+    colors: ThemeColors = field(default_factory=ThemeColors)
+
+    def get_color(self, slot: str) -> str:
+        """Get color for a specific slot."""
+        return getattr(self.colors, slot, "white")
+
+
+# === Predefined themes ===
+
+THEME_DARK = Theme(
+    name="dark",
+    display_name="Dark",
+    description="Default dark theme with cyan accents",
+    colors=ThemeColors(),
+)
+
+THEME_LIGHT = Theme(
+    name="light",
+    display_name="Light",
+    description="Light theme for bright terminals",
+    colors=ThemeColors(
+        primary="blue",
+        secondary="green",
+        text_primary="black",
+        text_secondary="grey37",
+        text_muted="grey50",
+        border="blue",
+        spinner="blue",
+        tool_call="dim blue",
+        sender_user="bold blue",
+        ctx_system_prompt="grey37",
+        ctx_free="grey62",
+        thinking_on="ansiblue bold",
+        thinking_off="grey50",
+        emphasis="bold blue",
+    ),
+)
+
+THEME_MONOKAI = Theme(
+    name="monokai",
+    display_name="Monokai",
+    description="Monokai-inspired color scheme",
+    colors=ThemeColors(
+        primary="#f92672",  # Monokai pink
+        secondary="#a6e22e",  # Monokai green
+        warning="#e6db74",  # Monokai yellow
+        error="#f92672",  # Monokai pink
+        info="#66d9ef",  # Monokai cyan
+        border="#f92672",
+        spinner="#66d9ef",
+        tool_call="#75715e",  # Monokai comment
+        sender_user="#a6e22e",
+        emphasis="#f92672",
+        ctx_mcp="#66d9ef",
+        ctx_tools="#a6e22e",
+        ctx_memory="#fd971f",  # Monokai orange
+        ctx_messages="#ae81ff",  # Monokai purple
+    ),
+)
+
+THEME_DRACULA = Theme(
+    name="dracula",
+    display_name="Dracula",
+    description="Dracula color scheme",
+    colors=ThemeColors(
+        primary="#bd93f9",  # Dracula purple
+        secondary="#50fa7b",  # Dracula green
+        warning="#f1fa8c",  # Dracula yellow
+        error="#ff5555",  # Dracula red
+        info="#8be9fd",  # Dracula cyan
+        border="#bd93f9",
+        spinner="#bd93f9",
+        tool_call="#6272a4",  # Dracula comment
+        sender_user="#50fa7b",
+        emphasis="#ff79c6",  # Dracula pink
+        ctx_mcp="#8be9fd",
+        ctx_tools="#50fa7b",
+        ctx_memory="#ffb86c",  # Dracula orange
+        ctx_messages="#bd93f9",
+    ),
+)
+
+THEME_SOLARIZED_DARK = Theme(
+    name="solarized_dark",
+    display_name="Solarized Dark",
+    description="Solarized dark color scheme",
+    colors=ThemeColors(
+        primary="#268bd2",  # Solarized blue
+        secondary="#859900",  # Solarized green
+        warning="#b58900",  # Solarized yellow
+        error="#dc322f",  # Solarized red
+        info="#2aa198",  # Solarized cyan
+        text_secondary="#586e75",  # Solarized base01
+        border="#268bd2",
+        spinner="#2aa198",
+        emphasis="#268bd2",
+        ctx_mcp="#2aa198",
+        ctx_tools="#859900",
+        ctx_memory="#cb4b16",  # Solarized orange
+        ctx_messages="#6c71c4",  # Solarized violet
+    ),
+)
+
+THEME_NORD = Theme(
+    name="nord",
+    display_name="Nord",
+    description="Arctic, bluish color scheme",
+    colors=ThemeColors(
+        primary="#88c0d0",  # Nord frost
+        secondary="#a3be8c",  # Nord green
+        warning="#ebcb8b",  # Nord yellow
+        error="#bf616a",  # Nord red
+        info="#81a1c1",  # Nord blue
+        text_secondary="#4c566a",  # Nord polar night
+        border="#88c0d0",
+        spinner="#88c0d0",
+        emphasis="#88c0d0",
+        ctx_mcp="#81a1c1",
+        ctx_tools="#a3be8c",
+        ctx_memory="#d08770",  # Nord orange
+        ctx_messages="#b48ead",  # Nord purple
+    ),
+)
+
+# Theme registry
+BUILTIN_THEMES: Dict[str, Theme] = {
+    "dark": THEME_DARK,
+    "light": THEME_LIGHT,
+    "monokai": THEME_MONOKAI,
+    "dracula": THEME_DRACULA,
+    "solarized_dark": THEME_SOLARIZED_DARK,
+    "nord": THEME_NORD,
+}
+
+
+class ThemeManager:
+    """Theme manager - singleton pattern."""
+
+    _instance: Optional["ThemeManager"] = None
+    _current_theme: Theme
+    _listeners: List[Callable[["Theme"], None]]
+
+    def __new__(cls) -> "ThemeManager":
+        if cls._instance is None:
+            cls._instance = super().__new__(cls)
+            cls._instance._current_theme = THEME_DARK
+            cls._instance._listeners = []
+        return cls._instance
+
+    @property
+    def current(self) -> Theme:
+        """Get current theme."""
+        return self._current_theme
+
+    def set_theme(self, theme_name: str) -> bool:
+        """Set theme by name (does not persist)."""
+        theme = BUILTIN_THEMES.get(theme_name)
+        if theme:
+            self._current_theme = theme
+            self._notify_listeners()
+            return True
+        return False
+
+    def get_color(self, slot: str) -> str:
+        """Get color for a slot from current theme."""
+        return self._current_theme.get_color(slot)
+
+    def add_listener(self, callback: Callable[["Theme"], None]) -> None:
+        """Add a theme change listener."""
+        self._listeners.append(callback)
+
+    def remove_listener(self, callback: Callable[["Theme"], None]) -> None:
+        """Remove a theme change listener."""
+        if callback in self._listeners:
+            self._listeners.remove(callback)
+
+    def _notify_listeners(self) -> None:
+        """Notify all listeners of theme change."""
+        for listener in self._listeners:
+            try:
+                listener(self._current_theme)
+            except Exception:
+                pass  # Don't let listener errors break theme switching
+
+    def list_themes(self) -> List[str]:
+        """List all available theme names."""
+        return list(BUILTIN_THEMES.keys())
+
+
+# Global accessor functions
+_theme_manager: Optional[ThemeManager] = None
+
+
+def get_theme_manager() -> ThemeManager:
+    """Get the global theme manager instance."""
+    global _theme_manager
+    if _theme_manager is None:
+        _theme_manager = ThemeManager()
+    return _theme_manager
+
+
+def theme_color(slot: str) -> str:
+    """Convenience function: get color for a slot from current theme."""
+    return get_theme_manager().get_color(slot)
+
+
+def styled(text: str, slot: str) -> str:
+    """Convenience function: wrap text with theme color markup."""
+    color = theme_color(slot)
+    # Handle colors that already include style modifiers (like "bold cyan")
+    if " " in color:
+        return f"[{color}]{text}[/]"
+    return f"[{color}]{text}[/{color}]"
+
+
+def get_current_theme() -> Theme:
+    """Get the current active theme."""
+    return get_theme_manager().current
+
+
+__all__ = [
+    "Theme",
+    "ThemeColors",
+    "ThemeManager",
+    "BUILTIN_THEMES",
+    "get_theme_manager",
+    "theme_color",
+    "styled",
+    "get_current_theme",
+]

ripperdoc/core/tool.py

@@ -10,6 +10,7 @@ from typing import Annotated, Any, AsyncGenerator, Dict, List, Optional, TypeVar
 from pydantic import BaseModel, ConfigDict, Field, SkipValidation
 from ripperdoc.utils.file_watch import FileCacheType
 from ripperdoc.utils.log import get_logger
+from ripperdoc.utils.pending_messages import PendingMessageQueue
 
 
 logger = get_logger()
@@ -30,6 +31,8 @@ class ToolProgress(BaseModel):
     content: Any
     normalized_messages: list = []
     tools: list = []
+    # Flag to indicate if content is a subagent message that should be forwarded to SDK
+    is_subagent_message: bool = False
 
 
 class ToolUseContext(BaseModel):
@@ -44,9 +47,7 @@ class ToolUseContext(BaseModel):
     # SkipValidation prevents Pydantic from copying the cache during validation,
     # ensuring Read and Edit tools share the same cache instance.
     # FileCacheType supports both Dict[str, FileSnapshot] and BoundedFileCache.
-    file_state_cache: Annotated[FileCacheType, SkipValidation] = Field(
-        default_factory=dict
-    )
+    file_state_cache: Annotated[FileCacheType, SkipValidation] = Field(default_factory=dict)
     conversation_messages: Annotated[Optional[List[Any]], SkipValidation] = Field(
         default=None,
         description="Full conversation history for tools that need parent context.",
@@ -60,6 +61,10 @@ class ToolUseContext(BaseModel):
     on_exit_plan_mode: Optional[Any] = Field(
         default=None, description="Callback invoked when exiting plan mode"
     )
+    pending_message_queue: Annotated[Optional[PendingMessageQueue], SkipValidation] = Field(
+        default=None,
+        description="Queue for pending conversation messages (background notices or user interjections).",
+    )
     model_config = ConfigDict(arbitrary_types_allowed=True)
 
 

ripperdoc/protocol/__init__.py

@@ -0,0 +1,14 @@
+"""SDK communication protocol modules.
+
+This package contains protocol handlers for communication between
+Ripperdoc CLI and external SDKs.
+"""
+
+from ripperdoc.protocol.stdio import stdio_cmd, StdioProtocolHandler
+from ripperdoc.protocol import models
+
+__all__ = [
+    "stdio_cmd",
+    "StdioProtocolHandler",
+    "models",
+]

ripperdoc/protocol/models.py

@@ -0,0 +1,300 @@
+"""Pydantic models for stdio protocol messages.
+
+This module defines type-safe models for all JSON messages exchanged
+over the stdio protocol, replacing raw dictionary construction with
+validated, self-documenting Pydantic models.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Literal
+from pydantic import BaseModel, Field, ConfigDict
+
+
+# ============================================================================
+# Content Block Models
+# ============================================================================
+
+
+class ContentBlock(BaseModel):
+    """Base class for content blocks in messages."""
+
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+
+
+class TextContentBlock(ContentBlock):
+    """A text content block."""
+
+    type: Literal["text"] = "text"
+    text: str
+
+
+class ThinkingContentBlock(ContentBlock):
+    """A thinking/reasoning content block."""
+
+    type: str = Field(default="thinking")
+    thinking: str = Field(alias="text")
+    signature: str | None = None
+
+
+class ToolUseContentBlock(ContentBlock):
+    """A tool use content block."""
+
+    type: str = Field(default="tool_use")
+    id: str = Field(default="")
+    name: str
+    input: dict[str, Any] = Field(default_factory=dict)
+
+
+class ToolResultContentBlock(ContentBlock):
+    """A tool result content block."""
+
+    type: str = Field(default="tool_result")
+    tool_use_id: str = Field(default="")
+    content: str = Field(default="")
+    is_error: bool | None = None
+
+
+class ImageSource(BaseModel):
+    """Image source data."""
+
+    type: str = Field(default="base64")
+    media_type: str = Field(default="image/jpeg")
+    data: str
+
+
+class ImageContentBlock(ContentBlock):
+    """An image content block."""
+
+    type: str = Field(default="image")
+    source: ImageSource
+
+
+# Union type for all content blocks
+ContentBlockType = (
+    TextContentBlock
+    | ThinkingContentBlock
+    | ToolUseContentBlock
+    | ToolResultContentBlock
+    | ImageContentBlock
+)
+
+
+# ============================================================================
+# Message Models
+# ============================================================================
+
+
+class MessageData(BaseModel):
+    """Base message data."""
+
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+
+
+class AssistantMessageData(MessageData):
+    """Assistant message data."""
+
+    content: list[dict[str, Any]] | str
+    model: str = "main"
+
+
+class UserMessageData(MessageData):
+    """User message data."""
+
+    content: str = ""
+
+
+class AssistantStreamMessage(BaseModel):
+    """An assistant message sent to the SDK."""
+
+    type: str = Field(default="assistant")
+    message: AssistantMessageData
+    parent_tool_use_id: str | None = None
+
+
+class UserStreamMessage(BaseModel):
+    """A user message sent to the SDK."""
+
+    type: str = Field(default="user")
+    message: UserMessageData
+    uuid: str | None = None
+    parent_tool_use_id: str | None = None
+    tool_use_result: Any = None
+
+
+# Union type for stream messages
+StreamMessage = AssistantStreamMessage | UserStreamMessage
+
+
+# ============================================================================
+# Control Protocol Models
+# ============================================================================
+
+
+class ControlResponseData(BaseModel):
+    """Base class for control response data."""
+
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+
+
+class ControlResponseSuccess(ControlResponseData):
+    """A successful control response."""
+
+    subtype: str = Field(default="success")
+    request_id: str
+    response: dict[str, Any] | None = None
+
+
+class ControlResponseError(ControlResponseData):
+    """An error control response."""
+
+    subtype: str = Field(default="error")
+    request_id: str
+    error: str
+
+
+class ControlResponseMessage(BaseModel):
+    """A control response message wrapper."""
+
+    type: str = Field(default="control_response")
+    response: ControlResponseSuccess | ControlResponseError
+
+
+# ============================================================================
+# Result/Usage Models
+# ============================================================================
+
+
+class UsageInfo(BaseModel):
+    """Token usage information."""
+
+    input_tokens: int = 0
+    cache_creation_input_tokens: int = 0
+    cache_read_input_tokens: int = 0
+    output_tokens: int = 0
+
+
+class MCPServerInfo(BaseModel):
+    """MCP server information."""
+
+    name: str
+
+
+class InitializeResponseData(BaseModel):
+    """Response data for initialize request."""
+
+    session_id: str
+    system_prompt: str
+    tools: list[str]
+    mcp_servers: list[MCPServerInfo] = Field(default_factory=list)
+    slash_commands: list[Any] = Field(default_factory=list)
+    apiKeySource: str = "none"
+    claude_code_version: str = "0.1.0"
+    output_style: str = "default"
+    agents: list[str] = Field(default_factory=list)
+    skills: list[Any] = Field(default_factory=list)
+    plugins: list[Any] = Field(default_factory=list)
+
+    model_config = ConfigDict(
+        extra="allow",
+        populate_by_name=True,
+    )
+
+
+class ResultMessage(BaseModel):
+    """A result message sent at the end of a query."""
+
+    type: str = Field(default="result")
+    subtype: str = Field(default="result")
+    duration_ms: int
+    duration_api_ms: int
+    is_error: bool
+    num_turns: int
+    session_id: str
+    total_cost_usd: float | None = None
+    usage: UsageInfo | None = None
+    result: str | None = None
+    structured_output: Any = None
+
+
+# ============================================================================
+# Permission Response Models
+# ============================================================================
+
+
+class PermissionResponseAllow(BaseModel):
+    """A permission allow response."""
+
+    decision: str = Field(default="allow")
+    updatedInput: dict[str, Any] | None = None
+
+
+class PermissionResponseDeny(BaseModel):
+    """A permission deny response."""
+
+    decision: str = Field(default="deny")
+    message: str = ""
+
+
+# ============================================================================
+# Helper Functions
+# ============================================================================
+
+
+def model_to_dict(model: BaseModel) -> dict[str, Any]:
+    """Convert a Pydantic model to a JSON-serializable dictionary.
+
+    This handles exclude_none=True and ensures proper serialization,
+    while always including type/subtype fields for protocol messages.
+
+    Args:
+        model: The Pydantic model to convert.
+
+    Returns:
+        A JSON-serializable dictionary.
+    """
+    return model.model_dump(exclude_none=True, by_alias=True, mode="json")
+
+
+__all__ = [
+    # Content Blocks
+    "ContentBlock",
+    "TextContentBlock",
+    "ThinkingContentBlock",
+    "ToolUseContentBlock",
+    "ToolResultContentBlock",
+    "ImageContentBlock",
+    "ImageSource",
+    "ContentBlockType",
+    # Messages
+    "MessageData",
+    "AssistantMessageData",
+    "UserMessageData",
+    "AssistantStreamMessage",
+    "UserStreamMessage",
+    "StreamMessage",
+    # Control Protocol
+    "ControlResponseData",
+    "ControlResponseSuccess",
+    "ControlResponseError",
+    "ControlResponseMessage",
+    # Result/Usage
+    "UsageInfo",
+    "MCPServerInfo",
+    "InitializeResponseData",
+    "ResultMessage",
+    # Permissions
+    "PermissionResponseAllow",
+    "PermissionResponseDeny",
+    # Helpers
+    "model_to_dict",
+]