minima-cli 0.4.9__py3-none-any.whl

minima_harness/tui/run_modes.py

@@ -0,0 +1,66 @@
+from __future__ import annotations
+
+import json
+import sys
+
+from minima_harness.agent.events import (
+    AgentEndEvent,
+    AgentStartEvent,
+    MessageUpdateEvent,
+    ToolExecutionEndEvent,
+    ToolExecutionStartEvent,
+    TurnEndEvent,
+)
+from minima_harness.ai.events import ErrorEvent, TextDeltaEvent
+from minima_harness.minima.runtime import MinimaAgent
+
+
+def event_to_dict(event) -> dict:  # noqa: ANN001
+    """Serialize an AgentEvent into a JSON-friendly dict (PI-style JSON mode)."""
+    if isinstance(event, MessageUpdateEvent):
+        stream = event.assistant_message_event
+        if isinstance(stream, TextDeltaEvent):
+            return {"type": "text_delta", "delta": stream.delta}
+        if isinstance(stream, ErrorEvent):
+            err = stream.error
+            return {
+                "type": "error",
+                "message": getattr(err, "error_message", "") or "provider error",
+                "model": getattr(err, "model", ""),
+            }
+        return {"type": "message_update"}
+    if isinstance(event, ToolExecutionStartEvent):
+        return {"type": "tool_start", "name": event.tool_name}
+    if isinstance(event, ToolExecutionEndEvent):
+        return {"type": "tool_end", "is_error": event.is_error}
+    if isinstance(event, TurnEndEvent):
+        return {"type": "turn_end"}
+    if isinstance(event, AgentEndEvent):
+        return {"type": "done"}
+    if isinstance(event, AgentStartEvent):
+        return {"type": "start"}
+    return {"type": getattr(event, "type", "unknown")}
+
+
+async def run_print(agent: MinimaAgent, prompt: str) -> int:
+    """One-shot: run the prompt, print the final assistant text, exit.
+
+    A provider failure (bad key, 404, network) produces empty output; report the classified
+    reason on stderr and exit non-zero instead of silently printing a blank line.
+    """
+    await agent.prompt(prompt)
+    err = getattr(agent, "_last_error", None)
+    last = agent._last_assistant()  # noqa: SLF001
+    text = last.text if last is not None else ""
+    if err and not text.strip():
+        print(err, file=sys.stderr)
+        return 1
+    print(text)
+    return 0
+
+
+async def run_json(agent: MinimaAgent, prompt: str) -> int:
+    """Stream every AgentEvent as a JSON line, then exit."""
+    agent.subscribe(lambda event: print(json.dumps(event_to_dict(event)), flush=True))
+    await agent.prompt(prompt)
+    return 0

minima_harness/tui/theme.py

@@ -0,0 +1,77 @@
+from __future__ import annotations
+
+from enum import StrEnum
+from pathlib import Path
+
+Palette = dict[str, str]
+
+
+class ThemeName(StrEnum):
+    DARK = "dark"
+    LIGHT = "light"
+
+
+DARK: Palette = {
+    "user": "#7aa2f7",
+    "assistant": "#e0e0e0",
+    "tool": "#bb9af7",
+    "warning": "#f7768e",
+    "muted": "#665c6e",
+    "accent": "#9ece6a",
+    # Footer/status emphasis: amber for $ value (legible against green/blue), a brighter
+    # dim than `muted` for de-emphasized metrics. .get()-accessed so JSON themes can omit them.
+    "footer_accent": "#e0af68",
+    "footer_dim": "#9aa0a6",
+}
+
+LIGHT: Palette = {
+    "user": "#1f4de0",
+    "assistant": "#222222",
+    "tool": "#7c3aed",
+    "warning": "#c0152e",
+    "muted": "#7a7a7a",
+    "accent": "#0f7b3a",
+    "footer_accent": "#b45309",
+    "footer_dim": "#6b7280",
+}
+
+THEMES: dict[ThemeName, Palette] = {ThemeName.DARK: DARK, ThemeName.LIGHT: LIGHT}
+
+# Registry of usable themes: the two built-ins plus any loaded from JSON files.
+_registry: dict[str, Palette] = {"dark": DARK, "light": LIGHT}
+_active: str = "dark"
+
+
+def available_themes() -> dict[str, Palette]:
+    """All themes usable by name right now (built-ins + loaded file themes)."""
+    return dict(_registry)
+
+
+def register_theme(name: str, palette: Palette) -> None:
+    _registry[name] = palette
+
+
+def reload_file_themes(cwd: Path) -> None:
+    """Re-discover ``*.json`` theme files and merge into the registry (hot-reload)."""
+    from minima_harness.tui.customize import load_file_themes
+
+    for name, palette in load_file_themes(cwd).items():
+        register_theme(name, palette)
+
+
+def current_theme() -> str:
+    return _active
+
+
+def set_theme(name: str) -> Palette:
+    global _active
+    if name not in _registry:
+        raise KeyError(f"unknown theme: {name}")
+    _active = name
+    return _registry[name]
+
+
+def get_theme(name: str) -> Palette:
+    if name not in _registry:
+        raise KeyError(f"unknown theme: {name}")
+    return _registry[name]

minima_harness/tui/welcome.py

@@ -0,0 +1,83 @@
+from __future__ import annotations
+
+import os
+from typing import TYPE_CHECKING
+
+from rich.console import Group
+from rich.text import Text
+
+from minima_harness.tui.theme import current_theme, get_theme
+
+if TYPE_CHECKING:
+    from minima_harness.tui.app import HarnessApp
+
+
+def selection_hint(mouse_on: bool) -> str:
+    """One-line guidance for selecting/copying text given the current mouse mode.
+
+    With mouse capture ON the wheel scrolls but the terminal's own click-drag selection is
+    suppressed; you select in-app instead (drag + Ctrl+C). macOS Terminal.app can't do in-app
+    drag-select (it doesn't report mouse motion), so capture there only blocks native selection —
+    `/mouse off` is the way to select+copy.
+    """
+    if not mouse_on:
+        return "native mouse select & copy · scroll with PageUp/PageDown · /mouse to toggle"
+    if os.environ.get("TERM_PROGRAM") == "Apple_Terminal":
+        return "Terminal.app can't drag-select while scrolling — /mouse off to select & copy"
+    return "scroll: wheel/PgUp · select+copy: drag then Ctrl+C · /mouse off for native selection"
+
+def _needs_setup() -> bool:
+    """No configured provider key (across the whole provider catalog) → first-run nudge."""
+    from minima_harness.ai.provider_catalog import configured_providers
+
+    return not configured_providers()
+
+# ANSI-Shadow-style block glyphs (6 rows). Built programmatically and joined row-wise so the
+# columns always line up — never hand-concatenate ASCII art. Each letter's rows are equal width.
+_GLYPHS: dict[str, list[str]] = {
+    "M": ["███╗   ███╗", "████╗ ████║", "██╔████╔██║", "██║╚██╔╝██║", "██║ ╚═╝ ██║", "╚═╝     ╚═╝"],
+    "I": ["██╗", "██║", "██║", "██║", "██║", "╚═╝"],
+    "N": ["███╗   ██╗", "████╗  ██║", "██╔██╗ ██║", "██║╚██╗██║", "██║ ╚████║", "╚═╝  ╚═══╝"],
+    "A": [" █████╗ ", "██╔══██╗", "███████║", "██╔══██║", "██║  ██║", "╚═╝  ╚═╝"],
+}
+
+
+def _ascii_banner(word: str) -> str:
+    return "\n".join(" ".join(_GLYPHS[ch][row] for ch in word) for row in range(6))
+
+
+BANNER = _ascii_banner("MINIMA")  # ~51 cols wide; the hero of the launch splash
+
+# A one-line workflow strap. Live state lives in the footer (the single status surface), not
+# here — the splash is pure onboarding. Auto-collapses on the first prompt; /banner toggles it.
+DIAGRAM = "recommend → run → judge → feedback → memory"
+
+
+def render_welcome(app: HarnessApp) -> Group:
+    """The centered launch splash: MINIMA CLI banner + workflow strap + one onboarding hint.
+
+    Carries NO live status (model/session/cost/theme — that's the footer's job) and NO
+    duplicated key help.
+    """
+    t = get_theme(current_theme())
+    accent, muted = t["accent"], t["muted"]
+    # justify="center" centers each line within the (auto-width = banner-width) splash widget, so
+    # the subtitle/strap/hint sit centered under the banner. The banner's 6 rows are equal width,
+    # so centering them keeps the ASCII art aligned.
+    banner = Text(BANNER, style=f"bold {accent}", justify="center")
+    subtitle = Text("CLI · cost-aware model routing", style=muted, justify="center")
+    strap = Text(DIAGRAM, style=muted, justify="center")
+    parts = [banner, Text(""), subtitle, Text(""), strap]
+    if _needs_setup():
+        parts.append(
+            Text(
+                "no API keys found — run  minima config  to add them",
+                style=t.get("warning", accent),
+                justify="center",
+            )
+        )
+    parts.append(Text("type a prompt, or / for commands", style=muted, justify="center"))
+    parts.append(
+        Text(selection_hint(getattr(app, "_mouse_enabled", True)), style=muted, justify="center")
+    )
+    return Group(*parts)

minima_harness/tui/widgets/__init__.py

@@ -0,0 +1,3 @@
+"""TUI widgets."""
+
+from __future__ import annotations

minima_harness/tui/widgets/banner.py

@@ -0,0 +1,38 @@
+from __future__ import annotations
+
+from rich.text import Text
+
+from minima_harness.tui.theme import current_theme, get_theme
+
+
+def render_banner(reason: str) -> Text:
+    """Genuine offline fallback: Minima was unreachable, so /reconnect is the action."""
+    t = get_theme(current_theme())
+    return Text(
+        f"⚠ routing offline: {reason} — /reconnect to retry Minima",
+        style=f"bold {t['warning']}",
+    )
+
+
+def render_config_banner(reason: str) -> Text:
+    """Routing is off due to a config/auth problem (no/invalid key). Retrying alone won't
+    fix it, so this deliberately omits the '/reconnect to retry' framing and instead carries
+    the actionable next step in ``reason`` (e.g. 'add MUBIT_API_KEY via /config')."""
+    t = get_theme(current_theme())
+    return Text(f"⚠ routing offline: {reason}", style=f"bold {t['warning']}")
+
+
+def render_model_error_banner(reason: str) -> Text:
+    """The chosen model's *call* failed (bad/missing provider key, quota, 403/404, network) —
+    routing itself succeeded. So this must NOT use the 'routing offline … /reconnect to retry
+    Minima' framing (reconnecting won't help); the fix is the provider key or a different model,
+    which ``reason`` already names (e.g. '… — check GEMINI_API_KEY (/config) or /model')."""
+    t = get_theme(current_theme())
+    return Text(f"⚠ {reason}", style=f"bold {t['warning']}")
+
+
+def render_notice(reason: str) -> Text:
+    """A non-offline heads-up (a surfaced warning or context-near-limit). Deliberately omits
+    the 'routing offline'/'/reconnect' framing — routing succeeded; this is just FYI."""
+    t = get_theme(current_theme())
+    return Text(f"⚠ {reason}", style=f"bold {t['warning']}")

minima_harness/tui/widgets/editor.py

@@ -0,0 +1,83 @@
+from __future__ import annotations
+
+from textual.events import Key
+from textual.message import Message
+from textual.widgets import TextArea
+
+from minima_harness.tui.history import History
+
+_NEWLINE_KEYS = frozenset({"shift+enter", "ctrl+enter"})
+
+
+class Editor(TextArea):
+    """Multi-line editor with /-command autocomplete.
+
+    Enter submits (or steers while the agent runs — decided by the app); Shift/Ctrl+Enter
+    inserts a newline; Alt+Enter queues a follow-up. Text changes flow out via TextArea's
+    built-in ``Changed`` message so the app can drive a command popup; Tab on a ``/``-prefixed
+    line requests completion.
+    """
+
+    class Submitted(Message):
+        def __init__(self, text: str) -> None:
+            super().__init__()
+            self.text = text
+
+    class FollowUp(Message):
+        def __init__(self, text: str) -> None:
+            super().__init__()
+            self.text = text
+
+    class CompleteRequested(Message):
+        def __init__(self, text: str) -> None:
+            super().__init__()
+            self.text = text
+
+    class CycleThinking(Message):
+        def __init__(self) -> None:
+            super().__init__()
+
+    def __init__(self) -> None:
+        super().__init__(id="editor", soft_wrap=True, show_line_numbers=False)
+        self.border_title = "prompt"  # titled accent border frames the input as the focus target
+        self.prompt_history: History | None = None  # set by the app for Up/Down recall
+
+    def on_key(self, event: Key) -> None:
+        if event.key in ("up", "down") and self.prompt_history is not None:
+            row = self.cursor_location[0]
+            on_edge = (event.key == "up" and row == 0) or (
+                event.key == "down" and row >= self.text.count("\n")
+            )
+            if "\n" not in self.text or on_edge:
+                entry = (
+                    self.prompt_history.prev() if event.key == "up" else self.prompt_history.next()
+                )
+                if entry is None:
+                    return  # nothing to recall / already at the new position
+                event.prevent_default()
+                event.stop()
+                self.text = entry
+                self.move_cursor((0, len(entry)))
+                return
+        if event.key == "tab" and self.text.startswith("/"):
+            event.prevent_default()
+            event.stop()
+            self.post_message(self.CompleteRequested(self.text))
+            return
+        if event.key == "shift+tab":
+            event.prevent_default()
+            event.stop()
+            self.post_message(self.CycleThinking())
+            return
+        if event.key == "enter":
+            event.prevent_default()
+            event.stop()
+            self.post_message(self.Submitted(self.text))
+        elif event.key == "alt+enter":
+            event.prevent_default()
+            event.stop()
+            self.post_message(self.FollowUp(self.text))
+        elif event.key in _NEWLINE_KEYS:
+            event.prevent_default()
+            event.stop()
+            self.insert("\n")

minima_harness/tui/widgets/footer.py

@@ -0,0 +1,73 @@
+from __future__ import annotations
+
+from rich.text import Text
+
+from minima_harness.minima.meter import CostMeter
+from minima_harness.tui.theme import current_theme, get_theme
+
+
+def render_footer(
+    cwd: str,
+    session_id: str,
+    model: str,
+    basis: str,
+    meter: CostMeter,
+    input_tokens: int,
+    output_tokens: int,
+    cache_read: int,
+    cache_write: int,
+    ctx_pct: float,
+    routing_offline: bool,
+    route_mode: str = "auto",
+    thinking_level: str = "off",
+    goal: str = "",
+) -> Text:
+    """The single canonical status surface. Per-segment colour by *meaning* (not blanket-dim):
+    model in user-colour, cost in amber, savings/ctx/route warnings in red — so Minima's
+    cost-routing value reads at a glance. Layout: MODES  |  METRICS.
+    """
+    t = get_theme(current_theme())
+    dim = t.get("footer_dim", t["muted"])
+    accent = t.get("footer_accent", t["accent"])
+    user, warn = t["user"], t["warning"]
+    totals = meter.totals()
+    out = Text(no_wrap=True)
+
+    def seg(label: str, value: str, style: str) -> None:
+        out.append(label, style=dim)
+        out.append(value, style=style)
+
+    # --- modes block (what am I doing) ---
+    seg("model: ", f"{model} ▸ {basis}", warn if basis == "offline" else user)
+    out.append("  ·  ", style=dim)
+    seg("route: ", route_mode, warn if route_mode == "confirm" else dim)
+    out.append("  ·  ", style=dim)
+    think_style = warn if thinking_level == "high" else (dim if thinking_level == "off" else accent)
+    seg("think: ", thinking_level, think_style)
+    if goal:
+        out.append("  ·  ", style=dim)
+        seg("ledger: ", goal, accent)
+
+    out.append("   |   ", style=dim)
+
+    # --- metrics block (what has it cost) ---
+    seg("ctx ", f"{ctx_pct:.0f}%", warn if ctx_pct > 80 else dim)
+    out.append("  ·  ", style=dim)
+    out.append(f"↑{input_tokens} ↓{output_tokens}", style=dim)
+    if cache_read:
+        out.append(f" ⚡{cache_read}", style=accent)  # tokens served from the prompt cache
+    out.append("  ·  ", style=dim)
+    out.append(f"${totals.actual_cost_usd:.4f}", style=accent)
+    if totals.baseline_rows:
+        pct = totals.savings_pct
+        out.append(
+            f" ({'save' if pct >= 0 else 'over'} {abs(pct):.0f}% vs base)",
+            style=accent if pct >= 0 else warn,
+        )
+    out.append("  ·  ", style=dim)
+    marker = "◈ " if session_id == "ephemeral" else ""
+    out.append(f"sess {marker}{session_id[:24]}", style=dim)
+    if routing_offline:
+        out.append("   ")
+        out.append("[routing offline]", style=f"bold {warn}")
+    return out

minima_harness/tui/widgets/messages.py

@@ -0,0 +1,151 @@
+from __future__ import annotations
+
+import time
+
+from rich.text import Text
+from textual.containers import ScrollableContainer
+from textual.widgets import Static
+
+from minima_harness.tui.theme import current_theme, get_theme
+
+# Min seconds between live-stream repaints (~16 Hz). The terminal emulator repaints the whole
+# chat region on each flush, so a tighter cadence (e.g. 0.03 = 33 Hz) drives terminal CPU/fans
+# hard for no readability gain. 16 Hz still reads as smooth streaming.
+THROTTLE_S = 0.06
+
+_ROLE_COLOR = {"user": "user", "assistant": "assistant", "tool": "tool", "thinking": "muted"}
+_ROLE_PREFIX = {
+    "user": "▸ ",
+    "assistant": "",
+    "tool": "",
+    "error": "✗ ",
+    "system": "",
+    "thinking": "thoughts  ",
+}
+
+
+def _color_for(role: str) -> str:
+    t = get_theme(current_theme())
+    return t.get(_ROLE_COLOR.get(role, "muted"), t["assistant"])
+
+
+class MessageBubble(Static):
+    """A single chat message. Appendable + throttled for live assistant streaming."""
+
+    def __init__(
+        self,
+        role: str,
+        text: str = "",
+        *,
+        prefix: str | None = None,
+        color: str | None = None,
+        italic: bool = False,
+    ) -> None:
+        self._role = role
+        self._color_override = color
+        self._color = color or _color_for(role)
+        self._italic = italic
+        self._prefix = prefix if prefix is not None else _ROLE_PREFIX.get(role, "")
+        self._buf = text
+        self._last_flush = 0.0
+        self._markdown = False
+        super().__init__(self._content_text())
+
+    def _style(self) -> str:
+        return f"italic {self._color}" if self._italic else self._color
+
+    @property
+    def buffer(self) -> str:
+        return self._buf
+
+    def append(self, delta: str) -> None:
+        self._buf += delta
+        if time.monotonic() - self._last_flush >= THROTTLE_S:
+            self.flush()
+
+    def set_text(self, text: str) -> None:
+        self._buf = text
+        self.flush()
+
+    def flush(self) -> None:
+        self._last_flush = time.monotonic()
+        try:
+            self.update(self._content_text())
+        except Exception:  # noqa: BLE001 - not mounted / no active app; buffer stays current
+            pass
+
+    def render_markdown(self) -> None:
+        """Swap the bubble's plain-streamed text for rendered Markdown (assistant finalize)."""
+        from rich.markdown import Markdown
+
+        self._markdown = True
+        self._last_flush = time.monotonic()
+        try:
+            self.update(Markdown(self._buf))
+        except Exception:  # noqa: BLE001 - fall back to plain text if markdown rendering fails
+            self.flush()
+
+    def refresh_theme(self) -> None:
+        """Re-read the active palette and re-render (used after /theme)."""
+        self._color = self._color_override or _color_for(self._role)
+        if self._markdown:
+            self.render_markdown()
+        else:
+            self.flush()
+
+    def _content_text(self) -> Text:
+        if self._role == "tool" and "\n" in self._buf:
+            return self._tool_diff_text()
+        return Text(f"{self._prefix}{self._buf}", style=self._style())
+
+    def _tool_diff_text(self) -> Text:
+        """Colorize a multi-line tool-call body like an IDE diff: + green, - red, @@ cyan."""
+        t = Text()
+        lines = f"{self._prefix}{self._buf}".split("\n")
+        for i, line in enumerate(lines):
+            body = line + ("" if i == len(lines) - 1 else "\n")
+            s = line.lstrip()
+            if s.startswith("+") and not s.startswith("+++"):
+                t.append(body, style="green")
+            elif s.startswith("-") and not s.startswith("---"):
+                t.append(body, style="red")
+            elif s.startswith("@@"):
+                t.append(body, style="cyan")
+            else:
+                t.append(body, style=self._color)
+        return t
+
+
+class ChatLog(ScrollableContainer):
+    """Scrolling list of message bubbles; auto-scrolls to the newest."""
+
+    async def _add(self, bubble: MessageBubble) -> MessageBubble:
+        await self.mount(bubble)
+        self.scroll_end(animate=False)
+        return bubble
+
+    async def add_user(self, text: str) -> MessageBubble:
+        return await self._add(MessageBubble("user", text))
+
+    async def add_assistant_stream(self) -> MessageBubble:
+        return await self._add(MessageBubble("assistant"))
+
+    async def add_thinking_stream(self) -> MessageBubble:
+        """A muted, 💭-prefixed bubble that streams the model's reasoning (when /thoughts is on)."""
+        return await self._add(MessageBubble("thinking", italic=True))
+
+    async def add_tool(self, name: str, args_repr: str = "") -> MessageBubble:
+        return await self._add(MessageBubble("tool", args_repr, prefix=f"◆ {name}  "))
+
+    async def add_tool_result(self, summary: str, is_error: bool) -> MessageBubble:
+        # A failed tool (incl. permission/sandbox denials) reads as a prominent red ✗ line, not
+        # a faint "→" that's easy to miss; a success stays a quiet dim snippet.
+        role = "error" if is_error else "system"
+        prefix = "   ✗ " if is_error else "   → "
+        return await self._add(MessageBubble(role, summary, prefix=prefix))
+
+    async def add_error(self, message: str) -> MessageBubble:
+        return await self._add(MessageBubble("error", message))
+
+    async def add_system(self, text: str, *, color: str | None = None) -> MessageBubble:
+        return await self._add(MessageBubble("system", text, color=color))

minima_harness/tui/widgets/status.py

@@ -0,0 +1,57 @@
+from __future__ import annotations
+
+from rich.text import Text
+from textual.widgets import Static
+
+from minima_harness.tui.theme import current_theme, get_theme
+
+_FRAMES = "⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏"
+
+
+class StatusBar(Static):
+    """Bottom loader/status bar: an animated spinner while the agent runs
+    (routing / thinking / working), and a static status line when idle."""
+
+    def __init__(self, *args, **kwargs) -> None:  # noqa: ANN002, ANN003
+        super().__init__(*args, **kwargs)
+        self._state = "idle"  # idle | routing | thinking | working
+        self._frame = 0
+        self._idle_text: Text | str = ""
+        self._timer = None
+
+    def on_mount(self) -> None:
+        # The spinner timer runs ONLY while the agent is busy — paused at idle so the event
+        # loop (and the terminal) can truly sleep instead of waking 10x/s for a no-op tick.
+        self._timer = self.set_interval(0.1, self._tick, pause=True)
+
+    def _tick(self) -> None:
+        self._frame = (self._frame + 1) % len(_FRAMES)
+        self._display()
+
+    def set_state(self, state: str) -> None:
+        # Idempotent: the streaming path calls this on every token delta with the same state,
+        # which would otherwise repaint the footer per token (50-100x/s) and spin fans. Only
+        # (re)render and toggle the spinner timer when the state actually changes.
+        if state == self._state:
+            return
+        self._state = state
+        if self._timer is not None:
+            if state == "idle":
+                self._timer.pause()
+            else:
+                self._frame = 0
+                self._timer.resume()
+        self._display()
+
+    def set_idle_text(self, text: Text | str) -> None:
+        # Accept a rich Text so the footer's per-segment colours survive (don't flatten).
+        self._idle_text = text
+        if self._state == "idle":
+            self._display()
+
+    def _display(self) -> None:
+        t = get_theme(current_theme())
+        if self._state == "idle":
+            self.update(self._idle_text or "")
+        else:
+            self.update(Text(f"{_FRAMES[self._frame]} {self._state}…", style=t["accent"]))