code-muse 0.0.1__py3-none-any.whl

code_muse/tools/ask_user_question/constants.py

@@ -0,0 +1,73 @@
+"""Constants for the ask_user_question tool."""
+
+from typing import Final
+
+# Question constraints
+MAX_QUESTIONS_PER_CALL: Final[int] = 10  # Reasonable limit for a single TUI interaction
+MIN_OPTIONS_PER_QUESTION: Final[int] = 2
+MAX_OPTIONS_PER_QUESTION: Final[int] = 6
+MAX_HEADER_LENGTH: Final[int] = 60
+MAX_LABEL_LENGTH: Final[int] = 50
+MAX_DESCRIPTION_LENGTH: Final[int] = 200
+MAX_QUESTION_LENGTH: Final[int] = 500
+MAX_OTHER_TEXT_LENGTH: Final[int] = 500
+
+# UI settings
+DEFAULT_TIMEOUT_SECONDS: Final[int] = 300  # 5 minutes
+TIMEOUT_WARNING_SECONDS: Final[int] = 60  # Show warning at 60s remaining
+AUTO_ADD_OTHER_OPTION: Final[bool] = True
+
+# Other option configuration
+OTHER_OPTION_LABEL: Final[str] = "Other"
+OTHER_OPTION_DESCRIPTION: Final[str] = "Enter a custom option"
+
+# Left panel width magic numbers (extracted for clarity)
+LEFT_PANEL_PADDING: Final[int] = (
+    14  # left(2) + cursor(2) + checkmark(2) + right(2) + buffer(6)
+)
+MIN_LEFT_PANEL_WIDTH: Final[int] = 21
+MAX_LEFT_PANEL_WIDTH: Final[int] = 36
+
+# Horizontal padding for panel content (matches left panel's "  " prefix)
+PANEL_CONTENT_PADDING: Final[str] = "  "
+
+# CI environment variables to check for non-interactive detection
+# Use tuple for true immutability (Final only prevents reassignment, not mutation)
+CI_ENV_VARS: Final[tuple[str, ...]] = (
+    "CI",
+    "GITHUB_ACTIONS",
+    "GITLAB_CI",
+    "JENKINS_URL",
+    "TRAVIS",
+    "CIRCLECI",
+    "BUILDKITE",
+    "AZURE_PIPELINES",
+    "TEAMCITY_VERSION",
+)
+
+# Terminal escape sequences for alternate screen buffer
+ENTER_ALT_SCREEN: Final[str] = "\033[?1049h"
+EXIT_ALT_SCREEN: Final[str] = "\033[?1049l"
+CLEAR_AND_HOME: Final[str] = "\033[2J\033[H"
+
+# Unicode symbols for TUI rendering
+CURSOR_POINTER: Final[str] = "\u276f"  # ❯
+CURSOR_TRIANGLE: Final[str] = "\u25b6"  # ▶
+CHECK_MARK: Final[str] = "\u2713"  # ✓
+RADIO_FILLED: Final[str] = "\u25cf"  # ●
+BORDER_DOUBLE: Final[str] = "\u2550"  # ═
+ARROW_LEFT: Final[str] = "\u2190"  # ←
+ARROW_RIGHT: Final[str] = "\u2192"  # →
+ARROW_UP: Final[str] = "\u2191"  # ↑
+ARROW_DOWN: Final[str] = "\u2193"  # ↓
+PIPE_SEPARATOR: Final[str] = "\u2502"  # │
+
+# Panel rendering
+MAX_READABLE_WIDTH: Final[int] = 120
+HELP_BORDER_WIDTH: Final[int] = 50
+
+# Error formatting
+MAX_VALIDATION_ERRORS_SHOWN: Final[int] = 3
+
+# Terminal synchronization delay (seconds)
+TERMINAL_SYNC_DELAY: Final[float] = 0.05

code_muse/tools/ask_user_question/demo_tui.py

@@ -0,0 +1,55 @@
+#!/usr/bin/env python
+"""Manual demo script for the ask_user_question TUI.
+
+This is NOT an automated test - it's for interactive visual testing.
+Run this script directly to demo the TUI:
+    python -m code_muse.tools.ask_user_question.demo_tui
+"""
+
+from .handler import ask_user_question
+
+
+def main():
+    """Run a test of the ask_user_question TUI."""
+    print("Testing ask_user_question TUI...")
+    print("=" * 50)
+
+    # Test single question, single select
+    result = ask_user_question(
+        [
+            {
+                "question": "Which database should we use for this project?",
+                "header": "Database",
+                "multi_select": False,
+                "options": [
+                    {
+                        "label": "PostgreSQL",
+                        "description": "Relational database, ACID compliant, great for complex queries",
+                    },
+                    {
+                        "label": "MongoDB",
+                        "description": "Document store, flexible schema, good for rapid iteration",
+                    },
+                    {
+                        "label": "Redis",
+                        "description": "In-memory store, ultra-fast, best for caching",
+                    },
+                    {
+                        "label": "SQLite",
+                        "description": "Lightweight, file-based, perfect for local development",
+                    },
+                ],
+            }
+        ]
+    )
+
+    print("\n" + "=" * 50)
+    print("Result:")
+    print(f"  Answers: {result.answers}")
+    print(f"  Cancelled: {result.cancelled}")
+    print(f"  Error: {result.error}")
+    print(f"  Timed out: {result.timed_out}")
+
+
+if __name__ == "__main__":
+    main()

code_muse/tools/ask_user_question/handler.py

@@ -0,0 +1,232 @@
+"""Main handler for ask_user_question tool."""
+
+import asyncio
+import logging
+import os
+import sys
+from typing import Any
+
+from pydantic import ValidationError
+
+from code_muse.command_line.wiggum_state import is_wiggum_active
+from code_muse.tools.subagent_context import is_subagent
+
+from .constants import CI_ENV_VARS, DEFAULT_TIMEOUT_SECONDS, MAX_VALIDATION_ERRORS_SHOWN
+from .models import (
+    AskUserQuestionInput,
+    AskUserQuestionOutput,
+    Question,
+    QuestionAnswer,
+)
+from .terminal_ui import CancelledException, interactive_question_picker
+
+logger = logging.getLogger(__name__)
+
+
+class AsyncContextError(RuntimeError):
+    """Raised when TUI is called from async context without await."""
+
+    pass
+
+
+def _cancelled_response() -> AskUserQuestionOutput:
+    """Create a standardized cancelled response.
+
+    Note: cancelled=True means intentional user action, not an error.
+    The error field is left None since cancellation is expected behavior.
+    """
+    return AskUserQuestionOutput.cancelled_response()
+
+
+def is_interactive() -> bool:
+    """
+    Check if we're running in an interactive terminal.
+
+    Returns:
+        True if stdin is a TTY and we're not in a CI environment.
+    """
+    # stdin might be replaced with a non-file object in some embedding scenarios
+    # (e.g., Jupyter, pytest capture, or custom wrappers), so we catch AttributeError
+    try:
+        if not sys.stdin.isatty():
+            return False
+    except AttributeError, OSError:
+        return False
+
+    return not any(os.environ.get(var) for var in CI_ENV_VARS)
+
+
+def ask_user_question(
+    questions: list[Question | dict[str, Any]],
+    timeout: int = DEFAULT_TIMEOUT_SECONDS,
+) -> AskUserQuestionOutput:
+    """
+    Ask the user one or more interactive multiple-choice questions.
+
+    This tool displays questions in a split-panel terminal TUI and captures
+    user responses through keyboard navigation and selection.
+
+    Args:
+        questions: List of question objects, each containing:
+            - question (str): The full question text
+            - header (str): Short label (max 60 chars)
+            - multi_select (bool, optional): Allow multiple selections
+            - options (list): 2-6 options, each with label and optional description
+        timeout: Inactivity timeout in seconds (default: 300)
+
+    Returns:
+        AskUserQuestionOutput containing:
+            - answers (list): List of answer objects for each question
+            - cancelled (bool): True if user cancelled
+            - error (str | None): Error message if failed
+            - timed_out (bool): True if timed out
+
+    Example:
+        >>> result = ask_user_question([{
+        ...     "question": "Which database?",
+        ...     "header": "Database",
+        ...     "options": [
+        ...         {"label": "PostgreSQL", "description": "Relational DB"},
+        ...         {"label": "MongoDB", "description": "Document store"}
+        ...     ]
+        ... }])
+        >>> print(result.answers[0].selected_options)
+        ['PostgreSQL']
+    """
+    logger.info("ask_user_question called with %d questions", len(questions))
+
+    # Block interactive tools in sub-agent context
+    if is_subagent():
+        logger.warning("ask_user_question called from sub-agent context - disabled")
+        return AskUserQuestionOutput.error_response(
+            "Interactive tools are disabled for sub-agents. "
+            "Sub-agents should make reasonable decisions or return to the parent agent "
+            "if user input is required."
+        )
+
+    # Block interactive tools in wiggum (autonomous loop) mode
+    if is_wiggum_active():
+        logger.warning("ask_user_question called during wiggum mode - disabled")
+        return AskUserQuestionOutput.error_response(
+            "Interactive tools are disabled during /wiggum mode. "
+            "The agent is running autonomously in a loop. "
+            "Make a reasonable decision to proceed, or stop and wait for user input "
+            "by completing the current task."
+        )
+
+    # Check for interactive environment
+    if not is_interactive():
+        logger.warning("Non-interactive environment detected")
+        return AskUserQuestionOutput.error_response(
+            "Cannot ask questions: not running in an interactive terminal. "
+            "Please provide configuration through arguments or config files."
+        )
+
+    # Validate input
+    try:
+        validated_input = _validate_input(questions)
+    except ValidationError as e:
+        error_msg = _format_validation_error(e)
+        logger.warning("Validation error: %s", error_msg)
+        return AskUserQuestionOutput.error_response(error_msg)
+    except (TypeError, ValueError) as e:
+        logger.error("Unexpected validation error: %s", e, exc_info=True)
+        return AskUserQuestionOutput.error_response(f"Validation error: {e!s}")
+
+    # Run the interactive TUI
+    try:
+        answers, cancelled, timed_out = _run_interactive_picker(
+            validated_input.questions, timeout
+        )
+
+        if timed_out:
+            logger.info("Interaction timed out after %d seconds", timeout)
+            return AskUserQuestionOutput.timeout_response(timeout)
+
+        if cancelled:
+            logger.info("User cancelled the interaction")
+            return _cancelled_response()
+
+        logger.info("Successfully collected %d answers", len(answers))
+        return AskUserQuestionOutput(answers=answers)
+
+    except CancelledException, KeyboardInterrupt:
+        logger.info("User cancelled the interaction")
+        return _cancelled_response()
+
+    except OSError as e:
+        logger.error("Unexpected error during interaction: %s", e)
+        return AskUserQuestionOutput.error_response(f"Interaction error: {e!s}")
+
+
+def _run_interactive_picker(
+    questions: list[Question], timeout: int
+) -> tuple[list[QuestionAnswer], bool, bool]:
+    """Run the interactive TUI, handling async context detection.
+
+    If called from an async context, raises AsyncContextError with guidance.
+    For async callers, use `await interactive_question_picker()` directly.
+    """
+    # Check for async context BEFORE creating the coroutine to avoid
+    # "coroutine was never awaited" warnings on the error path.
+    try:
+        asyncio.get_running_loop()
+        # Already in async context - fail fast with helpful message
+        # Note: We avoid nest_asyncio.apply() as it globally patches the event loop,
+        # which can break other async code in the process and is not thread-safe.
+        raise AsyncContextError(
+            "Cannot run interactive TUI from within an async context. "
+            "Either call from synchronous code, or use "
+            "'await interactive_question_picker()' directly for async callers."
+        )
+    except RuntimeError:
+        # No running loop - safe to proceed with asyncio.run()
+        pass
+
+    return asyncio.run(interactive_question_picker(questions, timeout_seconds=timeout))
+
+
+def _validate_input(
+    questions: list[Question | dict[str, Any]],
+) -> AskUserQuestionInput:
+    """
+    Validate and convert input dictionaries to Pydantic models.
+
+    Args:
+        questions: Raw question dictionaries or validated Question models
+
+    Returns:
+        Validated AskUserQuestionInput model
+
+    Raises:
+        ValidationError: If input doesn't match schema
+    """
+    # Single-pass validation - Pydantic handles nested dict->model conversion
+    return AskUserQuestionInput.model_validate({"questions": questions})
+
+
+def _format_validation_error(error: ValidationError) -> str:
+    """
+    Format a Pydantic ValidationError into a readable string.
+
+    Args:
+        error: The Pydantic ValidationError
+
+    Returns:
+        Human-readable error message
+    """
+    errors = error.errors()
+    if not errors:
+        return "Validation error"
+
+    messages = []
+    for err in errors[:MAX_VALIDATION_ERRORS_SHOWN]:
+        loc = ".".join(str(x) for x in err["loc"])
+        msg = err["msg"]
+        messages.append(f"{loc}: {msg}")
+
+    result = "Validation error: " + "; ".join(messages)
+    if len(errors) > MAX_VALIDATION_ERRORS_SHOWN:
+        result += f" (and {len(errors) - MAX_VALIDATION_ERRORS_SHOWN} more)"
+
+    return result

code_muse/tools/ask_user_question/models.py

@@ -0,0 +1,302 @@
+"""Pydantic models for the ask_user_question tool."""
+
+import re
+from typing import TYPE_CHECKING, Annotated, Any
+
+from pydantic import BaseModel, BeforeValidator, Field, model_validator
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+from .constants import (
+    MAX_DESCRIPTION_LENGTH,
+    MAX_HEADER_LENGTH,
+    MAX_LABEL_LENGTH,
+    MAX_OPTIONS_PER_QUESTION,
+    MAX_OTHER_TEXT_LENGTH,
+    MAX_QUESTION_LENGTH,
+    MAX_QUESTIONS_PER_CALL,
+    MIN_OPTIONS_PER_QUESTION,
+)
+
+__all__ = [
+    "AskUserQuestionInput",
+    "AskUserQuestionOutput",
+    "Question",
+    "QuestionAnswer",
+    "QuestionOption",
+    "sanitize_text",
+]
+
+# Regex to match ANSI escape codes
+ANSI_ESCAPE_PATTERN = re.compile(r"\x1B(?:[@-Z\\-_]|\[[0-?]*[ -/]*[@-~])")
+
+
+def sanitize_text(text: str) -> str:
+    """Remove ANSI escape codes and strip whitespace."""
+    return ANSI_ESCAPE_PATTERN.sub("", text).strip()
+
+
+def _make_sanitizer(
+    *, allow_none: bool = False, default: str = ""
+) -> Callable[[Any], str]:
+    """Create a sanitizer with configurable None handling.
+
+    Args:
+        allow_none: If True, None returns default. If False, raises ValueError.
+        default: Value to return when allow_none=True and input is None.
+
+    Returns:
+        A sanitizer function for use with BeforeValidator.
+    """
+
+    def sanitize(v: Any) -> str:
+        if v is None:
+            if allow_none:
+                return default
+            raise ValueError("Value cannot be None")
+        return sanitize_text(str(v))
+
+    return sanitize
+
+
+# Pre-built sanitizers for common cases
+_sanitize_required = _make_sanitizer(allow_none=False)
+_sanitize_optional = _make_sanitizer(allow_none=True, default="")
+
+
+def _sanitize_header(v: Any) -> str:
+    """Sanitize header: remove ANSI, strip, replace spaces with hyphens."""
+    return _sanitize_required(v).replace(" ", "-")
+
+
+def _check_unique(items: list[str], field_name: str) -> None:
+    """Raise ValueError if items has duplicates (case-insensitive)."""
+    lowered = [i.lower() for i in items]
+    if len(lowered) != len(set(lowered)):
+        raise ValueError(f"{field_name} must be unique")
+
+
+class QuestionOption(BaseModel):
+    """
+    A single selectable option for a question.
+
+    Attributes:
+        label: Short, descriptive name for the option (1-5 words recommended)
+        description: Longer explanation of what selecting this option means
+    """
+
+    label: Annotated[
+        str,
+        BeforeValidator(_sanitize_required),
+        Field(
+            min_length=1,
+            max_length=MAX_LABEL_LENGTH,
+            description="Short option name (1-5 words)",
+        ),
+    ]
+    description: Annotated[
+        str,
+        BeforeValidator(_sanitize_optional),
+        Field(
+            default="",
+            max_length=MAX_DESCRIPTION_LENGTH,
+            description="Explanation of what this option means",
+        ),
+    ]
+
+
+class Question(BaseModel):
+    """
+    A single question with multiple-choice options.
+
+    Attributes:
+        question: The full question text displayed to the user
+        header: Short label used for compact display and response mapping
+        multi_select: Whether user can select multiple options
+        options: List of 2-6 selectable options
+    """
+
+    question: Annotated[
+        str,
+        BeforeValidator(_sanitize_required),
+        Field(
+            min_length=1,
+            max_length=MAX_QUESTION_LENGTH,
+            description="The full question text to display",
+        ),
+    ]
+    header: Annotated[
+        str,
+        BeforeValidator(_sanitize_header),
+        Field(
+            min_length=1,
+            max_length=MAX_HEADER_LENGTH,
+            description="Short label for compact display (max 60 chars)",
+        ),
+    ]
+    multi_select: Annotated[
+        bool,
+        Field(
+            default=False,
+            description="If true, user can select multiple options",
+        ),
+    ]
+    options: Annotated[
+        list[QuestionOption],
+        Field(
+            min_length=MIN_OPTIONS_PER_QUESTION,
+            max_length=MAX_OPTIONS_PER_QUESTION,
+            description="Array of 2-6 selectable options",
+        ),
+    ]
+
+    @model_validator(mode="after")
+    def validate_unique_labels(self) -> Question:
+        """Ensure all option labels are unique within a question."""
+        _check_unique([opt.label for opt in self.options], "Option labels")
+        return self
+
+
+class AskUserQuestionInput(BaseModel):
+    """
+    Input schema for the ask_user_question tool.
+
+    Attributes:
+        questions: List of 1-10 questions to ask the user
+    """
+
+    questions: Annotated[
+        list[Question],
+        Field(
+            min_length=1,
+            max_length=MAX_QUESTIONS_PER_CALL,
+            description="Array of 1-10 questions to ask",
+        ),
+    ]
+
+    @model_validator(mode="after")
+    def validate_unique_headers(self) -> AskUserQuestionInput:
+        """Ensure all question headers are unique."""
+        _check_unique([q.header for q in self.questions], "Question headers")
+        return self
+
+
+class QuestionAnswer(BaseModel):
+    """
+    Answer to a single question.
+
+    Attributes:
+        question_header: The header of the question being answered
+        selected_options: List of labels for selected options
+        other_text: Custom text if user selected "Other" option
+    """
+
+    question_header: Annotated[
+        str,
+        Field(description="Header of the answered question"),
+    ]
+    selected_options: Annotated[
+        list[str],
+        Field(
+            default_factory=list,
+            description="Labels of selected options",
+        ),
+    ]
+    other_text: Annotated[
+        str | None,
+        Field(
+            default=None,
+            max_length=MAX_OTHER_TEXT_LENGTH,
+            description="Custom text if 'Other' was selected",
+        ),
+    ]
+
+    @property
+    def has_other(self) -> bool:
+        """Check if user provided custom 'Other' input."""
+        return self.other_text is not None
+
+    @property
+    def is_empty(self) -> bool:
+        """Check if no options were selected."""
+        return not self.selected_options and self.other_text is None
+
+
+class AskUserQuestionOutput(BaseModel):
+    """
+    Output schema for the ask_user_question tool.
+
+    Attributes:
+        answers: List of answers to all questions
+        cancelled: Whether user cancelled the interaction
+        error: Error message if something went wrong
+        timed_out: Whether the interaction timed out
+    """
+
+    answers: Annotated[
+        list[QuestionAnswer],
+        Field(
+            default_factory=list,
+            description="Answers to all questions",
+        ),
+    ]
+    cancelled: Annotated[
+        bool,
+        Field(
+            default=False,
+            description="True if user cancelled (Esc/Ctrl+C)",
+        ),
+    ]
+    error: Annotated[
+        str | None,
+        Field(
+            default=None,
+            description="Error message if interaction failed",
+        ),
+    ]
+    timed_out: Annotated[
+        bool,
+        Field(
+            default=False,
+            description="True if interaction timed out",
+        ),
+    ]
+
+    @property
+    def success(self) -> bool:
+        """Check if interaction completed successfully."""
+        return not self.cancelled and self.error is None and not self.timed_out
+
+    @classmethod
+    def error_response(cls, error: str) -> AskUserQuestionOutput:
+        """Create an error response."""
+        return cls(error=error)
+
+    @classmethod
+    def cancelled_response(cls) -> AskUserQuestionOutput:
+        """Create a cancelled response (intentional user action, not an error)."""
+        return cls(answers=[], cancelled=True, error=None)
+
+    @classmethod
+    def timeout_response(cls, timeout: int) -> AskUserQuestionOutput:
+        """Create a timeout response."""
+        return cls(
+            answers=[],
+            cancelled=False,
+            timed_out=True,
+            error=f"Interaction timed out after {timeout} seconds of inactivity",
+        )
+
+    def get_answer(self, header: str) -> QuestionAnswer | None:
+        """Get answer by question header (case-insensitive)."""
+        header_lower = header.lower()
+        return next(
+            (a for a in self.answers if a.question_header.lower() == header_lower),
+            None,
+        )
+
+    def get_selected(self, header: str) -> list[str]:
+        """Get selected options for a question by header."""
+        answer = self.get_answer(header)
+        return answer.selected_options if answer else []

code_muse/tools/ask_user_question/registration.py

@@ -0,0 +1,37 @@
+"""Tool registration for ask_user_question."""
+
+from typing import TYPE_CHECKING, Annotated, Any
+
+from pydantic import Field
+from pydantic_ai import RunContext
+
+from .handler import ask_user_question as _ask_user_question_impl
+from .models import AskUserQuestionOutput
+
+if TYPE_CHECKING:
+    from pydantic_ai import Agent
+
+
+def register_ask_user_question(agent: Agent) -> None:
+    """Register the ask_user_question tool with the given agent."""
+
+    @agent.tool
+    def ask_user_question(
+        context: RunContext,  # noqa: ARG001 - Required by framework
+        questions: Annotated[
+            list[dict[str, Any]],
+            Field(
+                description=(
+                    "Array of question objects. Each question should include: "
+                    "'question' (string), 'header' (short string), "
+                    "optional 'multi_select' (boolean), and 'options' "
+                    "(array of option objects with 'label' and optional "
+                    "'description')."
+                )
+            ),
+        ],
+    ) -> AskUserQuestionOutput:
+        """Ask the user multiple related questions in an interactive TUI."""
+        # Keep the external tool schema simple for provider compatibility.
+        # The handler performs the real nested validation and normalization.
+        return _ask_user_question_impl(questions)