glaip-sdk 0.1.0__py3-none-any.whl → 0.6.10__py3-none-any.whl

glaip_sdk/cli/slash/session.py

@@ -33,9 +33,15 @@ from glaip_sdk.branding import (
     WARNING_STYLE,
     AIPBranding,
 )
-from glaip_sdk.cli.commands.configure import configure_command, load_config
+from glaip_sdk.cli.auth import resolve_api_url_from_context
+from glaip_sdk.cli.account_store import get_account_store
+from glaip_sdk.cli.commands import transcripts as transcripts_cmd
+from glaip_sdk.cli.commands.configure import _configure_interactive, load_config
 from glaip_sdk.cli.commands.update import update_command
+from glaip_sdk.cli.hints import format_command_hint
+from glaip_sdk.cli.slash.accounts_controller import AccountsController
 from glaip_sdk.cli.slash.agent_session import AgentRunSession
+from glaip_sdk.cli.slash.accounts_shared import env_credentials_present
 from glaip_sdk.cli.slash.prompt import (
     FormattedText,
     PromptSession,
@@ -44,19 +50,19 @@ from glaip_sdk.cli.slash.prompt import (
     setup_prompt_toolkit,
     to_formatted_text,
 )
+from glaip_sdk.cli.slash.remote_runs_controller import RemoteRunsController
 from glaip_sdk.cli.transcript import (
     export_cached_transcript,
-    normalise_export_destination,
-    resolve_manifest_for_export,
-    suggest_filename,
+    load_history_snapshot,
 )
 from glaip_sdk.cli.transcript.viewer import ViewerContext, run_viewer_session
 from glaip_sdk.cli.update_notifier import maybe_notify_update
 from glaip_sdk.cli.utils import (
     _fuzzy_pick_for_resources,
     command_hint,
-    format_command_hint,
+    format_size,
     get_client,
+    restore_slash_session_context,
 )
 from glaip_sdk.rich_components import AIPGrid, AIPPanel, AIPTable
 
@@ -71,6 +77,72 @@ class SlashCommand:
     help: str
     handler: SlashHandler
     aliases: tuple[str, ...] = ()
+    agent_only: bool = False
+
+
+NEW_QUICK_ACTIONS: tuple[dict[str, Any], ...] = (
+    {
+        "cli": "transcripts",
+        "slash": "transcripts",
+        "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",
+    },
+)
+
+
+DEFAULT_QUICK_ACTIONS: tuple[dict[str, Any], ...] = (
+    {
+        "cli": None,
+        "slash": "accounts",
+        "description": "Switch account profile",
+        "priority": 5,
+    },
+    {
+        "cli": "status",
+        "slash": "status",
+        "description": "Connection check",
+        "priority": 0,
+    },
+    {
+        "cli": "agents list",
+        "slash": "agents",
+        "description": "Browse agents",
+        "priority": 0,
+    },
+    {
+        "cli": "help",
+        "slash": "help",
+        "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:
@@ -98,8 +170,9 @@ 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 = "Start with / to browse commands"
+        self._home_placeholder = "Hint: type / to explore commands · Ctrl+D exits"
 
         # Command string constants to avoid duplication
         self.STATUS_COMMAND = "/status"
@@ -120,8 +193,25 @@ class SlashSession:
     # ------------------------------------------------------------------
     # Session orchestration
     # ------------------------------------------------------------------
+    def refresh_branding(
+        self,
+        sdk_version: str | None = None,
+        *,
+        branding_cls: type[AIPBranding] | None = None,
+    ) -> None:
+        """Refresh branding assets after an in-session SDK upgrade."""
+        branding_type = branding_cls or AIPBranding
+        self._branding = branding_type.create_from_sdk(
+            sdk_version=sdk_version,
+            package_name="glaip-sdk",
+        )
+        self._welcome_rendered = False
+        self.console.print()
+        self.console.print(f"[{SUCCESS_STYLE}]CLI updated to {self._branding.version}. Refreshing banner...[/]")
+        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
@@ -149,10 +239,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."""
@@ -181,16 +268,12 @@ class SlashSession:
             return True
 
         if not raw.startswith("/"):
-            self.console.print(
-                f"[{INFO_STYLE}]Hint:[/] start commands with `/`. Try `/agents` to select an agent."
-            )
+            self.console.print(f"[{INFO_STYLE}]Hint:[/] start commands with `/`. Try `/agents` to select an agent.")
             return True
 
         return self.handle_command(raw)
 
-    def _run_non_interactive(
-        self, initial_commands: Iterable[str] | None = None
-    ) -> None:
+    def _run_non_interactive(self, initial_commands: Iterable[str] | None = None) -> None:
         """Run slash commands in non-interactive mode."""
         commands = list(initial_commands or [])
         if not commands:
@@ -202,38 +285,124 @@ class SlashSession:
             if not self.handle_command(raw):
                 break
 
+    def _handle_account_selection(self) -> bool:
+        """Handle account selection when accounts exist but none are active.
+
+        Returns:
+            True if configuration is ready after selection, False if user aborted.
+        """
+        self.console.print(f"[{INFO_STYLE}]No active account selected. Please choose an account:[/]")
+        try:
+            self._cmd_accounts([], False)
+            self._config_cache = None
+            return self._check_configuration_after_selection()
+        except KeyboardInterrupt:
+            self.console.print(f"[{ERROR_STYLE}]Account selection aborted. Closing the command palette.[/]")
+            return False
+
+    def _check_configuration_after_selection(self) -> bool:
+        """Check if configuration is ready after account selection.
+
+        Returns:
+            True if configuration is ready, False otherwise.
+        """
+        return self._configuration_ready()
+
+    def _handle_new_account_creation(self) -> bool:
+        """Handle new account creation when no accounts exist.
+
+        Returns:
+            True if configuration succeeded, False if user aborted.
+        """
+        previous_tip_env = os.environ.get("AIP_SUPPRESS_CONFIGURE_TIP")
+        os.environ["AIP_SUPPRESS_CONFIGURE_TIP"] = "1"
+        self._suppress_login_layout = True
+        try:
+            self._cmd_login([], False)
+            return True
+        except KeyboardInterrupt:
+            self.console.print(f"[{ERROR_STYLE}]Configuration aborted. Closing the command palette.[/]")
+            return False
+        finally:
+            self._suppress_login_layout = False
+            if previous_tip_env is None:
+                os.environ.pop("AIP_SUPPRESS_CONFIGURE_TIP", None)
+            else:
+                os.environ["AIP_SUPPRESS_CONFIGURE_TIP"] = previous_tip_env
+
     def _ensure_configuration(self) -> bool:
         """Ensure the CLI has both API URL and credentials before continuing."""
         while not self._configuration_ready():
-            self.console.print(
-                f"[{WARNING_STYLE}]Configuration required.[/] Launching `/login` wizard..."
-            )
-            self._suppress_login_layout = True
-            try:
-                self._cmd_login([], False)
-            except KeyboardInterrupt:
-                self.console.print(
-                    f"[{ERROR_STYLE}]Configuration aborted. Closing the command palette.[/]"
-                )
+            store = get_account_store()
+            accounts = store.list_accounts()
+            active_account = store.get_active_account()
+
+            # If accounts exist but none are active, show accounts list first
+            if accounts and (not active_account or active_account not in accounts):
+                if not self._handle_account_selection():
+                    return False
+                continue
+
+            # No accounts exist - prompt for configuration
+            if not self._handle_new_account_creation():
                 return False
-            finally:
-                self._suppress_login_layout = False
 
         return True
 
+    def _get_credentials_from_context_and_env(self) -> tuple[str, str]:
+        """Get credentials from context and environment variables.
+
+        Returns:
+            Tuple of (api_url, api_key) from context/env overrides.
+        """
+        api_url = ""
+        api_key = ""
+        if isinstance(self.ctx.obj, dict):
+            api_url = self.ctx.obj.get("api_url", "")
+            api_key = self.ctx.obj.get("api_key", "")
+        # Environment variables take precedence
+        env_url = os.getenv("AIP_API_URL", "")
+        env_key = os.getenv("AIP_API_KEY", "")
+        return (env_url or api_url, env_key or api_key)
+
+    def _get_credentials_from_account_store(self) -> tuple[str, str] | None:
+        """Get credentials from the active account in account store.
+
+        Returns:
+            Tuple of (api_url, api_key) if active account exists, None otherwise.
+        """
+        store = get_account_store()
+        active_account = store.get_active_account()
+        if not active_account:
+            return None
+
+        account = store.get_account(active_account)
+        if not account:
+            return None
+
+        api_url = account.get("api_url", "")
+        api_key = account.get("api_key", "")
+        return (api_url, api_key)
+
     def _configuration_ready(self) -> bool:
         """Check whether API URL and credentials are available."""
-        config = self._load_config()
-        api_url = self._get_api_url(config)
-        if not api_url:
+        # Check for explicit overrides in context/env first
+        override_url, override_key = self._get_credentials_from_context_and_env()
+        if override_url and override_key:
+            return True
+
+        # Read from account store directly to avoid stale cache
+        account_creds = self._get_credentials_from_account_store()
+        if account_creds is None:
             return False
 
-        api_key: str | None = None
-        if isinstance(self.ctx.obj, dict):
-            api_key = self.ctx.obj.get("api_key")
+        store_url, store_key = account_creds
 
-        api_key = api_key or config.get("api_key") or os.getenv("AIP_API_KEY")
-        return bool(api_key)
+        # Use override values if available, otherwise use store values
+        api_url = override_url or store_url
+        api_key = override_key or store_key
+
+        return bool(api_url and api_key)
 
     def handle_command(self, raw: str, *, invoked_from_agent: bool = False) -> bool:
         """Parse and execute a single slash command string."""
@@ -246,11 +415,9 @@ class SlashSession:
         if command is None:
             suggestion = self._suggest(verb)
             if suggestion:
-                self.console.print(
-                    f"[{WARNING_STYLE}]Unknown command '{verb}'. Did you mean '/{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.[/]"
@@ -263,15 +430,28 @@ class SlashSession:
             return False
         return True
 
+    def _continue_session(self) -> bool:
+        """Signal that the slash session should remain active."""
+        return not self._should_exit
+
     # ------------------------------------------------------------------
     # 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
@@ -279,21 +459,21 @@ 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:
-            panel_items.append(
-                Text.from_markup(f"[dim]Last run input:[/] {self.last_run_input}")
-            )
+            panel_items.append(Text.from_markup(f"[dim]Last run input:[/] {self.last_run_input}"))
         panel_items.append(
             Text.from_markup(
                 "[dim]Global commands (e.g. `/login`, `/status`) remain available inside the agent prompt.[/dim]"
@@ -307,13 +487,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:
@@ -321,7 +516,9 @@ class SlashSession:
             table.add_row(verb, cmd.help)
 
         tip = Text.from_markup(
-            f"[{HINT_PREFIX_STYLE}]Tip:[/] {format_command_hint(self.AGENTS_COMMAND) or self.AGENTS_COMMAND} lets you jump into an agent run prompt quickly."
+            f"[{HINT_PREFIX_STYLE}]Tip:[/] "
+            f"{format_command_hint(self.AGENTS_COMMAND) or self.AGENTS_COMMAND} "
+            "lets you jump into an agent run prompt quickly."
         )
 
         self.console.print(
@@ -331,12 +528,27 @@ 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)
-            self._config_cache = None
+            # Use the modern account-aware wizard directly (bypasses legacy config gating)
+            _configure_interactive(account_name=None)
+            self.on_account_switched()
             if self._suppress_login_layout:
                 self._welcome_rendered = False
                 self._default_actions_shown = False
@@ -345,14 +557,23 @@ class SlashSession:
                 self._show_default_quick_actions()
         except click.ClickException as exc:
             self.console.print(f"[{ERROR_STYLE}]{exc}[/]")
-        return True
+        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:
             status_module = importlib.import_module("glaip_sdk.cli.main")
-            status_command = getattr(status_module, "status")
+            status_command = status_module.status
 
             if ctx_obj is not None:
                 previous_console = ctx_obj.get("_slash_console")
@@ -360,9 +581,7 @@ class SlashSession:
 
             self.ctx.invoke(status_command)
 
-            hints: list[tuple[str, str]] = [
-                (self.AGENTS_COMMAND, "Browse agents and run them")
-            ]
+            hints: list[tuple[str, str]] = [(self.AGENTS_COMMAND, "Browse agents and run them")]
             if self.recent_agents:
                 top = self.recent_agents[0]
                 label = top.get("name") or top.get("id")
@@ -376,9 +595,176 @@ class SlashSession:
                     ctx_obj.pop("_slash_console", None)
                 else:
                     ctx_obj["_slash_console"] = previous_console
-        return True
+        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>[/]")
+                return self._continue_session()
+            self._show_transcript_detail(args[1])
+            return self._continue_session()
+
+        limit, ok = self._parse_transcripts_limit(args)
+        if not ok:
+            return self._continue_session()
+
+        snapshot = load_history_snapshot(limit=limit, ctx=self.ctx)
+
+        if self._handle_transcripts_empty(snapshot, limit):
+            return self._continue_session()
+
+        self._render_transcripts_snapshot(snapshot)
+        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:
+            limit = int(args[0])
+        except ValueError:
+            self.console.print(f"[{WARNING_STYLE}]Usage: /transcripts [limit][/]")
+            return None, False
+        if limit < 0:
+            self.console.print(f"[{WARNING_STYLE}]Usage: /transcripts [limit][/]")
+            return None, False
+        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:
+                self.console.print(f"[{WARNING_STYLE}]{warning}[/]")
+            return True
+        if limit == 0 and snapshot.cached_entries:
+            self.console.print(f"[{WARNING_STYLE}]Limit is 0; nothing to display.[/]")
+            return True
+        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)
+
+        if snapshot.limit_clamped:
+            self.console.print(
+                f"[{WARNING_STYLE}]Requested limit exceeded maximum; showing first {snapshot.limit_applied} runs.[/]"
+            )
+
+        if snapshot.total_entries > len(snapshot.entries):
+            subset_message = (
+                f"[dim]Showing {len(snapshot.entries)} of {snapshot.total_entries} "
+                f"runs (limit={snapshot.limit_applied}).[/]"
+            )
+            self.console.print(subset_message)
+            self.console.print("[dim]Hint: run `/transcripts <limit>` to change how many rows are displayed.[/]")
+
+        if snapshot.migration_summary:
+            self.console.print(f"[{INFO_STYLE}]{snapshot.migration_summary}[/]")
+
+        for warning in snapshot.warnings:
+            self.console.print(f"[{WARNING_STYLE}]{warning}[/]")
+
+        table = transcripts_cmd._build_table(snapshot.entries)
+        self.console.print(table)
+        self.console.print("[dim]! Missing transcript[/]")
+
+    def _show_transcript_detail(self, run_id: str) -> None:
+        """Render the cached transcript log for a single run."""
+        snapshot = load_history_snapshot(ctx=self.ctx)
+        entry = snapshot.index.get(run_id)
+        if entry is None:
+            self.console.print(f"[{WARNING_STYLE}]Run id {run_id} was not found in the cache manifest.[/]")
+            return
+
+        try:
+            transcript_path, transcript_text = transcripts_cmd._load_transcript_text(entry)
+        except click.ClickException as exc:
+            self.console.print(f"[{WARNING_STYLE}]{exc}[/]")
+            return
+
+        meta, events = transcripts_cmd._decode_transcript(transcript_text)
+        if transcripts_cmd._maybe_launch_transcript_viewer(
+            self.ctx,
+            entry,
+            meta,
+            events,
+            console_override=self.console,
+            force=True,
+            initial_view="transcript",
+        ):
+            if snapshot.migration_summary:
+                self.console.print(f"[{INFO_STYLE}]{snapshot.migration_summary}[/]")
+            for warning in snapshot.warnings:
+                self.console.print(f"[{WARNING_STYLE}]{warning}[/]")
+            return
+
+        if snapshot.migration_summary:
+            self.console.print(f"[{INFO_STYLE}]{snapshot.migration_summary}[/]")
+        for warning in snapshot.warnings:
+            self.console.print(f"[{WARNING_STYLE}]{warning}[/]")
+        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_accounts(self, args: list[str], _invoked_from_agent: bool) -> bool:
+        """Handle the /accounts command for listing and switching accounts."""
+        controller = AccountsController(self)
+        return controller.handle_accounts_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
@@ -417,9 +803,7 @@ class SlashSession:
         """Handle case when no agents are available."""
         hint = command_hint("agents create", slash_command=None, ctx=self.ctx)
         if hint:
-            self.console.print(
-                f"[{WARNING_STYLE}]No agents available. Use `{hint}` to add one.[/]"
-            )
+            self.console.print(f"[{WARNING_STYLE}]No agents available. Use `{hint}` to add one.[/]")
         else:
             self.console.print(f"[{WARNING_STYLE}]No agents available.[/]")
 
@@ -446,7 +830,7 @@ class SlashSession:
         self._render_header()
 
         self._show_agent_followup_actions(picked_agent)
-        return True
+        return self._continue_session()
 
     def _show_agent_followup_actions(self, picked_agent: Any) -> None:
         """Show follow-up action hints after agent session."""
@@ -458,6 +842,7 @@ class SlashSession:
             hints.append((f"/agents {agent_id}", f"Reopen {agent_label}"))
         hints.extend(
             [
+                ("/accounts", "Switch account"),
                 (self.AGENTS_COMMAND, "Browse agents"),
                 (self.STATUS_COMMAND, "Check connection"),
             ]
@@ -466,6 +851,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
@@ -479,6 +873,7 @@ class SlashSession:
     # Utilities
     # ------------------------------------------------------------------
     def _register_defaults(self) -> None:
+        """Register default slash commands."""
         self._register(
             SlashCommand(
                 name="help",
@@ -490,7 +885,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",),
             )
@@ -502,6 +897,23 @@ class SlashSession:
                 handler=SlashSession._cmd_status,
             )
         )
+        self._register(
+            SlashCommand(
+                name="accounts",
+                help="✨ NEW · Browse and switch stored accounts (Textual with Rich fallback).",
+                handler=SlashSession._cmd_accounts,
+            )
+        )
+        self._register(
+            SlashCommand(
+                name="transcripts",
+                help=(
+                    "✨ NEW · Review cached transcript history. "
+                    "Add a number (e.g. `/transcripts 5`) to change the row limit."
+                ),
+                handler=SlashSession._cmd_transcripts,
+            )
+        )
         self._register(
             SlashCommand(
                 name="agents",
@@ -531,28 +943,44 @@ 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()
         if payload is None or manifest is None:
             if announce:
-                self.console.print(
-                    f"[{WARNING_STYLE}]No transcript is available yet. Run an agent first.[/]"
-                )
+                self.console.print(f"[{WARNING_STYLE}]No transcript is available yet. Run an agent first.[/]")
             return
 
         run_id = manifest.get("run_id")
         if not run_id:
             if announce:
-                self.console.print(
-                    f"[{WARNING_STYLE}]Latest transcript is missing run metadata.[/]"
-                )
+                self.console.print(f"[{WARNING_STYLE}]Latest transcript is missing run metadata.[/]")
             return
 
         viewer_ctx = ViewerContext(
@@ -565,15 +993,21 @@ 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:
             run_viewer_session(self.console, viewer_ctx, _export)
         except Exception as exc:  # pragma: no cover - interactive failures
             if announce:
-                self.console.print(
-                    f"[{ERROR_STYLE}]Failed to launch transcript viewer: {exc}[/]"
-                )
+                self.console.print(f"[{ERROR_STYLE}]Failed to launch transcript viewer: {exc}[/]")
 
     def _get_last_transcript(self) -> tuple[Any | None, dict[str, Any] | None]:
         """Fetch the most recently stored transcript payload and manifest."""
@@ -584,65 +1018,18 @@ class SlashSession:
         manifest = ctx_obj.get("_last_transcript_manifest")
         return payload, manifest
 
-    def _cmd_export(self, args: list[str], _invoked_from_agent: bool) -> bool:
+    def _cmd_export(self, _args: list[str], _invoked_from_agent: bool) -> bool:
         """Slash handler for `/export` command."""
-        path_arg = args[0] if args else None
-        run_id = args[1] if len(args) > 1 else None
-
-        manifest_entry = resolve_manifest_for_export(self.ctx, run_id)
-        if manifest_entry is None:
-            if run_id:
-                self.console.print(
-                    f"[{WARNING_STYLE}]No cached transcript found with run id {run_id!r}. Omit the run id to export the most recent run.[/]"
-                )
-            else:
-                self.console.print(
-                    f"[{WARNING_STYLE}]No cached transcripts available yet. Run an agent first.[/]"
-                )
-            return False
-
-        destination = self._resolve_export_destination(path_arg, manifest_entry)
-        if destination is None:
-            return False
-
-        try:
-            exported = export_cached_transcript(
-                destination=destination,
-                run_id=manifest_entry.get("run_id"),
-            )
-        except FileNotFoundError as exc:
-            self.console.print(f"[{ERROR_STYLE}]{exc}[/]")
-            return False
-        except Exception as exc:  # pragma: no cover - unexpected IO failures
-            self.console.print(f"[{ERROR_STYLE}]Failed to export transcript: {exc}[/]")
-            return False
-        else:
-            self.console.print(f"[{SUCCESS_STYLE}]Transcript exported to[/] {exported}")
-            return True
-
-    def _resolve_export_destination(
-        self, path_arg: str | None, manifest_entry: dict[str, Any]
-    ) -> Path | None:
-        if path_arg:
-            return normalise_export_destination(Path(path_arg))
-
-        default_name = suggest_filename(manifest_entry)
-        prompt = f"Save transcript to [{default_name}]: "
-        try:
-            response = self.console.input(prompt)
-        except EOFError:
-            self.console.print("[dim]Export cancelled.[/dim]")
-            return None
-
-        chosen = response.strip() or default_name
-        return normalise_export_destination(Path(chosen))
+        self.console.print(
+            f"[{WARNING_STYLE}]`/export` is deprecated. Use `/transcripts`, select a run, "
+            "and open the transcript viewer to export.[/]"
+        )
+        return True
 
     def _cmd_update(self, args: list[str], _invoked_from_agent: bool) -> bool:
         """Slash handler for `/update` command."""
         if args:
-            self.console.print(
-                "Usage: `/update` upgrades glaip-sdk to the latest published version."
-            )
+            self.console.print("Usage: `/update` upgrades glaip-sdk to the latest published version.")
             return True
 
         try:
@@ -710,6 +1097,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:
@@ -725,6 +1120,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
@@ -742,21 +1145,18 @@ class SlashSession:
         prompt_kwargs: dict[str, Any] = {"style": self._ptk_style}
         if placeholder:
             placeholder_text = (
-                FormattedText([("class:placeholder", placeholder)])
-                if FormattedText is not None
-                else placeholder
+                FormattedText([("class:placeholder", placeholder)]) if FormattedText is not None else placeholder
             )
             prompt_kwargs["placeholder"] = placeholder_text
         return prompt_kwargs
 
-    def _prompt_with_prompt_toolkit(
-        self, message: str | Callable[[], Any], placeholder: str | None
-    ) -> str:
+    def _prompt_with_prompt_toolkit(self, message: str | Callable[[], Any], placeholder: str | None) -> str:
         """Handle prompting with prompt_toolkit."""
         with patch_stdout():  # pragma: no cover - UI specific
             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)
@@ -765,9 +1165,7 @@ class SlashSession:
 
             try:
                 return self._ptk_session.prompt(prompt_text, **prompt_kwargs)
-            except (
-                TypeError
-            ):  # pragma: no cover - compatibility with older prompt_toolkit
+            except TypeError:  # pragma: no cover - compatibility with older prompt_toolkit
                 prompt_kwargs.pop("placeholder", None)
                 return self._ptk_session.prompt(prompt_text, **prompt_kwargs)
 
@@ -786,9 +1184,7 @@ class SlashSession:
         except Exception:
             return str(raw_value)
 
-    def _prompt_with_basic_input(
-        self, message: str | Callable[[], Any], placeholder: str | None
-    ) -> str:
+    def _prompt_with_basic_input(self, message: str | Callable[[], Any], placeholder: str | None) -> str:
         """Handle prompting with basic input."""
         if placeholder:
             self.console.print(f"[dim]{placeholder}[/dim]")
@@ -798,9 +1194,7 @@ class SlashSession:
 
         return input(actual_message)
 
-    def _prompt(
-        self, message: str | Callable[[], Any], *, placeholder: str | None = None
-    ) -> str:
+    def _prompt(self, message: str | Callable[[], Any], *, placeholder: str | None = None) -> str:
         """Main prompt function with reduced complexity."""
         if self._ptk_session and self._ptk_style and patch_stdout:
             return self._prompt_with_prompt_toolkit(message, placeholder)
@@ -808,13 +1202,43 @@ 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
 
-    def set_contextual_commands(
-        self, commands: dict[str, str] | None, *, include_global: bool = True
-    ) -> None:
+    def on_account_switched(self, _account_name: str | None = None) -> None:
+        """Reset any state that depends on the active account.
+
+        The active account can change via `/accounts` (or other flows that call
+        AccountStore.set_active_account). The slash session caches a configured
+        client instance, so we must invalidate it to avoid leaking the previous
+        account's API URL/key into subsequent commands like `/agents` or `/runs`.
+
+        This method clears:
+        - Client and config cache (account-specific credentials)
+        - Current agent and recent agents (agent data is account-scoped)
+        - Runs pagination state (runs are account-scoped)
+        - Active renderer and transcript ready state (UI state tied to account context)
+        - Contextual commands (may be account-specific)
+
+        These broader resets ensure a clean slate when switching accounts, preventing
+        stale data from the previous account from appearing in the new account's context.
+        """
+        self._client = None
+        self._config_cache = None
+        self._current_agent = None
+        self.recent_agents = []
+        self._runs_pagination_state.clear()
+        self.clear_active_renderer()
+        self.clear_agent_transcript_ready()
+        self.set_contextual_commands(None)
+
+    def set_contextual_commands(self, commands: dict[str, str] | None, *, include_global: bool = True) -> None:
         """Set context-specific commands that should appear in completions."""
         self._contextual_commands = dict(commands or {})
         self._contextual_include_global = include_global if commands else True
@@ -828,15 +1252,18 @@ 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 "",
             "type": getattr(agent, "type", "") or "",
         }
 
-        self.recent_agents = [
-            a for a in self.recent_agents if a.get("id") != agent_data["id"]
-        ]
+        self.recent_agents = [a for a in self.recent_agents if a.get("id") != agent_data["id"]]
         self.recent_agents.insert(0, agent_data)
         self.recent_agents = self.recent_agents[:5]
 
@@ -847,6 +1274,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
@@ -889,11 +1323,10 @@ class SlashSession:
 
         header_grid = self._build_header_grid(agent_info, transcript_status)
         keybar = self._build_keybar()
-
         header_grid.add_row(keybar, "")
-        self.console.print(
-            AIPPanel(header_grid, title="Agent Session", border_style=PRIMARY)
-        )
+
+        # 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]:
         """Extract agent information for display."""
@@ -914,9 +1347,7 @@ class SlashSession:
         has_transcript = bool(payload and manifest and manifest.get("run_id"))
         run_id = (manifest or {}).get("run_id")
         transcript_ready = (
-            has_transcript
-            and latest_agent_id == agent_id
-            and self._agent_transcript_ready.get(agent_id) == run_id
+            has_transcript and latest_agent_id == agent_id and self._agent_transcript_ready.get(agent_id) == run_id
         )
 
         return {
@@ -925,9 +1356,7 @@ class SlashSession:
             "run_id": run_id,
         }
 
-    def _build_header_grid(
-        self, agent_info: dict[str, str], transcript_status: dict[str, Any]
-    ) -> AIPGrid:
+    def _build_header_grid(self, agent_info: dict[str, str], transcript_status: dict[str, Any]) -> AIPGrid:
         """Build the main header grid with agent information."""
         header_grid = AIPGrid(expand=True)
         header_grid.add_column(ratio=3)
@@ -938,18 +1367,16 @@ class SlashSession:
             f"[{ACCENT_STYLE}]{agent_info['id']}[/]"
         )
         status_line = f"[{SUCCESS_STYLE}]ready[/]"
-        status_line += (
-            " · transcript ready"
-            if transcript_status["transcript_ready"]
-            else " · transcript pending"
-        )
+        if not transcript_status["has_transcript"]:
+            status_line += " · no transcript"
+        elif transcript_status["transcript_ready"]:
+            status_line += " · transcript ready"
+        else:
+            status_line += " · transcript pending"
         header_grid.add_row(primary_line, status_line)
 
         if agent_info["description"]:
-            description = agent_info["description"]
-            if not transcript_status["transcript_ready"]:
-                description = f"{description}  (transcript pending)"
-            header_grid.add_row(f"[dim]{description}[/dim]", "")
+            header_grid.add_row(f"[dim]{agent_info['description']}[/dim]", "")
 
         return header_grid
 
@@ -958,28 +1385,40 @@ 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 "",
         )
 
         return keybar
 
-    def _render_main_header(
-        self, active_agent: Any | None = None, *, full: bool = False
-    ) -> None:
+    def _render_main_header(self, active_agent: Any | None = None, *, full: bool = False) -> None:
         """Render the main AIP environment header."""
         config = self._load_config()
 
+        account_name, account_host, env_lock = self._get_account_context()
         api_url = self._get_api_url(config)
-        status = "Configured" if config.get("api_key") else "Not configured"
 
-        segments = [
-            f"[dim]Base URL[/dim] • {api_url or 'Not configured'}",
-            f"[dim]Credentials[/dim] • {status}",
-        ]
+        host_display = account_host or "Not configured"
+        account_segment = f"[dim]Account[/dim] • {account_name} ({host_display})"
+        if env_lock:
+            account_segment += " 🔒"
+
+        segments = [account_segment]
+
+        if api_url:
+            base_label = "[dim]Base URL[/dim]"
+            if env_lock:
+                base_label = "[dim]Base URL (env)[/dim]"
+            # Always show Base URL when env-lock is active to reveal overrides
+            if env_lock or api_url != account_host:
+                segments.append(f"{base_label} • {api_url}")
+        elif not api_url:
+            segments.append("[dim]Base URL[/dim] • Not configured")
+
         agent_info = self._build_agent_status_line(active_agent)
         if agent_info:
             segments.append(agent_info)
@@ -987,7 +1426,7 @@ class SlashSession:
         rendered_line = "    ".join(segments)
 
         if full:
-            self.console.print(rendered_line)
+            self.console.print(rendered_line, soft_wrap=False)
             return
 
         status_bar = AIPGrid(expand=True)
@@ -1002,12 +1441,23 @@ class SlashSession:
             )
         )
 
-    def _get_api_url(self, config: dict[str, Any]) -> str | None:
-        """Get the API URL from various sources."""
-        api_url = None
-        if isinstance(self.ctx.obj, dict):
-            api_url = self.ctx.obj.get("api_url")
-        return api_url or config.get("api_url") or os.getenv("AIP_API_URL")
+    def _get_api_url(self, _config: dict[str, Any] | None = None) -> str | None:
+        """Get the API URL from context or account store (CLI/palette ignores env credentials)."""
+        return resolve_api_url_from_context(self.ctx)
+
+    def _get_account_context(self) -> tuple[str, str, bool]:
+        """Return active account name, host, and env-lock flag."""
+        try:
+            store = get_account_store()
+            active = store.get_active_account() or "default"
+            account = store.get_account(active) if hasattr(store, "get_account") else None
+            host = ""
+            if account:
+                host = account.get("api_url", "")
+            env_lock = env_credentials_present()
+            return active, host, env_lock
+        except Exception:
+            return "default", "", env_credentials_present()
 
     def _build_agent_status_line(self, active_agent: Any | None) -> str | None:
         """Return a short status line about the active or recent agent."""
@@ -1022,35 +1472,96 @@ class SlashSession:
         return None
 
     def _show_default_quick_actions(self) -> None:
-        hints: list[tuple[str | None, str]] = [
-            (
-                command_hint("status", slash_command="status", ctx=self.ctx),
-                "Connection check",
-            ),
-            (
-                command_hint("agents list", slash_command="agents", ctx=self.ctx),
-                "Browse agents",
-            ),
-            (
-                command_hint("help", slash_command="help", ctx=self.ctx),
-                "Show all commands",
-            ),
-        ]
-        filtered = [(cmd, desc) for cmd, desc in hints if cmd]
-        if filtered:
-            self._show_quick_actions(filtered, title="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]],
+    ) -> 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]] = []
+
+        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
+
+    def _build_quick_action_hint(
+        self,
+        action: dict[str, Any],
+    ) -> 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", "")
+        # 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:
+        """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_lines = [
-            f"[{HINT_PREFIX_STYLE}]Hint:[/]",
-            f"  Type {format_command_hint('/') or '/'} to explore commands",
-            "  Press [dim]Ctrl+C[/] to cancel the current entry",
-            "  Press [dim]Ctrl+D[/] to quit",
-        ]
-        self.console.print("\n".join(hint_lines))
+        hint_text = (
+            f"[{HINT_PREFIX_STYLE}]Hint:[/] "
+            f"Type {format_command_hint('/') or '/'} to explore commands · "
+            "Press [dim]Ctrl+D[/] to quit"
+        )
+        self.console.print(hint_text)
         self._home_hint_shown = True
 
     def _show_quick_actions(
@@ -1060,36 +1571,99 @@ class SlashSession:
         title: str = "Quick actions",
         inline: bool = False,
     ) -> None:
-        hint_list = [
-            (command, description) for command, description in hints if command
-        ]
+        """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
 
         if inline:
-            lines: list[str] = []
-            for command, description in hint_list:
-                formatted = format_command_hint(command, description)
-                if formatted:
-                    lines.append(formatted)
-            if lines:
-                self.console.print("\n".join(lines))
+            self._render_inline_quick_actions(hint_list, title)
             return
 
+        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)
+            if formatted:
+                tokens.append(formatted)
+        if not tokens:
+            return
+        prefix = f"[dim]{title}:[/]" if title else ""
+        body = "    ".join(tokens)
+        text = f"{prefix} {body}" if prefix else body
+        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)
             if formatted:
                 body_lines.append(Text.from_markup(formatted))
-
+        if not body_lines:
+            return
         panel_content = Group(*body_lines)
-        self.console.print(
-            AIPPanel(
-                panel_content, title=title, border_style=SECONDARY_LIGHT, expand=False
-            )
-        )
+        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 {}
@@ -1097,9 +1671,17 @@ class SlashSession:
                 self._config_cache = {}
         return self._config_cache
 
-    def _resolve_agent_from_ref(
-        self, client: Any, available_agents: list[Any], ref: str
-    ) -> Any | None:
+    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