kairo-code 0.1.0__py3-none-any.whl

kairo_code/agents/uiux.py

@@ -0,0 +1,88 @@
+"""UI/UX engineer agent — evaluates interfaces for usability and accessibility.
+
+Mirrors the ui-ux-engineer Claude Code agent.
+"""
+
+from .base import Agent
+
+
+class UiUxAgent(Agent):
+    name = "uiux"
+    description = "Evaluates UI/UX for usability, accessibility, and design best practices"
+    max_iterations = 15
+    require_confirmation = []
+
+    def get_system_prompt(self) -> str:
+        tools_desc = self.tools.format_for_prompt()
+
+        return f"""You are the UI/UX Engineer Agent — an expert in user interface design, interaction patterns, usability principles, and accessibility standards. You serve as the project's UX guardian.
+
+{tools_desc}
+
+## Your Expertise
+- **Interaction Design**: Affordances, feedback, progressive disclosure, micro-interactions
+- **Visual Design**: Hierarchy, proximity, alignment, contrast, repetition, white space
+- **Accessibility**: WCAG 2.1/2.2, ARIA patterns, keyboard navigation, screen readers
+- **Responsive Design**: Mobile-first, breakpoints, touch targets, adaptive layouts
+- **Design Systems**: Component consistency, pattern libraries, design tokens
+- **Cognitive Psychology**: Mental models, cognitive load, recognition over recall
+
+## Evaluation Framework
+
+### 1. Usability & Clarity
+- Is purpose immediately clear? Are labels self-explanatory?
+- Appropriate feedback for user actions?
+- Error messages helpful and actionable?
+- Cognitive load minimized?
+
+### 2. Visual Hierarchy & Layout
+- Does hierarchy guide attention appropriately?
+- Consistent, purposeful spacing? Precise alignment?
+- Natural reading patterns (F-pattern, Z-pattern)?
+
+### 3. Consistency
+- Similar elements behave similarly?
+- Interaction patterns consistent across the interface?
+- Aligned with project design system?
+
+### 4. Accessibility
+- Semantic HTML used appropriately?
+- ARIA roles and attributes correct?
+- Color contrast sufficient (4.5:1 text, 3:1 UI)?
+- Keyboard navigation logical and complete?
+- Focus states visible and meaningful?
+- Form fields properly labeled?
+
+### 5. Interaction States
+- All states handled: default, hover, focus, active, disabled?
+- Loading, empty, error, success states present?
+
+### 6. Responsiveness
+- Layout adapts across breakpoints?
+- Touch targets >= 44x44px?
+
+## TOOL FORMAT
+<tool>tool_name</tool>
+<params>{{"key": "value"}}</params>
+
+## Output Format
+
+**Summary**: Brief overview of UI/UX quality and main findings.
+
+**Critical Issues**: Problems significantly harming usability or accessibility.
+- Issue, user impact, recommended fix with code if applicable.
+
+**Improvements**: Opportunities to enhance the experience.
+- Current vs. recommended state, rationale, implementation suggestion.
+
+**Strengths**: What's working well.
+
+## Reference Heuristics
+- **Nielsen's 10**: Visibility, match with real world, user control, consistency, error prevention, recognition, flexibility, aesthetic design, error recovery, help
+- **Gestalt Principles**: Proximity, similarity, continuity, closure, figure-ground
+- **Fitts's Law**: Important targets large and close
+- **Hick's Law**: Minimize choices to reduce decision time
+- **Miller's Law**: Chunk information (7 plus or minus 2 items)"""
+
+    def get_tool_examples(self) -> str:
+        return ""

kairo_code/auth.py

@@ -0,0 +1,232 @@
+"""Browser-based authentication for Kairo Code CLI.
+
+Implements RFC 8628 Device Code flow:
+1. Request a device code from the Kairo backend
+2. Open browser for user approval
+3. Poll for token until approved/denied/expired
+4. Save credentials locally with restrictive permissions
+"""
+
+import sys
+import time
+import webbrowser
+from pathlib import Path
+from typing import Any
+
+import httpx
+import yaml
+from rich.console import Console
+from rich.panel import Panel
+
+console = Console()
+
+CREDENTIALS_DIR = Path.home() / ".kairo_code"
+CREDENTIALS_FILE = CREDENTIALS_DIR / "credentials.yaml"
+
+
+# ---------------------------------------------------------------------------
+# Credential storage
+# ---------------------------------------------------------------------------
+
+def load_credentials() -> dict[str, Any] | None:
+    """Load saved CLI credentials. Returns dict with api_key, email, plan or None."""
+    if not CREDENTIALS_FILE.exists():
+        return None
+    try:
+        with open(CREDENTIALS_FILE) as f:
+            data = yaml.safe_load(f)
+        if data and data.get("api_key"):
+            return data
+    except Exception:
+        pass
+    return None
+
+
+def save_credentials(api_key: str, email: str, plan: str) -> None:
+    """Save CLI credentials with restrictive permissions (0600)."""
+    CREDENTIALS_DIR.mkdir(parents=True, exist_ok=True)
+    data = {"api_key": api_key, "email": email, "plan": plan}
+    with open(CREDENTIALS_FILE, "w") as f:
+        yaml.dump(data, f, default_flow_style=False)
+    CREDENTIALS_FILE.chmod(0o600)
+
+
+def clear_credentials() -> None:
+    """Delete saved credentials."""
+    if CREDENTIALS_FILE.exists():
+        CREDENTIALS_FILE.unlink()
+
+
+def get_api_key() -> str | None:
+    """Get saved API key, or None if not authenticated."""
+    creds = load_credentials()
+    return creds["api_key"] if creds else None
+
+
+# ---------------------------------------------------------------------------
+# Device code authentication flow
+# ---------------------------------------------------------------------------
+
+def _derive_base_url(cloud_endpoint: str) -> str:
+    """Strip /v1 suffix to get the base API URL."""
+    base_url = cloud_endpoint.rstrip("/")
+    if base_url.endswith("/v1"):
+        base_url = base_url[:-3]
+    return base_url
+
+
+def _request_device_code(base_url: str) -> dict | None:
+    """POST /api/auth/device/code to obtain a device code."""
+    try:
+        resp = httpx.post(
+            f"{base_url}/api/auth/device/code",
+            json={"client_name": "kairo-code"},
+            timeout=10,
+        )
+        resp.raise_for_status()
+        return resp.json()
+    except Exception as e:
+        console.print(f"[red]Failed to start authentication: {e}[/]")
+        return None
+
+
+def _display_verification_prompt(verification_uri_complete: str, user_code: str) -> None:
+    """Show the verification URL and user code, then open the browser."""
+    console.print()
+    console.print(Panel(
+        f"[bold]To authenticate, open this URL:[/]\n\n"
+        f"  [cyan underline]{verification_uri_complete}[/]\n\n"
+        f"[bold]Then confirm this code:[/]  [bold yellow]{user_code}[/]",
+        title="[bold]Kairo Code -- Authentication[/]",
+        border_style="cyan",
+        padding=(1, 3),
+    ))
+    console.print()
+
+    try:
+        webbrowser.open(verification_uri_complete)
+        console.print("[dim]Browser opened. If it didn't open, copy the URL above.[/]")
+    except Exception:
+        console.print("[dim]Copy the URL above and open it in your browser.[/]")
+
+
+def _poll_for_token(base_url: str, device_code: str, expires_in: int, interval: int) -> dict | None:
+    """Poll /api/auth/device/token until approval, denial, or timeout.
+
+    Returns the token response dict on success, or None on failure.
+    """
+    console.print("[dim]Waiting for approval... (press Ctrl+C to cancel)[/]\n")
+    deadline = time.time() + expires_in
+
+    try:
+        while time.time() < deadline:
+            time.sleep(interval)
+
+            try:
+                resp = httpx.post(
+                    f"{base_url}/api/auth/device/token",
+                    json={"device_code": device_code},
+                    timeout=10,
+                )
+            except Exception:
+                continue  # Network error, retry
+
+            if resp.status_code == 200:
+                return resp.json()
+
+            if resp.status_code == 400:
+                error_code = _extract_error_code(resp)
+
+                if error_code == "authorization_pending":
+                    continue
+                elif error_code == "slow_down":
+                    interval += 1
+                    continue
+                elif error_code == "expired_token":
+                    console.print("[red]Authentication expired. Please try again.[/]")
+                    return None
+                elif error_code == "access_denied":
+                    console.print("[red]Access denied. Kairo Code requires a Max plan.[/]")
+                    return None
+
+        console.print("[red]Authentication timed out. Please try again.[/]")
+        return None
+
+    except KeyboardInterrupt:
+        console.print("\n[dim]Authentication cancelled.[/]")
+        return None
+
+
+def _extract_error_code(resp: httpx.Response) -> str:
+    """Extract the error code string from a 400 response."""
+    try:
+        error_data = resp.json()
+        error = error_data.get("detail", {})
+        if isinstance(error, dict):
+            return error.get("error", "")
+        return str(error)
+    except Exception:
+        return ""
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+def authenticate(cloud_endpoint: str) -> str | None:
+    """Run the full device code auth flow.
+
+    Returns the API key on success, or None on failure/cancellation.
+    """
+    base_url = _derive_base_url(cloud_endpoint)
+
+    # Step 1: Request device code
+    data = _request_device_code(base_url)
+    if data is None:
+        return None
+
+    device_code = data["device_code"]
+    user_code = data["user_code"]
+    verification_uri_complete = data["verification_uri_complete"]
+    expires_in = data["expires_in"]
+    interval = data["interval"]
+
+    # Step 2: Display prompt and open browser
+    _display_verification_prompt(verification_uri_complete, user_code)
+
+    # Step 3: Poll for approval
+    token_data = _poll_for_token(base_url, device_code, expires_in, interval)
+    if token_data is None:
+        return None
+
+    api_key = token_data["access_token"]
+    email = token_data.get("email", "")
+    plan = token_data.get("plan", "max")
+
+    save_credentials(api_key, email, plan)
+    console.print(f"[green bold]Authenticated as {email}[/]")
+    console.print()
+    return api_key
+
+
+def ensure_authenticated(cloud_endpoint: str) -> str | None:
+    """Check for saved credentials or trigger auth flow. Returns api_key or None."""
+    creds = load_credentials()
+    if creds and creds.get("api_key"):
+        base_url = _derive_base_url(cloud_endpoint)
+        try:
+            resp = httpx.get(
+                f"{base_url}/v1/models",
+                headers={"Authorization": f"Bearer {creds['api_key']}"},
+                timeout=5,
+            )
+            if resp.status_code == 200:
+                console.print(f"[dim]Authenticated as {creds.get('email', 'unknown')}[/]")
+                return creds["api_key"]
+        except Exception:
+            pass
+
+        console.print("[yellow]Saved credentials are invalid. Re-authenticating...[/]")
+        clear_credentials()
+
+    return authenticate(cloud_endpoint)

kairo_code/config.py

@@ -0,0 +1,172 @@
+"""Configuration loader for Kairo Code"""
+
+import os
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+
+def find_config() -> Path:
+    """Find config.yaml in current directory or parent directories."""
+    current = Path.cwd()
+
+    # Check current and parent directories
+    for path in [current] + list(current.parents):
+        config_path = path / "config.yaml"
+        if config_path.exists():
+            return config_path
+
+    # Fall back to package directory
+    package_dir = Path(__file__).parent.parent
+    config_path = package_dir / "config.yaml"
+    if config_path.exists():
+        return config_path
+
+    raise FileNotFoundError("config.yaml not found")
+
+
+def load_config(config_path: Path | None = None) -> dict[str, Any]:
+    """Load configuration from YAML file."""
+    if config_path is None:
+        config_path = find_config()
+
+    with open(config_path) as f:
+        config = yaml.safe_load(f)
+
+    # Override with environment variables if set
+    if os.getenv("KAIRO_CLOUD_ENDPOINT"):
+        config.setdefault("cloud", {})["endpoint"] = os.getenv("KAIRO_CLOUD_ENDPOINT")
+
+    if os.getenv("KAIRO_CLOUD_API_KEY"):
+        config.setdefault("cloud", {})["api_key"] = os.getenv("KAIRO_CLOUD_API_KEY")
+
+    if os.getenv("KAIRO_ROUTER_MODEL"):
+        config["models"]["router"] = os.getenv("KAIRO_ROUTER_MODEL")
+
+    if os.getenv("KAIRO_CODER_MODEL"):
+        config["models"]["coder"] = os.getenv("KAIRO_CODER_MODEL")
+
+    return config
+
+
+class Config:
+    """Configuration singleton for easy access throughout the app."""
+
+    _instance: "Config | None" = None
+
+    def __new__(cls) -> "Config":
+        if cls._instance is None:
+            cls._instance = super().__new__(cls)
+            cls._instance._config = load_config()
+        return cls._instance
+
+    @property
+    def router_model(self) -> str:
+        return self._config["models"]["router"]
+
+    @property
+    def coder_model(self) -> str:
+        return self._config["models"]["coder"]
+
+    @property
+    def chat_model(self) -> str:
+        return self._config["models"]["chat"]
+
+    @property
+    def cloud_endpoint(self) -> str:
+        return self._config.get("cloud", {}).get("endpoint", "http://localhost:8000/v1")
+
+    @property
+    def cloud_api_key(self) -> str:
+        # Priority: env var / config file > saved CLI credentials > placeholder
+        key = self._config.get("cloud", {}).get("api_key", "")
+        if key:
+            return key
+        # Check saved CLI credentials
+        from kairo_code.auth import get_api_key
+        cli_key = get_api_key()
+        if cli_key:
+            return cli_key
+        # OpenAI client requires a non-empty string
+        return "not-needed"
+
+    @property
+    def cloud_timeout(self) -> int:
+        return self._config.get("cloud", {}).get("timeout", 120)
+
+    @property
+    def search_max_results(self) -> int:
+        return self._config["search"]["max_results"]
+
+    @property
+    def max_history(self) -> int:
+        return self._config["conversation"]["max_history"]
+
+    @property
+    def system_prompt(self) -> str:
+        return self._config["conversation"]["system_prompt"]
+
+    @property
+    def router_prompt(self) -> str:
+        return self._config["router"]["system_prompt"]
+
+    # Safety settings
+    @property
+    def auto_approve(self) -> bool:
+        return self._config.get("safety", {}).get("auto_approve", False)
+
+    @property
+    def auto_approve_tools(self) -> list[str]:
+        return self._config.get("safety", {}).get("auto_approve_tools", [])
+
+    @property
+    def blocked_commands(self) -> list[str]:
+        return self._config.get("safety", {}).get("blocked_commands", [])
+
+    @property
+    def allowed_commands(self) -> list[str]:
+        return self._config.get("safety", {}).get("allowed_commands", [])
+
+    @property
+    def max_file_lines(self) -> int:
+        return self._config.get("safety", {}).get("max_file_lines", 500)
+
+    @property
+    def max_iterations(self) -> int:
+        return self._config.get("safety", {}).get("max_iterations", 12)
+
+    def should_auto_approve(self, tool_name: str) -> bool:
+        """Check if a tool should be auto-approved."""
+        if self.auto_approve:
+            return True
+        return tool_name in self.auto_approve_tools
+
+    def is_command_allowed(self, command: str) -> tuple[bool, str]:
+        """Check if a bash command is allowed. Returns (allowed, reason)."""
+        cmd_lower = command.lower().strip()
+
+        # Check blocked commands
+        for blocked in self.blocked_commands:
+            if blocked.lower() in cmd_lower:
+                return False, f"Command contains blocked pattern: {blocked}"
+
+        # Check allowed commands (if whitelist is set)
+        if self.allowed_commands:
+            for allowed in self.allowed_commands:
+                if cmd_lower.startswith(allowed.lower()):
+                    return True, ""
+            return False, "Command not in allowed list"
+
+        return True, ""
+
+    def get(self, key: str, default: Any = None) -> Any:
+        """Get a config value by dot-notation key."""
+        keys = key.split(".")
+        value = self._config
+        for k in keys:
+            if isinstance(value, dict) and k in value:
+                value = value[k]
+            else:
+                return default
+        return value

kairo_code/conversation.py

@@ -0,0 +1,173 @@
+"""Conversation manager for maintaining chat history with local persistence."""
+
+import json
+import os
+import re
+import stat
+import uuid
+from dataclasses import dataclass, field, asdict
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+from .config import Config
+
+
+CONVERSATIONS_DIR = Path.home() / ".kairo" / "conversations"
+
+# Only allow alphanumeric + hyphens for conversation IDs (no path traversal)
+_SAFE_ID_RE = re.compile(r"^[a-zA-Z0-9_-]{1,64}$")
+
+
+def _validate_conversation_id(cid: str) -> str:
+    """Validate conversation ID to prevent path traversal."""
+    if not _SAFE_ID_RE.match(cid):
+        raise ValueError(
+            f"Invalid conversation ID: {cid!r}. "
+            "Only alphanumeric characters, hyphens, and underscores are allowed (max 64 chars)."
+        )
+    return cid
+
+
+@dataclass
+class Message:
+    """A single message in the conversation."""
+    role: str  # "user", "assistant", "system"
+    content: str
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+
+class Conversation:
+    """Manages conversation history with context window limits and local persistence."""
+
+    def __init__(self, system_prompt: str | None = None, conversation_id: str | None = None):
+        self.config = Config()
+        self.system_prompt = system_prompt or self.config.system_prompt
+        self.messages: list[Message] = []
+        self.id = _validate_conversation_id(conversation_id) if conversation_id else uuid.uuid4().hex[:12]
+        self.created_at = datetime.now(timezone.utc).isoformat()
+
+    def add_user(self, content: str) -> None:
+        """Add a user message."""
+        self.messages.append(Message(role="user", content=content))
+        self._trim_history()
+        self._auto_save()
+
+    def add_assistant(self, content: str) -> None:
+        """Add an assistant message."""
+        self.messages.append(Message(role="assistant", content=content))
+        self._trim_history()
+        self._auto_save()
+
+    def add_system(self, content: str) -> None:
+        """Add a system message."""
+        self.messages.append(Message(role="system", content=content))
+
+    def _trim_history(self) -> None:
+        """Trim history to stay within max_history limit."""
+        max_messages = self.config.max_history
+        if len(self.messages) > max_messages:
+            self.messages = self.messages[-max_messages:]
+
+    def to_messages(self) -> list[dict[str, str]]:
+        """Convert to format expected by OpenAI-compatible API."""
+        result = [{"role": "system", "content": self.system_prompt}]
+        for msg in self.messages:
+            result.append({"role": msg.role, "content": msg.content})
+        return result
+
+    def clear(self) -> None:
+        """Clear conversation history."""
+        self.messages = []
+
+    def get_context_summary(self) -> str:
+        """Get a brief summary of the conversation context."""
+        if not self.messages:
+            return "No conversation history"
+        return f"{len(self.messages)} messages in history"
+
+    # ── Persistence ──────────────────────────────────────────────
+
+    def _auto_save(self) -> None:
+        """Auto-save after each message."""
+        try:
+            self.save()
+        except Exception:
+            pass  # Don't break the conversation if save fails
+
+    def save(self) -> Path:
+        """Save conversation to disk with secure permissions."""
+        CONVERSATIONS_DIR.mkdir(parents=True, exist_ok=True)
+        # Secure the directory: owner-only access
+        try:
+            os.chmod(CONVERSATIONS_DIR, stat.S_IRWXU)  # 0700
+        except OSError:
+            pass  # Windows doesn't support Unix permissions
+        path = CONVERSATIONS_DIR / f"{self.id}.json"
+        data = {
+            "id": self.id,
+            "created_at": self.created_at,
+            "updated_at": datetime.now(timezone.utc).isoformat(),
+            "system_prompt": self.system_prompt,
+            "messages": [asdict(m) for m in self.messages],
+        }
+        path.write_text(json.dumps(data, indent=2))
+        # Secure the file: owner read/write only
+        try:
+            os.chmod(path, stat.S_IRUSR | stat.S_IWUSR)  # 0600
+        except OSError:
+            pass
+        return path
+
+    @classmethod
+    def load(cls, conversation_id: str) -> "Conversation":
+        """Load a conversation from disk."""
+        _validate_conversation_id(conversation_id)
+        path = CONVERSATIONS_DIR / f"{conversation_id}.json"
+        if not path.exists():
+            raise FileNotFoundError(f"Conversation {conversation_id} not found")
+
+        data = json.loads(path.read_text())
+        conv = cls(
+            system_prompt=data.get("system_prompt"),
+            conversation_id=data["id"],
+        )
+        conv.created_at = data.get("created_at", conv.created_at)
+        conv.messages = [
+            Message(
+                role=m["role"],
+                content=m["content"],
+                metadata=m.get("metadata", {}),
+            )
+            for m in data.get("messages", [])
+        ]
+        return conv
+
+    @staticmethod
+    def list_saved() -> list[dict[str, str]]:
+        """List all saved conversations (id, created_at, preview)."""
+        if not CONVERSATIONS_DIR.exists():
+            return []
+
+        conversations = []
+        for path in sorted(CONVERSATIONS_DIR.glob("*.json"), reverse=True):
+            try:
+                data = json.loads(path.read_text())
+                # Get first user message as preview
+                preview = ""
+                for m in data.get("messages", []):
+                    if m.get("role") == "user":
+                        preview = m["content"][:80]
+                        break
+
+                conversations.append({
+                    "id": data["id"],
+                    "created_at": data.get("created_at", ""),
+                    "updated_at": data.get("updated_at", ""),
+                    "preview": preview,
+                    "message_count": str(len(data.get("messages", []))),
+                })
+            except Exception:
+                continue
+
+        return conversations