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

glaip_sdk/cli/slash/session.py

@@ -37,6 +37,7 @@ from glaip_sdk.cli.commands import transcripts as transcripts_cmd
 from glaip_sdk.cli.commands.configure import configure_command, load_config
 from glaip_sdk.cli.commands.update import update_command
 from glaip_sdk.cli.slash.agent_session import AgentRunSession
+from glaip_sdk.cli.slash.remote_runs_controller import RemoteRunsController
 from glaip_sdk.cli.slash.prompt import (
     FormattedText,
     PromptSession,
@@ -57,6 +58,7 @@ from glaip_sdk.cli.utils import (
     format_command_hint,
     format_size,
     get_client,
+    restore_slash_session_context,
 )
 from glaip_sdk.rich_components import AIPGrid, AIPPanel, AIPTable
 
@@ -71,6 +73,7 @@ class SlashCommand:
     help: str
     handler: SlashHandler
     aliases: tuple[str, ...] = ()
+    agent_only: bool = False
 
 
 NEW_QUICK_ACTIONS: tuple[dict[str, Any], ...] = (
@@ -80,6 +83,15 @@ NEW_QUICK_ACTIONS: tuple[dict[str, Any], ...] = (
         "description": "Review transcript cache",
         "tag": "NEW",
         "priority": 10,
+        "scope": "global",
+    },
+    {
+        "cli": None,
+        "slash": "runs",
+        "description": "View remote run history for the active agent",
+        "tag": "NEW",
+        "priority": 8,
+        "scope": "agent",
     },
 )
 
@@ -103,9 +115,26 @@ DEFAULT_QUICK_ACTIONS: tuple[dict[str, Any], ...] = (
         "description": "Show all commands",
         "priority": 0,
     },
+    {
+        "cli": "configure",
+        "slash": "login",
+        "description": f"Configure credentials (alias [{HINT_COMMAND_STYLE}]/configure[/])",
+        "priority": -1,
+    },
 )
 
 
+HELP_COMMAND = "/help"
+
+
+def _quick_action_scope(action: dict[str, Any]) -> str:
+    """Return the scope for a quick action definition."""
+    scope = action.get("scope") or "global"
+    if isinstance(scope, str):
+        return scope.lower()
+    return "global"
+
+
 class SlashSession:
     """Interactive command palette controller."""
 
@@ -131,6 +160,7 @@ class SlashSession:
         self._welcome_rendered = False
         self._active_renderer: Any | None = None
         self._current_agent: Any | None = None
+        self._runs_pagination_state: dict[str, dict[str, Any]] = {}  # agent_id -> {page, limit, cursor}
 
         self._home_placeholder = "Hint: type / to explore commands · Ctrl+D exits"
 
@@ -171,6 +201,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
@@ -198,10 +229,7 @@ class SlashSession:
             self._run_interactive_loop()
         finally:
             if ctx_obj is not None:
-                if previous_session is None:
-                    ctx_obj.pop("_slash_session", None)
-                else:
-                    ctx_obj["_slash_session"] = previous_session
+                restore_slash_session_context(ctx_obj, previous_session)
 
     def _run_interactive_loop(self) -> None:
         """Run the main interactive command loop."""
@@ -289,7 +317,7 @@ class SlashSession:
             if suggestion:
                 self.console.print(f"[{WARNING_STYLE}]Unknown command '{verb}'. Did you mean '/{suggestion}'?[/]")
             else:
-                help_command = "/help"
+                help_command = HELP_COMMAND
                 help_hint = format_command_hint(help_command) or help_command
                 self.console.print(
                     f"[{WARNING_STYLE}]Unknown command '{verb}'. Type {help_hint} for a list of options.[/]"
@@ -310,11 +338,20 @@ 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()
             else:
-                self._render_global_help()
+                self._render_global_help(include_agent_hint=True)
         except Exception as exc:  # pragma: no cover - UI/display errors
             self.console.print(f"[{ERROR_STYLE}]Error displaying help: {exc}[/]")
             return False
@@ -322,15 +359,17 @@ 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("/runs", "✨ NEW · Open the remote run browser for this agent.")
         table.add_row("/export [path]", "Export the latest agent transcript as JSONL.")
         table.add_row("/exit (/back)", "Return to the slash home screen.")
-        table.add_row("/help (/?)", "Display this context-aware menu.")
+        table.add_row(f"{HELP_COMMAND} (/?)", "Display this context-aware menu.")
 
         panel_items = [table]
         if self.last_run_input:
@@ -348,13 +387,28 @@ class SlashSession:
                 border_style=PRIMARY,
             )
         )
+        new_commands_table = AIPTable()
+        new_commands_table.add_column("Command", style=HINT_COMMAND_STYLE, no_wrap=True)
+        new_commands_table.add_column("Description", style=HINT_DESCRIPTION_COLOR)
+        new_commands_table.add_row(
+            "/runs",
+            "✨ NEW · View remote run history with keyboard navigation and export options.",
+        )
+        self.console.print(
+            AIPPanel(
+                new_commands_table,
+                title="New commands",
+                border_style=SECONDARY_LIGHT,
+            )
+        )
 
-    def _render_global_help(self) -> None:
+    def _render_global_help(self, *, include_agent_hint: bool = False) -> 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)
 
-        for cmd in sorted(self._unique_commands.values(), key=lambda c: c.name):
+        for cmd in self._visible_commands(include_agent_only=False):
             aliases = ", ".join(f"/{alias}" for alias in cmd.aliases if alias)
             verb = f"/{cmd.name}"
             if aliases:
@@ -374,8 +428,22 @@ class SlashSession:
                 border_style=PRIMARY,
             )
         )
+        if include_agent_hint:
+            self.console.print(
+                "[dim]Additional commands (e.g. `/runs`) become available after you pick an agent with `/agents`. "
+                "Those agent-only commands stay hidden here to avoid confusion.[/]"
+            )
 
     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 +459,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 +497,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 +526,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 +547,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 +567,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)
@@ -528,7 +636,29 @@ class SlashSession:
         view = transcripts_cmd._render_transcript_display(entry, snapshot.manifest_path, transcript_path, meta, events)
         self.console.print(view, markup=False, highlight=False, soft_wrap=True, end="")
 
+    def _cmd_runs(self, args: list[str], _invoked_from_agent: bool) -> bool:
+        """Handle the /runs command for browsing remote agent run history.
+
+        Args:
+            args: Command arguments (optional run_id for detail view).
+            _invoked_from_agent: Whether invoked from agent context.
+
+        Returns:
+            True to continue session.
+        """
+        controller = RemoteRunsController(self)
+        return controller.handle_runs_command(args)
+
     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 +744,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 +766,7 @@ class SlashSession:
     # Utilities
     # ------------------------------------------------------------------
     def _register_defaults(self) -> None:
+        """Register default slash commands."""
         self._register(
             SlashCommand(
                 name="help",
@@ -638,7 +778,7 @@ class SlashSession:
         self._register(
             SlashCommand(
                 name="login",
-                help="Run `/login` (alias `/configure`) to set credentials.",
+                help="Configure API credentials (alias `/configure`).",
                 handler=SlashSession._cmd_login,
                 aliases=("configure",),
             )
@@ -653,7 +793,10 @@ class SlashSession:
         self._register(
             SlashCommand(
                 name="transcripts",
-                help="Review cached transcript history. Add a number (e.g. `/transcripts 5`) to change the row limit.",
+                help=(
+                    "✨ NEW · Review cached transcript history. "
+                    "Add a number (e.g. `/transcripts 5`) to change the row limit."
+                ),
                 handler=SlashSession._cmd_transcripts,
             )
         )
@@ -686,12 +829,32 @@ class SlashSession:
                 handler=SlashSession._cmd_update,
             )
         )
+        self._register(
+            SlashCommand(
+                name="runs",
+                help="✨ NEW · Browse remote agent run history (requires active agent session).",
+                handler=SlashSession._cmd_runs,
+                agent_only=True,
+            )
+        )
 
     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
 
+    def _visible_commands(self, *, include_agent_only: bool) -> list[SlashCommand]:
+        """Return the list of commands that should be shown in global listings."""
+        commands = sorted(self._unique_commands.values(), key=lambda c: c.name)
+        if include_agent_only:
+            return commands
+        return [cmd for cmd in commands if not cmd.agent_only]
+
     def open_transcript_viewer(self, *, announce: bool = True) -> None:
         """Launch the transcript viewer for the most recent run."""
         payload, manifest = self._get_last_transcript()
@@ -716,6 +879,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 +983,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 +1006,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 +1042,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 +1088,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 +1111,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 +1133,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
@@ -977,8 +1182,9 @@ class SlashSession:
 
         header_grid = self._build_header_grid(agent_info, transcript_status)
         keybar = self._build_keybar()
-
         header_grid.add_row(keybar, "")
+
+        # Agent-scoped commands like /runs will appear in /help, no need to duplicate here
         self.console.print(AIPPanel(header_grid, title="Agent Session", border_style=PRIMARY))
 
     def _get_agent_info(self, active_agent: Any) -> dict[str, str]:
@@ -1036,10 +1242,11 @@ class SlashSession:
         keybar = AIPGrid(expand=True)
         keybar.add_column(justify="left", ratio=1)
         keybar.add_column(justify="left", ratio=1)
+        keybar.add_column(justify="left", ratio=1)
 
         keybar.add_row(
-            format_command_hint("/help", "Show commands") or "",
-            format_command_hint("/details", "Agent config") or "",
+            format_command_hint(HELP_COMMAND, "Show commands") or "",
+            format_command_hint("/details", "Agent config (expand prompt)") or "",
             format_command_hint("/exit", "Back") or "",
         )
 
@@ -1098,23 +1305,39 @@ class SlashSession:
         return None
 
     def _show_default_quick_actions(self) -> None:
-        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:
-            self.console.print(f"[dim]{'─' * 40}[/]")
-        self._render_quick_action_group(new_hints, "New commands")
-        self._render_quick_action_group(evergreen_hints, "Quick actions")
+        """Show simplified help hint to discover commands."""
+        self.console.print(f"[dim]{'─' * 40}[/]")
+        help_hint = format_command_hint(HELP_COMMAND, "Show all commands") or HELP_COMMAND
+        self.console.print(f"• {help_hint}")
         self._default_actions_shown = True
 
+    def _collect_scoped_new_action_hints(self, scope: str) -> list[tuple[str, str]]:
+        """Return new quick action hints filtered by scope."""
+        scoped_actions = [action for action in NEW_QUICK_ACTIONS if _quick_action_scope(action) == scope]
+        # Don't highlight with sparkle emoji in quick actions display - it will show in command palette instead
+        return self._collect_quick_action_hints(scoped_actions)
+
     def _collect_quick_action_hints(
         self,
         actions: Iterable[dict[str, Any]],
-        *,
-        highlight_new: bool = False,
     ) -> list[tuple[str, str]]:
+        """Collect quick action hints from action definitions.
+
+        Args:
+            actions: Iterable of action dictionaries.
+
+        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)
+
+        def sort_key(payload: dict[str, Any]) -> tuple[int, str]:
+            priority = int(payload.get("priority", 0))
+            label = str(payload.get("slash") or payload.get("cli") or "")
+            return (-priority, label.lower())
+
+        for action in sorted(actions, key=sort_key):
+            hint = self._build_quick_action_hint(action)
             if hint:
                 collected.append(hint)
         return collected
@@ -1122,41 +1345,48 @@ class SlashSession:
     def _build_quick_action_hint(
         self,
         action: dict[str, Any],
-        *,
-        highlight_new: bool = False,
     ) -> tuple[str, str] | None:
+        """Build a quick action hint from an action definition.
+
+        Args:
+            action: Action dictionary.
+
+        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
         description = action.get("description", "")
-        tag = action.get("tag")
-        if tag:
-            description = f"[{ACCENT_STYLE}]{tag}[/] · {description}"
-        if highlight_new:
-            description = f"✨ {description}"
+        # Don't include tag or sparkle emoji in quick actions display
+        # The NEW tag will only show in the command dropdown (help text)
         return command, description
 
     def _render_quick_action_group(self, hints: list[tuple[str, str]], title: str) -> None:
-        if not hints:
-            return
-        formatted_tokens: list[str] = []
-        for command, description in hints:
-            formatted = format_command_hint(command, description)
-            if formatted:
-                formatted_tokens.append(f"• {formatted}")
-        if not formatted_tokens:
-            return
-        header = f"[dim]{title}[/dim] · {formatted_tokens[0]}"
-        self.console.print(header)
-        remaining = formatted_tokens[1:]
-        for chunk in self._chunk_tokens(remaining, size=3):
-            self.console.print("  " + "    ".join(chunk))
+        """Render a group of quick action hints.
+
+        Args:
+            hints: List of (command, description) tuples.
+            title: Group title.
+        """
+        for line in self._format_quick_action_lines(hints, title):
+            self.console.print(line)
 
     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 +1404,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 +1422,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 +1452,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)
@@ -1211,7 +1468,35 @@ class SlashSession:
         panel_content = Group(*body_lines)
         self.console.print(AIPPanel(panel_content, title=title, border_style=SECONDARY_LIGHT, expand=False))
 
+    def _format_quick_action_lines(self, hints: list[tuple[str, str]], title: str) -> list[str]:
+        """Return formatted lines for quick action hints."""
+        if not hints:
+            return []
+        formatted_tokens: list[str] = []
+        for command, description in hints:
+            formatted = format_command_hint(command, description)
+            if formatted:
+                formatted_tokens.append(f"• {formatted}")
+        if not formatted_tokens:
+            return []
+        lines: list[str] = []
+        # Use vertical layout (1 per line) for better readability
+        chunks = list(self._chunk_tokens(formatted_tokens, size=1))
+        prefix = f"[dim]{title}[/dim]\n  " if title else ""
+        for idx, chunk in enumerate(chunks):
+            row = "    ".join(chunk)
+            if idx == 0:
+                lines.append(f"{prefix}{row}" if prefix else row)
+            else:
+                lines.append(f"  {row}")
+        return lines
+
     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 +1505,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