ai-comm 0.2.4__py3-none-any.whl

ai_comm/kitten_client.py

@@ -0,0 +1,199 @@
+"""Kitten client - wrapper for calling the simplified kitten via subprocess."""
+
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+
+class KittenError(Exception):
+    """Base exception for kitten errors."""
+
+    pass
+
+
+class WindowNotFoundError(KittenError):
+    """Window not found."""
+
+    pass
+
+
+class KittenCallError(KittenError):
+    """Failed to call kitten."""
+
+    pass
+
+
+@dataclass
+class KittenResult:
+    """Result from kitten call."""
+
+    status: str
+    data: dict[str, Any]
+
+
+class KittenClient:
+    """Client for calling the simplified ai_comm_kitten."""
+
+    # Default kitten path - bundled within the package
+    KITTEN_PATH = Path(__file__).parent / "kitten" / "ai_comm_kitten.py"
+
+    def __init__(self, socket: str | None = None) -> None:
+        """Initialize client.
+
+        Args:
+            socket: Optional kitty socket path. If None, uses KITTY_LISTEN_ON env var.
+        """
+        self.socket = socket or os.environ.get("KITTY_LISTEN_ON")
+        self._kitten_path = str(self.KITTEN_PATH.resolve())
+
+    def _call(self, *args: str, timeout: float = 15) -> KittenResult:
+        """Call kitten and return result.
+
+        Args:
+            *args: Arguments to pass to kitten
+            timeout: Subprocess timeout in seconds
+
+        Returns:
+            KittenResult with status and data
+
+        Raises:
+            KittenCallError: If call fails
+            WindowNotFoundError: If window not found
+        """
+        cmd = ["kitty", "@"]
+        if self.socket:
+            cmd.extend(["--to", self.socket])
+        cmd.extend(["kitten", self._kitten_path, *args])
+
+        try:
+            result = subprocess.run(
+                cmd,
+                check=False,
+                capture_output=True,
+                text=True,
+                timeout=timeout,
+            )
+        except subprocess.TimeoutExpired as e:
+            raise KittenCallError(f"Kitten call timed out after {timeout}s") from e
+        except Exception as e:
+            raise KittenCallError(f"Failed to call kitten: {e}") from e
+
+        if result.returncode != 0:
+            stderr = result.stderr.strip()
+            if "i/o timeout" in stderr.lower():
+                raise KittenCallError("Kitty I/O timeout - kitten took too long")
+            raise KittenCallError(f"Kitten failed: {stderr or result.stdout}")
+
+        try:
+            data = json.loads(result.stdout)
+        except json.JSONDecodeError as e:
+            raise KittenCallError(f"Invalid JSON from kitten: {result.stdout}") from e
+
+        if data.get("status") == "error":
+            msg = data.get("message", "Unknown error")
+            if "not found" in msg.lower():
+                raise WindowNotFoundError(msg)
+            raise KittenCallError(msg)
+
+        return KittenResult(status=data["status"], data=data)
+
+    def get_text(self, window_id: int, extent: str = "all") -> str:
+        """Get text content from window.
+
+        Args:
+            window_id: Target window ID
+            extent: "all" or "screen"
+
+        Returns:
+            Window text content
+        """
+        result = self._call("get-text", "--window", str(window_id), "--extent", extent)
+        text: str = result.data.get("text", "")
+        return text
+
+    def get_text_hash(self, window_id: int, extent: str = "all") -> tuple[str, str]:
+        """Get text content and hash from window.
+
+        Args:
+            window_id: Target window ID
+            extent: "all" or "screen"
+
+        Returns:
+            Tuple of (text, hash)
+        """
+        result = self._call("get-text", "--window", str(window_id), "--extent", extent)
+        text: str = result.data.get("text", "")
+        hash_val: str = result.data.get("hash", "")
+        return text, hash_val
+
+    def send_text(self, window_id: int, text: str) -> bool:
+        """Send text to window.
+
+        Args:
+            window_id: Target window ID
+            text: Text to send
+
+        Returns:
+            True if successful
+        """
+        result = self._call("send-text", "--window", str(window_id), text)
+        return result.status == "ok"
+
+    def send_key(self, window_id: int, key: str) -> bool:
+        """Send key press to window.
+
+        Args:
+            window_id: Target window ID
+            key: Key name (e.g., "enter", "escape")
+
+        Returns:
+            True if successful
+        """
+        result = self._call("send-key", "--window", str(window_id), key)
+        return result.status == "ok"
+
+    def check_idle(self, window_id: int, last_hash: str = "") -> tuple[bool, str]:
+        """Check if window content has changed.
+
+        Args:
+            window_id: Target window ID
+            last_hash: Previous content hash
+
+        Returns:
+            Tuple of (is_idle, current_hash)
+        """
+        result = self._call(
+            "check-idle", "--window", str(window_id), "--last-hash", last_hash
+        )
+        return result.data.get("idle", False), result.data.get("hash", "")
+
+    def list_ai_windows(self) -> list[dict[str, Any]]:
+        """List windows running AI CLIs.
+
+        Returns:
+            List of AI window info dicts with id, cli, cwd
+        """
+        result = self._call("list-ai-windows")
+        ai_windows: list[dict[str, Any]] = result.data.get("ai_windows", [])
+        return ai_windows
+
+    def get_window_cli(self, window_id: int) -> str | None:
+        """Get CLI type for a window.
+
+        Args:
+            window_id: Target window ID
+
+        Returns:
+            CLI name (e.g., "claude", "codex") or None if not an AI window
+        """
+        ai_windows = self.list_ai_windows()
+        for w in ai_windows:
+            if w["id"] == window_id:
+                cli: str = w["cli"]
+                return cli
+        return None

ai_comm/parsers/__init__.py

@@ -0,0 +1,27 @@
+"""Response parsers - low-level parsing utilities.
+
+For AI CLI adapters, use ai_comm.adapters instead.
+"""
+
+from __future__ import annotations
+
+from .base import ResponseCollector, ResponseParser
+from .utils import (
+    clean_response_lines,
+    is_separator_line,
+    join_response,
+    remove_base_indent,
+    strip_leading_empty,
+    strip_trailing_empty,
+)
+
+__all__ = [
+    "ResponseCollector",
+    "ResponseParser",
+    "clean_response_lines",
+    "is_separator_line",
+    "join_response",
+    "remove_base_indent",
+    "strip_leading_empty",
+    "strip_trailing_empty",
+]

ai_comm/parsers/base.py

@@ -0,0 +1,108 @@
+"""Base class for response parsers."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import ClassVar
+
+from .utils import clean_response_lines, join_response, remove_base_indent
+
+
+class ResponseParser(ABC):
+    """Abstract base class for AI CLI response parsers.
+
+    Subclasses should override:
+    - name: Parser identifier
+    - STATUS_INDICATORS: Strings that indicate status bar lines (filtered out)
+    - BASE_INDENT: Number of spaces for base indentation (stripped from content)
+    - extract_last_response(): Main parsing logic
+    """
+
+    name: str = "base"
+
+    # Override in subclasses: strings that indicate status bar lines
+    STATUS_INDICATORS: ClassVar[list[str]] = []
+
+    # Override in subclasses: base indentation to strip (0 = no stripping)
+    BASE_INDENT: ClassVar[int] = 0
+
+    @abstractmethod
+    def extract_last_response(self, text: str) -> str:
+        """Extract the last response from the terminal output.
+
+        Args:
+            text: Full terminal text content (screen + scrollback)
+
+        Returns:
+            The extracted response text
+        """
+        raise NotImplementedError
+
+    def is_status_line(self, line: str) -> bool:
+        """Check if line is a status bar line (should be skipped)."""
+        if not self.STATUS_INDICATORS:
+            return False
+        stripped = line.strip()
+        return any(indicator in stripped for indicator in self.STATUS_INDICATORS)
+
+    def strip_indent(self, line: str) -> str:
+        """Remove base indentation from line."""
+        return remove_base_indent(line, self.BASE_INDENT)
+
+    def finalize_response(self, lines: list[str]) -> str:
+        """Clean up and join response lines."""
+        cleaned = clean_response_lines(lines)
+        return join_response(cleaned)
+
+
+class ResponseCollector:
+    """Helper for collecting multi-block responses.
+
+    Common pattern used by most parsers:
+    - Track multiple response blocks
+    - Handle in_response state
+    - Save current block when new one starts or control element found
+    """
+
+    def __init__(self) -> None:
+        self.responses: list[list[str]] = []
+        self.current: list[str] = []
+        self.in_response: bool = False
+
+    def start_new(self, first_line: str | None = None) -> None:
+        """Start a new response block, saving current if exists."""
+        if self.in_response and self.current:
+            self.responses.append(self.current)
+        self.current = []
+        self.in_response = True
+        if first_line is not None:
+            self.current.append(first_line)
+
+    def end_current(self) -> None:
+        """End current response block."""
+        if self.in_response and self.current:
+            self.responses.append(self.current)
+            self.current = []
+        self.in_response = False
+
+    def add_line(self, line: str) -> None:
+        """Add line to current response if collecting."""
+        if self.in_response:
+            self.current.append(line)
+
+    def add_empty(self) -> None:
+        """Add empty line to current response if collecting."""
+        if self.in_response:
+            self.current.append("")
+
+    def finalize(self) -> list[str]:
+        """Get the last response block."""
+        # Don't forget current block
+        if self.in_response and self.current:
+            self.responses.append(self.current)
+            self.current = []
+            self.in_response = False
+
+        if self.responses:
+            return self.responses[-1]
+        return []

ai_comm/parsers/utils.py

@@ -0,0 +1,42 @@
+"""Common utilities for response parsers."""
+
+from __future__ import annotations
+
+
+def is_separator_line(line: str) -> bool:
+    """Check if line is a separator (all ─ characters)."""
+    stripped = line.strip()
+    return bool(stripped) and all(c == "─" for c in stripped)
+
+
+def strip_trailing_empty(lines: list[str]) -> list[str]:
+    """Remove trailing empty lines from a list."""
+    result = lines.copy()
+    while result and not result[-1].strip():
+        result.pop()
+    return result
+
+
+def strip_leading_empty(lines: list[str]) -> list[str]:
+    """Remove leading empty lines from a list."""
+    result = lines.copy()
+    while result and not result[0].strip():
+        result.pop(0)
+    return result
+
+
+def clean_response_lines(lines: list[str]) -> list[str]:
+    """Strip leading and trailing empty lines."""
+    return strip_leading_empty(strip_trailing_empty(lines))
+
+
+def remove_base_indent(line: str, indent: int) -> str:
+    """Remove base indentation while preserving relative indent."""
+    if indent > 0 and line.startswith(" " * indent):
+        return line[indent:]
+    return line
+
+
+def join_response(lines: list[str]) -> str:
+    """Join response lines and strip result."""
+    return "\n".join(lines).strip()

ai_comm/polling.py

@@ -0,0 +1,88 @@
+"""Polling logic for waiting on window content changes."""
+
+from __future__ import annotations
+
+import time
+from collections.abc import Callable
+
+
+class PollingTimeoutError(Exception):
+    """Raised when polling times out."""
+
+    def __init__(self, timeout: float, elapsed: float) -> None:
+        super().__init__(f"Timeout after {elapsed:.1f}s (limit: {timeout}s)")
+        self.timeout = timeout
+        self.elapsed = elapsed
+
+
+def wait_for_idle(
+    check_fn: Callable[[str], tuple[bool, str]],
+    idle_seconds: int = 3,
+    timeout: float = 1800,
+    poll_interval: float = 1.0,
+) -> float:
+    """Wait for content to stabilize.
+
+    Args:
+        check_fn: Function that takes last_hash and returns (is_same, current_hash)
+        idle_seconds: Number of consecutive stable checks required
+        timeout: Maximum wait time in seconds
+        poll_interval: Time between checks in seconds
+
+    Returns:
+        Total elapsed time in seconds
+
+    Raises:
+        PollingTimeoutError: If timeout is reached
+    """
+    start_time = time.time()
+    last_hash = ""
+    stable_count = 0
+
+    while True:
+        elapsed = time.time() - start_time
+        if elapsed >= timeout:
+            raise PollingTimeoutError(timeout, elapsed)
+
+        is_same, current_hash = check_fn(last_hash)
+
+        if is_same and last_hash:
+            stable_count += 1
+            if stable_count >= idle_seconds:
+                return elapsed
+        else:
+            stable_count = 0
+            last_hash = current_hash
+
+        time.sleep(poll_interval)
+
+
+def poll_until(
+    condition_fn: Callable[[], bool],
+    timeout: float = 1800,
+    poll_interval: float = 1.0,
+) -> float:
+    """Poll until condition is true.
+
+    Args:
+        condition_fn: Function that returns True when done
+        timeout: Maximum wait time in seconds
+        poll_interval: Time between checks in seconds
+
+    Returns:
+        Total elapsed time in seconds
+
+    Raises:
+        PollingTimeoutError: If timeout is reached
+    """
+    start_time = time.time()
+
+    while True:
+        elapsed = time.time() - start_time
+        if elapsed >= timeout:
+            raise PollingTimeoutError(timeout, elapsed)
+
+        if condition_fn():
+            return elapsed
+
+        time.sleep(poll_interval)

ai_comm/registry.py

@@ -0,0 +1,75 @@
+"""Unified CLI registry - single source of truth for CLI metadata."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class CLIInfo:
+    """Metadata for a supported AI CLI."""
+
+    name: str
+    display_name: str
+    aliases: tuple[str, ...]
+    adapter_module: str
+
+
+CLI_REGISTRY: dict[str, CLIInfo] = {
+    "claude": CLIInfo(
+        name="claude",
+        display_name="Claude Code",
+        aliases=("claude",),
+        adapter_module="ai_comm.adapters.claude",
+    ),
+    "codex": CLIInfo(
+        name="codex",
+        display_name="Codex CLI",
+        aliases=("codex",),
+        adapter_module="ai_comm.adapters.codex",
+    ),
+    "gemini": CLIInfo(
+        name="gemini",
+        display_name="Gemini CLI",
+        aliases=("gemini",),
+        adapter_module="ai_comm.adapters.gemini",
+    ),
+    "aider": CLIInfo(
+        name="aider",
+        display_name="Aider",
+        aliases=("aider",),
+        adapter_module="ai_comm.adapters.aider",
+    ),
+    "cursor": CLIInfo(
+        name="cursor",
+        display_name="Cursor",
+        aliases=("cursor", "cursor-cli", "cursor-agent"),
+        adapter_module="ai_comm.adapters.cursor",
+    ),
+    "opencode": CLIInfo(
+        name="opencode",
+        display_name="OpenCode",
+        aliases=("opencode",),
+        adapter_module="ai_comm.adapters.opencode",
+    ),
+}
+
+
+def get_display_name(cli_name: str) -> str:
+    """Get human-readable display name for CLI."""
+    info = CLI_REGISTRY.get(cli_name)
+    return info.display_name if info else cli_name.capitalize()
+
+
+def get_canonical_name(process_name: str) -> str | None:
+    """Map process name/alias to canonical CLI name."""
+    process_lower = process_name.lower()
+    for name, info in CLI_REGISTRY.items():
+        if process_lower in info.aliases:
+            return name
+    return None
+
+
+def list_cli_names() -> list[str]:
+    """List all registered CLI names."""
+    return list(CLI_REGISTRY.keys())

ai_comm/services/__init__.py

@@ -0,0 +1,7 @@
+"""Services for ai-comm."""
+
+from __future__ import annotations
+
+from .interaction import InteractionService
+
+__all__ = ["InteractionService"]

ai_comm/services/interaction.py

@@ -0,0 +1,115 @@
+"""Interaction service - unified send and response logic."""
+
+from __future__ import annotations
+
+import os
+import time
+from typing import TYPE_CHECKING
+
+from ai_comm.adapters import get_adapter
+from ai_comm.polling import wait_for_idle
+from ai_comm.registry import get_display_name
+
+if TYPE_CHECKING:
+    from ai_comm.kitten_client import KittenClient
+
+
+class InteractionService:
+    """Unified service for AI CLI interactions.
+
+    Handles message formatting, sending, waiting, and response fetching.
+    Accepts KittenClient via dependency injection.
+    """
+
+    def __init__(self, client: KittenClient) -> None:
+        """Initialize with injected client."""
+        self.client = client
+
+    def get_sender_name(self) -> str | None:
+        """Get the sender CLI name from current window."""
+        window_id_str = os.environ.get("KITTY_WINDOW_ID")
+        if not window_id_str:
+            return None
+        try:
+            window_id = int(window_id_str)
+            cli_type = self.client.get_window_cli(window_id)
+            if cli_type:
+                return get_display_name(cli_type)
+        except (ValueError, Exception):
+            pass
+        return None
+
+    def send_message(
+        self,
+        window_id: int,
+        message: str,
+        add_sender_header: bool = True,
+    ) -> None:
+        """Format and send message to target window."""
+        cli_type = self.client.get_window_cli(window_id)
+        adapter = get_adapter(cli_type or "generic")
+
+        sender = self.get_sender_name() if add_sender_header else None
+        formatted = adapter.format_message(message, sender)
+
+        self.client.send_text(window_id, formatted)
+        time.sleep(0.1)
+        self.client.send_key(window_id, "enter")
+
+    def wait_for_response(
+        self,
+        window_id: int,
+        idle_seconds: int = 3,
+        timeout: float = 1800,
+    ) -> float:
+        """Wait for window content to stabilize."""
+        time.sleep(0.5)
+
+        def check_fn(last_hash: str) -> tuple[bool, str]:
+            return self.client.check_idle(window_id, last_hash)
+
+        return wait_for_idle(check_fn, idle_seconds=idle_seconds, timeout=timeout)
+
+    def get_response(
+        self,
+        window_id: int,
+        parser: str = "auto",
+        extent: str = "all",
+        raw: bool = False,
+    ) -> tuple[str, str]:
+        """Get parsed response from window.
+
+        Returns:
+            Tuple of (response_text, effective_parser_name)
+        """
+        effective_parser = parser
+        if parser == "auto":
+            cli_type = self.client.get_window_cli(window_id)
+            effective_parser = cli_type or "generic"
+
+        if raw:
+            return self.client.get_text(window_id, extent), effective_parser
+
+        adapter = get_adapter(effective_parser)
+        response = adapter.fetch_response(self.client, window_id, extent)
+
+        return response, effective_parser
+
+    def send_and_wait(
+        self,
+        window_id: int,
+        message: str,
+        idle_seconds: int = 3,
+        timeout: float = 1800,
+        parser: str = "auto",
+        raw: bool = False,
+    ) -> tuple[str, float, str]:
+        """Send message and wait for response.
+
+        Returns:
+            Tuple of (response_text, elapsed_time, effective_parser_name)
+        """
+        self.send_message(window_id, message)
+        elapsed = self.wait_for_response(window_id, idle_seconds, timeout)
+        response, effective_parser = self.get_response(window_id, parser, raw=raw)
+        return response, elapsed, effective_parser