glaip-sdk 0.2.1__py3-none-any.whl → 0.3.0__py3-none-any.whl

glaip_sdk/cli/commands/tools.py

@@ -4,7 +4,6 @@ Authors:
     Raymond Christopher (raymond.christopher@gdplabs.id)
 """
 
-# pylint: disable=duplicate-code
 import json
 import re
 from pathlib import Path
@@ -40,7 +39,10 @@ from glaip_sdk.cli.resolution import resolve_resource_reference
 from glaip_sdk.cli.rich_helpers import markup_text, print_markup
 from glaip_sdk.cli.utils import (
     coerce_to_row,
+    format_datetime_fields,
     get_client,
+    handle_best_effort_check,
+    handle_resource_export,
     output_list,
     output_result,
     spinner_context,
@@ -57,16 +59,32 @@ def tools_group() -> None:
     pass
 
 
-# pylint: disable=duplicate-code
 def _resolve_tool(ctx: Any, client: Any, ref: str, select: int | None = None) -> Any | None:
-    """Resolve tool reference (ID or name) with ambiguity handling."""
+    """Resolve a tool by ID or name, handling ambiguous matches interactively.
+
+    This function provides tool-specific resolution logic. It uses
+    resolve_resource_reference to find tools by UUID or name, with interactive
+    selection when multiple matches are found.
+
+    Args:
+        ctx: Click context for CLI operations.
+        client: API client instance.
+        ref: Tool reference (UUID string or name).
+        select: Pre-selected index for non-interactive mode (1-based).
+
+    Returns:
+        Tool object if found, None otherwise.
+    """
+    # Configure tool-specific resolution with standard fuzzy matching
+    get_by_id = client.get_tool
+    find_by_name = client.find_tools
     return resolve_resource_reference(
         ctx,
         client,
         ref,
         "tool",
-        client.get_tool,
-        client.find_tools,
+        get_by_id,
+        find_by_name,
         "Tool",
         select=select,
     )
@@ -100,19 +118,16 @@ def _validate_name_match(provided: str | None, internal: str) -> str:
 
 def _check_duplicate_name(client: Any, tool_name: str) -> None:
     """Raise if a tool with the same name already exists."""
-    try:
+
+    def _check_duplicate() -> None:
         existing = client.find_tools(name=tool_name)
         if existing:
             raise click.ClickException(
                 f"A tool named '{tool_name}' already exists. "
                 "Please change your plugin's 'name' to a unique value, then re-run."
             )
-    except click.ClickException:
-        # Re-raise ClickException (intended error)
-        raise
-    except Exception:
-        # Non-fatal: best-effort duplicate check for other errors
-        pass
+
+    handle_best_effort_check(_check_duplicate)
 
 
 def _parse_tags(tags: str | None) -> list[str]:
@@ -211,6 +226,14 @@ def list_tools(ctx: Any, tool_type: str | None) -> None:
 
         # Transform function for safe dictionary access
         def transform_tool(tool: Any) -> dict[str, Any]:
+            """Transform a tool object to a display row dictionary.
+
+            Args:
+                tool: Tool object to transform.
+
+            Returns:
+                Dictionary with id, name, and framework fields.
+            """
             row = coerce_to_row(tool, ["id", "name", "framework"])
             # Ensure id is always a string
             row["id"] = str(row["id"])
@@ -341,8 +364,6 @@ def get(ctx: Any, tool_ref: str, select: int | None, export: str | None) -> None
 
         # Handle export option
         if export:
-            from glaip_sdk.cli.utils import handle_resource_export
-
             handle_resource_export(
                 ctx,
                 tool,
@@ -363,8 +384,6 @@ def get(ctx: Any, tool_ref: str, select: int | None, export: str | None) -> None
         if raw_tool_data:
             # Use raw API data - this preserves ALL fields
             # Format dates for better display (minimal postprocessing)
-            from glaip_sdk.cli.utils import format_datetime_fields
-
             formatted_data = format_datetime_fields(raw_tool_data)
 
             # Display using output_result with raw data

glaip_sdk/cli/commands/transcripts.py

@@ -156,6 +156,14 @@ def _launch_transcript_viewer(
     viewer_ctx = _build_viewer_context(entry, meta, events)
 
     def _export(destination: Path) -> Path:
+        """Export cached transcript to destination.
+
+        Args:
+            destination: Path to export transcript to.
+
+        Returns:
+            Path to exported transcript file.
+        """
         return export_cached_transcript(destination=destination, run_id=entry.run_id)
 
     run_viewer_session(target_console, viewer_ctx, _export, initial_view=initial_view)

glaip_sdk/cli/constants.py

@@ -0,0 +1,38 @@
+"""CLI-specific constants for glaip-sdk.
+
+Authors:
+    Raymond Christopher (raymond.christopher@gdplabs.id)
+"""
+
+# Minimum length that forces multiline YAML strings to be rendered using the literal
+# block style. This prevents long prompts and instructions from being inlined.
+LITERAL_STRING_THRESHOLD = 200
+
+# Masking configuration
+MASKING_ENABLED = True
+MASK_SENSITIVE_FIELDS = {
+    "api_key",
+    "apikey",
+    "token",
+    "access_token",
+    "secret",
+    "client_secret",
+    "password",
+    "private_key",
+    "bearer",
+}
+
+# Table + pager behaviour
+TABLE_SORT_ENABLED = True
+PAGER_MODE = "auto"  # valid values: "auto", "on", "off"
+PAGER_WRAP_LINES = False
+PAGER_HEADER_ENABLED = True
+
+# Update notification toggle
+UPDATE_CHECK_ENABLED = True
+
+# Agent instruction preview defaults
+DEFAULT_AGENT_INSTRUCTION_PREVIEW_LIMIT = 800
+
+# Remote runs defaults
+DEFAULT_REMOTE_RUNS_PAGE_LIMIT = 20

glaip_sdk/cli/context.py

@@ -106,6 +106,14 @@ def output_flags() -> Callable[[Callable[..., Any]], Callable[..., Any]]:
     """
 
     def decorator(f: Callable[..., Any]) -> Callable[..., Any]:
+        """Apply output flags to a click command.
+
+        Args:
+            f: Click command function to decorate.
+
+        Returns:
+            Decorated command function.
+        """
         f = click.option(
             "--json",
             "json_mode",

glaip_sdk/cli/display.py

@@ -17,7 +17,7 @@ from rich.text import Text
 
 from glaip_sdk.branding import ERROR_STYLE, SUCCESS, SUCCESS_STYLE, WARNING_STYLE
 from glaip_sdk.cli.rich_helpers import markup_text
-from glaip_sdk.cli.utils import command_hint, format_command_hint
+from glaip_sdk.cli.utils import command_hint, format_command_hint, in_slash_mode
 from glaip_sdk.icons import ICON_AGENT, ICON_TOOL
 from glaip_sdk.rich_components import AIPPanel
 
@@ -304,6 +304,7 @@ def display_agent_run_suggestions(agent: Any) -> Panel:
     """Return a panel with post-creation suggestions for an agent."""
     agent_id = getattr(agent, "id", "")
     agent_name = getattr(agent, "name", "")
+    slash_mode = in_slash_mode()
     run_hint_id = command_hint(
         f'agents run {agent_id} "Your message here"',
         slash_command=None,
@@ -313,27 +314,41 @@ def display_agent_run_suggestions(agent: Any) -> Panel:
         slash_command=None,
     )
 
-    cli_section = ""
-    if run_hint_id and run_hint_name:
-        cli_section = (
-            "📋 Prefer the CLI instead?\n"
-            f"   {format_command_hint(run_hint_id) or run_hint_id}\n"
-            f"   {format_command_hint(run_hint_name) or run_hint_name}\n\n"
+    content_parts: list[str] = ["[bold blue]💡 Next Steps:[/bold blue]\n\n"]
+
+    if slash_mode:
+        slash_shortcuts = "\n".join(
+            f"   {format_command_hint(command, description) or command}"
+            for command, description in (
+                ("/details", "Show configuration (toggle preview)"),
+                ("/help", "Show command palette menu"),
+                ("/exit", "Return to the palette"),
+            )
+        )
+        content_parts.append(
+            f"🚀 Start chatting with [bold]{agent_name}[/bold] right here:\n"
+            f"   Type your message below and press Enter to run it immediately.\n\n"
+            f"{ICON_TOOL} Slash shortcuts:\n"
+            f"{slash_shortcuts}"
+        )
+    else:
+        cli_hint_lines = [format_command_hint(hint) or hint for hint in (run_hint_id, run_hint_name) if hint]
+        if cli_hint_lines:
+            joined_hints = "\n".join(f"   {hint}" for hint in cli_hint_lines)
+            content_parts.append(f"🚀 Run this agent from the CLI:\n{joined_hints}\n\n")
+        content_parts.append(
+            f"{ICON_TOOL} Available options:\n"
+            f"   [dim]--chat-history[/dim]  Include previous conversation\n"
+            f"   [dim]--file[/dim]          Attach files\n"
+            f"   [dim]--input[/dim]         Alternative input method\n"
+            f"   [dim]--timeout[/dim]       Set execution timeout\n"
+            f"   [dim]--save[/dim]          Save transcript to file\n"
+            f"   [dim]--verbose[/dim]       Show detailed execution\n\n"
+            f"💡 [dim]Input text can be positional OR use --input flag (both work!)[/dim]"
         )
 
     return AIPPanel(
-        f"[bold blue]💡 Next Steps:[/bold blue]\n\n"
-        f"🚀 Start chatting with [bold]{agent_name}[/bold] right here:\n"
-        f"   Type your message below and press Enter to run it immediately.\n\n"
-        f"{cli_section}"
-        f"{ICON_TOOL} Available options:\n"
-        f"   [dim]--chat-history[/dim]  Include previous conversation\n"
-        f"   [dim]--file[/dim]          Attach files\n"
-        f"   [dim]--input[/dim]         Alternative input method\n"
-        f"   [dim]--timeout[/dim]       Set execution timeout\n"
-        f"   [dim]--save[/dim]          Save transcript to file\n"
-        f"   [dim]--verbose[/dim]       Show detailed execution\n\n"
-        f"💡 [dim]Input text can be positional OR use --input flag (both work!)[/dim]",
+        "".join(content_parts),
         title=f"{ICON_AGENT} Ready to Run Agent",
         border_style="blue",
         padding=(0, 1),

glaip_sdk/cli/main.py

@@ -34,7 +34,7 @@ from glaip_sdk.cli.commands.mcps import mcps_group
 from glaip_sdk.cli.commands.models import models_group
 from glaip_sdk.cli.commands.tools import tools_group
 from glaip_sdk.cli.commands.transcripts import transcripts_group
-from glaip_sdk.cli.commands.update import update_command
+from glaip_sdk.cli.commands.update import _build_upgrade_command, update_command
 from glaip_sdk.cli.config import load_config
 from glaip_sdk.cli.transcript import get_transcript_cache_stats
 from glaip_sdk.cli.update_notifier import maybe_notify_update
@@ -387,6 +387,7 @@ def version() -> None:
 )
 def update(check_only: bool, force: bool) -> None:
     """Update AIP SDK to the latest version from PyPI."""
+    slash_mode = in_slash_mode()
     try:
         console = Console()
 
@@ -400,11 +401,15 @@ def update(check_only: bool, force: bool) -> None:
             )
             return
 
+        update_hint = ""
+        if not slash_mode:
+            update_hint = "\n💡 Use --check-only to just check for updates"
+
         console.print(
             AIPPanel(
                 "[bold blue]🔄 Updating AIP SDK...[/bold blue]\n\n"
-                "📦 This will update the package from PyPI\n"
-                "💡 Use --check-only to just check for updates",
+                "📦 This will update the package from PyPI"
+                f"{update_hint}",
                 title="Update Process",
                 border_style="blue",
                 padding=(0, 1),
@@ -413,8 +418,6 @@ def update(check_only: bool, force: bool) -> None:
 
         # Update using pip
         try:
-            from glaip_sdk.cli.commands.update import _build_upgrade_command
-
             cmd = list(_build_upgrade_command(include_prerelease=False))
             # Replace package name with "glaip-sdk" (main.py uses different name)
             cmd[-1] = "glaip-sdk"
@@ -422,11 +425,15 @@ def update(check_only: bool, force: bool) -> None:
                 cmd.insert(5, "--force-reinstall")
             subprocess.run(cmd, capture_output=True, text=True, check=True)
 
+            verify_hint = ""
+            if not slash_mode:
+                verify_hint = "\n💡 Restart your terminal or run 'aip --version' to verify"
+
             console.print(
                 AIPPanel(
                     f"[{SUCCESS_STYLE}]✅ Update successful![/]\n\n"
-                    "🔄 AIP SDK has been updated to the latest version\n"
-                    "💡 Restart your terminal or run 'aip --version' to verify",
+                    "🔄 AIP SDK has been updated to the latest version"
+                    f"{verify_hint}",
                     title="🎉 Update Complete",
                     border_style=SUCCESS,
                     padding=(0, 1),

glaip_sdk/cli/masking.py

@@ -6,9 +6,10 @@ Authors:
 
 from __future__ import annotations
 
-import os
 from typing import Any
 
+from glaip_sdk.cli.constants import MASKING_ENABLED, MASK_SENSITIVE_FIELDS
+
 __all__ = [
     "mask_payload",
     "mask_rows",
@@ -18,18 +19,6 @@ __all__ = [
     "_resolve_mask_fields",
 ]
 
-_DEFAULT_MASK_FIELDS = {
-    "api_key",
-    "apikey",
-    "token",
-    "access_token",
-    "secret",
-    "client_secret",
-    "password",
-    "private_key",
-    "bearer",
-}
-
 
 def _mask_value(raw: Any) -> str:
     """Return a masked representation of the provided value.
@@ -90,22 +79,10 @@ def _maybe_mask_row(row: dict[str, Any], mask_fields: set[str]) -> dict[str, Any
 
 
 def _resolve_mask_fields() -> set[str]:
-    """Resolve the set of sensitive fields to mask based on environment.
-
-    Returns:
-        set[str]: Set of field names to mask. Empty set if masking is disabled
-                 via AIP_MASK_OFF environment variable, custom fields from
-                 AIP_MASK_FIELDS, or default fields if neither is set.
-    """
-    if os.getenv("AIP_MASK_OFF", "0") in {"1", "true", "on", "yes"}:
+    """Return the configured set of fields that should be masked."""
+    if not MASKING_ENABLED:
         return set()
-
-    env_fields = (os.getenv("AIP_MASK_FIELDS") or "").strip()
-    if env_fields:
-        parts = [part.strip().lower() for part in env_fields.split(",") if part.strip()]
-        return set(parts)
-
-    return set(_DEFAULT_MASK_FIELDS)
+    return set(MASK_SENSITIVE_FIELDS)
 
 
 def mask_payload(payload: Any) -> Any:
@@ -115,9 +92,7 @@ def mask_payload(payload: Any) -> Any:
         payload: Any data structure (dict, list, or primitive) to mask.
 
     Returns:
-        Any: The payload with sensitive fields masked based on environment
-             configuration. Returns original payload if masking is disabled
-             or if an error occurs during masking.
+        Any: The payload with sensitive fields masked based on configuration.
     """
     mask_fields = _resolve_mask_fields()
     if not mask_fields:
@@ -136,8 +111,8 @@ def mask_rows(rows: list[dict[str, Any]]) -> list[dict[str, Any]]:
 
     Returns:
         list[dict[str, Any]]: List of rows with sensitive fields masked based
-                              on environment configuration. Returns original
-                              rows if masking is disabled or if an error occurs.
+                              on configuration. Returns original rows if
+                              masking is disabled or if an error occurs.
     """
     mask_fields = _resolve_mask_fields()
     if not mask_fields:

glaip_sdk/cli/pager.py

@@ -19,6 +19,8 @@ from typing import Any
 
 from rich.console import Console
 
+from glaip_sdk.cli.constants import PAGER_HEADER_ENABLED, PAGER_MODE, PAGER_WRAP_LINES
+
 __all__ = [
     "console",
     "_prepare_pager_env",
@@ -64,8 +66,7 @@ def _prepare_pager_env(clear_on_exit: bool = True) -> None:
       -R  : pass ANSI color escapes
       -S  : chop long lines (horizontal scroll with ←/→)
     (No -F, no -X) so we open a full-screen pager and clear on exit.
-    Toggle wrapping with AIP_PAGER_WRAP=1 to drop -S.
-    Power users can override via AIP_LESS_FLAGS.
+    Toggle wrapping via `PAGER_WRAP_LINES` (True drops -S).
 
     Args:
         clear_on_exit: Whether to clear the pager on exit (default: True)
@@ -75,10 +76,9 @@ def _prepare_pager_env(clear_on_exit: bool = True) -> None:
     """
     os.environ.pop("LESSSECURE", None)
     if os.getenv("LESS") is None:
-        want_wrap = os.getenv("AIP_PAGER_WRAP", "0") == "1"
-        base = "-R" if want_wrap else "-RS"
+        base = "-R" if PAGER_WRAP_LINES else "-RS"
         default_flags = base if clear_on_exit else (base + "FX")
-        os.environ["LESS"] = os.getenv("AIP_LESS_FLAGS", default_flags)
+        os.environ["LESS"] = default_flags
 
 
 def _render_ansi(renderable: Any) -> str:
@@ -111,8 +111,7 @@ def _pager_header() -> str:
     Returns:
         str: Header text containing navigation help, or empty string if disabled
     """
-    v = (os.getenv("AIP_PAGER_HEADER", "1") or "1").strip().lower()
-    if v in {"0", "false", "off"}:
+    if not PAGER_HEADER_ENABLED:
         return ""
     return "\n".join(
         [
@@ -254,10 +253,10 @@ def _should_page_output(row_count: int, is_tty: bool) -> bool:
         bool: True if output should be paginated, False otherwise
     """
     active_console = _get_console()
-    pager_env = (os.getenv("AIP_PAGER", "auto") or "auto").lower()
-    if pager_env in ("0", "off", "false"):
+    pager_mode = (PAGER_MODE or "auto").lower()
+    if pager_mode in ("0", "off", "false"):
         return False
-    if pager_env in ("1", "on", "true"):
+    if pager_mode in ("1", "on", "true"):
         return is_tty
     try:
         term_h = active_console.size.height or 24

glaip_sdk/cli/slash/agent_session.py

@@ -14,8 +14,9 @@ import click
 from glaip_sdk.branding import ERROR_STYLE, HINT_PREFIX_STYLE
 from glaip_sdk.cli.commands.agents import get as agents_get_command
 from glaip_sdk.cli.commands.agents import run as agents_run_command
+from glaip_sdk.cli.constants import DEFAULT_AGENT_INSTRUCTION_PREVIEW_LIMIT
 from glaip_sdk.cli.slash.prompt import _HAS_PROMPT_TOOLKIT, FormattedText
-from glaip_sdk.cli.utils import format_command_hint
+from glaip_sdk.cli.utils import bind_slash_session_context, format_command_hint
 
 if TYPE_CHECKING:  # pragma: no cover - type checking only
     from glaip_sdk.cli.slash.session import SlashSession
@@ -38,11 +39,13 @@ class AgentRunSession:
         self._agent_name = getattr(agent, "name", "") or self._agent_id
         self._prompt_placeholder: str = "Chat with this agent here; use / for shortcuts. Alt+Enter inserts a newline."
         self._contextual_completion_help: dict[str, str] = {
-            "details": "Show this agent's full configuration.",
+            "details": "Show this agent's configuration (+ expands prompt).",
             "help": "Display this context-aware menu.",
+            "runs": "✨ NEW · Browse remote run history for this agent.",
             "exit": "Return to the command palette.",
             "q": "Return to the command palette.",
         }
+        self._instruction_preview_limit = DEFAULT_AGENT_INSTRUCTION_PREVIEW_LIMIT
 
     def run(self) -> None:
         """Run the interactive agent session loop."""
@@ -86,6 +89,7 @@ class AgentRunSession:
         try:
 
             def _prompt_message() -> Any:
+                """Get formatted prompt message for agent session."""
                 prompt_prefix = f"{self._agent_name} ({self._agent_id}) "
 
                 # Use FormattedText if prompt_toolkit is available, otherwise use simple string
@@ -122,7 +126,7 @@ class AgentRunSession:
         if raw in {"/exit", "/back", "/q"}:
             return self._handle_exit_command()
 
-        if raw in {"/details", "/detail"}:
+        if raw == "/details":
             return self._handle_details_command(agent_id)
 
         if raw in {"/help", "/?"}:
@@ -151,16 +155,59 @@ class AgentRunSession:
         self.session.handle_command(raw, invoked_from_agent=True)
         return not self.session._should_exit
 
-    def _show_details(self, agent_id: str) -> None:
+    def _show_details(self, agent_id: str, *, enable_prompt: bool = True) -> None:
+        """Render the agent's configuration export inside the command palette."""
         try:
-            self.session.ctx.invoke(agents_get_command, agent_ref=agent_id)
-            self.console.print(
-                f"[{HINT_PREFIX_STYLE}]Tip:[/] Continue the conversation in this prompt, or use "
-                f"{format_command_hint('/help') or '/help'} for shortcuts."
+            self.session.ctx.invoke(
+                agents_get_command,
+                agent_ref=agent_id,
+                instruction_preview=self._instruction_preview_limit,
             )
+            if enable_prompt:
+                self._prompt_instruction_view_toggle(agent_id)
+                self.console.print(
+                    f"[{HINT_PREFIX_STYLE}]Tip:[/] Continue the conversation in this prompt, or use "
+                    f"{format_command_hint('/help') or '/help'} for shortcuts."
+                )
         except click.ClickException as exc:
             self.console.print(f"[{ERROR_STYLE}]{exc}[/]")
 
+    def _prompt_instruction_view_toggle(self, agent_id: str) -> None:
+        """Offer a prompt to expand or collapse the instruction preview after details."""
+        if not getattr(self.console, "is_terminal", False):
+            return
+
+        while True:
+            mode = "expanded" if self._instruction_preview_limit == 0 else "trimmed"
+            self.console.print(f"[dim]Instruction view is {mode}. Press Ctrl+T to toggle, Enter to continue.[/dim]")
+            try:
+                ch = click.getchar()
+            except (EOFError, KeyboardInterrupt):  # pragma: no cover - defensive guard
+                return
+
+            if not self._handle_instruction_toggle_input(agent_id, ch):
+                break
+
+        if self._instruction_preview_limit == 0:
+            self._instruction_preview_limit = DEFAULT_AGENT_INSTRUCTION_PREVIEW_LIMIT
+        self.console.print("")
+
+    def _handle_instruction_toggle_input(self, agent_id: str, ch: str) -> bool:
+        """Process a single toggle keypress; return False when the loop should exit."""
+        if ch in {"\r", "\n"}:
+            return False
+
+        lowered = ch.lower()
+        if lowered == "t" or ch == "\x14":  # support literal 't' or Ctrl+T
+            self._instruction_preview_limit = (
+                DEFAULT_AGENT_INSTRUCTION_PREVIEW_LIMIT if self._instruction_preview_limit == 0 else 0
+            )
+            self._show_details(agent_id, enable_prompt=False)
+            return True
+
+        # Ignore other keys and continue prompting.
+        return True
+
     def _after_agent_run(self) -> None:
         """Handle transcript viewer behaviour after a successful run."""
         payload, manifest = self.session._get_last_transcript()
@@ -206,21 +253,11 @@ class AgentRunSession:
     @contextmanager
     def _bind_session_context(self) -> Any:
         """Temporarily attach this slash session to the Click context."""
-        ctx_obj = getattr(self.session.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"] = self.session
-        try:
+        with bind_slash_session_context(self.session.ctx, self.session):
             yield
-        finally:
-            if has_context:
-                if previous_session is None:
-                    ctx_obj.pop("_slash_session", None)
-                else:
-                    ctx_obj["_slash_session"] = previous_session
 
     def _run_agent(self, agent_id: str, message: str) -> None:
+        """Execute the agents run command for the active agent."""
         if not message:
             return
 

glaip_sdk/cli/slash/prompt.py

@@ -123,6 +123,11 @@ def _create_key_bindings(_session: SlashSession) -> Any:
     bindings = KeyBindings()
 
     def _refresh_completions(buffer: Any) -> None:  # type: ignore[no-any-return]
+        """Refresh completions when slash command is typed.
+
+        Args:
+            buffer: Prompt buffer instance.
+        """
         text = buffer.document.text_before_cursor or ""
         if text.startswith("/") and " " not in text:
             buffer.start_completion(select_first=False)
@@ -172,8 +177,11 @@ def _iter_command_completions(
         return []
 
     commands = sorted(session._unique_commands.values(), key=lambda c: c.name)
+    agent_context = bool(getattr(session, "_current_agent", None))
 
     for cmd in commands:
+        if getattr(cmd, "agent_only", False) and not agent_context:
+            continue
         yield from _generate_command_completions(cmd, prefix, text, seen)