⚡️ perf(cli): render startup header with Textual

Replace the Rich title panel with a Textual Header wired to model/base URL, keep output inline, and make CLI tests stub the header render. Tighten MCP spec typing in CLI commands and ensure tool output formatting remains type-safe. Update CLI guidance to reflect the new header behavior.

Author: bearlike

meeseeks-cli/AGENTS.md

@@ -10,9 +10,9 @@ Scope: this file applies to the `meeseeks-cli/` package only. It covers the term
 
 ## Rendering Pipeline (How we produce output)
 - Entry point: `meeseeks-cli/cli_master.py` (`run_cli`).
-- Rendering is **Rich**-based and printed via a single `Console` instance.
+- Rendering is primarily **Rich**-based and printed via a single `Console` instance.
 - High-level sections:
-  - Ready panel with model/base URL (within the same border).
+  - Startup header via Textual `Header` plus a ready line with session info.
   - Action plan checklist (Panel + Text + Group).
   - Tool results as cards (Panel + Columns).
   - Response panel (Markdown in a bold border).
@@ -28,7 +28,7 @@ Scope: this file applies to the `meeseeks-cli/` package only. It covers the term
 If you change any of these, update this file.
 
 ## Dialogs / Prompts (Textual)
-We use **Textual** only for interactive dialogs, not for overall output.
+We use **Textual** for the startup header and interactive dialogs, not the full CLI output.
 
 Location: `meeseeks-cli/cli_dialogs.py`
 

meeseeks-cli/cli_commands.py

@@ -22,7 +22,7 @@
 
 from core.task_master import orchestrate_session  # noqa: E402
 from core.token_budget import get_token_budget  # noqa: E402
-from core.tool_registry import ToolRegistry, load_registry  # noqa: E402
+from core.tool_registry import ToolRegistry, ToolSpec, load_registry  # noqa: E402
 
 
 @dataclass(frozen=True)
@@ -275,8 +275,8 @@ def _refresh_mcp_registry(context: CommandContext) -> None:
 
 def _maybe_select_mcp_specs(
     context: CommandContext,
-    mcp_specs: list[object],
-) -> list[object] | None:
+    mcp_specs: list[ToolSpec],
+) -> list[ToolSpec] | None:
     if context.prompt_func is None:
         return None
     dialogs = DialogFactory(console=context.console, prompt_func=context.prompt_func)
@@ -471,7 +471,7 @@ def _handle_model_wizard(
 def _render_mcp(
     console: Console,
     tool_registry: ToolRegistry,
-    mcp_specs: list[object] | None = None,
+    mcp_specs: list[ToolSpec] | None = None,
 ) -> None:
     config_path = os.getenv("MESEEKS_MCP_CONFIG")
     if config_path and os.path.exists(config_path):

meeseeks-cli/cli_master.py

@@ -14,8 +14,11 @@
 from rich.console import Console, Group
 from rich.markdown import Markdown
 from rich.panel import Panel
+from rich.status import Status
 from rich.syntax import Syntax
 from rich.text import Text
+from textual.app import App, ComposeResult
+from textual.widgets import Header
 
 
 def _verbosity_to_level(verbosity: int) -> str:
@@ -139,6 +142,27 @@ def _resolve_display_model(model_name: str | None) -> str:
     )
 
 
+class _HeaderApp(App[None]):
+    """Minimal Textual app for rendering the CLI header."""
+
+    def __init__(self, title: str, subtitle: str) -> None:
+        super().__init__()
+        self.title = title
+        self.sub_title = subtitle
+
+    def compose(self) -> ComposeResult:
+        yield Header(show_clock=False)
+
+    def on_mount(self) -> None:
+        self.set_timer(0, self.exit)
+
+
+def _render_startup_header(title: str, subtitle: str) -> None:
+    app = _HeaderApp(title, subtitle)
+    headless = not (sys.stdin.isatty() and sys.stdout.isatty())
+    app.run(inline=True, inline_no_clear=True, headless=headless)
+
+
 def run_cli(args: argparse.Namespace) -> int:
     """Run the CLI application loop.
 
@@ -161,12 +185,10 @@ def run_cli(args: argparse.Namespace) -> int:
     registry = get_registry()
 
     base_url = os.getenv("OPENAI_API_BASE") or os.getenv("OPENAI_BASE_URL")
-    ready_lines = [
-        Text("Meeseeks CLI ready"),
-        Text(f"Model: {_resolve_display_model(state.model_name)}", style="dim"),
-        Text(f"Base URL: {base_url or '(not set)'}", style="dim"),
-    ]
-    console.print(Panel(Group(*ready_lines), title="Meeseeks"))
+    model_name = _resolve_display_model(state.model_name)
+    subtitle = f"Model: {model_name} • Base URL: {base_url or '(not set)'}"
+    _render_startup_header("Meeseeks", subtitle)
+    console.print("Meeseeks CLI ready")
     console.print(f"Session: {state.session_id}")
     console.print("Type /help for commands.\n")
 
@@ -255,7 +277,7 @@ def _run_query(
         task_queue,
         tool_registry,
         highlight_latest=not bool(task_queue.task_result),
-        verbose=args.verbose > 0,
+        verbose=getattr(args, "verbose", 0) > 0,
     )
     if task_queue.task_result:
         console.print(
@@ -401,6 +423,7 @@ def _render_results_with_registry(
 
 
 def _format_tool_output(result: object, content_style: str | None) -> Text | Syntax:
+    style = content_style or ""
     if isinstance(result, dict | list):
         return Syntax(
             json.dumps(result, indent=2, ensure_ascii=True),
@@ -422,15 +445,15 @@ def _format_tool_output(result: object, content_style: str | None) -> Text | Syn
                     theme="ansi_dark",
                     word_wrap=True,
                 )
-        return Text(result, style=content_style)
-    return Text(str(result), style=content_style)
+        return Text(result, style=style)
+    return Text(str(result), style=style)
 
 
 def _build_cli_hook_manager(
     console: Console,
     tool_registry: ToolRegistry,
 ) -> HookManager:
-    status_holder: dict[str, object] = {}
+    status_holder: dict[str, Status] = {}
     specs = _tool_specs_by_id(tool_registry)
 
     def _start_spinner(action_step: ActionStep) -> ActionStep:

meeseeks-cli/tests/test_cli.py

@@ -221,6 +221,9 @@ def test_run_cli_single_query(monkeypatch, tmp_path):
         auto_approve=False,
     )
 
+    def fake_header(*args, **kwargs):
+        return None
+
     def fake_orchestrate(*args, **kwargs):
         step = ActionStep(
             action_consumer="home_assistant_tool",
@@ -231,6 +234,7 @@ def fake_orchestrate(*args, **kwargs):
         task_queue.task_result = "ok"
         return task_queue
 
+    monkeypatch.setattr("cli_master._render_startup_header", fake_header)
     monkeypatch.setattr("cli_master.orchestrate_session", fake_orchestrate)
     assert run_cli(args) == 0
 
@@ -265,6 +269,7 @@ def prompt(self, *args, **kwargs):
             self.calls += 1
             return "/quit"
 
+    monkeypatch.setattr("cli_master._render_startup_header", lambda *args, **kwargs: None)
     monkeypatch.setattr("cli_master.FileHistory", DummyHistory)
     monkeypatch.setattr("cli_master.PromptSession", lambda *args, **kwargs: DummySession())
     assert run_cli(args) == 0