presenter.py

Go to the documentation of this file.

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# oc_ui/terminal/presenter.py
 
"""
Plain-ANSI console presenter for OC Chat.
 
Purpose
-------
:class:`ConsolePresenter` implements the
:class:`~oc_ui.presenter_base.Presenter` contract using simple
``print`` calls and ANSI escape codes from
:mod:`oc_chat.core.config`. It is the default presenter and the
fallback used by CI, headless runs, and any environment without
optional ``rich`` / ``textual`` dependencies installed.
 
The Phase 0 quick wins live here:
 
- Horizontal rule + turn number + timestamp at :meth:`start_turn`.
- :meth:`show_waiting` indicator that is cleared by the first
  reasoning / content chunk.
- Compact :meth:`show_turn_summary` (one dim line) — full
  per-iteration breakdown only when ``verbose`` is set.
- ``NO_COLOR`` / ``FORCE_COLOR`` honoured via the STYLE_* constants
  in :mod:`oc_chat.core.config`.
 
Responsibilities
----------------
- :class:`ConsolePresenter` — concrete :class:`Presenter`
  implementation backed by ``print``.
- :func:`_color_enabled` — env-var-based ANSI gating.
- All ``show_*`` event hooks for reasoning / content / tool / usage
  / turn-summary / compressed / welcome.
- :meth:`turn` returns a no-op ``contextmanager`` (no live region).
 
Diagnostics
-----------
Domain: OC_UI.TERMINAL
Levels:
    L2 — lifecycle events
    L3 — semantic details
    L4 — deep tracing
 
Contracts
---------
- Output goes to ``stdout`` exclusively; diagnostics and warnings
  live on ``stderr`` via ``oc_diagnostics``.
- ``NO_COLOR`` set (any value) disables every ANSI sequence.
- ``FORCE_COLOR`` overrides ``NO_COLOR`` and forces ANSI on.
- ``show_*`` hooks are append-only — the presenter never rewinds.
- Safe to use under CI / non-TTY: ``shutil.get_terminal_size`` is
  used with a fallback when the size is undetermined.
 
Dependencies
------------
- oc_diagnostics (structured debug logging via _dbg)
- oc_ui.presenter_base (Presenter ABC contract)
- oc_ui.terminal.activity (plan_progress_from_result for the plan progress line under planner results)
- oc_ui.terminal.diffview (mutation argument pairing and plain unified diff rendering for write_file and edit_file)
- oc_ui.terminal.turn_layout (turn indent, rule labels, answer box markers and line indenters)
- oc_chat.core.commands (lazy; _fmt_tokens_display for the session list table)
- oc_chat.core.formatting (lazy; format_duration for the turn summary)
- oc_chat.core.iteration_stat (lazy; iteration_stat_human_line for the per-iteration stats line)
- oc_chat.core.session (lazy; ChatSession type hint for show_welcome)
- oc_ui.terminal.statusline (lazy; StatusBarState type hint for bind_status)
"""
from __future__ import annotations
 
import json
import shutil
from contextlib import contextmanager
from datetime import datetime
from typing import TYPE_CHECKING, Callable, Iterator
 
from oc_diagnostics import _dbg
 
from oc_ui.presenter_base import Presenter, SpinnerHandle
from oc_ui.terminal.activity import plan_progress_from_result
from oc_ui.terminal.diffview import (
    MutationArgsLedger,
    build_mutation_diff,
    render_diff_plain,
    summarize_mutation_call,
)
from oc_ui.terminal.turn_layout import (
    ANSWER_BOX_TITLE,
    PLAIN_RULE_FILL,
    REASONING_TITLE,
    TURN_INDENT,
    LineIndenter,
    plain_box_bottom,
    plain_box_top,
    rule_fits,
    rule_line,
    running_total_text,
    start_rule_label,
    turn_end_rule_label,
    turn_rule_label,
)
 
if TYPE_CHECKING:
    from oc_chat.core.session import ChatSession
    from oc_ui.terminal.statusline import StatusBarState
 
# Define styles locally to avoid circular dependency
def _color_enabled() -> bool:
    """Return True iff ANSI styles should be emitted."""
    import os
    if os.getenv("FORCE_COLOR"):
        return True
    if os.getenv("NO_COLOR") is not None:
        return False
    return True
 
_COLOR = _color_enabled()
STYLE_RESET  = "\033[0m"  if _COLOR else ""
STYLE_DIM    = "\033[2m"  if _COLOR else ""
STYLE_ITALIC = "\033[3m"  if _COLOR else ""
STYLE_BOLD   = "\033[1m"  if _COLOR else ""
STYLE_CYAN   = "\033[36m" if _COLOR else ""
STYLE_YELLOW = "\033[33m" if _COLOR else ""
STYLE_GREEN  = "\033[32m" if _COLOR else ""
STYLE_RED    = "\033[31m" if _COLOR else ""
REASONING_EFFORT_LEVELS = ["low", "medium", "high"]
 
 
class ConsolePresenter(Presenter):
    """Terminal UI presenter using plain ANSI escape codes.
 
    Always satisfies the :class:`Presenter` contract with no optional
    dependencies.  Suitable for CI, headless servers, and any environment
    where Rich/Textual aren't appropriate.
 
    *verbose* (default ``False``) controls whether per-iteration
    :meth:`show_usage` is emitted.  When ``False``, only the compact turn
    summary is printed at the end of each turn.
    """
 
    def __init__(self, verbose: bool = False) -> None:
        self._reasoning_shown = False
        self._content_shown = False
        self._waiting_shown = False
        self._turn_number = 0
        self.verbose = verbose
        # Plan 188 T1: pairs a mutation tool's call arguments with its result so
        # ``show_tool_result`` can render a diff instead of truncated JSON.
        self._mutation_args = MutationArgsLedger()
        # Plan 218: turn-scoped layout state. ``_in_turn`` gates the indent;
        # ``_answer_open`` marks a degraded answer box awaiting its closing
        # marker; the indenters buffer partial streamed lines so the indent
        # lands at line starts and never mid-sentence.
        self._in_turn = False
        self._answer_open = False
        self._content_indenter = LineIndenter()
        self._reasoning_indenter = LineIndenter()
        self._status_provider: Callable[[], "StatusBarState | None"] | None = None
 
    # ── Turn-scoped layout helpers (Plan 218) ──────────────────────────────
 
    def bind_status(self, provider: Callable[[], "StatusBarState | None"]) -> None:
        """Store the status-snapshot provider (plan 147 D1 / plan 218 T2).
 
        The plain console has no live chrome to refresh, so this was a
        no-op before plan 218. It now keeps the provider because the
        turn-end rule's running total is read from that snapshot — the
        plain presenter must be able to show the same two numbers the
        rich one does, not a degraded rule missing them.
        """
        self._status_provider = provider
 
    @staticmethod
    def _width() -> int:
        """Terminal width, with the module's long-standing 80x24 fallback."""
        return max(20, shutil.get_terminal_size((80, 24)).columns)
 
    def _now_ts(self) -> str:
        """Wall-clock ``HH:MM:SS`` for the rule labels — the one clock read."""
        return datetime.now().strftime("%H:%M:%S")
 
    def _indent(self) -> str:
        """The turn indent while a turn is open; nothing outside one."""
        return TURN_INDENT if self._in_turn else ""
 
    def _print_rule(self, label: "str | list[tuple[str, str]]",
                    trailer: str = "") -> None:
        """Print the two-line plain separator: full rule, then the label line.
 
        Structure and both style tokens are exactly the pre-218 ones; only
        the label's CONTENT grows (plan 218 P1 element 4) and the trailer
        is new. The label line keeps its ``·`` fill.
        """
        width = self._width()
        print(f"\n{STYLE_DIM}{'─' * width}{STYLE_RESET}")
        print(f"{STYLE_DIM}"
              f"{rule_line(label, width, trailer, PLAIN_RULE_FILL)}"
              f"{STYLE_RESET}")
 
    def _running_total(self) -> str:
        """The ``↻ total · turn / session`` trailer, or ``""`` when unknown.
 
        Same contract as the rich presenter's: read off the bound status
        snapshot, add this turn to the session figure (``finish_turn``
        folds it in only after the summary renders), and render NOTHING
        rather than a zero when no provider is bound.
        """
        func = "_running_total"
        if self._status_provider is None:
            return ""
        try:
            state = self._status_provider()
        except Exception as exc:
            # EXTERNAL_ERROR — a caller-supplied provider misbehaved; the
            # rule renders without its trailer rather than failing the turn.
            _dbg("OC_UI.TERMINAL", func,
                 f"EXTERNAL_ERROR: {type(exc).__name__}: {exc}", 2, override=True)
            return ""
        if state is None:
            return ""
        return running_total_text(state.turn_tokens,
                                  state.session_tokens + state.turn_tokens)
 
    def _close_answer_box(self, subtitle: str = "", error: str = "") -> None:
        """Emit the degraded box's closing marker (plan 218 P2/W5).
 
        Called from every hook that can follow the answer, so the box is
        closed before anything that logically comes after it prints — and
        it is closed on the error path too, carrying the failure text
        inside. Idempotent: a second call with no open box does nothing.
        """
        if not self._answer_open:
            return
        self._answer_open = False
        for line in self._content_indenter.flush():
            print(line)
        if error:
            print(f"{TURN_INDENT}{STYLE_RED}{error}{STYLE_RESET}")
        marker = plain_box_bottom(self._width() - len(TURN_INDENT), subtitle,
                                  indent="")
        print(f"{TURN_INDENT}{STYLE_DIM}{marker}{STYLE_RESET}")
 
    # ── Per-turn lifecycle ─────────────────────────────────────────────────
 
    def show_session_start(self) -> None:
        """Draw the ``start @ <time>`` rule that opens the session (P1.1)."""
        self._print_rule(start_rule_label(self._now_ts()))
 
    @contextmanager
    def turn(self) -> Iterator[None]:
        """Context manager wrapping the streamed portion of a turn.
 
        The plain console has no Live region — every chunk prints as it
        arrives — but plan 218 P2 still needs the answer box CLOSED on
        every exit path, so the teardown does that here rather than
        relying on a later hook that an exception may never reach.
        """
        try:
            yield
        except Exception as exc:
            # Plan 218 P2/W2: close the box with the failure inside it, so
            # no opening marker is ever left dangling.
            self._close_answer_box(error=f"{type(exc).__name__}: {exc}")
            raise
        finally:
            # Belt-and-braces: if a turn ended without clearing the waiting
            # indicator, clear it now so it doesn't pollute the next prompt.
            if self._waiting_shown:
                self._clear_waiting()
 
    def start_turn(self) -> None:
        """Reset per-turn flags and print the turn separator."""
        func = "start_turn"
        _dbg("OC_UI.TERMINAL", func, f"turn={self._turn_number + 1}", 4)
        self._close_answer_box()
        self._reasoning_shown = False
        self._content_shown = False
        self._waiting_shown = False
        self._turn_number += 1
        # Plan 188 T1: a tool call announced but never resulted (an exception
        # mid-dispatch) must not pair with a later call's result.
        self._mutation_args.clear()
 
        # Plan 218: the rule closes the previous region and opens the turn
        # body, so the indent starts AFTER it is drawn.
        self._in_turn = False
        self._print_rule(turn_rule_label(self._turn_number, self._now_ts()))
        self._in_turn = True
 
    def end_turn(self) -> None:
        """Finalise the current turn (trailing newline)."""
        self._close_answer_box()
        if self._waiting_shown:
            self._clear_waiting()
        self._in_turn = False
        print()  # newline after streamed response
 
    # ── Streaming events ──────────────────────────────────────────────────
 
    def show_waiting(self) -> None:
        """Print a transient "Thinking…" indicator before the first chunk."""
        # Use a distinguishable prefix and dim style; cleared by first chunk.
        print(f"{STYLE_DIM}{STYLE_ITALIC}⏳ Thinking…{STYLE_RESET}",
              end="", flush=True)
        self._waiting_shown = True
 
    def _clear_waiting(self) -> None:
        """Erase the in-line waiting indicator with carriage-return + spaces."""
        # Width 20 covers '⏳ Thinking…' plus a margin.
        print("\r" + " " * 20 + "\r", end="", flush=True)
        self._waiting_shown = False
 
    def show_reasoning(self, text: str) -> None:
        """Print chain-of-thought (reasoning) text as it streams.
 
        Plan 218: line-buffered so the turn indent lands at line starts —
        a chunk that stops mid-sentence waits for its newline rather than
        splicing three spaces into the middle of a word.
        """
        if self._waiting_shown:
            self._clear_waiting()
        if not self._reasoning_shown:
            print(f"{self._indent()}{STYLE_CYAN}{REASONING_TITLE}{STYLE_RESET}")
            self._reasoning_shown = True
        for line in self._reasoning_indenter.feed(text):
            print(f"{STYLE_DIM}{STYLE_ITALIC}{line}{STYLE_RESET}", flush=True)
 
    def show_content(self, text: str) -> None:
        """Stream the answer inside the degraded (glyph-free) answer box.
 
        Plan 218 P2/P4: the opening marker prints with the first chunk,
        each completed line prints indented as it lands, and the closing
        marker — carrying the iteration metadata — prints at turn end via
        :meth:`_close_answer_box`. No box-drawing glyph is used, so a dumb
        terminal renders the same information faithfully (W5).
        """
        if self._waiting_shown:
            self._clear_waiting()
        if not self._content_shown:
            for line in self._reasoning_indenter.flush():
                print(f"{STYLE_DIM}{STYLE_ITALIC}{line}{STYLE_RESET}")
            if self._reasoning_shown:
                print()   # blank separator
            marker = plain_box_top(self._width() - len(TURN_INDENT), indent="")
            print(f"{TURN_INDENT}{STYLE_BOLD}{marker}{STYLE_RESET}")
            self._content_shown = True
            self._answer_open = True
        for line in self._content_indenter.feed(text):
            print(line, flush=True)
 
    # ── Tools ─────────────────────────────────────────────────────────────
 
    def show_tool_call(self, name: str, arguments: str) -> None:
        """Display a tool-call invocation with pretty-printed arguments."""
        func = "show_tool_call"
        self._close_answer_box()
        if self._waiting_shown:
            self._clear_waiting()
        try:
            args_pretty = json.dumps(json.loads(arguments or "{}"), ensure_ascii=False)
        except (json.JSONDecodeError, ValueError) as e:
            # VALIDATION_ERROR — model emitted non-JSON tool args; render raw string
            _dbg("OC_UI.TERMINAL", func, f"VALIDATION_ERROR: {type(e).__name__}: {e}", 3)
            args_pretty = arguments
        # Plan 188 T1: remember mutation-tool arguments for the diff render that
        # follows in show_tool_result, and elide the bulky payload here (the
        # diff below IS the content view). Both no-ops for every other tool.
        self._mutation_args.record(name, arguments)
        args_pretty = summarize_mutation_call(name, arguments) or args_pretty
        print(f"\n{self._indent()}{STYLE_YELLOW}"
              f"[Tool call → {name}({args_pretty})]{STYLE_RESET}")
 
    def show_tool_progress(self, name: str) -> None:
        """No-op for the plain console; rich/textual presenters spin here."""
        # Plain console has no animation primitive; the show_tool_call line
        # is enough indication that the tool is running.
 
    def show_tool_result(self, name: str, result: object) -> None:
        """Display the result of a tool call (truncated if > 400 chars).
 
        Plan 188 T1: an applied ``write_file`` / ``edit_file`` renders as a
        plain unified diff (ANSI-coloured when colour is enabled) instead of
        the truncated JSON line. Everything else — every other tool, and any
        mutation result that is an error, a gate block, or an unpaired call —
        keeps the legacy rendering exactly.
 
        If *result* is a ``requires_confirmation`` dict (from Tier-2
        shell commands), it is displayed as a warning prompt.
        """
        self._close_answer_box()
        indent = self._indent()
        if isinstance(result, dict) and result.get("requires_confirmation"):
            msg = result.get("message", str(result))
            print(f"{indent}{STYLE_YELLOW}"
                  f"[⏳ Confirmation required — {msg}]{STYLE_RESET}")
            return
 
        diff = build_mutation_diff(name, self._mutation_args.take(name), result)
        if diff is not None:
            for line in render_diff_plain(diff, color=_COLOR):
                print(f"{indent}{line}")
            return
 
        result_str = json.dumps(result, ensure_ascii=False)
        if len(result_str) > 400:
            result_str = result_str[:400] + "…"
        print(f"{indent}{STYLE_GREEN}[{name} ← {result_str}]{STYLE_RESET}")
 
        # Plan 188 T2 — the plan lane: a planner tool just changed plan state,
        # so show the REPL's current progress underneath its result.
        progress = plan_progress_from_result(name, result)
        if progress:
            self.show_activity("plan", progress)
 
    # ── Activity lane (Plan 188 T2) ───────────────────────────────────────
 
    #: Tone → ANSI style. An unknown tone renders neutral (never raises).
    _ACTIVITY_STYLES = {
        "info": STYLE_DIM,
        "ok": STYLE_GREEN,
        "warn": STYLE_YELLOW,
        "error": STYLE_RED,
    }
 
    def show_activity(self, label: str, detail: str = "", *, tone: str = "info") -> None:
        """Print a compact one-line state update for a non-streaming lane."""
        self._close_answer_box()
        style = self._ACTIVITY_STYLES.get(tone, "")
        body = f" {detail}" if detail else ""
        print(f"{self._indent()}{style}[{label}]{STYLE_RESET}"
              f"{STYLE_DIM}{body}{STYLE_RESET}")
 
    # ── Stats ─────────────────────────────────────────────────────────────
 
    @staticmethod
    def _fmt_usage_line(label: str, prompt: int, completion: int, total: int,
                        prompt_cached=None, reasoning=None, content=None) -> str:
        """Build a one-line usage summary string."""
        parts = [f"{label}:  prompt={prompt}"]
        if prompt_cached is not None:
            parts.append(f"(cache hits: {prompt_cached})")
        parts.append(f"  completion={completion}")
        if reasoning is not None and content is not None:
            parts.append(f"(reasoning:{reasoning} content:{content})")
        parts.append(f"  total={total}")
        return "".join(parts)
 
    def show_usage(self, usage: dict) -> None:
        """Per-iteration token usage — compact one-line format.
 
        Plan 134 C1: render only in ``--verbose`` mode (restores the contract
        this class's own docstring already promised). Terminal rendering only;
        structured emission/logging is unaffected.
        """
        self._close_answer_box()
        if not self.verbose:
            return
        prompt     = usage.get("prompt_tokens", 0)
        completion = usage.get("completion_tokens", 0)
        total      = usage.get("total_tokens", 0)
        prompt_cached = None
        if usage.get("prompt_tokens_details"):
            pd = usage["prompt_tokens_details"]
            if isinstance(pd, dict):
                prompt_cached = pd.get("cached_tokens")
 
        cached = ""
        if prompt_cached:
            cached = self._fmt_compact_tokens(prompt_cached)
            cached = f" · cache:{cached}"
 
        line = (
            f"{self._indent()}{STYLE_DIM}  prompt:{self._fmt_compact_tokens(prompt)}"
            f" · completion:{self._fmt_compact_tokens(completion)}"
            f" · total:{self._fmt_compact_tokens(total)}"
            f"{cached}{STYLE_RESET}"
        )
        print(line)
 
    def show_iteration_stat(self, stat: "IterationStat") -> None:
        """Render the per-iteration stats — in the answer box's closing marker.
 
        Plan 218 P1 element 3, degraded per P4: when this iteration
        produced an answer, the stat line IS the box's closing marker.
        An iteration with no answer (a pure tool-call round) has no box to
        close, so the line renders as before, just carrying the indent.
        """
        from oc_chat.core.iteration_stat import iteration_stat_human_line
        line = iteration_stat_human_line(stat)
        if self._answer_open:
            self._close_answer_box(subtitle=line)
            return
        print(f"{self._indent()}{STYLE_DIM}{line}{STYLE_RESET}")
 
    @staticmethod
    def _fmt_compact_tokens(n: int) -> str:
        """Render a token count compactly (``12.4k`` / ``1.6M``)."""
        if n >= 1_000_000:
            return f"{n / 1_000_000:.2f}M"
        if n >= 1_000:
            return f"{n / 1_000:.1f}k"
        return str(n)
 
    def show_turn_summary(self, prompt: int, completion: int, total: int,
                          iterations: int, tool_calls: int,
                          prompt_cached: int | None = None, *,
                          cache_hit_pct: float | None = None,
                          cache_saved_tokens: int | None = None,
                          performance_stats: object = None,
                          model: str | None = None,
                          context_used_pct: float | None = None,
                          duration_ms: int | None = None,
                          turn_cost: object = None) -> None:
        """Print the end-of-turn rule, with the turn stats absorbed into it.
 
        Plan 218 P1 element 4: the stats string that used to occupy its own
        line under the rule is now part of the rule's label, and the
        running total rides in the right-hand fill run. Wording and both
        style tokens are unchanged \u2014 only the position is (P3).
 
        Plan 188 T4: when *turn_cost* is present the compact line gains a
        ``~$`` estimate; when it is ``None`` no cost is rendered at all (an
        unpriceable turn shows nothing rather than a wrong figure). The
        price table's capture date is appended in verbose mode, where the
        provenance is worth the width.
        """
        self._close_answer_box()
        self._in_turn = False
 
        cached_str = ""
        if prompt_cached is not None and prompt_cached > 0:
            cached_str = f" \u00b7 cache:{self._fmt_compact_tokens(prompt_cached)}"
        # Plan 134 C2: honest labels \u2014 cache-hit ratio vs real context saturation.
        cache_hit_str = ""
        if cache_hit_pct is not None:
            cache_hit_str = f" \u00b7 cache-hit:{cache_hit_pct:.0f}%"
        ctx_str = ""
        if context_used_pct is not None:
            ctx_str = f" \u00b7 ctx:{context_used_pct:.0f}%"
            if model:
                ctx_str += f" of {model}"
        duration_str = ""
        if duration_ms is not None:
            from oc_chat.core.formatting import format_duration
            duration_str = f" \u00b7 {format_duration(duration_ms)}"
        cost_str = self._fmt_turn_cost(turn_cost, verbose=self.verbose)
        stats = (
            f"  this turn: prompt:{self._fmt_compact_tokens(prompt)}"
            f" \u00b7 completion:{self._fmt_compact_tokens(completion)}"
            f" \u00b7 total:{self._fmt_compact_tokens(total)}"
            f"{cached_str}{cache_hit_str}{ctx_str}{duration_str}{cost_str}"
        )
        ts = self._now_ts()
        absorbed = turn_end_rule_label(self._turn_number, ts, stats)
        if rule_fits(absorbed, self._width()):
            self._print_rule(absorbed, trailer=self._running_total())
            return
        # Terminal too narrow to absorb the stats — degrade to the pre-218
        # two-line form rather than let the rule wrap.
        self._print_rule(turn_end_rule_label(self._turn_number, ts))
        print(f"{STYLE_DIM}{stats}{STYLE_RESET}")
 
    @staticmethod
    def _fmt_turn_cost(turn_cost: object, *, verbose: bool = False) -> str:
        """Format the plan 188 T4 cost segment, or ``""`` when unpriceable.
 
        Shared by every terminal presenter (Rich subclasses reuse it) so the
        honesty markers cannot drift apart: the leading ``~`` says modelled,
        not billed, and verbose adds the rate table's capture date.
        """
        total = getattr(turn_cost, "total_usd", None)
        if total is None:
            return ""
        out = f" \u00b7 ~${total:.4f}"
        as_of = getattr(turn_cost, "as_of", "")
        if verbose and as_of:
            out += f" (prices as of {as_of})"
        return out
 
    def show_welcome(self, session: ChatSession) -> None:
        """Display the welcome banner with model info and available commands."""
        print(f"\nChat with DeepSeek — model: {session.model}")
        print(f"Reasoning effort: {session.reasoning_effort}  "
              f"(options: {', '.join(REASONING_EFFORT_LEVELS)})")
        # print("Commands: /help  /models  /model <name>  /pro  /flash  /effort [level]")
        # print("          /system [prompt]  /ls [-r] [path]  /read <file>  /context <file>")
        # print("          /session <subcommand>  /ui <subcommand>  /goal <task>  /status  /stop  /exit")
        print("Type /help for full command details and session subcommands.")
        print("-" * 60)
 
    def show_available_models(self, models: dict) -> None:
        """Print a table of available models with capability indicators."""
        print("\nAvailable models:")
        for name, caps in models.items():
            thinking = "✓" if caps.get("supports_thinking") else "✗"
            reasoning = "✓" if caps.get("supports_reasoning") else "✗"
            tools = "✓" if caps.get("supports_tools", True) else "✗"
            print(f"  {name:<25} thinking:{thinking}  reasoning:{reasoning}  tools:{tools}")
        print()
 
    def show_session_list(self, sessions: list, current_name: str | None = None) -> None:
        """Print the saved-sessions table for ``/session list``."""
        if not sessions:
            print("(no saved sessions)")
            return
        from oc_chat.core.commands import _fmt_tokens_display
 
        header = (
            f"{'Name':<30} {'Model':<22} {'Msgs':>4} {'Tools':>5} "
            f"{'Tokens':>10}  Last Modified"
        )
        print(f"\n{header}")
        print("-" * 90)
        for s in sessions:
            marker = "*" if s["name"] == current_name else " "
            stats = s["stats"]
            tokens_str = _fmt_tokens_display(stats)
            print(
                f"{marker}{s['name']:<29} {s['model']:<22} "
                f"{stats.message_count:>4} {stats.tool_call_count:>5} "
                f"{tokens_str:>10}  {s['last_modified']}"
            )
        print()
 
    def show_help(self, command_help: dict, tools: list[str] | None = None) -> None:
        """Print the ``/help`` listing of slash commands and registered tools."""
        print("\nCommands:")
        for line in command_help.values():
            print(f"  {line}")
        if tools:
            print("\nAgent tools (callable by the model via tool-use):")
            for name in tools:
                print(f"  {name}")
        print()
 
    def show_compressed(self) -> None:
        """Notify the user that context compression just occurred."""
        self._close_answer_box()
        print(f"\n{self._indent()}{STYLE_DIM}"
              f"[Context compressed — older messages summarised]{STYLE_RESET}")
 
    def show_error(self, msg: str) -> None:
        """Display an error message in red."""
        self._close_answer_box()
        print(f"\n{self._indent()}{STYLE_RED}Error: {msg}{STYLE_RESET}")
 
    def show_info(self, msg: str) -> None:
        """Display an informational message."""
        self._close_answer_box()
        print(f"\n{self._indent()}{msg}")
 
    # ── Progress spinner (Phase H.4) ──────────────────────────────────────
 
    def spinner_start(self, label: str) -> SpinnerHandle:
        """No-op on the plain console — returns a handle with ``status=None``."""
        return SpinnerHandle(status=None)
 
    def spinner_stop(self, handle: SpinnerHandle) -> None:
        """No-op on the plain console."""
        return None