glaip-sdk 0.7.0__py3-none-any.whl → 0.7.2__py3-none-any.whl

glaip_sdk/cli/slash/tui/terminal.py

@@ -89,7 +89,7 @@ class TerminalCapabilities:
 
         # Basic capability detection
         ansi = tty_available and term not in ("dumb", "")
-        osc52 = _detect_osc52_support()
+        osc52 = detect_osc52_support()
         mouse = tty_available and term not in ("dumb", "")
         truecolor = colorterm in ("truecolor", "24bit")
 
@@ -366,7 +366,7 @@ def _check_terminal_in_env(env_value: str, terminals: list[str]) -> bool:
     return any(terminal in env_value for terminal in terminals)
 
 
-def _detect_osc52_support() -> bool:
+def detect_osc52_support() -> bool:
     """Check if terminal likely supports OSC 52 (clipboard).
 
     Returns:

glaip_sdk/cli/slash/tui/theme/__init__.py

@@ -0,0 +1,15 @@
+"""Theme system primitives for Textual TUIs."""
+
+from __future__ import annotations
+
+from glaip_sdk.cli.slash.tui.theme.catalog import get_builtin_theme, list_builtin_themes
+from glaip_sdk.cli.slash.tui.theme.manager import ThemeManager, ThemeMode
+from glaip_sdk.cli.slash.tui.theme.tokens import ThemeTokens
+
+__all__ = [
+    "ThemeManager",
+    "ThemeMode",
+    "ThemeTokens",
+    "get_builtin_theme",
+    "list_builtin_themes",
+]

glaip_sdk/cli/slash/tui/theme/catalog.py

@@ -0,0 +1,79 @@
+"""Built-in theme catalog for TUI applications.
+
+This module implements Phase 2 of the TUI Theme System spec, providing a foundational
+set of 12 color tokens (primary, secondary, accent, background, background_panel, text,
+text_muted, success, warning, error, info). Additional tokens (e.g., diff.added,
+syntax.*, backgroundElevated, textDim) will be added in future phases per the spec's
+"100+ color tokens" requirement.
+"""
+
+from __future__ import annotations
+
+from glaip_sdk.cli.slash.tui.theme.tokens import ThemeModeLiteral, ThemeTokens
+
+_BUILTIN_THEMES: dict[str, ThemeTokens] = {
+    "gl-dark": ThemeTokens(
+        name="gl-dark",
+        mode="dark",
+        primary="#6EA8FE",
+        secondary="#ADB5BD",
+        accent="#C77DFF",
+        background="#0B0F19",
+        background_panel="#111827",
+        text="#E5E7EB",
+        text_muted="#9CA3AF",
+        success="#34D399",
+        warning="#FBBF24",
+        error="#F87171",
+        info="#60A5FA",
+    ),
+    "gl-light": ThemeTokens(
+        name="gl-light",
+        mode="light",
+        primary="#1D4ED8",
+        secondary="#4B5563",
+        accent="#7C3AED",
+        background="#FFFFFF",
+        background_panel="#F3F4F6",
+        text="#111827",
+        text_muted="#4B5563",
+        success="#059669",
+        warning="#B45309",
+        error="#B91C1C",
+        info="#1D4ED8",
+    ),
+    "gl-high-contrast": ThemeTokens(
+        name="gl-high-contrast",
+        mode="dark",
+        # High-contrast theme uses uniform colors (#FFFFFF on #000000) to maximize
+        # contrast for accessibility. Semantic distinctions (success/warning/error)
+        # are intentionally uniform to prioritize maximum readability over color
+        # coding, per accessibility best practices for high-contrast modes.
+        primary="#FFFFFF",
+        secondary="#FFFFFF",
+        accent="#FFFFFF",
+        background="#000000",
+        background_panel="#000000",
+        text="#FFFFFF",
+        text_muted="#FFFFFF",
+        success="#FFFFFF",
+        warning="#FFFFFF",
+        error="#FFFFFF",
+        info="#FFFFFF",
+    ),
+}
+
+
+def get_builtin_theme(name: str) -> ThemeTokens | None:
+    """Return a built-in theme by name."""
+    return _BUILTIN_THEMES.get(name)
+
+
+def list_builtin_themes() -> list[str]:
+    """List available built-in theme names."""
+    return sorted(_BUILTIN_THEMES)
+
+
+def default_theme_name_for_mode(mode: ThemeModeLiteral) -> str:
+    """Return the default theme name for the given light/dark mode."""
+    return "gl-light" if mode == "light" else "gl-dark"

glaip_sdk/cli/slash/tui/theme/manager.py

@@ -0,0 +1,86 @@
+"""Theme manager for TUI applications."""
+
+from __future__ import annotations
+
+import logging
+from enum import Enum
+from typing import Literal
+
+from glaip_sdk.cli.slash.tui.terminal import TerminalCapabilities
+from glaip_sdk.cli.slash.tui.theme.catalog import default_theme_name_for_mode, get_builtin_theme
+from glaip_sdk.cli.slash.tui.theme.tokens import ThemeTokens
+
+logger = logging.getLogger(__name__)
+
+
+class ThemeMode(str, Enum):
+    """User-selectable theme mode."""
+
+    AUTO = "auto"
+    LIGHT = "light"
+    DARK = "dark"
+
+
+class ThemeManager:
+    """Resolve active theme tokens from terminal state and user preferences."""
+
+    def __init__(
+        self,
+        terminal: TerminalCapabilities,
+        *,
+        mode: ThemeMode | str = ThemeMode.AUTO,
+        theme: str | None = None,
+    ) -> None:
+        """Initialize the theme manager."""
+        self._terminal = terminal
+        self._mode = self._coerce_mode(mode)
+        self._theme = theme
+
+    @property
+    def mode(self) -> ThemeMode:
+        """Return configured mode (auto/light/dark)."""
+        return self._mode
+
+    @property
+    def effective_mode(self) -> Literal["light", "dark"]:
+        """Return resolved light/dark mode."""
+        if self._mode == ThemeMode.AUTO:
+            return self._terminal.background_mode
+        return "light" if self._mode == ThemeMode.LIGHT else "dark"
+
+    @property
+    def theme_name(self) -> str:
+        """Return resolved theme name."""
+        return self._theme or default_theme_name_for_mode(self.effective_mode)
+
+    @property
+    def tokens(self) -> ThemeTokens:
+        """Return tokens for the resolved theme."""
+        chosen = get_builtin_theme(self.theme_name)
+        if chosen is not None:
+            return chosen
+
+        fallback_name = default_theme_name_for_mode(self.effective_mode)
+        fallback = get_builtin_theme(fallback_name)
+        if fallback is None:
+            raise RuntimeError(f"Missing default theme: {fallback_name}")
+
+        return fallback
+
+    def set_mode(self, mode: ThemeMode | str) -> None:
+        """Set auto/light/dark mode."""
+        self._mode = self._coerce_mode(mode)
+
+    def set_theme(self, theme: str | None) -> None:
+        """Set explicit theme name (or None to use the default)."""
+        self._theme = theme
+
+    def _coerce_mode(self, mode: ThemeMode | str) -> ThemeMode:
+        """Coerce a mode value to ThemeMode enum, defaulting to AUTO on invalid input."""
+        if isinstance(mode, ThemeMode):
+            return mode
+        try:
+            return ThemeMode(mode)
+        except ValueError:
+            logger.warning(f"Invalid theme mode '{mode}', defaulting to AUTO")
+            return ThemeMode.AUTO

glaip_sdk/cli/slash/tui/theme/tokens.py

@@ -0,0 +1,55 @@
+"""Theme token definitions for TUI applications."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Literal
+
+ThemeModeLiteral = Literal["light", "dark"]
+
+
+@dataclass(frozen=True, slots=True)
+class ThemeTokens:
+    """Color token set for a built-in theme."""
+
+    name: str
+    mode: ThemeModeLiteral
+
+    primary: str
+    secondary: str
+    accent: str
+
+    background: str
+    background_panel: str
+
+    text: str
+    text_muted: str
+
+    success: str
+    warning: str
+    error: str
+    info: str
+
+    def as_dict(self) -> dict[str, str]:
+        """Return color tokens as a plain dictionary.
+
+        Returns only color tokens (primary, secondary, accent, background, etc.),
+        excluding metadata fields (name, mode). This is intentional for use cases
+        like Textual TCSS mapping where only color values are needed.
+
+        Returns:
+            Dictionary mapping color token names to hex color strings.
+        """
+        return {
+            "primary": self.primary,
+            "secondary": self.secondary,
+            "accent": self.accent,
+            "background": self.background,
+            "background_panel": self.background_panel,
+            "text": self.text,
+            "text_muted": self.text_muted,
+            "success": self.success,
+            "warning": self.warning,
+            "error": self.error,
+            "info": self.info,
+        }

glaip_sdk/cli/slash/tui/toast.py

@@ -0,0 +1,123 @@
+"""Toast notification helpers for Textual TUIs.
+
+Authors:
+    Raymond Christopher (raymond.christopher@gdplabs.id)
+"""
+
+from __future__ import annotations
+
+import asyncio
+from dataclasses import dataclass
+from enum import Enum
+
+
+class ToastVariant(str, Enum):
+    """Toast message variant."""
+
+    INFO = "info"
+    SUCCESS = "success"
+    WARNING = "warning"
+    ERROR = "error"
+
+
+DEFAULT_TOAST_DURATIONS_SECONDS: dict[ToastVariant, float] = {
+    ToastVariant.SUCCESS: 2.0,
+    ToastVariant.INFO: 3.0,
+    ToastVariant.WARNING: 3.0,
+    ToastVariant.ERROR: 5.0,
+}
+
+
+@dataclass(frozen=True, slots=True)
+class ToastState:
+    """Immutable toast payload."""
+
+    message: str
+    variant: ToastVariant
+    duration_seconds: float
+
+
+class ToastBus:
+    """Single-toast state holder with auto-dismiss."""
+
+    def __init__(self) -> None:
+        """Initialize the bus."""
+        self._state: ToastState | None = None
+        self._dismiss_task: asyncio.Task[None] | None = None
+
+    @property
+    def state(self) -> ToastState | None:
+        """Return the current toast state."""
+        return self._state
+
+    def show(
+        self,
+        message: str,
+        variant: ToastVariant | str = ToastVariant.INFO,
+        *,
+        duration_seconds: float | None = None,
+    ) -> None:
+        """Set toast state and schedule auto-dismiss."""
+        resolved_variant = self._coerce_variant(variant)
+        resolved_duration = (
+            DEFAULT_TOAST_DURATIONS_SECONDS[resolved_variant] if duration_seconds is None else float(duration_seconds)
+        )
+
+        self._state = ToastState(
+            message=message,
+            variant=resolved_variant,
+            duration_seconds=resolved_duration,
+        )
+
+        self._cancel_dismiss_task()
+
+        try:
+            loop = asyncio.get_running_loop()
+        except RuntimeError:
+            raise RuntimeError(
+                "Cannot schedule toast auto-dismiss: no running event loop. "
+                "ToastBus.show() must be called from within an async context."
+            ) from None
+
+        self._dismiss_task = loop.create_task(self._auto_dismiss(resolved_duration))
+
+    def clear(self) -> None:
+        """Clear the current toast."""
+        self._cancel_dismiss_task()
+        self._state = None
+
+    def copy_success(self, label: str | None = None) -> None:
+        """Show clipboard success toast."""
+        message = "Copied to clipboard" if not label else f"Copied {label} to clipboard"
+        self.show(message=message, variant=ToastVariant.SUCCESS)
+
+    def copy_failed(self) -> None:
+        """Show clipboard failure toast."""
+        self.show(
+            message="Clipboard unavailable. Text printed below",
+            variant=ToastVariant.WARNING,
+        )
+
+    def _coerce_variant(self, variant: ToastVariant | str) -> ToastVariant:
+        if isinstance(variant, ToastVariant):
+            return variant
+        try:
+            return ToastVariant(variant)
+        except ValueError:
+            return ToastVariant.INFO
+
+    def _cancel_dismiss_task(self) -> None:
+        if self._dismiss_task is None:
+            return
+        if not self._dismiss_task.done():
+            self._dismiss_task.cancel()
+        self._dismiss_task = None
+
+    async def _auto_dismiss(self, duration_seconds: float) -> None:
+        try:
+            await asyncio.sleep(duration_seconds)
+        except asyncio.CancelledError:
+            return
+
+        self._state = None
+        self._dismiss_task = None

glaip_sdk/client/agents.py

@@ -17,6 +17,7 @@ from typing import TYPE_CHECKING, Any, BinaryIO
 
 if TYPE_CHECKING:
     from glaip_sdk.client.schedules import ScheduleClient
+    from glaip_sdk.hitl.remote import RemoteHITLHandler
 
 import httpx
 from glaip_sdk.agents import Agent
@@ -415,6 +416,7 @@ class AgentClient(BaseClient):
         timeout_seconds: float,
         agent_name: str | None,
         meta: dict[str, Any],
+        hitl_handler: "RemoteHITLHandler | None" = None,
     ) -> tuple[str, dict[str, Any], float | None, float | None]:
         """Process stream events from an HTTP response.
 
@@ -424,6 +426,7 @@ class AgentClient(BaseClient):
             timeout_seconds: Timeout in seconds.
             agent_name: Optional agent name.
             meta: Metadata dictionary.
+            hitl_handler: Optional HITL handler for approval callbacks.
 
         Returns:
             Tuple of (final_text, stats_usage, started_monotonic, finished_monotonic).
@@ -435,6 +438,7 @@ class AgentClient(BaseClient):
             timeout_seconds,
             agent_name,
             meta,
+            hitl_handler=hitl_handler,
         )
 
     def _finalize_renderer(
@@ -1112,6 +1116,7 @@ class AgentClient(BaseClient):
         *,
         renderer: RichStreamRenderer | str | None = "auto",
         runtime_config: dict[str, Any] | None = None,
+        hitl_handler: "RemoteHITLHandler | None" = None,
         **kwargs,
     ) -> str:
         """Run an agent with a message, streaming via a renderer.
@@ -1129,6 +1134,8 @@ class AgentClient(BaseClient):
                     "mcp_configs": {"mcp-id": {"setting": "on"}},
                     "agent_config": {"planning": True},
                 }
+            hitl_handler: Optional RemoteHITLHandler for approval callbacks.
+                Set GLAIP_HITL_AUTO_APPROVE=true for auto-approval without handler.
             **kwargs: Additional arguments to pass to the run API.
 
         Returns:
@@ -1185,6 +1192,7 @@ class AgentClient(BaseClient):
                     timeout_seconds,
                     agent_name,
                     meta,
+                    hitl_handler=hitl_handler,
                 )
 
         except KeyboardInterrupt:
@@ -1201,6 +1209,13 @@ class AgentClient(BaseClient):
             if multipart_data:
                 multipart_data.close()
 
+        # Wait for pending HITL decisions before returning
+        if hitl_handler and hasattr(hitl_handler, "wait_for_pending_decisions"):
+            try:
+                hitl_handler.wait_for_pending_decisions(timeout=30)
+            except Exception as e:
+                logger.warning(f"Error waiting for HITL decisions: {e}")
+
         return self._finalize_renderer(
             r,
             final_text,
@@ -1282,6 +1297,7 @@ class AgentClient(BaseClient):
         *,
         request_timeout: float | None = None,
         runtime_config: dict[str, Any] | None = None,
+        hitl_handler: "RemoteHITLHandler | None" = None,
         **kwargs,
     ) -> AsyncGenerator[dict, None]:
         """Async run an agent with a message, yielding streaming JSON chunks.
@@ -1298,16 +1314,26 @@ class AgentClient(BaseClient):
                     "mcp_configs": {"mcp-id": {"setting": "on"}},
                     "agent_config": {"planning": True},
                 }
+            hitl_handler: Optional HITL handler for remote approval requests.
+                Note: Async HITL support is currently deferred. This parameter
+                is accepted for API consistency but will raise NotImplementedError
+                if provided.
             **kwargs: Additional arguments (chat_history, pii_mapping, etc.)
 
         Yields:
             Dictionary containing parsed JSON chunks from the streaming response
 
         Raises:
+            NotImplementedError: If hitl_handler is provided (async HITL not yet supported)
             AgentTimeoutError: When agent execution times out
             httpx.TimeoutException: When general timeout occurs
             Exception: For other unexpected errors
         """
+        if hitl_handler is not None:
+            raise NotImplementedError(
+                "Async HITL support is currently deferred. "
+                "Please use the synchronous run_agent() method with hitl_handler."
+            )
         # Include runtime_config in kwargs only when caller hasn't already provided it
         if runtime_config is not None and "runtime_config" not in kwargs:
             kwargs["runtime_config"] = runtime_config

glaip_sdk/client/hitl.py

@@ -0,0 +1,136 @@
+#!/usr/bin/env python3
+"""HITL REST client for manual approval operations.
+
+Authors:
+    GLAIP SDK Team
+"""
+
+from typing import Any
+
+from glaip_sdk.client.base import BaseClient
+from glaip_sdk.hitl.base import HITLDecision
+
+
+class HITLClient(BaseClient):
+    """Client for HITL REST endpoints.
+
+    Use for manual approval workflows separate from agent runs.
+
+    Example:
+        >>> # List pending approvals
+        >>> pending = client.hitl.list_pending()
+        >>>
+        >>> # Approve a request
+        >>> client.hitl.approve(
+        ...     request_id="bc4d0a77-7800-470e-a91c-7fd663a66b4d",
+        ...     operator_input="Verified and approved",
+        ... )
+    """
+
+    def approve(
+        self,
+        request_id: str,
+        operator_input: str | None = None,
+        run_id: str | None = None,
+    ) -> dict[str, Any]:
+        """Approve a HITL request.
+
+        Args:
+            request_id: HITL request ID from SSE stream
+            operator_input: Optional notes/reason for approval
+            run_id: Optional client-side run correlation ID
+
+        Returns:
+            Response dict: {"status": "ok", "message": "..."}
+        """
+        return self._post_decision(
+            request_id,
+            HITLDecision.APPROVED,
+            operator_input,
+            run_id,
+        )
+
+    def reject(
+        self,
+        request_id: str,
+        operator_input: str | None = None,
+        run_id: str | None = None,
+    ) -> dict[str, Any]:
+        """Reject a HITL request.
+
+        Args:
+            request_id: HITL request ID
+            operator_input: Optional reason for rejection
+            run_id: Optional run correlation ID
+
+        Returns:
+            Response dict
+        """
+        return self._post_decision(
+            request_id,
+            HITLDecision.REJECTED,
+            operator_input,
+            run_id,
+        )
+
+    def skip(
+        self,
+        request_id: str,
+        operator_input: str | None = None,
+        run_id: str | None = None,
+    ) -> dict[str, Any]:
+        """Skip a HITL request.
+
+        Args:
+            request_id: HITL request ID
+            operator_input: Optional notes
+            run_id: Optional run correlation ID
+
+        Returns:
+            Response dict
+        """
+        return self._post_decision(
+            request_id,
+            HITLDecision.SKIPPED,
+            operator_input,
+            run_id,
+        )
+
+    def _post_decision(
+        self,
+        request_id: str,
+        decision: HITLDecision,
+        operator_input: str | None,
+        run_id: str | None,
+    ) -> dict[str, Any]:
+        """Post HITL decision to backend."""
+        payload = {
+            "request_id": request_id,
+            "decision": decision.value,
+        }
+
+        if operator_input:
+            payload["operator_input"] = operator_input
+        if run_id:
+            payload["run_id"] = run_id
+
+        return self._request("POST", "/agents/hitl/decision", json=payload)
+
+    def list_pending(self) -> list[dict[str, Any]]:
+        """List all pending HITL requests.
+
+        Returns:
+            List of pending request dicts with metadata:
+            [
+                {
+                    "request_id": "...",
+                    "tool": "...",
+                    "arguments": {...},
+                    "created_at": "...",
+                    "agent_id": "...",
+                    "hitl_metadata": {...},
+                },
+                ...
+            ]
+        """
+        return self._request("GET", "/agents/hitl/pending")

glaip_sdk/client/main.py

@@ -12,6 +12,7 @@ from typing import TYPE_CHECKING, Any
 
 from glaip_sdk.client.agents import AgentClient
 from glaip_sdk.client.base import BaseClient
+from glaip_sdk.client.hitl import HITLClient
 from glaip_sdk.client.mcps import MCPClient
 from glaip_sdk.client.schedules import ScheduleClient
 from glaip_sdk.client.shared import build_shared_config
@@ -40,6 +41,7 @@ class Client(BaseClient):
         self.tools = ToolClient(**shared_config)
         self.mcps = MCPClient(**shared_config)
         self.schedules = ScheduleClient(**shared_config)
+        self.hitl = HITLClient(**shared_config)
 
     # ---- Core API Methods (Public Interface) ----