pcli-agent 0.1.0__py3-none-any.whl

pcli/tui/widgets/message_view.py

@@ -0,0 +1,328 @@
+"""Scrollable conversation history widget with streaming append support."""
+
+from __future__ import annotations
+
+import json
+import time
+from typing import Any
+
+from rich.console import Group, RenderableType
+from rich.markdown import Markdown
+from rich.syntax import Syntax
+from rich.text import Text
+from textual.containers import VerticalScroll
+from textual.widgets import Collapsible, Static
+
+_ROLE_LABELS = {
+    "user": "You",
+    "assistant": "pcli",
+    "system": "System",
+    "tool": "Tool",
+    "shell": "Shell",
+    "decision": "Decision",
+}
+
+# Caps how often a streaming message repaints. Re-rendering on every single
+# token (unthrottled) is more redraws/sec than some terminals (e.g. VTE-based
+# ones on Linux) can cleanly keep up with, and manifests as flicker/ghosted
+# duplicate frames. 20fps is smooth to read and gentle on any terminal.
+_MIN_REFRESH_INTERVAL_S = 1 / 20
+
+# Tool name -> the argument holding its "payload" (real, unescaped multi-line
+# text worth syntax-highlighting on its own) rather than a short scalar like
+# a path. edit_file's replace mode (old_string+new_string) is handled
+# separately below since it has two such arguments; this same entry also
+# covers edit_file's insert mode (insert_after_line+new_string has no
+# old_string, so it falls through to here) - delete mode (no big text
+# payload at all) falls further through to the generic pretty-JSON path,
+# which is fine for it. Anything not listed here just gets its whole
+# arguments dict pretty-printed as indented JSON instead.
+_CODE_ARG_BY_TOOL = {
+    "write_file": "content",
+    "run_shell": "command",
+    "run_shell_background": "command",
+    "edit_file": "new_string",
+}
+
+# A tool call rendered larger than this (in characters of its formatted body)
+# is collapsed by default, same threshold spirit as tool *results* — small,
+# common calls (read_file, grep, list_dir, ...) stay visible inline, only
+# genuinely large payloads (a big write_file/edit_file, a long script) get
+# tucked behind a click.
+_LARGE_TOOL_CALL_THRESHOLD_CHARS = 500
+
+# Roles whose output can pile up in the transcript and pollute the view -
+# real reported complaint: /help, /memory, /subagent, a long !command all
+# just print permanently with no way to reclaim the space. "user"/
+# "assistant" are never wrapped (primary conversation content — "assistant"
+# also streams into self._current via append_to_last/_flush, which needs a
+# plain Static it can .update() in place). "decision" is deliberately
+# excluded too - see test_chat_screen_decisions.py: a recorded decision is
+# meant to stay always-visible, not tucked behind a click, unlike ordinary
+# system notices/slash-command output.
+_COLLAPSIBLE_MESSAGE_ROLES = frozenset({"system", "shell"})
+
+# Below this, a message in one of the roles above still renders as a plain,
+# permanent line, same as before - short confirmations ("Model set to
+# 'x'.") don't need a collapse affordance. At or above it, it's substantial
+# enough to be worth hiding once read - still expanded by default (the user
+# just asked to see this; only the *option* to collapse it away is new),
+# unlike tool calls/results/reasoning above which default to collapsed.
+_COLLAPSIBLE_MESSAGE_THRESHOLD_CHARS = 300
+
+
+def _format_tool_output(output: str) -> RenderableType:
+    """Pretty-prints/syntax-highlights JSON tool output; otherwise renders
+    verbatim as monospace text (not Markdown — tool output routinely contains
+    underscores/asterisks/etc. that Markdown would misinterpret)."""
+    stripped = output.strip()
+    if stripped[:1] in "{[":
+        parsed: Any = None
+        try:
+            parsed = json.loads(stripped)
+        except (json.JSONDecodeError, ValueError):
+            pass
+        if parsed is not None:
+            pretty = json.dumps(parsed, indent=2, ensure_ascii=False)
+            return Syntax(pretty, "json", word_wrap=True, background_color="default")
+    return Text(output, no_wrap=False, overflow="fold")
+
+
+def _guess_lexer(path: str | None, code: str, default: str = "text") -> str:
+    if path:
+        try:
+            return Syntax.guess_lexer(path, code=code)
+        except Exception:  # noqa: BLE001, S110 - lexer guessing is cosmetic, never fatal
+            pass
+    return default
+
+
+def _format_tool_call_body(tool_name: str, arguments: dict[str, Any]) -> tuple[RenderableType, int]:
+    """Returns (renderable, char_count) — char_count drives the collapse
+    threshold in add_tool_call, measured from the actual formatted content
+    (code/JSON), not the raw arguments JSON string, so it reflects what the
+    user would actually see."""
+    path = arguments.get("path") if isinstance(arguments.get("path"), str) else None
+
+    if tool_name == "edit_file" and "old_string" in arguments and "new_string" in arguments:
+        remaining = {k: v for k, v in arguments.items() if k not in ("old_string", "new_string")}
+        old_code = str(arguments["old_string"])
+        new_code = str(arguments["new_string"])
+        lexer = _guess_lexer(path, old_code)
+        parts: list[RenderableType] = []
+        if remaining:
+            parts.append(Text(_format_remaining_args(remaining), style="dim"))
+        parts.append(Text("- old_string", style="bold red"))
+        parts.append(Syntax(old_code, lexer, word_wrap=True, background_color="default"))
+        parts.append(Text("+ new_string", style="bold green"))
+        parts.append(Syntax(new_code, lexer, word_wrap=True, background_color="default"))
+        return Group(*parts), len(old_code) + len(new_code)
+
+    code_arg = _CODE_ARG_BY_TOOL.get(tool_name)
+    if code_arg and code_arg in arguments and isinstance(arguments[code_arg], str):
+        remaining = {k: v for k, v in arguments.items() if k != code_arg}
+        code = arguments[code_arg]
+        default_lexer = "bash" if tool_name.startswith("run_shell") else "text"
+        lexer = _guess_lexer(path, code, default=default_lexer)
+        parts = []
+        if remaining:
+            parts.append(Text(_format_remaining_args(remaining), style="dim"))
+        parts.append(Syntax(code, lexer, word_wrap=True, background_color="default"))
+        return Group(*parts), len(code)
+
+    if not arguments:
+        return Text("(no arguments)", style="dim"), 0
+    pretty = json.dumps(arguments, indent=2, ensure_ascii=False)
+    return Syntax(pretty, "json", word_wrap=True, background_color="default"), len(pretty)
+
+
+def _format_remaining_args(remaining: dict[str, Any]) -> str:
+    return ", ".join(f"{key}={value!r}" for key, value in remaining.items())
+
+
+def _message_title(role: str, text: str) -> str:
+    """Collapsible title for a long system/shell message - mirrors
+    add_tool_result's "{name} — {char count} char(s)" convention. A shell
+    message's first line is "$ <command>" (see _run_shell_command below);
+    surfacing the command itself in the title is more useful than the
+    generic role label alone, same reasoning as showing the tool name for a
+    tool result."""
+    label = _ROLE_LABELS.get(role, role)
+    first_line = text.strip().splitlines()[0] if text.strip() else ""
+    if role == "shell" and first_line.startswith("$ "):
+        preview = first_line[2:]
+        if len(preview) > 60:
+            preview = preview[:57] + "..."
+        return f"{label}: {preview} — {len(text):,} char(s)"
+    return f"{label} — {len(text):,} char(s)"
+
+
+class MessageView(VerticalScroll):
+    def __init__(self, **kwargs) -> None:
+        super().__init__(**kwargs)
+        self._current: Static | None = None
+        self._current_role: str = "assistant"
+        self._current_text = ""
+        self._last_refresh = 0.0
+        self._refresh_pending = False
+
+    def _scroll_end_if_at_bottom(self, was_at_bottom: bool) -> None:
+        """Auto-scroll is "stick to bottom", not "force to bottom": if the
+        user had already scrolled up (e.g. to read an expanded "Thinking" or
+        tool-result panel while a turn keeps streaming below it), further
+        content must not drag them back down and fight that scroll. Only
+        resumes once they scroll back to the bottom themselves. Callers must
+        capture is_vertical_scroll_end *before* mounting/updating content —
+        doing it after would always read as "not at bottom" once the
+        content just grew."""
+        if was_at_bottom:
+            self.scroll_end(animate=False)
+
+    def add_message(self, role: str, text: str = "") -> Static:
+        was_at_bottom = self.is_vertical_scroll_end
+        widget = Static(classes=f"message message-{role}")
+        widget.update(self._render_message(role, text))
+        if role in _COLLAPSIBLE_MESSAGE_ROLES and len(text) >= _COLLAPSIBLE_MESSAGE_THRESHOLD_CHARS:
+            self.mount(
+                Collapsible(
+                    widget,
+                    title=_message_title(role, text),
+                    collapsed=False,
+                    classes=f"message-collapsible message-collapsible-{role}",
+                )
+            )
+        else:
+            self.mount(widget)
+        self._current = widget
+        self._current_role = role
+        self._current_text = text
+        self._scroll_end_if_at_bottom(was_at_bottom)
+        self._last_refresh = time.monotonic()
+        return widget
+
+    def add_queued_user_message(self, text: str) -> Static:
+        """Shows a user message submitted while a turn is still in progress
+        (ChatScreen._turn_in_progress) — deliberately does NOT reassign
+        self._current/_current_role/_current_text the way add_message does.
+        Those track whatever widget append_to_last is currently streaming
+        text into; calling add_message here (a real prior bug) would hijack
+        that target mid-stream, silently redirecting the rest of the
+        in-flight turn's own reply (or reasoning, or a tool-call preview)
+        into this new user message's widget instead of its own. The queued
+        message is only folded into session.messages once the active turn
+        actually finishes (see ChatScreen._stream_response), so this widget
+        is purely a "received, will send once ready" visual - styled via
+        message-queued rather than a plain message-user."""
+        was_at_bottom = self.is_vertical_scroll_end
+        widget = Static(classes="message message-user message-queued")
+        widget.update(self._render_message("user", text))
+        self.mount(widget)
+        self._scroll_end_if_at_bottom(was_at_bottom)
+        return widget
+
+    def append_to_last(self, fragment: str) -> None:
+        if self._current is None:
+            self.add_message("assistant", fragment)
+            return
+        self._current_text += fragment
+        if time.monotonic() - self._last_refresh >= _MIN_REFRESH_INTERVAL_S:
+            self._flush()
+        elif not self._refresh_pending:
+            self._refresh_pending = True
+            self.set_timer(_MIN_REFRESH_INTERVAL_S, self._flush)
+
+    def _flush(self) -> None:
+        self._refresh_pending = False
+        self._last_refresh = time.monotonic()
+        if self._current is None:
+            return
+        was_at_bottom = self.is_vertical_scroll_end
+        self._current.update(self._render_message(self._current_role, self._current_text))
+        self._scroll_end_if_at_bottom(was_at_bottom)
+
+    def add_tool_call(self, tool_name: str, arguments_json: str, *, purpose: str | None = None) -> None:
+        """The "→ tool_name(...)" preview shown as soon as a call is
+        dispatched, before its result is known. Known code-bearing arguments
+        (write_file's content, run_shell's command, edit_file's old/new
+        strings) are syntax-highlighted with real line breaks instead of the
+        raw, single-line-escaped JSON string; anything else falls back to
+        pretty-printed JSON. Large calls collapse behind a click, mirroring
+        add_tool_result — small/common calls (read_file, grep, ...) stay
+        visible inline."""
+        was_at_bottom = self.is_vertical_scroll_end
+        try:
+            arguments = json.loads(arguments_json or "{}")
+        except (json.JSONDecodeError, ValueError):
+            arguments = None
+        if not isinstance(arguments, dict):
+            # Malformed/non-object arguments (shouldn't normally happen -
+            # AgentLoop's own dispatch would separately reject these) - fall
+            # back to the raw string rather than crashing the render.
+            self.add_message("tool", f"→ {tool_name}({arguments_json})")
+            self._scroll_end_if_at_bottom(was_at_bottom)
+            return
+
+        # "purpose" is shown on its own line below, not mixed into the
+        # argument listing/highlighting.
+        arguments = {k: v for k, v in arguments.items() if k != "purpose"}
+        body_renderable, char_count = _format_tool_call_body(tool_name, arguments)
+
+        if char_count > _LARGE_TOOL_CALL_THRESHOLD_CHARS:
+            parts: list[RenderableType] = []
+            if purpose:
+                parts.append(Text(purpose, style="italic"))
+            parts.append(body_renderable)
+            title = f"→ {tool_name}(...) — {char_count:,} char(s)"
+            body = Static(Group(*parts), classes="tool-result-body")
+            collapsible = Collapsible(body, title=title, collapsed=True, classes="tool-call-collapsible")
+            self.mount(collapsible)
+        else:
+            parts = [Text(f"→ {tool_name}", style="bold")]
+            if purpose:
+                parts.append(Text(purpose, style="italic"))
+            parts.append(body_renderable)
+            widget = Static(Group(*parts), classes="message message-tool")
+            self.mount(widget)
+        self._scroll_end_if_at_bottom(was_at_bottom)
+
+    def add_tool_result(self, tool_name: str, output: str, *, is_error: bool) -> None:
+        """Tool results render as a collapsed-by-default Collapsible (full
+        content available on demand) rather than a fixed-length preview —
+        the previous view-layer truncation hid content that was often
+        already fully available in memory at this point. Formatting is
+        handled by _format_tool_output; this never touches self._current
+        (no ongoing streaming state to track for a tool result)."""
+        was_at_bottom = self.is_vertical_scroll_end
+        status_icon = "✗" if is_error else "✓"
+        title = f"{status_icon} {tool_name} — {len(output):,} char(s)"
+        body = Static(_format_tool_output(output), classes="tool-result-body")
+        classes = "tool-result-collapsible" + (" error" if is_error else "")
+        collapsible = Collapsible(body, title=title, collapsed=True, classes=classes)
+        self.mount(collapsible)
+        self._scroll_end_if_at_bottom(was_at_bottom)
+
+    def add_reasoning(self, text: str) -> None:
+        """A reasoning/"thinking" model's chain-of-thought (delta.reasoning_content
+        — see llm/streaming.py), rendered collapsed by default: it's the
+        model's internal monologue, not its actual answer, and can run to
+        thousands of tokens. One-shot render like add_tool_result (never
+        streamed token-by-token into the DOM) — this is secondary content,
+        and the "busy" spinner already covers the in-progress case."""
+        if not text.strip():
+            return
+        was_at_bottom = self.is_vertical_scroll_end
+        title = f"\U0001f9e0 Thinking — {len(text):,} char(s)"
+        body = Static(Text(text, no_wrap=False, overflow="fold"), classes="tool-result-body")
+        collapsible = Collapsible(body, title=title, collapsed=True, classes="reasoning-collapsible")
+        self.mount(collapsible)
+        self._scroll_end_if_at_bottom(was_at_bottom)
+
+    def finish_streaming(self) -> None:
+        self._flush()  # ensure the last throttled fragment(s) are actually shown
+        self._current = None
+        self._current_text = ""
+
+    @staticmethod
+    def _render_message(role: str, text: str) -> Group:
+        label = _ROLE_LABELS.get(role, role)
+        return Group(Text(label, style="bold"), Markdown(text or ""))

pcli/tui/widgets/paste_input.py

@@ -0,0 +1,99 @@
+"""Input subclass making paste (however it reaches the app) respect
+expand_full_paste, instead of Textual's built-in always-first-line-only
+behavior.
+
+Two independent paths can deliver a paste, and both needed fixing:
+
+1. **Terminal-intercepted paste.** Most terminals (Windows Terminal, xterm,
+   GNOME Terminal, ...) intercept Shift+Insert (and middle-click, and
+   Ctrl+Shift+V) themselves and deliver the clipboard through the
+   already-enabled bracketed-paste ANSI channel — Textual turns that into an
+   `events.Paste` message, which `Input._on_paste` handles by taking only
+   `event.text.splitlines()[0]`. This is the path that fires in practice on
+   most setups, and overriding `_on_paste` here is what actually matters.
+2. **Literal keystroke.** Any terminal that instead passes Shift+Insert
+   through as a plain keystroke leaves Textual with nothing bound to it by
+   default (Input.BINDINGS has ctrl+v, not shift+insert) — plus Textual's
+   own ctrl+v (Input.action_paste) only reads text copied *within* the app
+   (App.clipboard's docstring says explicitly it doesn't track the OS
+   clipboard), which can't help here either. The explicit shift+insert
+   binding below reads the OS clipboard directly via pyperclip as a
+   fallback for this case.
+
+Both paths funnel into the same `_apply_pasted_text`. By default
+(`expand_full_paste=False`, e.g. the sessions-import path field) only the
+first line is kept, matching Textual's own prior behavior — appropriate for
+fields that are conceptually single-value. With `expand_full_paste=True`
+(the main chat input), the *whole* paste is kept: since Input can only ever
+display one line, a multi-line paste is shown as a compact "[Pasted N
+lines]" placeholder while composing, and the real full text is substituted
+back in at submit time via `consume_pending_paste()` — the placeholder is a
+display affordance only, never the actual message content.
+"""
+
+from __future__ import annotations
+
+from typing import ClassVar
+
+import pyperclip
+from textual import events
+from textual.binding import Binding, BindingType
+from textual.widgets import Input
+
+from pcli.tui.widgets.paste_marker import PendingPaste, decide_paste
+
+
+class PasteInput(Input):
+    BINDINGS: ClassVar[list[BindingType]] = [
+        Binding("shift+insert", "paste_from_os_clipboard", "Paste", show=False),
+    ]
+
+    def __init__(self, *args, expand_full_paste: bool = False, **kwargs) -> None:
+        super().__init__(*args, **kwargs)
+        self._expand_full_paste = expand_full_paste
+        self._pending_paste = PendingPaste()
+
+    def _on_paste(self, event: events.Paste) -> None:
+        """Overrides Input's own bracketed-paste handler — see module
+        docstring: this is the path that fires for most terminals'
+        Shift+Insert (and middle-click, Ctrl+Shift+V, ...).
+
+        Textual dispatches "_on_<event>"-named handlers from *every* class
+        in the MRO independently (see MessagePump._get_dispatch_methods) —
+        this is cooperative layering, not standard method-override
+        semantics, so merely defining _on_paste here does not stop
+        Input._on_paste from *also* running right after (which would
+        insert its own first-line text a second time, right after ours).
+        event.prevent_default() is what actually suppresses it — the
+        dispatch loop checks message._no_default_action before walking
+        further up the MRO."""
+        if event.text:
+            self._apply_pasted_text(event.text)
+        event.prevent_default()
+        event.stop()
+
+    def action_paste_from_os_clipboard(self) -> None:
+        """Explicit shift+insert binding, for terminals that pass it
+        through as a literal keystroke instead of intercepting it
+        themselves (in which case _on_paste above never fires)."""
+        try:
+            text = pyperclip.paste()
+        except pyperclip.PyperclipException as exc:
+            self.notify(f"Couldn't read the system clipboard: {exc}", severity="error")
+            return
+        if text:
+            self._apply_pasted_text(text)
+
+    def _apply_pasted_text(self, text: str) -> None:
+        decision = decide_paste(text, expand_full_paste=self._expand_full_paste)
+        if decision is None:
+            return
+        if decision.pending_marker is not None:
+            self._pending_paste.set(decision.pending_marker, decision.pending_full_text)
+        start, end = self.selection
+        self.replace(decision.text_to_insert, start, end)
+
+    def consume_pending_paste(self, text: str) -> str:
+        """Expands a still-present placeholder marker back to the full
+        clipboard text it stands in for — see PendingPaste.consume."""
+        return self._pending_paste.consume(text)

pcli/tui/widgets/paste_marker.py

@@ -0,0 +1,69 @@
+"""Shared "what should a paste look like in the input box" decision, used by
+both PasteInput (Input-based) and ChatInput (TextArea-based) — the two
+widgets differ in how they actually insert text (Input.replace() takes flat
+character offsets; TextArea.replace() takes row/col Locations), but the
+placeholder/expansion behavior itself is one implementation, not two
+diverging copies.
+
+By default (expand_full_paste=False, e.g. the sessions-import path field)
+only the first line is kept, matching Textual's own Input._on_paste
+behavior — appropriate for fields that are conceptually single-value. With
+expand_full_paste=True (the main chat input), the *whole* paste is kept: a
+multi-line paste is shown as a compact "[Pasted N lines]" placeholder while
+composing (never the raw multi-line text — this is what keeps a large
+paste from growing an auto-growing input box), and the real full text is
+substituted back in at submit time via PendingPaste.consume().
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass
+class PasteDecision:
+    text_to_insert: str
+    pending_full_text: str | None = None
+    pending_marker: str | None = None
+
+
+def decide_paste(text: str, *, expand_full_paste: bool) -> PasteDecision | None:
+    """Returns None for an empty clipboard/paste (nothing to insert)."""
+    lines = text.splitlines()
+    if not lines:
+        return None
+
+    if not expand_full_paste or len(lines) <= 1:
+        line = lines[0]
+        if not line:
+            return None
+        return PasteDecision(text_to_insert=line)
+
+    marker = f"[Pasted {len(lines)} lines]"
+    return PasteDecision(text_to_insert=marker, pending_full_text=text, pending_marker=marker)
+
+
+class PendingPaste:
+    """Tracks a still-composing placeholder marker and the full text it
+    stands in for, until consume() expands it back at submit time (or the
+    marker gets edited away, in which case consume() is a no-op)."""
+
+    def __init__(self) -> None:
+        self._text: str | None = None
+        self._marker: str | None = None
+
+    def set(self, marker: str, full_text: str) -> None:
+        self._marker = marker
+        self._text = full_text
+
+    def consume(self, text: str) -> str:
+        """Expands a still-present placeholder marker back to the full
+        text it stands in for. Always clears the pending state — a
+        submitted turn resets it either way, so an edited-away or
+        already-used marker can't leak into a later, unrelated paste."""
+        pending_text, marker = self._text, self._marker
+        self._text = None
+        self._marker = None
+        if pending_text is not None and marker is not None and marker in text:
+            return text.replace(marker, pending_text)
+        return text

pcli/tui/widgets/status_bar.py

@@ -0,0 +1,133 @@
+"""Live cost/context/model/sandbox status line. Grows to a second line only
+while a subagent is running (see spawn_subagent) — collapses back to one
+line once it finishes."""
+
+from __future__ import annotations
+
+from textual.reactive import reactive
+from textual.widgets import Static
+
+from pcli.util.text import truncate
+
+# Classic braille "circling" spinner frames.
+_SPINNER_FRAMES = "⠋⠙⠹⠸⠼⠴⠦⠧⠇⠏"
+# Ticked only while busy, and well under the ~20fps ceiling that keeps
+# repaints smooth on slower (e.g. VTE-based Linux) terminal renderers.
+_SPINNER_INTERVAL_S = 0.1
+
+
+def format_token_count(n: int) -> str:
+    if n >= 1_000_000:
+        return f"{n / 1_000_000:.1f}m"
+    if n >= 1_000:
+        return f"{n / 1_000:.1f}k"
+    return str(n)
+
+
+_MODEL_NAME_MAX_LEN = 40
+
+
+def format_model_name(model: str) -> str:
+    """Shortens an overly long model identifier for the status bar -
+    notably a full local file path, which a raw llama-server instance with
+    no --alias configured reports as its own "model" id (unlike LM Studio's
+    short, friendly names) - e.g. "E:\\...\\Mistral-Nemo-Instruct-2407-
+    Q4_K_M.gguf" down to "Mistral-Nemo-Instruct-2407-Q4_K_M". Only the
+    display is shortened; the underlying model string used for actual
+    requests is untouched. Falls back to plain truncation for anything
+    else still too long to fit the line."""
+    name = model
+    if "/" in name or "\\" in name:
+        name = name.replace("\\", "/").rsplit("/", 1)[-1]
+        if name.lower().endswith(".gguf"):
+            name = name[: -len(".gguf")]
+    return truncate(name, _MODEL_NAME_MAX_LEN)
+
+
+class StatusBar(Static):
+    model: reactive[str] = reactive("")
+    session_cost_usd: reactive[float] = reactive(0.0)
+    total_tokens: reactive[int] = reactive(0)
+    context_used_tokens: reactive[int] = reactive(0)
+    context_limit_tokens: reactive[int] = reactive(0)
+    sandbox_backend: reactive[str] = reactive("n/a")
+    # True for the whole duration the agent is working on a turn (waiting on
+    # the LLM, streaming its reply, running tool calls, ...) — cleared only
+    # once the response has been fully printed.
+    busy: reactive[bool] = reactive(False)
+    # The main agent's own top-level tool-call count for the current turn -
+    # reset to 0 at the start of each turn (see ChatScreen._run_one_turn),
+    # incremented on each of its own tool_result chunks. Deliberately
+    # separate from subagent_tool_calls below: a subagent's internal calls
+    # are its own isolated count, not part of this one (spawn_subagent
+    # itself counts here as a single call).
+    main_tool_calls: reactive[int] = reactive(0)
+    # guardrails.max_tool_calls_per_turn as of the start of the current turn
+    # (re-read fresh each turn, since it's live-editable via /max-tool-calls
+    # -per-turn) - the denominator for the "n/N" display below. 0 means
+    # unlimited (same convention the guardrail itself uses, e.g. local-api
+    # mode), in which case only "n" is shown - there's no N to divide by.
+    main_tool_calls_limit: reactive[int] = reactive(0)
+    # Second line, shown only while non-None: a running subagent's progress.
+    subagent_task: reactive[str | None] = reactive(None)
+    subagent_tool_calls: reactive[int] = reactive(0)
+    subagent_last_tool: reactive[str | None] = reactive(None)
+    # True while /plan is active (see ChatScreen) — read/explore tools only.
+    plan_mode: reactive[bool] = reactive(False)
+
+    def __init__(self, *args, **kwargs) -> None:
+        super().__init__(*args, **kwargs)
+        self._spinner_index = 0
+
+    def on_mount(self) -> None:
+        self.set_interval(_SPINNER_INTERVAL_S, self._advance_spinner)
+        self._sync_height()
+
+    def watch_subagent_task(self, _task: str | None) -> None:
+        self._sync_height()
+
+    def _sync_height(self) -> None:
+        self.styles.height = 2 if self.subagent_task is not None else 1
+
+    def _advance_spinner(self) -> None:
+        if not self.busy:
+            return
+        self._spinner_index = (self._spinner_index + 1) % len(_SPINNER_FRAMES)
+        self.refresh()
+
+    def _render_line1(self) -> str:
+        context_part = ""
+        if self.context_limit_tokens:
+            pct = 100 * self.context_used_tokens / self.context_limit_tokens
+            context_part = (
+                f"ctx: {format_token_count(self.context_used_tokens)}/"
+                f"{format_token_count(self.context_limit_tokens)} ({pct:.0f}%)   "
+            )
+        spinner_part = f"{_SPINNER_FRAMES[self._spinner_index]} Working...   " if self.busy else ""
+        plan_part = "[PLAN MODE]   " if self.plan_mode else ""
+        tools_part = (
+            f"{self.main_tool_calls}/{self.main_tool_calls_limit}"
+            if self.main_tool_calls_limit > 0
+            else str(self.main_tool_calls)
+        )
+        return (
+            f"{plan_part}"
+            f"{spinner_part}"
+            f"model: {format_model_name(self.model) if self.model else '-'}   "
+            f"cost: ${self.session_cost_usd:.4f}   "
+            f"{context_part}"
+            f"tokens: {format_token_count(self.total_tokens)}   "
+            f"tools: {tools_part}   "
+            f"sandbox: {self.sandbox_backend}"
+        )
+
+    def render(self) -> str:
+        line1 = self._render_line1()
+        if self.subagent_task is None:
+            return line1
+        detail = f", last: {self.subagent_last_tool}" if self.subagent_last_tool else ""
+        line2 = (
+            f"⟳ Subagent: {truncate(self.subagent_task, 60)} "
+            f"— {self.subagent_tool_calls} tool call(s){detail}"
+        )
+        return f"{line1}\n{line2}"