kweaver-dolphin 0.1.0__py3-none-any.whl

dolphin/cli/interrupt/handler.py

@@ -0,0 +1,205 @@
+"""
+Interrupt Token - Thread-safe signal bridge between CLI and Agent layers.
+
+This module provides the InterruptToken class which bridges UI threads (prompt_toolkit)
+and asyncio event loops, enabling safe communication of user interrupt signals.
+
+Key Features:
+- Thread-safe interrupt signaling using threading.Event
+- Bridges UI thread to asyncio event loop via run_coroutine_threadsafe
+- Idempotent trigger_interrupt() to handle multiple key presses
+- Clear separation from asyncio.Event used in Agent/Block layers
+
+Usage:
+    token = InterruptToken()
+    token.bind(agent, asyncio.get_running_loop())
+
+    # In UI thread (e.g., ESC key handler):
+    token.trigger_interrupt()
+
+    # After handling interrupt:
+    token.clear()
+"""
+
+import asyncio
+import threading
+from typing import TYPE_CHECKING, Optional
+
+if TYPE_CHECKING:
+    from dolphin.core.agent.base_agent import BaseAgent
+
+
+class InterruptToken:
+    """Thread-safe user interrupt token (CLI -> Agent signal bridge).
+
+    Bridges UI threads (prompt_toolkit) and asyncio event loops,
+    transmitting interrupt signals to the execution layer via agent.interrupt().
+
+    Terminology Alignment:
+    - CLI Layer: InterruptToken.trigger_interrupt()
+    - Agent Layer: agent.interrupt() / agent.resume_with_input()
+    - Block Layer: context.check_user_interrupt() / raise UserInterrupt
+
+    Thread Safety:
+    - Uses threading.Event internally (thread-safe)
+    - Schedules agent.interrupt() via run_coroutine_threadsafe
+
+    Warning:
+    - NEVER directly access agent._interrupt_event from UI thread
+    - asyncio.Event is NOT thread-safe, always use this bridge
+
+    Attributes:
+        _interrupted: Thread-safe event flag
+        _agent: Bound agent instance (optional)
+        _loop: Bound event loop (optional)
+    """
+
+    def __init__(self):
+        """Initialize the interrupt token."""
+        self._interrupted = threading.Event()
+        self._agent: Optional["BaseAgent"] = None
+        self._loop: Optional[asyncio.AbstractEventLoop] = None
+        self._pending_input: Optional[str] = None
+        self._realtime_input_buffer: str = "" # Real-time typing buffer
+
+    def bind(self, agent: "BaseAgent", loop: asyncio.AbstractEventLoop) -> None:
+        """Bind agent instance and event loop.
+
+        Must be called before trigger_interrupt() to enable signal transmission.
+
+        Args:
+            agent: The agent instance to interrupt
+            loop: The asyncio event loop running the agent
+        """
+        self._agent = agent
+        self._loop = loop
+
+    def unbind(self) -> None:
+        """Unbind agent and event loop.
+
+        Call this when the agent execution ends to prevent stale references.
+        """
+        self._agent = None
+        self._loop = None
+
+    def trigger_interrupt(self) -> None:
+        """Trigger user interrupt (called from UI thread, thread-safe).
+
+        This method is idempotent - calling it multiple times has no additional effect.
+
+        The interrupt signal is transmitted to the agent layer by scheduling
+        agent.interrupt() on the bound event loop using run_coroutine_threadsafe.
+        """
+        if self._interrupted.is_set():
+            return  # Idempotent
+
+        self._interrupted.set()
+
+        # Cross-thread scheduling of agent.interrupt()
+        if self._agent and self._loop:
+            try:
+                asyncio.run_coroutine_threadsafe(
+                    self._agent.interrupt(),
+                    self._loop
+                )
+            except Exception:
+                # Ignore errors if loop is closed or agent is unavailable
+                pass
+
+    def is_interrupted(self) -> bool:
+        """Check if interrupt has been triggered.
+
+        Returns:
+            True if interrupt was triggered, False otherwise
+        """
+        return self._interrupted.is_set()
+
+    def clear(self) -> None:
+        """Clear interrupt state (call before starting a new execution round).
+
+        This resets the token for the next user input cycle.
+        Also clears any pending user input and real-time buffer.
+        """
+        self._interrupted.clear()
+        self._pending_input = None
+        self._realtime_input_buffer = ""
+
+    def append_realtime_input(self, char: str) -> str:
+        """Append a character to the real-time input buffer.
+
+        Args:
+            char: Character to append
+
+        Returns:
+            The full current buffer
+        """
+        if char == "\x1b": # ESC
+            return self._realtime_input_buffer
+        
+        if char in ("\x7f", "\x08"): # Backspace
+            self._realtime_input_buffer = self._realtime_input_buffer[:-1]
+        else:
+            self._realtime_input_buffer += char
+        return self._realtime_input_buffer
+
+    def get_realtime_input(self, consume: bool = True) -> str:
+        """Get the current real-time input buffer.
+
+        Args:
+            consume: Whether to clear the buffer after reading
+
+        Returns:
+            The current buffer string
+        """
+        res = self._realtime_input_buffer
+        if consume:
+            self._realtime_input_buffer = ""
+        return res
+
+    def set_pending_input(self, user_input: Optional[str]) -> None:
+        """Store pending user input for resume.
+
+        Args:
+            user_input: The user's new instruction after interrupt
+        """
+        self._pending_input = user_input
+
+    def get_pending_input(self) -> Optional[str]:
+        """Get and clear pending user input.
+
+        Returns:
+            The pending user input, or None if no input is pending
+        """
+        result = self._pending_input
+        self._pending_input = None
+        return result
+
+    async def wait_for_interrupt(self, timeout: Optional[float] = None) -> bool:
+        """Async wait for interrupt signal (for use in asyncio code).
+
+        This is a convenience method for asyncio code that needs to wait
+        for an interrupt signal without blocking the event loop.
+
+        Args:
+            timeout: Maximum time to wait in seconds, None for indefinite
+
+        Returns:
+            True if interrupted, False if timeout
+        """
+        loop = asyncio.get_running_loop()
+
+        def check_interrupted():
+            return self._interrupted.wait(timeout=0.1)
+
+        start_time = loop.time()
+        while True:
+            if self._interrupted.is_set():
+                return True
+
+            if timeout is not None:
+                elapsed = loop.time() - start_time
+                if elapsed >= timeout:
+                    return False
+
+            # Yield control to allow other coroutines to run
+            await asyncio.sleep(0.05)

dolphin/cli/interrupt/keyboard.py

@@ -0,0 +1,82 @@
+
+import asyncio
+import threading
+import sys
+import select
+from typing import Optional
+
+async def _monitor_interrupt(token, stop_event: threading.Event):
+    """Monitor stdin for ESC key in a separate thread."""
+    loop = asyncio.get_running_loop()
+    try:
+        await loop.run_in_executor(None, _blocking_stdin_monitor, token, stop_event)
+    except:
+        pass
+
+def _blocking_stdin_monitor(token, stop_event: threading.Event):
+    """Blocking monitor for ESC key using select/termios."""
+    import tty
+    import termios
+    
+    if not sys.stdin.isatty():
+        return
+        
+    fd = sys.stdin.fileno()
+    try:
+        old_settings = termios.tcgetattr(fd)
+    except:
+        return
+
+    try:
+        # Set to cbreak mode to read keys without waiting for newline
+        tty.setcbreak(fd)
+        while not stop_event.is_set():
+            # Check if input is available (timeout 0.1s)
+            if select.select([sys.stdin], [], [], 0.1)[0]:
+                try:
+                    key = sys.stdin.read(1)
+                    if key == '\x1b': # ESC code
+                        token.trigger_interrupt()
+                        # Once triggered, we can stop
+                        break
+                    elif key == '\x03': # Ctrl-C
+                        # Also trigger interrupt on Ctrl-C
+                        token.trigger_interrupt()
+                        break
+                    elif key in ('\r', '\n'): # Enter
+                        # Treat Enter as an interrupt signal only if there is buffered text
+                        # This makes the UI feel like a real-time chat
+                        if token._realtime_input_buffer:
+                            token.trigger_interrupt()
+                            break
+                        # Otherwise ignore empty Enter
+                    else:
+                        # Append to buffer and ECHO to the fixed input line
+                        buffer = token.append_realtime_input(key)
+                        
+                        # Echoing with cursor preservation
+                        try:
+                            import shutil
+                            height = shutil.get_terminal_size().lines
+                            # Save cursor, move to bottom line, clear, draw prompt + buffer, restore
+                            # We use atomic write to minimize flickering
+                            echo_output = (
+                                f"\0337"                 # Save cursor
+                                f"\033[{height};1H"      # Move to bottom line
+                                f"\033[K> {buffer}█"     # Clear and draw with block cursor
+                                f"\0338"                 # Restore cursor
+                            )
+                            sys.stdout.write(echo_output)
+                            sys.stdout.flush()
+                        except:
+                            pass
+                except:
+                    break
+    except:
+        pass
+    finally:
+        # ABSOLUTELY ESSENTIAL: Restore original terminal settings
+        try:
+            termios.tcsetattr(fd, termios.TCSADRAIN, old_settings)
+        except:
+            pass

dolphin/cli/main.py

@@ -0,0 +1,49 @@
+"""
+Main entry point for Dolphin CLI
+
+This module provides the main() function that serves as the CLI entry point.
+"""
+
+import asyncio
+import logging
+
+from dolphin.cli.args.parser import parseArgs
+from dolphin.cli.runner.runner import runDolphin
+from dolphin.cli.utils.helpers import setupFlagsFromArgs
+
+
+def main() -> None:
+    """Main CLI entry point
+    
+    This function:
+    1. Parses command-line arguments
+    2. Sets up logging
+    3. Configures feature flags
+    4. Runs the dolphin program
+    """
+    args = parseArgs()
+    
+    # Setup logging
+    from dolphin.core.logging.logger import setup_default_logger, set_log_level
+    
+    setup_default_logger(args.logSuffix)
+    
+    if args.logLevel:
+        logLevelMap = {
+            "DEBUG": logging.DEBUG,
+            "INFO": logging.INFO,
+            "WARNING": logging.WARNING,
+            "ERROR": logging.ERROR,
+        }
+        set_log_level(logLevelMap.get(args.logLevel, logging.INFO))
+    
+    # Setup feature flags
+    setupFlagsFromArgs(args)
+    
+    # Run
+    asyncio.run(runDolphin(args))
+
+
+if __name__ == "__main__":
+    main()
+

dolphin/cli/multimodal/__init__.py

@@ -0,0 +1,34 @@
+"""
+Multimodal input module for Dolphin CLI.
+
+This module provides support for multimodal input in the CLI, including:
+- Clipboard image reading (@paste)
+- File path references (@image:<path>)
+- URL references (@url:<url>)
+"""
+
+from dolphin.cli.multimodal.input_parser import (
+    MultimodalInputParser,
+    ParsedMultimodalInput,
+    ImageReference,
+    ImageSourceType,
+)
+from dolphin.cli.multimodal.clipboard import ClipboardImageReader
+from dolphin.cli.multimodal.image_processor import ImageProcessor, ImageProcessConfig
+from dolphin.cli.multimodal.handler import (
+    MultimodalInputHandler,
+    process_multimodal_input,
+)
+
+__all__ = [
+    "MultimodalInputParser",
+    "ParsedMultimodalInput",
+    "ImageReference",
+    "ImageSourceType",
+    "ClipboardImageReader",
+    "ImageProcessor",
+    "ImageProcessConfig",
+    "MultimodalInputHandler",
+    "process_multimodal_input",
+]
+

dolphin/cli/multimodal/clipboard.py

@@ -0,0 +1,327 @@
+"""
+Clipboard image reader for multimodal CLI input.
+
+Provides cross-platform clipboard image reading functionality.
+
+Platform Support (Linux-first for commercial deployments):
+- Linux X11: Primary target, requires PIL and xclip/xsel
+- macOS: Secondary platform, requires pyobjc (AppKit)
+- macOS: Secondary platform, requires pyobjc (AppKit)
+- Windows: Fallback, requires PIL
+"""
+
+import io
+import sys
+import os
+import base64
+from typing import Optional
+
+from dolphin.core.common.multimodal import ClipboardEmptyError
+from dolphin.core.logging.logger import get_logger
+
+logger = get_logger("clipboard")
+
+
+class ClipboardImageReader:
+    """Cross-platform clipboard image reader.
+    
+    Platform priority (Linux-first for commercial deployments):
+    - Linux X11: Primary target, uses Pillow's ImageGrab
+    - Linux Wayland: Quick fail with clear message
+    - macOS: Secondary platform, uses AppKit/Cocoa APIs
+    - Windows: Fallback, uses Pillow's ImageGrab
+        reader = ClipboardImageReader()
+        data = reader.read()
+        if data:
+            url = reader.to_base64_url(data)
+    """
+    
+    def read(self) -> Optional[bytes]:
+        """Read image data from clipboard.
+        
+        Platform detection order (Linux-first for commercial deployments):
+        1. Linux (X11) - Primary target for commercial versions
+        2. Linux (Wayland) - Quick fail with clear message
+        3. macOS - Secondary platform
+        4. Windows - Fallback
+        
+        Returns:
+            PNG image data as bytes, or None if no image in clipboard
+            
+        Note:
+            On failure, logs a warning with platform-specific guidance.
+        """
+        platform = sys.platform
+        import os
+        
+        try:
+            # Linux-first: Commercial versions primarily run on Linux
+            if platform.startswith("linux"):
+                # Quick check for Wayland (not supported)
+                if "WAYLAND_DISPLAY" in os.environ:
+                    logger.warning(
+                        "Clipboard image read not supported on Wayland. "
+                        "Please use file upload instead: /image path/to/image.png"
+                    )
+                    return None
+                
+                # Try Linux X11 method (Pillow ImageGrab)
+                data = self._read_linux()
+                if data is not None:
+                    return data
+            
+            # macOS fallback
+            elif platform == "darwin":
+                data = self._read_macos()
+                if data is not None:
+                    return data
+            
+            # Windows fallback
+            elif platform == "win32":
+                data = self._read_windows()
+                if data is not None:
+                    return data
+            
+            # No image found - this is normal, not an error
+            return None
+            
+        except Exception as e:
+            # Log platform-specific guidance
+            self._log_platform_error(platform, e)
+            return None
+    
+    def _log_platform_error(self, platform: str, error: Exception) -> None:
+        """Log platform-specific error message with helpful guidance.
+        
+        Args:
+            platform: sys.platform value
+            error: The exception that occurred
+        """
+        if platform == "darwin":
+            logger.warning(
+                f"Clipboard image read failed on macOS: {error}. "
+                f"Install pyobjc: pip install pyobjc-framework-Cocoa"
+            )
+        elif platform.startswith("linux"):
+            # Detect Wayland
+            wayland_display = sys.platform.startswith("linux") and "WAYLAND_DISPLAY" in __import__("os").environ
+            if wayland_display:
+                logger.warning(
+                    f"Clipboard image read not supported on Wayland. "
+                    f"Please use file upload instead: /image path/to/image.png"
+                )
+            else:
+                logger.warning(
+                    f"Clipboard image read failed on Linux: {error}. "
+                    f"Install dependencies: pip install pillow && sudo apt-get install xclip"
+                )
+        elif platform == "win32":
+            logger.warning(
+                f"Clipboard image read failed on Windows: {error}. "
+                f"Install Pillow: pip install pillow"
+            )
+        else:
+            logger.warning(
+                f"Clipboard image read failed on {platform}: {error}"
+            )
+    
+    def _read_macos(self) -> Optional[bytes]:
+        """Read clipboard on macOS using AppKit.
+        
+        Returns:
+            Image data as PNG bytes, or None if not available
+            
+        Raises:
+            ImportError: If pyobjc is not installed
+        """
+        try:
+            from AppKit import NSPasteboard, NSPasteboardTypePNG, NSPasteboardTypeTIFF
+            
+            pb = NSPasteboard.generalPasteboard()
+            
+            # Try PNG first
+            data = pb.dataForType_(NSPasteboardTypePNG)
+            if data:
+                return bytes(data)
+            
+            # Try TIFF (macOS screenshots are often TIFF)
+            data = pb.dataForType_(NSPasteboardTypeTIFF)
+            if data:
+                return self._convert_to_png(bytes(data))
+            
+            return None
+        except ImportError as e:
+            # AppKit not available - re-raise for proper error handling
+            raise ImportError(
+                "pyobjc not installed. Install with: pip install pyobjc-framework-Cocoa"
+            ) from e
+    
+    def _convert_to_png(self, image_data: bytes) -> bytes:
+        """Convert image data to PNG format.
+        
+        Args:
+            image_data: Image data in any format supported by Pillow
+            
+        Returns:
+            PNG image data
+        """
+        try:
+            from PIL import Image
+            
+            img = Image.open(io.BytesIO(image_data))
+            output = io.BytesIO()
+            
+            # Handle RGBA to RGB conversion if needed
+            if img.mode in ('RGBA', 'LA') or (img.mode == 'P' and 'transparency' in img.info):
+                # Keep as PNG to preserve transparency
+                img.save(output, format='PNG')
+            else:
+                img.save(output, format='PNG')
+            
+            return output.getvalue()
+        except Exception as e:
+            raise RuntimeError(f"Failed to convert image to PNG: {e}")
+    
+    def _read_linux(self) -> Optional[bytes]:
+        """Read clipboard on Linux X11 using Pillow's ImageGrab.
+        
+        Returns:
+            Image data as PNG bytes, or None if not available
+            
+        Raises:
+            ImportError: If PIL is not installed
+            RuntimeError: If clipboard access fails (e.g., no X server)
+        """
+        try:
+            from PIL import ImageGrab
+            
+            img = ImageGrab.grabclipboard()
+            if img is None:
+                return None
+            
+            output = io.BytesIO()
+            img.save(output, format='PNG')
+            return output.getvalue()
+        except ImportError as e:
+            # Pillow not installed - re-raise for proper error handling
+            raise ImportError(
+                "Pillow not installed. Install with: pip install pillow"
+            ) from e
+    
+    def _read_windows(self) -> Optional[bytes]:
+        """Read clipboard on Windows using Pillow's ImageGrab.
+        
+        Returns:
+            Image data as PNG bytes, or None if not available
+            
+        Raises:
+            ImportError: If PIL is not installed
+            RuntimeError: If clipboard access fails
+        """
+        try:
+            from PIL import ImageGrab
+            
+            img = ImageGrab.grabclipboard()
+            if img is None:
+                return None
+            
+            output = io.BytesIO()
+            img.save(output, format='PNG')
+            return output.getvalue()
+        except ImportError as e:
+            # Pillow not installed - re-raise for proper error handling
+            raise ImportError(
+                "Pillow not installed. Install with: pip install pillow"
+            ) from e
+    
+    def to_base64_url(self, image_data: bytes, mime_type: str = "image/png") -> str:
+        """Convert image data to base64 data URL.
+        
+        Args:
+            image_data: Raw image bytes
+            mime_type: MIME type of the image (default: image/png)
+            
+        Returns:
+            Data URL string (e.g., "data:image/png;base64,...")
+        """
+        b64 = base64.b64encode(image_data).decode('utf-8')
+        return f"data:{mime_type};base64,{b64}"
+    
+    def read_as_base64_url(self) -> str:
+        """Read clipboard image and return as base64 data URL.
+        
+        Returns:
+            Data URL string
+            
+        Raises:
+            ClipboardEmptyError: If no image in clipboard
+        """
+        data = self.read()
+        if data is None:
+            raise ClipboardEmptyError("No image found in clipboard")
+        return self.to_base64_url(data)
+    
+    def has_image(self) -> bool:
+        """Check if clipboard contains an image.
+        
+        Returns:
+            True if clipboard has an image
+        """
+        return self.read() is not None
+    
+    @staticmethod
+    def get_platform_support_info() -> dict:
+        """Get platform-specific clipboard support information.
+        
+        Returns:
+            Dictionary with platform support details
+        """
+        platform = sys.platform
+        import os
+        
+        info = {
+            "platform": platform,
+            "supported": True,
+            "requirements": [],
+            "notes": []
+        }
+        
+        if platform == "darwin":
+            info["requirements"] = ["pyobjc-framework-Cocoa"]
+            info["notes"] = ["May require clipboard access permission in System Preferences"]
+            try:
+                import AppKit
+                info["installed"] = True
+            except ImportError:
+                info["installed"] = False
+                
+        elif platform.startswith("linux"):
+            wayland = "WAYLAND_DISPLAY" in os.environ
+            if wayland:
+                info["supported"] = False
+                info["notes"] = [
+                    "Wayland display server detected",
+                    "Clipboard image reading not supported",
+                    "Use file upload instead: /image path/to/file.png"
+                ]
+            else:
+                info["requirements"] = ["pillow", "xclip or xsel (system package)"]
+                info["notes"] = ["Requires X11 display server"]
+                try:
+                    from PIL import ImageGrab
+                    info["installed"] = True
+                except ImportError:
+                    info["installed"] = False
+                    
+        elif platform == "win32":
+            info["requirements"] = ["pillow"]
+            try:
+                from PIL import ImageGrab
+                info["installed"] = True
+            except ImportError:
+                info["installed"] = False
+        else:
+            info["supported"] = False
+            info["notes"] = [f"Platform '{platform}' not explicitly supported"]
+        
+        return info