glaip-sdk 0.2.2__py3-none-any.whl → 0.4.0__py3-none-any.whl

glaip_sdk/cli/update_notifier.py

@@ -26,7 +26,8 @@ from glaip_sdk.branding import (
 )
 from glaip_sdk.cli.commands.update import update_command
 from glaip_sdk.cli.constants import UPDATE_CHECK_ENABLED
-from glaip_sdk.cli.utils import command_hint, format_command_hint
+from glaip_sdk.cli.hints import format_command_hint
+from glaip_sdk.cli.utils import command_hint
 from glaip_sdk.rich_components import AIPPanel
 
 FetchLatestVersion = Callable[[], str | None]

glaip_sdk/cli/utils.py

@@ -7,13 +7,14 @@ Authors:
 
 from __future__ import annotations
 
+import asyncio
 import importlib
 import json
 import logging
 import os
 import sys
 from collections.abc import Callable, Iterable
-from contextlib import AbstractContextManager, nullcontext
+from contextlib import AbstractContextManager, contextmanager, nullcontext
 from pathlib import Path
 from typing import TYPE_CHECKING, Any, cast
 
@@ -26,29 +27,206 @@ from rich.syntax import Syntax
 from glaip_sdk import _version as _version_module
 from glaip_sdk.branding import (
     ACCENT_STYLE,
-    HINT_COMMAND_STYLE,
-    HINT_DESCRIPTION_COLOR,
     SUCCESS_STYLE,
     WARNING_STYLE,
 )
 from glaip_sdk.cli import masking, pager
-from glaip_sdk.cli.constants import LITERAL_STRING_THRESHOLD, TABLE_SORT_ENABLED
 from glaip_sdk.cli.config import load_config
+from glaip_sdk.cli.constants import LITERAL_STRING_THRESHOLD, TABLE_SORT_ENABLED
 from glaip_sdk.cli.context import (
     _get_view,
-    detect_export_format as _detect_export_format,
     get_ctx_value,
 )
-from glaip_sdk.cli.rich_helpers import markup_text
+from glaip_sdk.cli.context import (
+    detect_export_format as _detect_export_format,
+)
+from glaip_sdk.cli import display as cli_display
+from glaip_sdk.cli.hints import command_hint
+from glaip_sdk.cli.io import export_resource_to_file_with_validation
+from glaip_sdk.cli.rich_helpers import markup_text, print_markup
 from glaip_sdk.icons import ICON_AGENT
 from glaip_sdk.rich_components import AIPPanel, AIPTable
-from glaip_sdk.utils import is_uuid
+from glaip_sdk.utils import format_datetime, is_uuid
 from glaip_sdk.utils.rendering.renderer import (
     CapturingConsole,
-    RendererConfig,
+    RendererFactoryOptions,
     RichStreamRenderer,
+    make_default_renderer,
+    make_verbose_renderer,
 )
 
+questionary = None  # type: ignore[assignment]
+
+
+def _load_questionary_module() -> tuple[Any | None, Any | None]:
+    """Return the questionary module and Choice class if available."""
+    module = questionary
+    if module is not None:
+        return module, getattr(module, "Choice", None)
+
+    try:  # pragma: no cover - optional dependency
+        module = __import__("questionary")
+    except ImportError:
+        return None, None
+
+    return module, getattr(module, "Choice", None)
+
+
+def _make_questionary_choice(choice_cls: Any | None, **kwargs: Any) -> Any:
+    """Create a questionary Choice instance or lightweight fallback."""
+    if choice_cls is None:
+        return kwargs
+    return choice_cls(**kwargs)
+
+
+@contextmanager
+def bind_slash_session_context(ctx: Any, session: Any) -> Any:
+    """Temporarily attach a slash session to the Click context.
+
+    Args:
+        ctx: Click context object.
+        session: SlashSession instance to bind.
+
+    Yields:
+        None - context manager for use in with statement.
+    """
+    ctx_obj = getattr(ctx, "obj", None)
+    has_context = isinstance(ctx_obj, dict)
+    previous_session = ctx_obj.get("_slash_session") if has_context else None
+    if has_context:
+        ctx_obj["_slash_session"] = session
+    try:
+        yield
+    finally:
+        if has_context:
+            if previous_session is None:
+                ctx_obj.pop("_slash_session", None)
+            else:
+                ctx_obj["_slash_session"] = previous_session
+
+
+def restore_slash_session_context(ctx_obj: dict[str, Any], previous_session: Any | None) -> None:
+    """Restore slash session context after operation.
+
+    Args:
+        ctx_obj: Click context obj dictionary.
+        previous_session: Previous session to restore, or None to remove.
+    """
+    if previous_session is None:
+        ctx_obj.pop("_slash_session", None)
+    else:
+        ctx_obj["_slash_session"] = previous_session
+
+
+def handle_best_effort_check(
+    check_func: Callable[[], None],
+) -> None:
+    """Handle best-effort duplicate/existence checks with proper exception handling.
+
+    Args:
+        check_func: Function that performs the check and raises ClickException if duplicate found.
+    """
+    try:
+        check_func()
+    except click.ClickException:
+        raise
+    except Exception:
+        # Non-fatal: best-effort duplicate check
+        pass
+
+
+def prompt_export_choice_questionary(
+    default_path: Path,
+    default_display: str,
+) -> tuple[str, Path | None] | None:
+    """Prompt user for export destination using questionary with numeric shortcuts.
+
+    Args:
+        default_path: Default export path.
+        default_display: Formatted display string for default path.
+
+    Returns:
+        Tuple of (choice, path) or None if cancelled/unavailable.
+        Choice can be "default", "custom", or "cancel".
+    """
+    questionary_module, choice_cls = _load_questionary_module()
+    if questionary_module is None or choice_cls is None:
+        return None
+
+    try:
+        question = questionary_module.select(
+            "Export transcript",
+            choices=[
+                _make_questionary_choice(
+                    choice_cls,
+                    title=f"Save to default ({default_display})",
+                    value=("default", default_path),
+                    shortcut_key="1",
+                ),
+                _make_questionary_choice(
+                    choice_cls,
+                    title="Choose a different path",
+                    value=("custom", None),
+                    shortcut_key="2",
+                ),
+                _make_questionary_choice(
+                    choice_cls,
+                    title="Cancel",
+                    value=("cancel", None),
+                    shortcut_key="3",
+                ),
+            ],
+            use_shortcuts=True,
+            instruction="Press 1-3 (or arrows) then Enter.",
+        )
+        answer = questionary_safe_ask(question)
+    except Exception:
+        return None
+
+    if answer is None:
+        return ("cancel", None)
+    return answer
+
+
+def questionary_safe_ask(question: Any, *, patch_stdout: bool = False) -> Any:
+    """Run `questionary.Question` safely even when an asyncio loop is active."""
+    ask_fn = getattr(question, "unsafe_ask", None)
+    if not callable(ask_fn):
+        raise RuntimeError("Questionary prompt is missing unsafe_ask()")
+
+    if not _asyncio_loop_running():
+        return ask_fn(patch_stdout=patch_stdout)
+
+    return _run_questionary_in_thread(question, patch_stdout=patch_stdout)
+
+
+def _asyncio_loop_running() -> bool:
+    """Return True when an asyncio event loop is already running."""
+    try:
+        asyncio.get_running_loop()
+    except RuntimeError:
+        return False
+    return True
+
+
+def _run_questionary_in_thread(question: Any, *, patch_stdout: bool = False) -> Any:
+    """Execute a questionary prompt in a background thread."""
+    if getattr(question, "should_skip_question", False):
+        return getattr(question, "default", None)
+
+    application = getattr(question, "application", None)
+    run_callable = getattr(application, "run", None) if application is not None else None
+    if callable(run_callable):
+        try:
+            if patch_stdout and pt_patch_stdout is not None:
+                with pt_patch_stdout():
+                    return run_callable(in_thread=True)
+            return run_callable(in_thread=True)
+        except TypeError:
+            pass
+
+    return question.unsafe_ask(patch_stdout=patch_stdout)
+
 
 class _LiteralYamlDumper(yaml.SafeDumper):
     """YAML dumper that emits literal scalars for multiline strings."""
@@ -70,6 +248,7 @@ _LiteralYamlDumper.add_representer(str, _literal_str_representer)
 try:
     from prompt_toolkit.buffer import Buffer
     from prompt_toolkit.completion import Completion
+    from prompt_toolkit.patch_stdout import patch_stdout as pt_patch_stdout
     from prompt_toolkit.selection import SelectionType
     from prompt_toolkit.shortcuts import PromptSession, prompt
 
@@ -79,13 +258,9 @@ except Exception:  # pragma: no cover - optional dependency
     SelectionType = None  # type: ignore[assignment]
     PromptSession = None  # type: ignore[assignment]
     prompt = None  # type: ignore[assignment]
+    pt_patch_stdout = None  # type: ignore[assignment]
     _HAS_PTK = False
 
-try:
-    import questionary
-except Exception:  # pragma: no cover - optional dependency
-    questionary = None
-
 if TYPE_CHECKING:  # pragma: no cover - import-only during type checking
     from glaip_sdk import Client
 
@@ -160,8 +335,6 @@ def format_datetime_fields(
     Returns:
         New dictionary with formatted datetime fields
     """
-    from glaip_sdk.utils import format_datetime
-
     formatted = data.copy()
     for field in fields:
         if field in formatted:
@@ -224,10 +397,6 @@ def handle_resource_export(
         get_by_id_func: Function to fetch resource by ID
         console_override: Optional console override
     """
-    from glaip_sdk.cli.display import handle_rich_output
-    from glaip_sdk.cli.io import export_resource_to_file_with_validation
-    from glaip_sdk.cli.rich_helpers import print_markup
-
     active_console = console_override or console
 
     # Auto-detect format from file extension
@@ -251,7 +420,7 @@ def handle_resource_export(
         ):
             export_resource_to_file_with_validation(full_resource, export_path, detected_format)
     except Exception:
-        handle_rich_output(
+        cli_display.handle_rich_output(
             ctx,
             markup_text(f"[{WARNING_STYLE}]⚠️  Failed to fetch full details, using available data[/]"),
         )
@@ -264,73 +433,6 @@ def handle_resource_export(
     )
 
 
-def in_slash_mode(ctx: click.Context | None = None) -> bool:
-    """Return True when running inside the slash command palette."""
-    if ctx is None:
-        try:
-            ctx = click.get_current_context(silent=True)
-        except RuntimeError:
-            ctx = None
-
-    if ctx is None:
-        return False
-
-    obj = getattr(ctx, "obj", None)
-    if isinstance(obj, dict):
-        return bool(obj.get("_slash_session"))
-
-    return bool(getattr(obj, "_slash_session", False))
-
-
-def command_hint(
-    cli_command: str | None,
-    slash_command: str | None = None,
-    *,
-    ctx: click.Context | None = None,
-) -> str | None:
-    """Return the appropriate command string for the current mode.
-
-    Args:
-        cli_command: Command string without the ``aip`` prefix (e.g., ``"status"``).
-        slash_command: Slash command counterpart (e.g., ``"status"`` or ``"/status"``).
-        ctx: Optional Click context override.
-
-    Returns:
-        The formatted command string for the active mode, or ``None`` when no
-        equivalent command exists in that mode.
-    """
-    if in_slash_mode(ctx):
-        if not slash_command:
-            return None
-        return slash_command if slash_command.startswith("/") else f"/{slash_command}"
-
-    if not cli_command:
-        return None
-    return f"aip {cli_command}"
-
-
-def format_command_hint(
-    command: str | None,
-    description: str | None = None,
-) -> str | None:
-    """Return a Rich markup string that highlights a command hint.
-
-    Args:
-        command: Command text to highlight (already formatted for the active mode).
-        description: Optional short description to display alongside the command.
-
-    Returns:
-        Markup string suitable for Rich rendering, or ``None`` when ``command`` is falsy.
-    """
-    if not command:
-        return None
-
-    highlighted = f"[{HINT_COMMAND_STYLE}]{command}[/]"
-    if description:
-        highlighted += f"  [{HINT_DESCRIPTION_COLOR}]{description}[/{HINT_DESCRIPTION_COLOR}]"
-    return highlighted
-
-
 def sdk_version() -> str:
     """Return the current SDK version, warning if metadata is unavailable."""
     version = getattr(_version_module, "__version__", None)
@@ -345,6 +447,28 @@ def sdk_version() -> str:
     return "0.0.0"
 
 
+@contextmanager
+def with_client_and_spinner(
+    ctx: Any,
+    spinner_message: str,
+    *,
+    console_override: Console | None = None,
+) -> Any:
+    """Context manager for commands that need client and spinner.
+
+    Args:
+        ctx: Click context.
+        spinner_message: Message to display in spinner.
+        console_override: Optional console override.
+
+    Yields:
+        Client instance.
+    """
+    client = get_client(ctx)
+    with spinner_context(ctx, spinner_message, console_override=console_override):
+        yield client
+
+
 def spinner_context(
     ctx: Any | None,
     message: str,
@@ -1184,19 +1308,20 @@ def build_renderer(
 
     # Configure renderer based on verbose mode and explicit overrides
     live_enabled = bool(live) if live is not None else not verbose
-    renderer_cfg = RendererConfig(
-        live=live_enabled,
-        append_finished_snapshots=bool(snapshots)
-        if snapshots is not None
-        else RendererConfig.append_finished_snapshots,
+    cfg_overrides = {
+        "live": live_enabled,
+        "append_finished_snapshots": bool(snapshots) if snapshots is not None else False,
+    }
+    renderer_console = (
+        working_console.original_console if isinstance(working_console, CapturingConsole) else working_console
     )
-
-    # Create the renderer instance
-    renderer = RichStreamRenderer(
-        working_console.original_console if isinstance(working_console, CapturingConsole) else working_console,
-        cfg=renderer_cfg,
-        verbose=verbose,
+    factory = make_verbose_renderer if verbose else make_default_renderer
+    factory_options = RendererFactoryOptions(
+        console=renderer_console,
+        cfg_overrides=cfg_overrides,
+        verbose=verbose if factory is make_default_renderer else None,
     )
+    renderer = factory_options.build(factory)
 
     # Link the renderer back to the slash session when running from the palette.
     _register_renderer_with_session(_ctx, renderer)
@@ -1366,17 +1491,19 @@ def _handle_json_view_ambiguity(matches: list[Any]) -> Any:
 
 def _handle_questionary_ambiguity(resource_type: str, ref: str, matches: list[Any]) -> Any:
     """Handle ambiguity using questionary interactive interface."""
-    if not (questionary and os.getenv("TERM") and os.isatty(0) and os.isatty(1)):
+    questionary_module, choice_cls = _load_questionary_module()
+    if not (questionary_module and os.getenv("TERM") and os.isatty(0) and os.isatty(1)):
         raise click.ClickException("Interactive selection not available")
 
     # Escape special characters for questionary
     safe_resource_type = resource_type.replace("{", "{{").replace("}", "}}")
     safe_ref = ref.replace("{", "{{").replace("}", "}}")
 
-    picked_idx = questionary.select(
+    picked_idx = questionary_module.select(
         f"Multiple {safe_resource_type}s match '{safe_ref}'. Pick one:",
         choices=[
-            questionary.Choice(
+            _make_questionary_choice(
+                choice_cls,
                 title=(
                     f"{getattr(m, 'name', '—').replace('{', '{{').replace('}', '}}')} — "
                     f"{getattr(m, 'id', '').replace('{', '{{').replace('}', '}}')}"

glaip_sdk/cli/validators.py

@@ -13,6 +13,7 @@ from typing import Any
 
 import click
 
+from glaip_sdk.cli.utils import handle_best_effort_check
 from glaip_sdk.utils.validation import (
     coerce_timeout,
     validate_agent_instruction,
@@ -226,14 +227,12 @@ def validate_name_uniqueness_cli(
     Raises:
         click.ClickException: If name is not unique
     """
-    try:
+
+    def _check_duplicate() -> None:
         existing = finder_func(name=name)
         if existing:
             raise click.ClickException(
                 f"A {resource_type.lower()} named '{name}' already exists. Please choose a unique name."
             )
-    except click.ClickException:
-        raise
-    except Exception:
-        # Non-fatal: best-effort duplicate check
-        pass
+
+    handle_best_effort_check(_check_duplicate)

glaip_sdk/client/__init__.py

@@ -5,6 +5,7 @@ Authors:
     Raymond Christopher (raymond.christopher@gdplabs.id)
 """
 
+from glaip_sdk.client.agent_runs import AgentRunsClient
 from glaip_sdk.client.main import Client
 
-__all__ = ["Client"]
+__all__ = ["AgentRunsClient", "Client"]

glaip_sdk/client/agent_runs.py

@@ -0,0 +1,147 @@
+#!/usr/bin/env python3
+"""Agent runs client for AIP SDK.
+
+Authors:
+    Raymond Christopher (raymond.christopher@gdplabs.id)
+"""
+
+from typing import Any
+
+import httpx
+
+from glaip_sdk.client.base import BaseClient
+from glaip_sdk.exceptions import TimeoutError, ValidationError
+from glaip_sdk.models.agent_runs import RunSummary, RunsPage, RunWithOutput
+
+
+class AgentRunsClient(BaseClient):
+    """Client for agent run operations."""
+
+    def list_runs(
+        self,
+        agent_id: str,
+        *,
+        limit: int = 20,
+        page: int = 1,
+    ) -> RunsPage:
+        """List agent runs with pagination.
+
+        Args:
+            agent_id: UUID of the agent
+            limit: Number of runs per page (1-100, default 20)
+            page: Page number (1-based, default 1)
+
+        Returns:
+            RunsPage containing paginated run summaries
+
+        Raises:
+            ValidationError: If pagination parameters are invalid
+            NotFoundError: If agent is not found
+            AuthenticationError: If authentication fails
+            TimeoutError: If request times out (30s default)
+        """
+        self._validate_pagination_params(limit, page)
+        envelope = self._fetch_runs_envelope(agent_id, limit, page)
+        normalized_data = self._normalize_runs_payload(envelope.get("data"))
+        runs = [RunSummary(**item) for item in normalized_data]
+        return self._build_runs_page(envelope, runs, limit, page)
+
+    def _fetch_runs_envelope(self, agent_id: str, limit: int, page: int) -> dict[str, Any]:
+        params = {"limit": limit, "page": page}
+        try:
+            envelope = self._request_with_envelope(
+                "GET",
+                f"/agents/{agent_id}/runs",
+                params=params,
+            )
+        except httpx.TimeoutException as e:
+            raise TimeoutError(f"Request timed out after {self._timeout}s while fetching agent runs") from e
+
+        if isinstance(envelope, dict):
+            return envelope
+        return {"data": envelope}
+
+    @staticmethod
+    def _validate_pagination_params(limit: int, page: int) -> None:
+        if limit < 1 or limit > 100:
+            raise ValidationError("limit must be between 1 and 100")
+        if page < 1:
+            raise ValidationError("page must be >= 1")
+
+    @staticmethod
+    def _normalize_runs_payload(data_payload: Any) -> list[Any]:
+        if not data_payload:
+            return []
+        normalized_data: list[Any] = []
+        for item in data_payload:
+            normalized_data.append(AgentRunsClient._normalize_run_item(item))
+        return normalized_data
+
+    @staticmethod
+    def _normalize_run_item(item: Any) -> Any:
+        if isinstance(item, dict):
+            if item.get("config") is None:
+                item["config"] = {}
+            schedule_id = item.get("schedule_id")
+            if schedule_id == "None" or schedule_id == "":
+                item["schedule_id"] = None
+        return item
+
+    @staticmethod
+    def _build_runs_page(
+        envelope: dict[str, Any],
+        runs: list[RunSummary],
+        limit: int,
+        page: int,
+    ) -> RunsPage:
+        return RunsPage(
+            data=runs,
+            total=envelope.get("total", 0),
+            page=envelope.get("page", page),
+            limit=envelope.get("limit", limit),
+            has_next=envelope.get("has_next", False),
+            has_prev=envelope.get("has_prev", False),
+        )
+
+    def get_run(
+        self,
+        agent_id: str,
+        run_id: str,
+    ) -> RunWithOutput:
+        """Get detailed run information including SSE event stream.
+
+        Args:
+            agent_id: UUID of the agent
+            run_id: UUID of the run
+
+        Returns:
+            RunWithOutput containing complete run details and event stream
+
+        Raises:
+            NotFoundError: If run or agent is not found
+            AuthenticationError: If authentication fails
+            TimeoutError: If request times out (30s default)
+        """
+        try:
+            envelope = self._request_with_envelope(
+                "GET",
+                f"/agents/{agent_id}/runs/{run_id}",
+            )
+        except httpx.TimeoutException as e:
+            raise TimeoutError(f"Request timed out after {self._timeout}s while fetching run detail") from e
+
+        if not isinstance(envelope, dict):
+            envelope = {"data": envelope}
+
+        data = envelope.get("data") or {}
+        # Normalize config, output, and schedule_id fields
+        if data.get("config") is None:
+            data["config"] = {}
+        if data.get("output") is None:
+            data["output"] = []
+        # Normalize schedule_id: convert string "None" to None
+        schedule_id = data.get("schedule_id")
+        if schedule_id == "None" or schedule_id == "":
+            data["schedule_id"] = None
+
+        return RunWithOutput(**data)