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

glaip_sdk/cli/slash/agent_session.py

@@ -14,6 +14,7 @@ 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
 
@@ -38,11 +39,12 @@ 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.",
             "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 +88,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 +125,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 +154,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()
@@ -221,6 +267,7 @@ class AgentRunSession:
                     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)

glaip_sdk/cli/slash/session.py

@@ -171,6 +171,7 @@ class SlashSession:
         self._render_header(initial=True)
 
     def _setup_prompt_toolkit(self) -> None:
+        """Initialize prompt_toolkit session and style."""
         session, style = setup_prompt_toolkit(self, interactive=self._interactive)
         self._ptk_session = session
         self._ptk_style = style
@@ -310,6 +311,15 @@ class SlashSession:
     # Command handlers
     # ------------------------------------------------------------------
     def _cmd_help(self, _args: list[str], invoked_from_agent: bool) -> bool:
+        """Handle the /help command.
+
+        Args:
+            _args: Command arguments (unused).
+            invoked_from_agent: Whether invoked from agent context.
+
+        Returns:
+            True to continue session.
+        """
         try:
             if invoked_from_agent:
                 self._render_agent_help()
@@ -322,11 +332,12 @@ class SlashSession:
         return True
 
     def _render_agent_help(self) -> None:
+        """Render help text for agent context commands."""
         table = AIPTable()
         table.add_column("Input", style=HINT_COMMAND_STYLE, no_wrap=True)
         table.add_column("What happens", style=HINT_DESCRIPTION_COLOR)
         table.add_row("<message>", "Run the active agent once with that prompt.")
-        table.add_row("/details", "Show the full agent export and metadata.")
+        table.add_row("/details", "Show the agent export (prompts to expand instructions).")
         table.add_row(self.STATUS_COMMAND, "Display connection status without leaving.")
         table.add_row("/export [path]", "Export the latest agent transcript as JSONL.")
         table.add_row("/exit (/back)", "Return to the slash home screen.")
@@ -350,6 +361,7 @@ class SlashSession:
         )
 
     def _render_global_help(self) -> None:
+        """Render help text for global slash commands."""
         table = AIPTable()
         table.add_column("Command", style=HINT_COMMAND_STYLE, no_wrap=True)
         table.add_column("Description", style=HINT_DESCRIPTION_COLOR)
@@ -376,6 +388,15 @@ class SlashSession:
         )
 
     def _cmd_login(self, _args: list[str], _invoked_from_agent: bool) -> bool:
+        """Handle the /login command.
+
+        Args:
+            _args: Command arguments (unused).
+            _invoked_from_agent: Whether invoked from agent context (unused).
+
+        Returns:
+            True to continue session.
+        """
         self.console.print(f"[{ACCENT_STYLE}]Launching configuration wizard...[/]")
         try:
             self.ctx.invoke(configure_command)
@@ -391,6 +412,15 @@ class SlashSession:
         return self._continue_session()
 
     def _cmd_status(self, _args: list[str], _invoked_from_agent: bool) -> bool:
+        """Handle the /status command.
+
+        Args:
+            _args: Command arguments (unused).
+            _invoked_from_agent: Whether invoked from agent context (unused).
+
+        Returns:
+            True to continue session.
+        """
         ctx_obj = self.ctx.obj if isinstance(self.ctx.obj, dict) else None
         previous_console = None
         try:
@@ -420,6 +450,15 @@ class SlashSession:
         return self._continue_session()
 
     def _cmd_transcripts(self, args: list[str], _invoked_from_agent: bool) -> bool:
+        """Handle the /transcripts command.
+
+        Args:
+            args: Command arguments (limit or detail/show with run_id).
+            _invoked_from_agent: Whether invoked from agent context (unused).
+
+        Returns:
+            True to continue session.
+        """
         if args and args[0].lower() in {"detail", "show"}:
             if len(args) < 2:
                 self.console.print(f"[{WARNING_STYLE}]Usage: /transcripts detail <run_id>[/]")
@@ -440,6 +479,14 @@ class SlashSession:
         return self._continue_session()
 
     def _parse_transcripts_limit(self, args: list[str]) -> tuple[int | None, bool]:
+        """Parse limit argument from transcripts command.
+
+        Args:
+            args: Command arguments.
+
+        Returns:
+            Tuple of (limit value or None, success boolean).
+        """
         if not args:
             return None, True
         try:
@@ -453,6 +500,15 @@ class SlashSession:
         return limit, True
 
     def _handle_transcripts_empty(self, snapshot: Any, limit: int | None) -> bool:
+        """Handle empty transcript snapshot cases.
+
+        Args:
+            snapshot: Transcript snapshot object.
+            limit: Limit value or None.
+
+        Returns:
+            True if empty case was handled, False otherwise.
+        """
         if snapshot.cached_entries == 0:
             self.console.print(f"[{WARNING_STYLE}]No cached transcripts yet. Run an agent first.[/]")
             for warning in snapshot.warnings:
@@ -464,6 +520,11 @@ class SlashSession:
         return False
 
     def _render_transcripts_snapshot(self, snapshot: Any) -> None:
+        """Render transcript snapshot table and metadata.
+
+        Args:
+            snapshot: Transcript snapshot object to render.
+        """
         size_text = format_size(snapshot.total_size_bytes)
         header = f"[dim]Manifest: {snapshot.manifest_path} · {snapshot.total_entries} runs · {size_text} used[/]"
         self.console.print(header)
@@ -529,6 +590,15 @@ class SlashSession:
         self.console.print(view, markup=False, highlight=False, soft_wrap=True, end="")
 
     def _cmd_agents(self, args: list[str], _invoked_from_agent: bool) -> bool:
+        """Handle the /agents command.
+
+        Args:
+            args: Command arguments (optional agent reference).
+            _invoked_from_agent: Whether invoked from agent context (unused).
+
+        Returns:
+            True to continue session.
+        """
         client = self._get_client_or_fail()
         if not client:
             return True
@@ -614,6 +684,15 @@ class SlashSession:
         self._show_quick_actions(hints, title="Next actions")
 
     def _cmd_exit(self, _args: list[str], invoked_from_agent: bool) -> bool:
+        """Handle the /exit command.
+
+        Args:
+            _args: Command arguments (unused).
+            invoked_from_agent: Whether invoked from agent context.
+
+        Returns:
+            False to exit session, True to continue.
+        """
         if invoked_from_agent:
             # Returning False would stop the full session; we only want to exit
             # the agent context. Raising a custom flag keeps the outer loop
@@ -627,6 +706,7 @@ class SlashSession:
     # Utilities
     # ------------------------------------------------------------------
     def _register_defaults(self) -> None:
+        """Register default slash commands."""
         self._register(
             SlashCommand(
                 name="help",
@@ -688,6 +768,11 @@ class SlashSession:
         )
 
     def _register(self, command: SlashCommand) -> None:
+        """Register a slash command.
+
+        Args:
+            command: SlashCommand to register.
+        """
         self._unique_commands[command.name] = command
         for key in (command.name, *command.aliases):
             self._commands[key] = command
@@ -716,6 +801,14 @@ class SlashSession:
         )
 
         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=run_id)
 
         try:
@@ -812,6 +905,14 @@ class SlashSession:
                 pass
 
     def _parse(self, raw: str) -> tuple[str, list[str]]:
+        """Parse a raw command string into verb and arguments.
+
+        Args:
+            raw: Raw command string.
+
+        Returns:
+            Tuple of (verb, args).
+        """
         try:
             tokens = shlex.split(raw)
         except ValueError:
@@ -827,6 +928,14 @@ class SlashSession:
         return head, tokens[1:]
 
     def _suggest(self, verb: str) -> str | None:
+        """Suggest a similar command name for an unknown verb.
+
+        Args:
+            verb: Unknown command verb.
+
+        Returns:
+            Suggested command name or None.
+        """
         keys = [cmd.name for cmd in self._unique_commands.values()]
         match = get_close_matches(verb, keys, n=1)
         return match[0] if match else None
@@ -855,6 +964,7 @@ class SlashSession:
             if callable(message):
 
                 def prompt_text() -> Any:
+                    """Get formatted prompt text from callable message."""
                     return self._convert_message(message())
             else:
                 prompt_text = self._convert_message(message)
@@ -900,6 +1010,11 @@ class SlashSession:
         return self._prompt_with_basic_input(message, placeholder)
 
     def _get_client(self) -> Any:  # type: ignore[no-any-return]
+        """Get or create the API client instance.
+
+        Returns:
+            API client instance.
+        """
         if self._client is None:
             self._client = get_client(self.ctx)
         return self._client
@@ -918,6 +1033,11 @@ class SlashSession:
         return self._contextual_include_global
 
     def _remember_agent(self, agent: Any) -> None:  # type: ignore[no-any-return]
+        """Remember an agent in recent agents list.
+
+        Args:
+            agent: Agent object to remember.
+        """
         agent_data = {
             "id": str(getattr(agent, "id", "")),
             "name": getattr(agent, "name", "") or "",
@@ -935,6 +1055,13 @@ class SlashSession:
         focus_agent: bool = False,
         initial: bool = False,
     ) -> None:
+        """Render the session header with branding and status.
+
+        Args:
+            active_agent: Optional active agent to display.
+            focus_agent: Whether to focus on agent display.
+            initial: Whether this is the initial render.
+        """
         if focus_agent and active_agent is not None:
             self._render_focused_agent_header(active_agent)
             return
@@ -1039,7 +1166,7 @@ class SlashSession:
 
         keybar.add_row(
             format_command_hint("/help", "Show commands") or "",
-            format_command_hint("/details", "Agent config") or "",
+            format_command_hint("/details", "Agent config (expand prompt)") or "",
             format_command_hint("/exit", "Back") or "",
         )
 
@@ -1098,6 +1225,7 @@ class SlashSession:
         return None
 
     def _show_default_quick_actions(self) -> None:
+        """Show default quick action hints for new and evergreen commands."""
         new_hints = self._collect_quick_action_hints(NEW_QUICK_ACTIONS, highlight_new=True)
         evergreen_hints = self._collect_quick_action_hints(DEFAULT_QUICK_ACTIONS)
         if new_hints or evergreen_hints:
@@ -1112,6 +1240,15 @@ class SlashSession:
         *,
         highlight_new: bool = False,
     ) -> list[tuple[str, str]]:
+        """Collect quick action hints from action definitions.
+
+        Args:
+            actions: Iterable of action dictionaries.
+            highlight_new: Whether to highlight new actions.
+
+        Returns:
+            List of (command, description) tuples.
+        """
         collected: list[tuple[str, str]] = []
         for action in sorted(actions, key=lambda payload: payload.get("priority", 0), reverse=True):
             hint = self._build_quick_action_hint(action, highlight_new=highlight_new)
@@ -1125,6 +1262,15 @@ class SlashSession:
         *,
         highlight_new: bool = False,
     ) -> tuple[str, str] | None:
+        """Build a quick action hint from an action definition.
+
+        Args:
+            action: Action dictionary.
+            highlight_new: Whether to highlight as new.
+
+        Returns:
+            Tuple of (command, description) or None.
+        """
         command = command_hint(action.get("cli"), slash_command=action.get("slash"), ctx=self.ctx)
         if not command:
             return None
@@ -1137,6 +1283,12 @@ class SlashSession:
         return command, description
 
     def _render_quick_action_group(self, hints: list[tuple[str, str]], title: str) -> None:
+        """Render a group of quick action hints.
+
+        Args:
+            hints: List of (command, description) tuples.
+            title: Group title.
+        """
         if not hints:
             return
         formatted_tokens: list[str] = []
@@ -1153,10 +1305,20 @@ class SlashSession:
             self.console.print("  " + "    ".join(chunk))
 
     def _chunk_tokens(self, tokens: list[str], *, size: int) -> Iterable[list[str]]:
+        """Chunk tokens into groups of specified size.
+
+        Args:
+            tokens: List of tokens to chunk.
+            size: Size of each chunk.
+
+        Yields:
+            Lists of tokens.
+        """
         for index in range(0, len(tokens), size):
             yield tokens[index : index + size]
 
     def _render_home_hint(self) -> None:
+        """Render hint text for home screen."""
         if self._home_hint_shown:
             return
         hint_text = (
@@ -1174,6 +1336,13 @@ class SlashSession:
         title: str = "Quick actions",
         inline: bool = False,
     ) -> None:
+        """Show quick action hints.
+
+        Args:
+            hints: Iterable of (command, description) tuples.
+            title: Title for the hints.
+            inline: Whether to render inline or in a panel.
+        """
         hint_list = self._normalize_quick_action_hints(hints)
         if not hint_list:
             return
@@ -1185,9 +1354,23 @@ class SlashSession:
         self._render_panel_quick_actions(hint_list, title)
 
     def _normalize_quick_action_hints(self, hints: Iterable[tuple[str, str]]) -> list[tuple[str, str]]:
+        """Normalize quick action hints by filtering out empty commands.
+
+        Args:
+            hints: Iterable of (command, description) tuples.
+
+        Returns:
+            List of normalized hints.
+        """
         return [(command, description) for command, description in hints if command]
 
     def _render_inline_quick_actions(self, hint_list: list[tuple[str, str]], title: str) -> None:
+        """Render quick actions inline.
+
+        Args:
+            hint_list: List of (command, description) tuples.
+            title: Title for the hints.
+        """
         tokens: list[str] = []
         for command, description in hint_list:
             formatted = format_command_hint(command, description)
@@ -1201,6 +1384,12 @@ class SlashSession:
         self.console.print(text.strip())
 
     def _render_panel_quick_actions(self, hint_list: list[tuple[str, str]], title: str) -> None:
+        """Render quick actions in a panel.
+
+        Args:
+            hint_list: List of (command, description) tuples.
+            title: Panel title.
+        """
         body_lines: list[Text] = []
         for command, description in hint_list:
             formatted = format_command_hint(command, description)
@@ -1212,6 +1401,11 @@ class SlashSession:
         self.console.print(AIPPanel(panel_content, title=title, border_style=SECONDARY_LIGHT, expand=False))
 
     def _load_config(self) -> dict[str, Any]:
+        """Load configuration with caching.
+
+        Returns:
+            Configuration dictionary.
+        """
         if self._config_cache is None:
             try:
                 self._config_cache = load_config() or {}
@@ -1220,6 +1414,16 @@ class SlashSession:
         return self._config_cache
 
     def _resolve_agent_from_ref(self, client: Any, available_agents: list[Any], ref: str) -> Any | None:
+        """Resolve an agent from a reference string.
+
+        Args:
+            client: API client instance.
+            available_agents: List of available agents.
+            ref: Reference string (ID or name).
+
+        Returns:
+            Resolved agent or None.
+        """
         ref = ref.strip()
         if not ref:
             return None