presenter_base.py

Go to the documentation of this file.

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# oc_ui/presenter_base.py
 
"""
Presenter contract — the abstract interface every presenter must satisfy.
 
Purpose
-------
A *presenter* is everything OC Chat knows about how to render the
chat to a human. The contract is intentionally minimal and procedural
so that:
 
- :class:`~oc_ui.terminal.presenter.ConsolePresenter` (plain ANSI)
  can satisfy it with simple ``print`` calls.
- A future ``RichPresenter`` (Phase 1) can satisfy the same interface
  using ``rich.live.Live`` to render token-by-token streaming inside
  a borderless region without scrolling history off screen.
- A future ``TextualPresenter`` (Phase 3) can satisfy it via async
  widgets.
 
The single non-trivial method is :meth:`Presenter.turn`: it returns
a context manager wrapping a chat turn so streaming presenters have
an unambiguous place to open and close their live region.
``ConsolePresenter`` implements it as a no-op contextmanager.
 
See ``oc_chat/docs/Terminal_and_UI_design (Synthesis).md`` for the
full rationale and ``oc_chat/docs/Terminal_and_UI_design
(Implementation Plan).md`` for the multi-phase rollout this contract
enables.
 
Responsibilities
----------------
- :class:`Presenter` — abstract base with the per-turn lifecycle
  hooks (``start_turn`` / ``turn`` contextmanager / ``end_turn``)
  and event hooks (``show_reasoning``, ``show_content``,
  ``show_tool_call``, ``show_tool_result``, ``show_usage``,
  ``show_turn_summary``, ``show_compressed``, ``show_welcome``,
  etc.).
- Document the streaming-event contract so subclasses don't have to
  guess about ordering or completion.
 
Diagnostics
-----------
Domain: OC_UI.TERMINAL
Levels:
    L2 — lifecycle events
    L3 — semantic details
    L4 — deep tracing
 
Contracts
---------
- All hooks are ``@abstractmethod`` — subclasses must implement them.
- Implementations must be safe to call from a single thread; any
  presenter that wants to support background streaming must
  serialise internally.
- ``turn()`` always returns a context manager, even if it's a no-op.
- ``show_content`` / ``show_reasoning`` chunks are append-only — the
  presenter never sees a "rewind" event.
 
Dependencies
------------
- oc_diagnostics (structured debug logging via _dbg)
- oc_chat.core.session (lazy; ChatSession, for type checking the show_welcome session argument)
- oc_ui.terminal.statusline (lazy; StatusBarState, for type checking the bind_status provider)
 
See Also
--------
oc_chat/docs/conventions/CONTRACTS.md §2.3 Presenter — owner of the 19-method
presenter ABC pinned by tests/unit/test_presenter_contract.py.
"""
from __future__ import annotations
 
from abc import ABC, abstractmethod
from contextlib import AbstractContextManager
from dataclasses import dataclass
from typing import TYPE_CHECKING
 
from oc_diagnostics import _dbg
 
if TYPE_CHECKING:
    from typing import Callable
 
    from oc_chat.core.session import ChatSession
    from oc_ui.terminal.statusline import StatusBarState
 
_dbg("OC_UI.TERMINAL", "module", "loaded", 4)
 
 
#: Plan 188 T5 — the two-stage Ctrl+C notices, owned here so every presenter
#: says the same thing on the same stream discipline. Both are single strings
#: written in ONE call: :meth:`Presenter.show_interrupt_notice` runs inside a
#: signal handler, where a multi-write render could interleave with whatever
#: the main thread was printing.
INTERRUPT_NOTICES: dict[str, str] = {
    "cancel": "\n[Ctrl+C — will ask to stop at the next safe point; the "
              "current tool keeps running. Ctrl+C again to force-stop now]\n",
    "force": "\n[Ctrl+C — forcing stop…]\n",
}
 
 
@dataclass
class SpinnerHandle:
    """Opaque handle returned by :meth:`Presenter.spinner_start`.
 
    Holds a backend object that knows how to render the spinner (typically
    a ``rich.status.Status`` instance for :class:`RichPresenter`). For
    presenters that cannot render an animated spinner (plain console,
    headless CI, JSON-lines logger), the ``status`` field is ``None`` and
    :meth:`Presenter.spinner_stop` is a no-op.
 
    Stored as :class:`object` rather than the concrete Rich type so this
    module does not require ``rich`` to be importable.
    """
 
    status: object | None = None
 
 
class Presenter(ABC):
    """Abstract base class for all OC Chat terminal presenters.
 
    Implementations: :class:`~oc_ui.terminal.presenter.ConsolePresenter`
    (always available); ``RichPresenter`` (Phase 1, optional dep);
    ``TextualPresenter`` (Phase 3).
 
    Lifecycle (per chat turn):
 
        presenter.start_turn()
        with presenter.turn():
            presenter.show_waiting()
            # … streaming events: show_reasoning / show_content / show_tool_*
        presenter.show_turn_summary(...)
        presenter.end_turn()
    """
 
    # ── Per-turn lifecycle ────────────────────────────────────────────────
 
    @abstractmethod
    def turn(self) -> AbstractContextManager:
        """Return a context manager wrapping the streaming portion of a turn.
 
        Plain presenters return a no-op contextmanager.  Streaming
        presenters use this to open a Live region on ``__enter__`` and
        commit it (or clear it) on ``__exit__``.
        """
 
    @abstractmethod
    def start_turn(self) -> None:
        """Reset per-turn flags / display the turn separator."""
 
    @abstractmethod
    def end_turn(self) -> None:
        """Finalise the current turn (newline, cleanup)."""
 
    # ── Streaming events ──────────────────────────────────────────────────
 
    @abstractmethod
    def show_waiting(self) -> None:
        """Indicate the request is in flight before any tokens arrive.
 
        Should be cleared automatically by the first reasoning/content
        chunk.  Plain presenters print a transient line; rich presenters
        show an animated spinner.
        """
 
    @abstractmethod
    def show_reasoning(self, text: str) -> None:
        """Stream a chunk of chain-of-thought / reasoning text."""
 
    @abstractmethod
    def show_content(self, text: str) -> None:
        """Stream a chunk of the assistant's answer."""
 
    # ── Tools ─────────────────────────────────────────────────────────────
 
    @abstractmethod
    def show_tool_call(self, name: str, arguments: str) -> None:
        """Display the *invocation* of a tool, before it runs."""
 
    @abstractmethod
    def show_tool_progress(self, name: str) -> None:
        """Indicate that a tool is currently executing.
 
        Plain presenters typically no-op.  Rich/textual presenters show a
        spinner that is replaced by :meth:`show_tool_result` when the tool
        finishes.
        """
 
    @abstractmethod
    def show_tool_result(self, name: str, result: object) -> None:
        """Display the result of a completed tool call."""
 
    # ── Stats ─────────────────────────────────────────────────────────────
 
    @abstractmethod
    def show_usage(self, usage: dict) -> None:
        """Render per-iteration usage stats.
 
        Plan 134 C1: terminal presenters render this ONLY in ``--verbose``
        mode (the render is gated, not the event). The structured usage signal
        is preserved elsewhere — ``react_loop`` records it and
        ``LoggingPresenter`` tees it to its JSONL log unconditionally before
        delegating — so quiet mode loses only the on-screen line.
        """
 
 
    @abstractmethod
    def show_iteration_stat(self, stat: "IterationStat") -> None:
        """Render a timestamped per-iteration analytics stat line.
 
        Called once per ReAct iteration with a structured
        :class:`IterationStat` record.  Implementations may print
        a compact one-liner, write JSON to a file, or both.
        """
    @abstractmethod
    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:
        """Render the aggregated turn-level summary.
 
        Plan 134 C2: *cache_hit_pct* is the cache-hit ratio (label it
        ``cache-hit:`` — NOT ``ctx:``). *context_used_pct* is the real
        context-window saturation (main-loop prompt high-water ÷ the model's
        window), already computed by the caller; *model* names the window.
        Presenters render what they're given and do no config/caps lookup.
 
        Plan 147 D1: *duration_ms* is the real wall-clock turn duration,
        computed by the caller directly from a turn-start monotonic
        timestamp (never derived from :class:`~oc_ui.terminal.input.TurnStats`
        finish-turn state — see the summary-ordering pin). ``None`` when the
        caller has no timing available (e.g. a synthetic/test turn).
 
        Plan 188 T4: *turn_cost* is a
        :class:`~oc_chat.core.turn_cost.TurnCost` — the modelled USD spend
        plus the price table's provenance — or ``None``. Typed as ``object``
        for the same reason as *performance_stats*: presenters read it
        duck-typed and ``oc_ui`` never imports ``oc_chat.core`` at module
        load. ``None`` means the turn could NOT be priced honestly (unknown
        model, unaccounted cache split, separately-billed reasoning) and
        presenters MUST then render no cost at all — a missing line is the
        designed outcome, not a degraded one, and rendering ``$0.00`` in its
        place would be exactly the false line T4 forbids.
        """
 
    # ── Static UI ─────────────────────────────────────────────────────────
 
    @abstractmethod
    def show_welcome(self, session: ChatSession) -> None:
        """Display the startup banner."""
 
    @abstractmethod
    def show_available_models(self, models: dict) -> None:
        """Display the model list / capability table."""
 
    @abstractmethod
    def show_session_list(self, sessions: list, current_name: str | None = None) -> None:
        """Display the list of saved sessions for ``/session list``.
 
        *sessions* is the return value of :func:`oc_chat.core.persistence.list_sessions`.
        Plain console: a hand-padded text table.  Rich: a styled
        ``rich.table.Table`` with proper column sizing and overflow.
        """
 
    @abstractmethod
    def show_help(self, command_help: dict, tools: list[str] | None = None) -> None:
        """Display the ``/help`` listing of commands (and optionally agent tools).
 
        *command_help* maps verb → usage string (the ``COMMAND_HELP``
        registry).  *tools* is the sorted list of registered agent-tool
        names; ``None`` skips the tools section.
        """
 
    @abstractmethod
    def show_compressed(self) -> None:
        """Notify the user that context compression occurred."""
 
    @abstractmethod
    def show_error(self, msg: str) -> None:
        """Display an error message."""
 
    @abstractmethod
    def show_info(self, msg: str) -> None:
        """Display an informational message."""
 
    # ── Progress spinner (Phase H.4) ──────────────────────────────────────
    # NOT abstract: default to no-op so backward-compat with every existing
    # Presenter subclass (including in-test recording mocks) is preserved.
    # :class:`RichPresenter` overrides with a real ``rich.status.Status``.
 
    def spinner_start(self, label: str) -> SpinnerHandle:
        """Start an animated progress spinner with the given label.
 
        Used by long-running operations (slow tool dispatch, sub-loop
        provider calls) to indicate liveness so users don't wonder if the
        app has hung. Returns a :class:`SpinnerHandle` the caller passes
        back to :meth:`spinner_stop`. The base implementation is a no-op
        returning a handle with ``status=None`` — appropriate for plain
        console, headless CI, and tests; :class:`RichPresenter` overrides
        with a real animated spinner.
        """
        return SpinnerHandle(status=None)
 
    def spinner_stop(self, handle: SpinnerHandle) -> None:
        """Stop the spinner identified by *handle*.
 
        Idempotent — safe to call multiple times on the same handle (e.g.
        once on first-chunk arrival and again in a ``finally`` block).
        The base implementation is a no-op (handle's ``status`` is
        ``None`` by default).
        """
        return None
 
    # ── Activity lane (Plan 188 T2) ───────────────────────────────────────
    # NOT abstract: default to no-op so every existing Presenter subclass
    # (including in-test recording mocks) keeps working without modification,
    # exactly like spinner_start / bind_status above. The 19-method abstract
    # contract is deliberately unchanged.
 
    def show_activity(self, label: str, detail: str = "", *, tone: str = "info") -> None:
        """Render a compact one-line state update for a non-streaming lane.
 
        Plan 188 T2 surfaces state the loop ALREADY produces but never
        showed: the pending-approval lane (``permission_decision``), the
        sub-agent lane (``subagent_started`` / ``subagent_completed``) —
        both fed by the :mod:`oc_chat.core.presenter_events` bus
        subscriber — and plan progress, fed presenter-side from the
        planner singleton (see :mod:`oc_ui.terminal.activity`).
 
        *label* names the lane (``"approval"`` / ``"sub-agent"`` /
        ``"plan"``); *detail* is the already-formatted body; *tone* is one
        of :data:`~oc_ui.terminal.activity.TONES` and selects styling
        only — an unknown tone must render neutral, never raise.
 
        No new event kind and no bus semantic change: this hook renders
        existing signal (synthesis §2 — observability, not control).
        """
        return None
 
    # ── Session-opening rule (Plan 218 T2) ────────────────────────────────
    # NOT abstract: default to no-op so every existing Presenter subclass
    # (including in-test recording mocks) keeps working without modification,
    # exactly like show_activity / spinner_start / bind_status above. The
    # 19-method abstract contract is deliberately unchanged.
 
    def show_session_start(self) -> None:
        """Draw the ``start @ <time>`` rule that opens the session.
 
        Plan 218 P1 element 1: the REPL's first prompt used to float in
        unbounded space — the first horizontal rule only appeared once the
        user had already pressed Enter. Emitting a rule at session start
        means every prompt echo, including the first, sits inside a
        bounded region, which is what makes the three-space turn indent
        read as containment rather than as a stray margin.
 
        Called once by :func:`oc_chat.main.main`, after the welcome banner
        and the pre-turn notices and before the REPL loop. Terminal
        presenters draw their existing rule; the base implementation is a
        no-op — appropriate for headless, JSON-lines and recording
        presenters that have no rules to draw.
        """
        return None
 
    # ── Two-stage Ctrl+C notice (Plan 188 T5) ─────────────────────────────
    # NOT abstract, same rationale as above.
 
    def show_interrupt_notice(self, stage: str) -> None:
        """Announce a Ctrl+C stage — called FROM THE SIGNAL HANDLER.
 
        *stage* is ``"cancel"`` (first press: a stop-confirmation is now
        pending at the turn's next safe checkpoint; nothing is cancelled
        yet and the in-flight tool keeps running) or ``"force"`` (second
        press: hard interrupt). Any other value is ignored.
 
        **Signal-safety contract.** This runs inside
        :func:`oc_chat.main._o3_sigint_handler`, so an implementation must
        do at most ONE short write and must never block, prompt, or raise.
        The default writes the notice to ``stderr`` — which is exactly
        what the handler did inline before plan 188, so presenters that do
        not override this keep byte-identical behaviour; the point of the
        hook is that the presenter which OWNS the terminal (Rich, with a
        live region) gets to choose the stream.
        """
        import sys
        text = INTERRUPT_NOTICES.get(stage)
        if text is None:
            return None
        sys.stderr.write(text)
        sys.stderr.flush()
        return None
 
    # ── Realtime status bar (Plan 147 D1) ───────────────────────────────────
    # NOT abstract: default to no-op so every existing Presenter subclass
    # (including in-test recording mocks predating plan 147) keeps working
    # without modification. :class:`RichPresenter` overrides to render the
    # shared statusline formatter; :class:`LoggingPresenter` passes through.
 
    def bind_status(self, provider: Callable[[], StatusBarState | None]) -> None:
        """Register the late-binding status-snapshot provider for this presenter.
 
        *provider* is a zero-arg callable a presenter invokes AT RENDER TIME
        to obtain the current :class:`~oc_ui.terminal.statusline.StatusBarState`
        (or ``None`` when no snapshot is available yet). It MUST NOT be a
        closure that captures a ``ChatSession`` object — sessions are
        replaced at runtime (``/session new`` / ``clear``) — it should read
        current state (e.g. off a ``Context``) fresh on every call. Called
        via :func:`~oc_chat.core.commands.refresh_presenter_bindings` on
        every session-mutation path, alongside ``bind_session``. The base
        implementation is a no-op — appropriate for :class:`ConsolePresenter`
        and any presenter with no persistent chrome to refresh.
        """
        return None