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

ripperdoc/tools/ask_user_question_tool.py

@@ -0,0 +1,433 @@
+"""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 Exception as e:
+            logger.exception("[ask_user_question_tool] Error during prompt", extra={"error": str(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 Exception:
+                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 Exception as exc:
+            logger.exception(
+                "[ask_user_question_tool] Error collecting answers",
+                extra={"error": str(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 Exception:
+                    logger.debug("[ask_user_question_tool] Failed to resume UI")

ripperdoc/tools/background_shell.py

@@ -47,6 +47,12 @@ _background_loop: Optional[asyncio.AbstractEventLoop] = None
 _background_thread: Optional[threading.Thread] = None
 _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 Exception:
+        pass
 
 
 def _ensure_background_loop() -> asyncio.AbstractEventLoop:
@@ -301,11 +307,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 +316,68 @@ def shutdown_background_shell() -> None:
     for task in tasks:
         try:
             task.killed = True
-            task.process.kill()
+            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 Exception:
-            pass
-        for reader in task.reader_tasks:
-            if loop and loop.is_running():
-                loop.call_soon_threadsafe(reader.cancel)
-        task.done_event.set()
+            _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)
+    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
 
-    _background_loop = None
-    _background_thread = None
+    try:
+        if loop.is_running():
+            try:
+                fut = asyncio.run_coroutine_threadsafe(_shutdown_loop(loop), loop)
+                fut.result(timeout=3)
+            except Exception:
+                logger.debug("Failed to cleanly shutdown background loop", exc_info=True)
+            try:
+                loop.call_soon_threadsafe(loop.stop)
+            except Exception:
+                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