code-muse 0.0.1__py3-none-any.whl

code_muse/messaging/commands.py

@@ -0,0 +1,166 @@
+"""Command models for User → Agent communication in Muse's messaging system.
+
+This module defines Pydantic models for commands that flow FROM the UI TO the Agent.
+This is the opposite direction of messages.py (which flows Agent → UI).
+
+Commands are used for:
+- Controlling agent execution (cancel, interrupt)
+- Responding to agent requests for user input
+- Providing confirmations and selections
+
+The UI layer creates these commands and sends them to the agent/runtime.
+The agent processes them and may emit messages in response.
+
+    ┌─────────┐   Commands    ┌─────────┐
+    │   UI    │ ────────────> │  Agent  │
+    │ (User)  │               │         │
+    │         │ <──────────── │         │
+    └─────────┘   Messages    └─────────┘
+
+NO Rich markup or formatting should be embedded in any string fields.
+"""
+
+from datetime import UTC, datetime
+from uuid import uuid4
+
+from pydantic import BaseModel, Field
+
+# =============================================================================
+# Base Command
+# =============================================================================
+
+
+class BaseCommand(BaseModel):
+    """Base class for all commands with auto-generated id and timestamp."""
+
+    id: str = Field(
+        default_factory=lambda: str(uuid4()),
+        description="Unique identifier for this command instance",
+    )
+    timestamp: datetime = Field(
+        default_factory=lambda: datetime.now(UTC),
+        description="When this command was created (UTC)",
+    )
+
+    model_config = {"frozen": False, "extra": "forbid"}
+
+
+# =============================================================================
+# Agent Control Commands
+# =============================================================================
+
+
+class CancelAgentCommand(BaseCommand):
+    """Signals the agent to stop current execution gracefully.
+
+    The agent should finish any in-progress atomic operation, clean up,
+    and return control to the user. This is a soft cancellation.
+    """
+
+    reason: str | None = Field(
+        default=None,
+        description="Optional reason for cancellation (for logging/debugging)",
+    )
+
+
+class InterruptShellCommand(BaseCommand):
+    """Signals to interrupt a currently running shell command.
+
+    This is equivalent to pressing Ctrl+C in a terminal. The shell process
+    should receive SIGINT and terminate. Use this when a command is taking
+    too long or producing unwanted output.
+    """
+
+    command_id: str | None = Field(
+        default=None,
+        description="ID of the specific shell command to interrupt (None = current)",
+    )
+
+
+# =============================================================================
+# User Interaction Responses
+# =============================================================================
+
+
+class UserInputResponse(BaseCommand):
+    """Response to a UserInputRequest from the agent.
+
+    The prompt_id must match the prompt_id from the original UserInputRequest
+    so the agent can correlate the response with the request.
+    """
+
+    prompt_id: str = Field(
+        description="ID of the prompt this responds to (must match request)"
+    )
+    value: str = Field(description="The user's input value")
+
+
+class ConfirmationResponse(BaseCommand):
+    """Response to a ConfirmationRequest from the agent.
+
+    The user can confirm or deny, and optionally provide feedback text
+    if the original request had allow_feedback=True.
+    """
+
+    prompt_id: str = Field(
+        description="ID of the prompt this responds to (must match request)"
+    )
+    confirmed: bool = Field(
+        description="Whether the user confirmed (True) or denied (False)"
+    )
+    feedback: str | None = Field(
+        default=None,
+        description="Optional feedback text from the user",
+    )
+
+
+class SelectionResponse(BaseCommand):
+    """Response to a SelectionRequest from the agent.
+
+    Contains both the index and the value for convenience and validation.
+    The agent can verify that selected_value matches options[selected_index].
+    """
+
+    prompt_id: str = Field(
+        description="ID of the prompt this responds to (must match request)"
+    )
+    selected_index: int = Field(
+        ge=0,
+        description="Zero-based index of the selected option",
+    )
+    selected_value: str = Field(description="The value of the selected option")
+
+
+# =============================================================================
+# Union Type for Type Checking
+# =============================================================================
+
+
+# All concrete command types (excludes BaseCommand itself)
+AnyCommand = (
+    CancelAgentCommand
+    | InterruptShellCommand
+    | UserInputResponse
+    | ConfirmationResponse
+    | SelectionResponse
+)
+"""Union of all command types for type checking."""
+
+
+# =============================================================================
+# Export all public symbols
+# =============================================================================
+
+__all__ = [
+    # Base
+    "BaseCommand",
+    # Agent control
+    "CancelAgentCommand",
+    "InterruptShellCommand",
+    # User interaction responses
+    "UserInputResponse",
+    "ConfirmationResponse",
+    "SelectionResponse",
+    # Union type
+    "AnyCommand",
+]

code_muse/messaging/markdown_patches.py

@@ -0,0 +1,57 @@
+"""Patches for Rich's Markdown rendering.
+
+This module provides customizations to Rich's default Markdown rendering,
+particularly for header justification which is hardcoded to center in Rich.
+"""
+
+from rich import box
+from rich.markdown import Heading, Markdown
+from rich.panel import Panel
+from rich.text import Text
+
+
+class LeftJustifiedHeading(Heading):
+    """A heading that left-justifies text instead of centering.
+
+    Rich's default Heading class hardcodes `text.justify = 'center'`,
+    which can look odd in a CLI context. This subclass overrides that
+    to use left justification instead.
+    """
+
+    def __rich_console__(self, console, options):
+        """Render the heading with left justification."""
+        text = self.text
+        text.justify = "left"  # Override Rich's default 'center'
+
+        if self.tag == "h1":
+            # Draw a border around h1s (same as Rich default)
+            yield Panel(
+                text,
+                box=box.HEAVY,
+                style="markdown.h1.border",
+            )
+        else:
+            # Styled text for h2 and beyond (same as Rich default)
+            if self.tag == "h2":
+                yield Text("")
+            yield text
+
+
+_patched = False
+
+
+def patch_markdown_headings():
+    """Patch Rich's Markdown to use left-justified headings.
+
+    This function is idempotent - calling it multiple times has no effect
+    after the first call.
+    """
+    global _patched
+    if _patched:
+        return
+
+    Markdown.elements["heading_open"] = LeftJustifiedHeading
+    _patched = True
+
+
+__all__ = ["patch_markdown_headings", "LeftJustifiedHeading"]

code_muse/messaging/message_queue.py

@@ -0,0 +1,397 @@
+"""
+Message queue system for decoupling Rich console output from renderers.
+
+This allows interactive mode to consume messages and render them appropriately.
+"""
+
+import asyncio
+import logging
+import queue
+import threading
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from enum import Enum
+from typing import Any
+
+from rich.text import Text
+
+logger = logging.getLogger(__name__)
+
+
+class MessageType(Enum):
+    """Types of messages that can be sent through the queue."""
+
+    # Basic content types
+    INFO = "info"
+    SUCCESS = "success"
+    WARNING = "warning"
+    ERROR = "error"
+    DIVIDER = "divider"
+
+    # Tool-specific types
+    TOOL_OUTPUT = "tool_output"
+    COMMAND_OUTPUT = "command_output"
+    FILE_OPERATION = "file_operation"
+
+    # Agent-specific types
+    AGENT_REASONING = "agent_reasoning"
+    PLANNED_NEXT_STEPS = "planned_next_steps"
+    AGENT_RESPONSE = "agent_response"
+    AGENT_STATUS = "agent_status"
+
+    # Human interaction types
+    HUMAN_INPUT_REQUEST = "human_input_request"
+
+    # System types
+    SYSTEM = "system"
+    DEBUG = "debug"
+
+
+@dataclass
+class UIMessage:
+    """A message to be displayed in the UI."""
+
+    type: MessageType
+    content: str | Text | Any  # Can be Rich Text, Table, Markdown, etc.
+    timestamp: datetime = None
+    metadata: dict[str, Any] = None
+
+    def __post_init__(self):
+        if self.timestamp is None:
+            self.timestamp = datetime.now(UTC)
+        if self.metadata is None:
+            self.metadata = {}
+
+
+class MessageQueue:
+    """Thread-safe message queue for UI messages."""
+
+    def __init__(self, maxsize: int = 1000):
+        self._queue = queue.Queue(maxsize=maxsize)
+        self._async_queue = None  # Will be created when needed
+        self._async_queue_maxsize = maxsize
+        self._listeners = []
+        self._running = False
+        self._thread = None
+        self._startup_buffer = []  # Buffer messages before any renderer starts
+        self._has_active_renderer = False
+        self._event_loop = None  # Store reference to the event loop
+        self._prompt_responses = {}  # Store responses to human input requests
+        self._prompt_events = {}  # threading.Event per prompt_id
+        self._prompt_id_counter = 0  # Counter for unique prompt IDs
+
+    def start(self):
+        """Start the queue processing."""
+        if self._running:
+            return
+
+        self._running = True
+        self._thread = threading.Thread(target=self._process_messages, daemon=True)
+        self._thread.start()
+
+    def get_buffered_messages(self):
+        """Get all currently buffered messages without waiting."""
+        # First get any startup buffered messages
+        messages = list(self._startup_buffer)
+
+        # Then get any queued messages
+        while True:
+            try:
+                message = self._queue.get_nowait()
+                messages.append(message)
+            except queue.Empty:
+                break
+        return messages
+
+    def clear_startup_buffer(self):
+        """Clear the startup buffer after processing."""
+        self._startup_buffer.clear()
+
+    def stop(self):
+        """Stop the queue processing."""
+        self._running = False
+        if self._thread and self._thread.is_alive():
+            self._thread.join(timeout=1.0)
+
+    def emit(self, message: UIMessage):
+        """Emit a message to the queue."""
+        # If no renderer is active yet, buffer the message for startup
+        if not self._has_active_renderer:
+            self._startup_buffer.append(message)
+            return
+
+        try:
+            self._queue.put_nowait(message)
+        except queue.Full:
+            # Drop oldest message to make room
+            try:
+                self._queue.get_nowait()
+                self._queue.put_nowait(message)
+            except queue.Empty:
+                pass
+
+    def emit_simple(self, message_type: MessageType, content: Any, **metadata):
+        """Emit a simple message with just type and content."""
+        msg = UIMessage(type=message_type, content=content, metadata=metadata)
+        self.emit(msg)
+
+    def get_nowait(self) -> UIMessage | None:
+        """Get a message without blocking."""
+        try:
+            return self._queue.get_nowait()
+        except queue.Empty:
+            return None
+
+    def drain(self, timeout: float = 1.0) -> bool:
+        """Best-effort wait for queued messages to render.
+
+        Call this immediately before reading from stdin (input(), safe_input,
+        prompt_toolkit, etc.) so that any previously-emitted emit_info /
+        emit_warning text has a chance to actually appear on screen
+        before the prompt steals the terminal. Without this, a prompt label
+        can show up *above* the message that was meant to introduce it.
+
+        Args:
+            timeout: Maximum seconds to wait for the queue to empty.
+
+        Returns:
+            True if the queue drained within the timeout, False otherwise.
+        """
+        import time
+
+        # Fast path: queue already empty. Do one short paint-pause so the
+        # daemon thread can finish rendering whatever it just dequeued.
+        if self._queue.empty():
+            time.sleep(0.05)
+            return True
+
+        deadline = time.monotonic() + max(0.0, timeout)
+        while time.monotonic() < deadline:
+            if self._queue.empty():
+                time.sleep(0.05)
+                return True
+            time.sleep(0.02)
+        return False
+
+    async def get_async(self) -> UIMessage:
+        """Get a message asynchronously."""
+        # Lazy initialization of async queue and store event loop reference
+        if self._async_queue is None:
+            self._async_queue = asyncio.Queue(maxsize=self._async_queue_maxsize)
+            self._event_loop = asyncio.get_running_loop()
+        return await self._async_queue.get()
+
+    def _process_messages(self):
+        """Process messages from sync to async queue."""
+        while self._running:
+            try:
+                message = self._queue.get(timeout=0.1)
+
+                # Try to put in async queue if we have an event loop reference
+                if self._event_loop is not None and self._async_queue is not None:
+                    # Use thread-safe call to put message in async queue
+                    # Create a bound method to avoid closure issues
+                    try:
+                        self._event_loop.call_soon_threadsafe(
+                            self._async_queue.put_nowait, message
+                        )
+                    except Exception as e:
+                        logger.debug("Failed to enqueue message to async queue: %s", e)
+
+                # Notify listeners immediately for sync processing
+                for listener in self._listeners:
+                    try:
+                        listener(message)
+                    except Exception as e:
+                        logger.debug("Listener error in message queue: %s", e)
+
+            except queue.Empty:
+                continue
+
+    def add_listener(self, callback):
+        """Add a listener for messages (for direct sync consumption)."""
+        self._listeners.append(callback)
+        # Mark that we have an active renderer
+        self._has_active_renderer = True
+
+    def remove_listener(self, callback):
+        """Remove a listener."""
+        if callback in self._listeners:
+            self._listeners.remove(callback)
+        # If no more listeners, mark as no active renderer
+        if not self._listeners:
+            self._has_active_renderer = False
+
+    def mark_renderer_active(self):
+        """Mark that a renderer is now active and consuming messages."""
+        self._has_active_renderer = True
+
+    def mark_renderer_inactive(self):
+        """Mark that no renderer is currently active."""
+        self._has_active_renderer = False
+
+    def create_prompt_request(self, prompt_text: str) -> str:
+        """Create a human input request and return its unique ID."""
+        self._prompt_id_counter += 1
+        prompt_id = f"prompt_{self._prompt_id_counter}"
+
+        # Create event for this prompt
+        self._prompt_events[prompt_id] = threading.Event()
+
+        # Emit the human input request message
+        message = UIMessage(
+            type=MessageType.HUMAN_INPUT_REQUEST,
+            content=prompt_text,
+            metadata={"prompt_id": prompt_id},
+        )
+        self.emit(message)
+
+        return prompt_id
+
+    def wait_for_prompt_response(self, prompt_id: str, timeout: float = None) -> str:
+        """Wait for a response to a human input request."""
+        # If response is already available, return immediately
+        if prompt_id in self._prompt_responses:
+            self._prompt_events.pop(prompt_id, None)
+            return self._prompt_responses.pop(prompt_id)
+
+        event = self._prompt_events.get(prompt_id)
+        if event is None:
+            # Fallback: create event if not already present
+            event = threading.Event()
+            self._prompt_events[prompt_id] = event
+
+        signaled = event.wait(timeout=timeout)
+
+        # Clean up the event
+        self._prompt_events.pop(prompt_id, None)
+
+        if not signaled:
+            raise TimeoutError(f"No response for prompt {prompt_id} within {timeout}s")
+
+        return self._prompt_responses.pop(prompt_id)
+
+    def provide_prompt_response(self, prompt_id: str, response: str):
+        """Provide a response to a human input request."""
+        self._prompt_responses[prompt_id] = response
+        event = self._prompt_events.get(prompt_id)
+        if event is not None:
+            event.set()
+
+
+# Global message queue instance
+_global_queue: MessageQueue | None = None
+# FREE-THREADED: _queue_lock guards sync-only singleton creation.
+_queue_lock = threading.Lock()
+
+
+def get_global_queue() -> MessageQueue:
+    """Get or create the global message queue."""
+    global _global_queue
+
+    with _queue_lock:
+        if _global_queue is None:
+            _global_queue = MessageQueue()
+            _global_queue.start()
+
+    return _global_queue
+
+
+def get_buffered_startup_messages():
+    """Get any messages that were buffered before renderers started."""
+    queue = get_global_queue()
+    # Only return startup buffer messages, don't clear them yet
+    messages = list(queue._startup_buffer)
+    return messages
+
+
+def emit_message(message_type: MessageType, content: Any, **metadata):
+    """Convenience function to emit a message to the global queue."""
+    queue = get_global_queue()
+    queue.emit_simple(message_type, content, **metadata)
+
+
+def emit_info(content: Any, **metadata):
+    """Emit an info message."""
+    emit_message(MessageType.INFO, content, **metadata)
+
+
+def emit_success(content: Any, **metadata):
+    """Emit a success message."""
+    emit_message(MessageType.SUCCESS, content, **metadata)
+
+
+def emit_warning(content: Any, **metadata):
+    """Emit a warning message."""
+    emit_message(MessageType.WARNING, content, **metadata)
+
+
+def emit_error(content: Any, **metadata):
+    """Emit an error message."""
+    emit_message(MessageType.ERROR, content, **metadata)
+
+
+def emit_tool_output(content: Any, tool_name: str = None, **metadata):
+    """Emit tool output."""
+    if tool_name:
+        metadata["tool_name"] = tool_name
+    emit_message(MessageType.TOOL_OUTPUT, content, **metadata)
+
+
+def emit_command_output(content: Any, command: str = None, **metadata):
+    """Emit command output."""
+    if command:
+        metadata["command"] = command
+    emit_message(MessageType.COMMAND_OUTPUT, content, **metadata)
+
+
+def emit_agent_reasoning(content: Any, **metadata):
+    """Emit agent reasoning."""
+    emit_message(MessageType.AGENT_REASONING, content, **metadata)
+
+
+def emit_planned_next_steps(content: Any, **metadata):
+    """Emit planned_next_steps"""
+    emit_message(MessageType.PLANNED_NEXT_STEPS, content, **metadata)
+
+
+def emit_agent_response(content: Any, **metadata):
+    """Emit agent_response"""
+    emit_message(MessageType.AGENT_RESPONSE, content, **metadata)
+
+
+def emit_system_message(content: Any, **metadata):
+    """Emit a system message."""
+    emit_message(MessageType.SYSTEM, content, **metadata)
+
+
+def emit_divider(content: str = "─" * 100 + "\n", **metadata):
+    """Emit a divider line"""
+    # TUI mode has been removed, always emit dividers
+    emit_message(MessageType.DIVIDER, content, **metadata)
+
+
+def emit_prompt(prompt_text: str, timeout: float = None) -> str:
+    """Emit a human input request and wait for response.
+
+    Uses safe_input for cross-platform compatibility, especially on Windows
+    where raw input() can fail after prompt_toolkit Applications.
+
+    The drain() inside safe_input ensures the prompt_text we just enqueued
+    actually renders before stdin is read -- otherwise input() would race
+    ahead and the user would see a bare prompt with no question above it.
+    """
+    from code_muse.command_line.utils import safe_input
+    from code_muse.messaging import emit_info
+
+    emit_info(prompt_text)
+
+    # Use safe_input which resets Windows console state before reading
+    response = safe_input(">>> ")
+    return response
+
+
+def provide_prompt_response(prompt_id: str, response: str):
+    """Provide a response to a human input request."""
+    queue = get_global_queue()
+    queue.provide_prompt_response(prompt_id, response)