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

ripperdoc/core/tool.py

@@ -44,6 +44,13 @@ class ToolUseContext(BaseModel):
     file_state_cache: Dict[str, "FileSnapshot"] = Field(default_factory=dict)
     tool_registry: Optional[Any] = None
     abort_signal: Optional[Any] = None
+    # UI control callbacks for tools that need user interaction
+    pause_ui: Optional[Any] = Field(default=None, description="Callback to pause UI spinner")
+    resume_ui: Optional[Any] = Field(default=None, description="Callback to resume UI spinner")
+    # Plan mode control callback
+    on_exit_plan_mode: Optional[Any] = Field(
+        default=None, description="Callback invoked when exiting plan mode"
+    )
     model_config = ConfigDict(arbitrary_types_allowed=True)
 
 
@@ -201,9 +208,10 @@ async def build_tool_description(
 
         if parts:
             return f"{description_text}\n\nInput examples:\n" + "\n\n".join(parts)
-    except Exception:
-        logger.exception(
-            "[tool] Failed to build input example section",
+    except (TypeError, ValueError, AttributeError, KeyError) as exc:
+        logger.warning(
+            "[tool] Failed to build input example section: %s: %s",
+            type(exc).__name__, exc,
             extra={"tool": getattr(tool, "name", None)},
         )
         return description_text
@@ -220,9 +228,10 @@ def tool_input_examples(tool: Tool[Any, Any], limit: int = 5) -> List[Dict[str,
     for example in examples[:limit]:
         try:
             results.append(example.example)
-        except Exception:
-            logger.exception(
-                "[tool] Failed to format tool input example",
+        except (TypeError, ValueError, AttributeError) as exc:
+            logger.warning(
+                "[tool] Failed to format tool input example: %s: %s",
+                type(exc).__name__, exc,
                 extra={"tool": getattr(tool, "name", None)},
             )
             continue

ripperdoc/sdk/client.py

@@ -27,6 +27,7 @@ from ripperdoc.core.default_tools import get_default_tools
 from ripperdoc.core.query import QueryContext, query as _core_query
 from ripperdoc.core.permissions import PermissionResult
 from ripperdoc.core.system_prompt import build_system_prompt
+from ripperdoc.core.skills import build_skill_summary, load_all_skills
 from ripperdoc.core.tool import Tool
 from ripperdoc.tools.task_tool import TaskTool
 from ripperdoc.tools.mcp_tools import load_dynamic_mcp_tools_async, merge_tools_with_dynamic
@@ -42,6 +43,7 @@ from ripperdoc.utils.mcp import (
     load_mcp_servers_async,
     shutdown_mcp_runtime,
 )
+from ripperdoc.utils.log import get_logger
 
 MessageType = Union[UserMessage, AssistantMessage, ProgressMessage]
 PermissionChecker = Callable[
@@ -67,6 +69,8 @@ QueryRunner = Callable[
 
 _END_OF_STREAM = object()
 
+logger = get_logger()
+
 
 def _coerce_to_path(path: Union[str, Path]) -> Path:
     return path if isinstance(path, Path) else Path(path)
@@ -281,12 +285,21 @@ class RipperdocClient:
             return self.options.system_prompt
 
         instructions: List[str] = []
+        project_path = _coerce_to_path(self.options.cwd or Path.cwd())
+        skill_result = load_all_skills(project_path)
+        for err in skill_result.errors:
+            logger.warning(
+                "[skills] Failed to load skill",
+                extra={"path": str(err.path), "reason": err.reason},
+            )
+        skill_instructions = build_skill_summary(skill_result.skills)
+        if skill_instructions:
+            instructions.append(skill_instructions)
         instructions.extend(self.options.extra_instructions())
         memory = build_memory_instructions()
         if memory:
             instructions.append(memory)
 
-        project_path = _coerce_to_path(self.options.cwd or Path.cwd())
         dynamic_tools = await load_dynamic_mcp_tools_async(project_path)
         if dynamic_tools:
             self._tools = merge_tools_with_dynamic(self._tools, dynamic_tools)

ripperdoc/tools/ask_user_question_tool.py

@@ -0,0 +1,431 @@
+"""Ask user question tool for interactive clarification.
+
+This tool allows the AI to ask the user questions during execution,
+enabling clarification of ambiguous instructions, gathering preferences,
+and making decisions on implementation choices.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from textwrap import dedent
+from typing import AsyncGenerator, Dict, List, Optional
+
+from pydantic import BaseModel, Field
+
+from ripperdoc.core.tool import (
+    Tool,
+    ToolOutput,
+    ToolResult,
+    ToolUseContext,
+    ValidationResult,
+)
+from ripperdoc.utils.log import get_logger
+
+logger = get_logger()
+
+TOOL_NAME = "AskUserQuestion"
+OTHER_VALUE = "__other__"
+HEADER_MAX_CHARS = 12
+
+ASK_USER_QUESTION_PROMPT = dedent(
+    """\
+    Use this tool when you need to ask the user questions during execution. This allows you to:
+    1. Gather user preferences or requirements
+    2. Clarify ambiguous instructions
+    3. Get decisions on implementation choices as you work
+    4. Offer choices to the user about what direction to take.
+
+    Usage notes:
+    - Users will always be able to select "Other" to provide custom text input
+    - Use multiSelect: true to allow multiple answers to be selected for a question
+    - If you recommend a specific option, make that the first option in the list and add "(Recommended)" at the end of the label
+    """
+)
+
+
+class OptionInput(BaseModel):
+    """Single option for a question."""
+
+    label: str = Field(
+        description="The display text for this option that the user will see and select. "
+        "Should be concise (1-5 words) and clearly describe the choice."
+    )
+    description: str = Field(
+        description="Explanation of what this option means or what will happen if chosen. "
+        "Useful for providing context about trade-offs or implications."
+    )
+
+
+class QuestionInput(BaseModel):
+    """Single question to ask the user."""
+
+    question: str = Field(
+        description="The complete question to ask the user. Should be clear, specific, and end "
+        'with a question mark. Example: "Which library should we use for date formatting?" '
+        'If multiSelect is true, phrase it accordingly, e.g. "Which features do you want to enable?"'
+    )
+    header: str = Field(
+        description=f"Very short label displayed as a chip/tag (max {HEADER_MAX_CHARS} chars). "
+        'Examples: "Auth method", "Library", "Approach".'
+    )
+    options: List[OptionInput] = Field(
+        min_length=2,
+        max_length=4,
+        description="The available choices for this question. Must have 2-4 options. "
+        "Each option should be a distinct, mutually exclusive choice (unless multiSelect is enabled). "
+        "There should be no 'Other' option, that will be provided automatically.",
+    )
+    multiSelect: bool = Field(
+        description="Set to true to allow the user to select multiple options instead of just one. "
+        "Use when choices are not mutually exclusive."
+    )
+
+
+class AskUserQuestionToolInput(BaseModel):
+    """Input for the AskUserQuestion tool."""
+
+    questions: List[QuestionInput] = Field(
+        min_length=1,
+        max_length=4,
+        description="Questions to ask the user (1-4 questions)",
+    )
+    answers: Optional[Dict[str, str]] = Field(
+        default=None,
+        description="User answers collected by the permission component",
+    )
+
+
+class AskUserQuestionToolOutput(BaseModel):
+    """Output from the AskUserQuestion tool."""
+
+    questions: List[QuestionInput]
+    answers: Dict[str, str]
+    cancelled: bool = False
+
+
+def truncate_header(header: str) -> str:
+    """Truncate header to maximum characters."""
+    if len(header) <= HEADER_MAX_CHARS:
+        return header
+    return f"{header[: HEADER_MAX_CHARS - 1]}..."
+
+
+def format_option_display(option: OptionInput, index: int) -> str:
+    """Format a single option for display."""
+    desc = f" - {option.description}" if option.description.strip() else ""
+    return f"  {index}. {option.label}{desc}"
+
+
+def format_question_prompt(question: QuestionInput, question_num: int, total: int) -> str:
+    """Format a question for terminal display."""
+    header = truncate_header(question.header)
+    lines = [
+        "",
+        f"[{header}] Question {question_num}/{total}",
+        f"  {question.question}",
+        "",
+    ]
+
+    for idx, opt in enumerate(question.options, start=1):
+        lines.append(format_option_display(opt, idx))
+
+    # Add "Other" option
+    lines.append(f"  {len(question.options) + 1}. Other (type your own answer)")
+
+    if question.multiSelect:
+        lines.append("")
+        lines.append("  Enter numbers separated by commas (e.g., 1,3), or 'o' for other: ")
+    else:
+        lines.append("")
+        lines.append("  Enter choice (1-{}) or 'o' for other: ".format(len(question.options) + 1))
+
+    return "\n".join(lines)
+
+
+async def prompt_user_for_answer(
+    question: QuestionInput, question_num: int, total: int
+) -> Optional[str]:
+    """Prompt user for an answer to a single question.
+
+    Returns the answer string, or None if cancelled.
+    """
+    loop = asyncio.get_running_loop()
+
+    def _prompt() -> Optional[str]:
+        try:
+            from prompt_toolkit import prompt as pt_prompt
+
+            prompt_text = format_question_prompt(question, question_num, total)
+            print(prompt_text, end="")
+
+            while True:
+                response = pt_prompt("").strip()
+
+                if not response:
+                    print("  Please enter a valid choice.")
+                    continue
+
+                if response.lower() in ("q", "quit", "cancel", "exit"):
+                    return None
+
+                if response.lower() == "o" or response == str(len(question.options) + 1):
+                    # Other option selected
+                    print("  Enter your custom answer: ", end="")
+                    custom = pt_prompt("")
+                    if custom.strip():
+                        return custom.strip()
+                    print("  Custom answer cannot be empty.")
+                    continue
+
+                if question.multiSelect:
+                    # Parse comma-separated numbers
+                    try:
+                        indices = [int(x.strip()) for x in response.split(",")]
+                        valid_range = range(1, len(question.options) + 2)
+                        if all(i in valid_range for i in indices):
+                            selected = []
+                            for i in indices:
+                                if i == len(question.options) + 1:
+                                    # Other option
+                                    print("  Enter your custom answer: ", end="")
+                                    custom = pt_prompt("")
+                                    if custom.strip():
+                                        selected.append(custom.strip())
+                                else:
+                                    selected.append(question.options[i - 1].label)
+                            if selected:
+                                return ", ".join(selected)
+                        print(
+                            f"  Invalid selection. Enter numbers from 1 to {len(question.options) + 1}."
+                        )
+                    except ValueError:
+                        print("  Invalid input. Enter numbers separated by commas.")
+                else:
+                    # Single selection
+                    try:
+                        choice = int(response)
+                        if 1 <= choice <= len(question.options):
+                            return question.options[choice - 1].label
+                        elif choice == len(question.options) + 1:
+                            # Other option
+                            print("  Enter your custom answer: ", end="")
+                            custom = pt_prompt("")
+                            if custom.strip():
+                                return custom.strip()
+                            print("  Custom answer cannot be empty.")
+                        else:
+                            print(
+                                f"  Invalid choice. Enter a number from 1 to {len(question.options) + 1}."
+                            )
+                    except ValueError:
+                        print("  Invalid input. Enter a number.")
+
+        except KeyboardInterrupt:
+            return None
+        except EOFError:
+            return None
+        except (OSError, RuntimeError, ValueError) as e:
+            logger.warning(
+                "[ask_user_question_tool] Error during prompt: %s: %s",
+                type(e).__name__, e,
+            )
+            return None
+
+    return await loop.run_in_executor(None, _prompt)
+
+
+async def collect_answers(
+    questions: List[QuestionInput], initial_answers: Dict[str, str]
+) -> tuple[Dict[str, str], bool]:
+    """Collect answers for all questions.
+
+    Returns (answers_dict, cancelled_flag).
+    """
+    answers = dict(initial_answers)
+    total = len(questions)
+
+    for idx, question in enumerate(questions, start=1):
+        # Skip if already answered
+        if question.question in answers and answers[question.question]:
+            continue
+
+        answer = await prompt_user_for_answer(question, idx, total)
+        if answer is None:
+            return answers, True  # Cancelled
+        answers[question.question] = answer
+
+    return answers, False
+
+
+class AskUserQuestionTool(Tool[AskUserQuestionToolInput, AskUserQuestionToolOutput]):
+    """Tool for asking the user questions interactively."""
+
+    @property
+    def name(self) -> str:
+        return TOOL_NAME
+
+    async def description(self) -> str:
+        return (
+            "Asks the user multiple choice questions to gather information, "
+            "clarify ambiguity, understand preferences, make decisions or offer them choices."
+        )
+
+    @property
+    def input_schema(self) -> type[AskUserQuestionToolInput]:
+        return AskUserQuestionToolInput
+
+    async def prompt(self, safe_mode: bool = False) -> str:  # noqa: ARG002
+        return ASK_USER_QUESTION_PROMPT
+
+    def user_facing_name(self) -> str:
+        return ""
+
+    def is_read_only(self) -> bool:
+        return True
+
+    def is_concurrency_safe(self) -> bool:
+        return True
+
+    def needs_permissions(
+        self,
+        input_data: Optional[AskUserQuestionToolInput] = None,  # noqa: ARG002
+    ) -> bool:
+        return False
+
+    async def validate_input(
+        self,
+        input_data: AskUserQuestionToolInput,
+        context: Optional[ToolUseContext] = None,  # noqa: ARG002
+    ) -> ValidationResult:
+        """Validate that question texts and option labels are unique."""
+        seen_questions: set[str] = set()
+
+        for question in input_data.questions:
+            if question.question in seen_questions:
+                return ValidationResult(result=False, message="Question texts must be unique")
+            seen_questions.add(question.question)
+
+            option_labels: set[str] = set()
+            for option in question.options:
+                if option.label in option_labels:
+                    return ValidationResult(
+                        result=False,
+                        message=f'Option labels for "{question.question}" must be unique',
+                    )
+                option_labels.add(option.label)
+
+        return ValidationResult(result=True)
+
+    def render_result_for_assistant(self, output: AskUserQuestionToolOutput) -> str:
+        """Render the tool output for the AI assistant."""
+        if output.cancelled:
+            return "User declined to answer your questions."
+
+        if not output.answers:
+            return "User did not provide any answers."
+
+        serialized = ", ".join(
+            f'"{question}"="{answer}"' for question, answer in output.answers.items()
+        )
+        return (
+            f"User has answered your questions: {serialized}. "
+            "You can now continue with the user's answers in mind."
+        )
+
+    def render_tool_use_message(
+        self,
+        input_data: AskUserQuestionToolInput,
+        verbose: bool = False,  # noqa: ARG002
+    ) -> str:
+        """Render the tool use message for display."""
+        question_count = len(input_data.questions)
+        if question_count == 1:
+            return f"Asking user: {input_data.questions[0].question}"
+        return f"Asking user {question_count} questions"
+
+    async def call(
+        self,
+        input_data: AskUserQuestionToolInput,
+        context: ToolUseContext,
+    ) -> AsyncGenerator[ToolOutput, None]:
+        """Execute the tool to ask user questions."""
+        questions = input_data.questions
+        initial_answers = input_data.answers or {}
+
+        # Pause UI spinner before user interaction
+        if context.pause_ui:
+            try:
+                context.pause_ui()
+            except (RuntimeError, ValueError, OSError):
+                logger.debug("[ask_user_question_tool] Failed to pause UI")
+
+        try:
+            # Display introduction
+            loop = asyncio.get_running_loop()
+
+            def _print_intro() -> None:
+                print("\n" + "=" * 60)
+                print("I need a few answers to proceed:")
+                print("=" * 60)
+
+            await loop.run_in_executor(None, _print_intro)
+
+            # Collect answers
+            answers, cancelled = await collect_answers(questions, initial_answers)
+
+            if cancelled:
+                output = AskUserQuestionToolOutput(
+                    questions=questions,
+                    answers=answers,
+                    cancelled=True,
+                )
+                yield ToolResult(
+                    data=output,
+                    result_for_assistant=self.render_result_for_assistant(output),
+                )
+                return
+
+            # Display summary
+            def _print_summary() -> None:
+                print("\n" + "-" * 40)
+                print("Your answers:")
+                for q, a in answers.items():
+                    print(f"  - {q}")
+                    print(f"    -> {a}")
+                print("-" * 40 + "\n")
+
+            await loop.run_in_executor(None, _print_summary)
+
+            output = AskUserQuestionToolOutput(
+                questions=questions,
+                answers=answers,
+                cancelled=False,
+            )
+            yield ToolResult(
+                data=output,
+                result_for_assistant=self.render_result_for_assistant(output),
+            )
+
+        except (OSError, RuntimeError, ValueError, KeyError) as exc:
+            logger.warning(
+                "[ask_user_question_tool] Error collecting answers: %s: %s",
+                type(exc).__name__, exc,
+            )
+            output = AskUserQuestionToolOutput(
+                questions=questions,
+                answers={},
+                cancelled=True,
+            )
+            yield ToolResult(
+                data=output,
+                result_for_assistant="Error while collecting user answers: " + str(exc),
+            )
+
+        finally:
+            # Resume UI spinner after user interaction
+            if context.resume_ui:
+                try:
+                    context.resume_ui()
+                except (RuntimeError, ValueError, OSError):
+                    logger.debug("[ask_user_question_tool] Failed to resume UI")

ripperdoc/tools/background_shell.py

@@ -49,6 +49,14 @@ _loop_lock = threading.Lock()
 _shutdown_registered = False
 
 
+def _safe_log_exception(message: str, **extra: Any) -> None:
+    """Log an exception but never let logging failures bubble up."""
+    try:
+        logger.exception(message, extra=extra)
+    except (OSError, RuntimeError, ValueError):
+        pass
+
+
 def _ensure_background_loop() -> asyncio.AbstractEventLoop:
     """Create (or return) a dedicated loop for background processes."""
     global _background_loop, _background_thread
@@ -106,7 +114,9 @@ async def _pump_stream(stream: asyncio.StreamReader, sink: List[str]) -> None:
             text = chunk.decode("utf-8", errors="replace")
             with _tasks_lock:
                 sink.append(text)
-    except Exception as exc:
+    except (OSError, RuntimeError, asyncio.CancelledError) as exc:
+        if isinstance(exc, asyncio.CancelledError):
+            return  # Normal cancellation
         # Best effort; ignore stream read errors to avoid leaking tasks.
         logger.debug(
             f"Stream pump error for background task: {exc}",
@@ -149,9 +159,10 @@ async def _monitor_task(task: BackgroundTask) -> None:
             task.exit_code = -1
     except asyncio.CancelledError:
         return
-    except Exception:
-        logger.exception(
-            "Error monitoring background task",
+    except (OSError, RuntimeError, ProcessLookupError) as exc:
+        logger.warning(
+            "Error monitoring background task: %s: %s",
+            type(exc).__name__, exc,
             extra={"task_id": task.id, "command": task.command},
         )
         with _tasks_lock:
@@ -301,11 +312,8 @@ def list_background_tasks() -> List[str]:
         return list(_tasks.keys())
 
 
-def shutdown_background_shell() -> None:
-    """Stop background tasks/loop to avoid asyncio 'Event loop is closed' warnings."""
-    global _background_loop, _background_thread
-
-    loop = _background_loop
+async def _shutdown_loop(loop: asyncio.AbstractEventLoop) -> None:
+    """Drain running background processes before stopping the loop."""
     with _tasks_lock:
         tasks = list(_tasks.values())
         _tasks.clear()
@@ -313,21 +321,69 @@ def shutdown_background_shell() -> None:
     for task in tasks:
         try:
             task.killed = True
-            task.process.kill()
-        except Exception:
-            pass
-        for reader in task.reader_tasks:
-            if loop and loop.is_running():
-                loop.call_soon_threadsafe(reader.cancel)
-        task.done_event.set()
+            with contextlib.suppress(ProcessLookupError):
+                task.process.kill()
+            try:
+                with contextlib.suppress(ProcessLookupError):
+                    await asyncio.wait_for(task.process.wait(), timeout=1.5)
+            except asyncio.TimeoutError:
+                with contextlib.suppress(ProcessLookupError, PermissionError):
+                    task.process.kill()
+                with contextlib.suppress(asyncio.TimeoutError, ProcessLookupError):
+                    await asyncio.wait_for(task.process.wait(), timeout=0.5)
+            task.exit_code = task.process.returncode or -1
+        except (OSError, RuntimeError, asyncio.CancelledError) as exc:
+            if not isinstance(exc, asyncio.CancelledError):
+                _safe_log_exception(
+                    "Error shutting down background task",
+                    task_id=task.id,
+                    command=task.command,
+                )
+        finally:
+            await _finalize_reader_tasks(task.reader_tasks)
+            task.done_event.set()
 
-    if loop and loop.is_running():
-        try:
-            loop.call_soon_threadsafe(loop.stop)
-        except Exception:
-            pass
-    if _background_thread and _background_thread.is_alive():
-        _background_thread.join(timeout=2)
-
-    _background_loop = None
-    _background_thread = None
+    current = asyncio.current_task()
+    pending = [t for t in asyncio.all_tasks(loop) if t is not current]
+    for pending_task in pending:
+        pending_task.cancel()
+    if pending:
+        with contextlib.suppress(Exception):
+            await asyncio.gather(*pending, return_exceptions=True)
+
+    with contextlib.suppress(Exception):
+        await loop.shutdown_asyncgens()
+
+
+def shutdown_background_shell() -> None:
+    """Stop background tasks/loop to avoid asyncio 'Event loop is closed' warnings."""
+    global _background_loop, _background_thread
+
+    loop = _background_loop
+    thread = _background_thread
+
+    if not loop or loop.is_closed():
+        _background_loop = None
+        _background_thread = None
+        return
+
+    try:
+        if loop.is_running():
+            try:
+                fut = asyncio.run_coroutine_threadsafe(_shutdown_loop(loop), loop)
+                fut.result(timeout=3)
+            except (RuntimeError, TimeoutError, concurrent.futures.TimeoutError):
+                logger.debug("Failed to cleanly shutdown background loop", exc_info=True)
+            try:
+                loop.call_soon_threadsafe(loop.stop)
+            except (RuntimeError, OSError):
+                logger.debug("Failed to stop background loop", exc_info=True)
+        else:
+            loop.run_until_complete(_shutdown_loop(loop))
+    finally:
+        if thread and thread.is_alive():
+            thread.join(timeout=2)
+        with contextlib.suppress(Exception):
+            loop.close()
+        _background_loop = None
+        _background_thread = None