glaip-sdk 0.6.5b6__py3-none-any.whl → 0.7.12__py3-none-any.whl

glaip_sdk/cli/tui_settings.py

@@ -0,0 +1,125 @@
+"""Typed loader/saver for TUI preferences stored in config.yaml.
+
+This module implements the TUI preferences store as defined in
+`specs/architecture/tui-preferences-store/spec.md`.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Literal, cast
+
+from glaip_sdk.cli.account_store import AccountStore, get_account_store
+
+ThemeModeValue = Literal["auto", "light", "dark"]
+
+_DEFAULT_THEME_MODE: ThemeModeValue = "auto"
+_DEFAULT_LEADER = "ctrl+x"
+_DEFAULT_MOUSE_CAPTURE = False
+
+
+@dataclass(frozen=True)
+class TUISettings:
+    """Resolved TUI preferences from config.yaml."""
+
+    theme_mode: ThemeModeValue = _DEFAULT_THEME_MODE
+    theme_name: str | None = None
+    leader: str = _DEFAULT_LEADER
+    keybind_overrides: dict[str, str] = field(default_factory=dict)
+    mouse_capture: bool = _DEFAULT_MOUSE_CAPTURE
+
+
+def load_tui_settings(*, store: AccountStore | None = None) -> TUISettings:
+    """Load TUI preferences from the CLI config file."""
+    store = store or get_account_store()
+    config = store.load_config()
+
+    tui = _as_dict(config.get("tui"))
+    theme = _as_dict(tui.get("theme"))
+    mode = _coerce_theme_mode(theme.get("mode"))
+    name = _normalize_theme_name(theme.get("name"))
+
+    keybinds = _as_dict(tui.get("keybinds"))
+    leader = keybinds.get("leader")
+    if not isinstance(leader, str) or not leader.strip():
+        leader = _DEFAULT_LEADER
+
+    overrides = _coerce_keybind_overrides(keybinds.get("overrides"))
+
+    mouse_capture = tui.get("mouse_capture")
+    if not isinstance(mouse_capture, bool):
+        mouse_capture = _DEFAULT_MOUSE_CAPTURE
+
+    return TUISettings(
+        theme_mode=mode,
+        theme_name=name,
+        leader=leader,
+        keybind_overrides=overrides,
+        mouse_capture=mouse_capture,
+    )
+
+
+def update_tui_settings(patch: dict[str, Any], *, store: AccountStore | None = None) -> None:
+    """Update TUI preferences, preserving unrelated config keys."""
+    store = store or get_account_store()
+    config = store.load_config()
+
+    existing = _as_dict(config.get("tui"))
+    config["tui"] = _merge_dict(existing, patch)
+
+    store.save_config_updates(config)
+
+
+def persist_tui_theme(*, mode: ThemeModeValue, name: str | None, store: AccountStore | None = None) -> None:
+    """Persist theme preferences in the tui.theme namespace."""
+    update_tui_settings(
+        {"theme": {"mode": _coerce_theme_mode(mode), "name": _serialize_theme_name(name)}},
+        store=store,
+    )
+
+
+def _as_dict(value: Any) -> dict[str, Any]:
+    if isinstance(value, dict):
+        return dict(value)
+    return {}
+
+
+def _coerce_theme_mode(value: Any) -> ThemeModeValue:
+    if isinstance(value, str):
+        lowered = value.strip().lower()
+        if lowered in {"auto", "light", "dark"}:
+            return cast(ThemeModeValue, lowered)
+    return _DEFAULT_THEME_MODE
+
+
+def _normalize_theme_name(value: Any) -> str | None:
+    if not isinstance(value, str):
+        return None
+    cleaned = value.strip()
+    if not cleaned or cleaned.lower() == "default":
+        return None
+    return cleaned
+
+
+def _serialize_theme_name(name: str | None) -> str:
+    if isinstance(name, str):
+        cleaned = name.strip()
+        if cleaned:
+            return cleaned
+    return "default"
+
+
+def _coerce_keybind_overrides(value: Any) -> dict[str, str]:
+    if not isinstance(value, dict):
+        return {}
+    return {key: val for key, val in value.items() if isinstance(key, str) and isinstance(val, str)}
+
+
+def _merge_dict(base: dict[str, Any], patch: dict[str, Any]) -> dict[str, Any]:
+    merged = dict(base)
+    for key, value in patch.items():
+        if isinstance(value, dict) and isinstance(merged.get(key), dict):
+            merged[key] = _merge_dict(cast(dict[str, Any], merged[key]), value)
+        else:
+            merged[key] = value
+    return merged

glaip_sdk/cli/update_notifier.py

@@ -22,13 +22,19 @@ from rich.console import Console
 from glaip_sdk.branding import (
     ACCENT_STYLE,
     ERROR_STYLE,
+    INFO_STYLE,
     SUCCESS_STYLE,
     WARNING_STYLE,
 )
-from glaip_sdk.cli.commands.update import update_command
+from glaip_sdk.cli.commands.update import (
+    PACKAGE_NAME,
+    _build_command_parts,
+    _build_manual_upgrade_command,
+    _is_uv_managed_environment,
+    update_command,
+)
 from glaip_sdk.cli.constants import UPDATE_CHECK_ENABLED
-from glaip_sdk.cli.hints import format_command_hint
-from glaip_sdk.cli.utils import command_hint
+from glaip_sdk.cli.hints import command_hint, format_command_hint
 from glaip_sdk.rich_components import AIPPanel
 
 FetchLatestVersion = Callable[[], str | None]
@@ -37,6 +43,7 @@ PYPI_JSON_URL = "https://pypi.org/pypi/{package}/json"
 DEFAULT_TIMEOUT = 1.5  # seconds
 
 _LOGGER = logging.getLogger(__name__)
+_UPDATE_VERSIONS_KEY = "_update_notifier_versions"
 
 
 def _parse_version(value: str) -> Version | None:
@@ -146,6 +153,7 @@ def maybe_notify_update(
                 "- choose Update now or Skip to continue."
             )
             active_console.print(message)
+            _stash_update_versions(ctx, current_version, latest_version)
             _handle_update_decision(active_console, ctx)
             return
 
@@ -161,6 +169,7 @@ def maybe_notify_update(
     )
     active_console.print(panel)
     if should_prompt:
+        _stash_update_versions(ctx, current_version, latest_version)
         _handle_update_decision(active_console, ctx)
 
 
@@ -201,7 +210,13 @@ def _prompt_update_decision(console: Console) -> Literal["update", "skip"]:
 
     while True:
         try:
-            response = console.input("Choice [1/2]: ").strip().lower()
+            raw_response = console.input("Choice [1/2]: ")
+            # Strip whitespace and convert to lowercase
+            response = raw_response.strip().lower()
+            # Remove any non-printable control characters (but keep printable chars)
+            # This handles cases where ANSI escape sequences or other control chars leak into input
+            response = "".join(char for char in response if char.isprintable() or char.isspace())
+            response = response.strip()  # Strip again after filtering
         except (KeyboardInterrupt, EOFError):
             console.print(f"\n[{WARNING_STYLE}]Update skipped.[/]")
             return "skip"
@@ -214,19 +229,93 @@ def _prompt_update_decision(console: Console) -> Literal["update", "skip"]:
         console.print(f"[{ERROR_STYLE}]Please enter 1 to update now or 2 to skip.[/]")
 
 
+def _get_manual_upgrade_command(is_uv: bool) -> str:
+    """Get the manual upgrade command for the given environment type.
+
+    Args:
+        is_uv: True if running in uv tool environment, False for pip environment.
+
+    Returns:
+        Manual upgrade command string.
+    """
+    try:
+        return _build_manual_upgrade_command(include_prerelease=False, is_uv=is_uv)
+    except Exception:
+        # Fallback: rebuild from shared command parts to avoid hardcoded strings.
+        try:
+            command_parts, _ = _build_command_parts(
+                package_name=PACKAGE_NAME,
+                is_uv=is_uv,
+                force_reinstall=False,
+                include_prerelease=False,
+            )
+        except Exception:
+            command_parts = (
+                ["uv", "tool", "install", "--upgrade", PACKAGE_NAME]
+                if is_uv
+                else ["pip", "install", "--upgrade", PACKAGE_NAME]
+            )
+        return " ".join(command_parts)
+
+
+def _show_proactive_uv_guidance(console: Console, is_uv: bool) -> None:
+    """Show proactive guidance for uv environments before update attempt.
+
+    Args:
+        console: Rich console for output.
+        is_uv: True if running in uv tool environment.
+    """
+    if not is_uv:
+        return
+
+    manual_cmd = _get_manual_upgrade_command(is_uv=True)
+    console.print(
+        f"[{INFO_STYLE}]💡 Detected uv tool environment.[/] "
+        f"If automatic update fails, run: [{ACCENT_STYLE}]{manual_cmd}[/]"
+    )
+
+
+def _show_error_guidance(console: Console, is_uv: bool) -> None:
+    """Show error guidance with correct manual command based on environment.
+
+    Args:
+        console: Rich console for output.
+        is_uv: True if running in uv tool environment.
+    """
+    try:
+        manual_cmd = _get_manual_upgrade_command(is_uv=is_uv)
+        console.print(f"[{INFO_STYLE}]💡 Tip:[/] Run this command manually:\n   [{ACCENT_STYLE}]{manual_cmd}[/]")
+    except Exception as exc:  # pragma: no cover - defensive guard
+        _LOGGER.debug("Failed to render update tip: %s", exc, exc_info=True)
+
+
 def _run_update_command(console: Console, ctx: Any) -> None:
     """Invoke the built-in update command and surface any errors."""
+    # Detect uv environment proactively before attempting update
+    is_uv = _is_uv_managed_environment()
+
+    # Provide proactive guidance for uv environments
+    # This helps users on older versions (e.g., 0.6.19) that don't have uv detection
+    # in their update command
+    _show_proactive_uv_guidance(console, is_uv)
+
     try:
         ctx.invoke(update_command)
     except click.ClickException as exc:
         exc.show()
         console.print(f"[{ERROR_STYLE}]Update command exited with an error.[/]")
+        _show_error_guidance(console, is_uv)
     except click.Abort:
         console.print(f"[{WARNING_STYLE}]Update aborted by user.[/]")
     except Exception as exc:  # pragma: no cover - defensive guard
         console.print(f"[{ERROR_STYLE}]Unexpected error while running update: {exc}[/]")
+        # Also provide guidance for unexpected errors in uv environments
+        if is_uv:
+            manual_cmd = _get_manual_upgrade_command(is_uv=True)
+            console.print(f"[{INFO_STYLE}]💡 Tip:[/] Try running manually:\n   [{ACCENT_STYLE}]{manual_cmd}[/]")
     else:
-        _refresh_installed_version(console, ctx)
+        new_version = _refresh_installed_version(console, ctx)
+        _maybe_retry_update(console, ctx, new_version, is_uv)
 
 
 @contextmanager
@@ -247,7 +336,7 @@ def _suppress_library_logging(
             logger.setLevel(previous_level)
 
 
-def _refresh_installed_version(console: Console, ctx: Any) -> None:
+def _refresh_installed_version(console: Console, ctx: Any) -> str | None:
     """Reload runtime metadata after an in-process upgrade."""
     new_version: str | None = None
     branding_module: Any | None = None
@@ -271,12 +360,13 @@ def _refresh_installed_version(console: Console, ctx: Any) -> None:
         try:
             branding_cls = getattr(branding_module, "AIPBranding", None) if branding_module else None
             session.refresh_branding(new_version, branding_cls=branding_cls)
-            return
+            return new_version
         except Exception as exc:  # pragma: no cover - defensive guard
             _LOGGER.debug("Failed to refresh active slash session: %s", exc, exc_info=True)
 
     if new_version:
         console.print(f"[{SUCCESS_STYLE}]CLI now running glaip-sdk {new_version}.[/]")
+    return new_version
 
 
 def _get_slash_session(ctx: Any) -> Any | None:
@@ -287,4 +377,122 @@ def _get_slash_session(ctx: Any) -> Any | None:
     return None
 
 
+def _stash_update_versions(ctx: Any | None, current_version: str, latest_version: str) -> None:
+    """Persist update versions in the Click context for post-update checks."""
+    if ctx is None:
+        return
+    ctx_obj = getattr(ctx, "obj", None)
+    if isinstance(ctx_obj, dict):
+        ctx_obj[_UPDATE_VERSIONS_KEY] = {"current": current_version, "latest": latest_version}
+
+
+def _get_update_versions(ctx: Any | None) -> tuple[str | None, str | None]:
+    """Return current/latest versions captured during the update prompt."""
+    if ctx is None:
+        return None, None
+    ctx_obj = getattr(ctx, "obj", None)
+    if not isinstance(ctx_obj, dict):
+        return None, None
+    payload = ctx_obj.get(_UPDATE_VERSIONS_KEY)
+    if not isinstance(payload, dict):
+        return None, None
+    current = payload.get("current")
+    latest = payload.get("latest")
+    return (
+        current if isinstance(current, str) else None,
+        latest if isinstance(latest, str) else None,
+    )
+
+
+def _should_retry_update(
+    ctx: Any,
+    console: Console,
+    new_version: str | None,
+) -> tuple[str, str, Version, Version, Version] | None:
+    """Check if update retry is needed and return parsed versions if so."""
+    if ctx is None or not hasattr(ctx, "invoke"):
+        return None
+    if not _should_prompt_for_action(console, ctx):
+        return None
+
+    current_version, latest_version = _get_update_versions(ctx)
+    if not current_version or not latest_version or not new_version:
+        return None
+
+    current = _parse_version(current_version)
+    latest = _parse_version(latest_version)
+    installed = _parse_version(new_version)
+    if current is None or latest is None or installed is None:
+        return None
+
+    if installed >= latest:
+        return None
+
+    # Note: installed > current case is handled in _maybe_retry_update()
+    # to allow warning message to be printed before returning
+
+    return current_version, latest_version, current, latest, installed
+
+
+def _handle_reinstall_error(console: Console, exc: Exception, is_uv: bool) -> None:
+    """Handle errors during reinstall attempt."""
+    if isinstance(exc, click.ClickException):
+        exc.show()
+        console.print(f"[{ERROR_STYLE}]Reinstall attempt failed.[/]")
+        _show_error_guidance(console, is_uv)
+    elif isinstance(exc, click.Abort):
+        console.print(f"[{WARNING_STYLE}]Reinstall skipped by user.[/]")
+    else:
+        console.print(f"[{ERROR_STYLE}]Unexpected error while reinstalling: {exc}[/]")
+        if is_uv:
+            manual_cmd = _get_manual_upgrade_command(is_uv=True)
+            console.print(f"[{INFO_STYLE}]💡 Tip:[/] Try running manually:\n   [{ACCENT_STYLE}]{manual_cmd}[/]")
+
+
+def _check_final_version(
+    console: Console, new_version: str | None, latest_version: str, latest: Version, is_uv: bool
+) -> None:
+    """Check and report final version status after reinstall."""
+    installed = _parse_version(new_version) if isinstance(new_version, str) else None
+    if installed is None or installed < latest:
+        console.print(
+            f"[{WARNING_STYLE}]Still on {new_version}. Your package index may not have {latest_version} yet.[/]"
+        )
+        if is_uv:
+            console.print(
+                f"[{INFO_STYLE}]💡 Tip:[/] If you need PyPI immediately, set "
+                f"[{ACCENT_STYLE}]UV_INDEX_URL=https://pypi.org/simple[/]."
+            )
+
+
+def _maybe_retry_update(
+    console: Console,
+    ctx: Any,
+    new_version: str | None,
+    is_uv: bool,
+) -> None:
+    """Retry once with reinstall when the update did not advance versions."""
+    versions = _should_retry_update(ctx, console, new_version)
+    if versions is None:
+        return
+
+    current_version, latest_version, current, latest, installed = versions
+    if installed > current:
+        console.print(f"[{WARNING_STYLE}]Update installed {new_version}, but {latest_version} is still available.[/]")
+        return
+
+    console.print(
+        f"[{WARNING_STYLE}]Update completed but version stayed at {new_version}. Retrying with reinstall...[/]"
+    )
+
+    try:
+        ctx.invoke(update_command, force_reinstall=True)
+    except Exception as exc:
+        _handle_reinstall_error(console, exc, is_uv)
+        return
+
+    new_version = _refresh_installed_version(console, ctx)
+    _check_final_version(console, new_version, latest_version, latest, is_uv)
+
+
 __all__ = ["maybe_notify_update"]

glaip_sdk/cli/validators.py

@@ -13,7 +13,7 @@ from typing import Any
 
 import click
 
-from glaip_sdk.cli.utils import handle_best_effort_check
+from glaip_sdk.cli.core.context import handle_best_effort_check
 from glaip_sdk.utils.validation import (
     coerce_timeout,
     validate_agent_instruction,

glaip_sdk/client/__init__.py

@@ -7,5 +7,6 @@ Authors:
 
 from glaip_sdk.client.agent_runs import AgentRunsClient
 from glaip_sdk.client.main import Client
+from glaip_sdk.client.schedules import AgentScheduleManager, ScheduleClient
 
-__all__ = ["AgentRunsClient", "Client"]
+__all__ = ["AgentRunsClient", "AgentScheduleManager", "Client", "ScheduleClient"]

glaip_sdk/client/_schedule_payloads.py

@@ -0,0 +1,89 @@
+"""Schedule request payload builders for AIP SDK.
+
+Authors:
+    Christian Trisno Sen Long Chen (christian.t.s.l.chen@gdplabs.id)
+"""
+
+from dataclasses import dataclass
+from typing import Any
+
+from glaip_sdk.models.schedule import ScheduleConfig
+
+
+@dataclass
+class ScheduleListParams:
+    """Parameters for listing schedules.
+
+    Args:
+        limit: Maximum number of schedules to return (1-100, default 50)
+        page: Page number for pagination (default 1)
+        agent_id: Filter schedules by agent ID
+    """
+
+    limit: int | None = None
+    page: int | None = None
+    agent_id: str | None = None
+
+    def to_query_params(self) -> dict[str, Any]:
+        """Convert to query parameters dictionary.
+
+        Returns:
+            Dictionary of non-None parameters for the API request
+        """
+        params: dict[str, Any] = {}
+        if self.limit is not None:
+            params["limit"] = self.limit
+        if self.page is not None:
+            params["page"] = self.page
+        if self.agent_id is not None:
+            params["agent_id"] = self.agent_id
+        return params
+
+
+def normalize_schedule(
+    schedule: ScheduleConfig | dict[str, str] | str | None,
+) -> dict[str, str] | None:
+    """Normalize schedule input to a dictionary for API requests.
+
+    Accepts multiple input formats for user convenience:
+    - ScheduleConfig: Pydantic model with cron fields
+    - dict: Dictionary with cron fields (minute, hour, etc.)
+    - str: Cron string like "0 9 * * 1-5"
+    - None: Returns None
+
+    Args:
+        schedule: Schedule in various formats
+
+    Returns:
+        Dictionary suitable for API request or None
+
+    Raises:
+        ValueError: If cron string format is invalid
+        TypeError: If schedule is an unsupported type
+
+    Examples:
+        >>> normalize_schedule(ScheduleConfig(minute="0", hour="9"))
+        {'minute': '0', 'hour': '9', 'day_of_month': '*', 'month': '*', 'day_of_week': '*'}
+
+        >>> normalize_schedule({"minute": "0", "hour": "9"})
+        {'minute': '0', 'hour': '9', 'day_of_month': '*', 'month': '*', 'day_of_week': '*'}
+
+        >>> normalize_schedule("0 9 * * 1-5")
+        {'minute': '0', 'hour': '9', 'day_of_month': '*', 'month': '*', 'day_of_week': '1-5'}
+    """
+    if schedule is None:
+        return None
+
+    if isinstance(schedule, ScheduleConfig):
+        return schedule.model_dump()
+
+    if isinstance(schedule, dict):
+        # Validate and merge with defaults
+        return ScheduleConfig(**schedule).model_dump()
+
+    if isinstance(schedule, str):
+        # Parse cron string
+        config = ScheduleConfig.from_cron_string(schedule)
+        return config.model_dump()
+
+    raise TypeError(f"schedule must be ScheduleConfig, dict, or str, got {type(schedule).__name__}")

glaip_sdk/client/agents.py

@@ -13,11 +13,15 @@ from collections.abc import AsyncGenerator, Callable, Iterator, Mapping
 from contextlib import asynccontextmanager
 from os import PathLike
 from pathlib import Path
-from typing import Any, BinaryIO
+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
-from glaip_sdk.client._agent_payloads import (
+from glaip_sdk.client.payloads.agent import (
     AgentCreateRequest,
     AgentListParams,
     AgentListResult,
@@ -264,6 +268,7 @@ class AgentClient(BaseClient):
         self._tool_client: ToolClient | None = None
         self._mcp_client: MCPClient | None = None
         self._runs_client: AgentRunsClient | None = None
+        self._schedule_client: ScheduleClient | None = None
 
     def list_agents(
         self,
@@ -411,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.
 
@@ -420,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).
@@ -431,6 +438,7 @@ class AgentClient(BaseClient):
             timeout_seconds,
             agent_name,
             meta,
+            hitl_handler=hitl_handler,
         )
 
     def _finalize_renderer(
@@ -453,13 +461,11 @@ class AgentClient(BaseClient):
         Returns:
             Final text string.
         """
+        from glaip_sdk.client.run_rendering import finalize_render_manager  # noqa: PLC0415
+
         manager = self._get_renderer_manager()
-        return manager.finalize_renderer(
-            renderer,
-            final_text,
-            stats_usage,
-            started_monotonic,
-            finished_monotonic,
+        return finalize_render_manager(
+            manager, renderer, final_text, stats_usage, started_monotonic, finished_monotonic
         )
 
     def _get_tool_client(self) -> ToolClient:
@@ -482,6 +488,20 @@ class AgentClient(BaseClient):
             self._mcp_client = MCPClient(parent_client=self)
         return self._mcp_client
 
+    @property
+    def schedules(self) -> "ScheduleClient":
+        """Get or create the schedule client instance.
+
+        Returns:
+            ScheduleClient instance.
+        """
+        if self._schedule_client is None:
+            # Import here to avoid circular import
+            from glaip_sdk.client.schedules import ScheduleClient  # noqa: PLC0415
+
+            self._schedule_client = ScheduleClient(parent_client=self)
+        return self._schedule_client
+
     def _normalise_reference_entry(
         self,
         entry: Any,
@@ -1096,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.
@@ -1113,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:
@@ -1169,6 +1192,7 @@ class AgentClient(BaseClient):
                     timeout_seconds,
                     agent_name,
                     meta,
+                    hitl_handler=hitl_handler,
                 )
 
         except KeyboardInterrupt:
@@ -1185,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,
@@ -1266,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.
@@ -1282,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