render_turn_layout.py

Go to the documentation of this file.

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# oc_chat/scripts/render_turn_layout.py
 
# OCT-LINT: disable=tests_exist reason="Helper script, not a production module"
"""
Render one scripted chat turn to a file — the plan-218 acceptance capture.
 
Purpose
-------
Plan 218's acceptance target is the operator's layout mock at
``docs/architecture/Terminal output layout Improvements.txt``. Proving a
render matches it needs a DETERMINISTIC capture of the same event
sequence, taken twice: once on the pre-218 tree and once after, so the
report can show them side by side.
 
This script drives a presenter through exactly the mock's sequence —
welcome banner, the two pre-turn notices, the session-start rule, the
prompt echo, one streamed answer, the per-iteration metadata, and the
turn-end rule — with every clock-dependent value injected, so two runs
differ only where the LAYOUT differs.
 
It runs unchanged on a pre-218 tree: hooks plan 218 adds are called
through ``getattr`` guards, so the "before" capture is taken with the
same script as the "after" one.
 
Responsibilities
----------------
- :func:`render` — drive one presenter and return the captured text.
- :func:`main` — write the rich and plain captures to a UTF-8 file.
 
Diagnostics
-----------
Domain: OC_CHAT.MAIN
Levels:
    L2 — lifecycle events
    L3 — semantic details
    L4 — deep tracing
 
Contracts
---------
- Deterministic: timestamps, token counts and durations are fixed
  literals; the only variable is terminal width, which is a parameter.
- Console output is ASCII-only (the capture itself is UTF-8 and goes to
  the ``--out`` file) so the script is safe under a cp1252 console.
- Read-only with respect to the app: it constructs presenters directly
  and never touches a session, the registry, or the network.
 
Dependencies
------------
- oc_diagnostics (structured debug logging via _dbg)
- rich.console (lazy; Console, which renders the rich capture into a string buffer at a fixed width)
- oc_chat.core.iteration_stat (lazy; IterationStat, the pinned record the per-iteration metadata line reports)
- oc_ui.terminal.statusline (lazy; StatusBarState, the pinned status snapshot bound to each presenter)
- oc_ui.terminal.rich_presenter (lazy; RichPresenter, the rich presenter under capture)
- oc_ui.terminal.presenter (lazy; ConsolePresenter, the plain presenter under capture)
- oc_ui.terminal.input (lazy; build_prompt_prefix for the prompt echo line)
- rich.text (lazy; Text, so the prompt echo prints without markup parsing)
"""
from __future__ import annotations
 
import argparse
import io
import os
import sys
from pathlib import Path
from types import SimpleNamespace
 
from oc_diagnostics import _dbg
 
_dbg("OC_CHAT.MAIN", "module", "loaded", 4)
 
#: Every clock/usage value the mock shows, pinned so two captures differ
#: only in layout.
SESSION_START_TS = "02:13:32"
TURN_TS = "02:13:37"
TURN_END_TS = "02:13:40"
MODEL = "z-ai/glm-5.3-flash"
ANSWER = (
    "Hello. I'm ready to help with your Option C project - code, tests, git, "
    "quality gates, or planning. What would you like to work on?\n"
)
SECURITY_LINE = (
    "[security] permissive profile: the agent runs in-process with your "
    "account's authority. Use the 'guarded' profile for less-trusted projects."
)
PROMPT_TOOLKIT_LINE = (
    "[prompt_toolkit enabled - Tab completes commands, up/down cycles history, "
    "Alt+Enter inserts newline, Ctrl+P opens command palette]"
)
 
 
def _stat():
    """The single iteration record the mock's metadata line reports."""
    from oc_chat.core.iteration_stat import IterationStat
    return IterationStat(
        ts=f"2026-08-31T{TURN_END_TS}.371+02:00",
        iter=0,
        model=MODEL,
        effort="high",
        tools=(),
        prompt_tokens=7148,
        completion_tokens=83,
        cache_hit_tokens=0,
        cache_miss_tokens=0,
        dur_ms=2530,
    )
 
 
def _status_state():
    """The bound status snapshot the running total and status bar read."""
    from oc_ui.terminal.statusline import StatusBarState
    return StatusBarState(
        model=MODEL, session_name="GLM 5.4 Flash test 01", effort="high",
        turn_tokens=7231, turn_iterations=1, turn_tools=0,
        turn_cache_hit_pct=None, turn_cache_saved_tokens=0,
        turn_elapsed_ms=2530,
        session_tokens=0, session_tools=0,
        session_cache_hit_pct=None, session_cache_saved_tokens=0,
        session_elapsed_ms=1_103_000,
    )
 
 
def _frozen_clock(presenter, ts: str) -> None:
    """Pin the presenter's rule clock so timestamps are reproducible.
 
    ``_now_ts`` is the presenters' one wall-clock read for rule labels
    (plan 218). On a pre-218 tree the attribute does not exist and the
    capture simply carries real timestamps — the layout comparison the
    "before" capture exists for is unaffected.
    """
    if hasattr(type(presenter), "_now_ts"):
        setattr(presenter, "_now_ts", lambda: ts)
 
 
def render(kind: str, width: int) -> str:
    """Drive *kind* (``"rich"`` / ``"plain"``) through the scripted turn."""
    func = "render"
    _dbg("OC_CHAT.MAIN", func, f"kind={kind} width={width}", 3)
    session = SimpleNamespace(name="GLM 5.4 Flash test 01", model=MODEL,
                              reasoning_effort="high", ui_prefs={})
    buf = io.StringIO()
 
    if kind == "rich":
        from rich.console import Console
        from rich.text import Text
        from oc_ui.terminal.rich_presenter import RichPresenter
        # legacy_windows=False: Rich otherwise deducts a column from an
        # explicit width on a legacy Windows console, which would make the
        # capture one column narrower than the width being demonstrated.
        console = Console(file=buf, force_terminal=False, width=width,
                          no_color=True, soft_wrap=False, legacy_windows=False)
        presenter = RichPresenter(console=console)
 
        def emit(text: str) -> None:
            # Text(), never a markup string: the prompt echo contains
            # ``[<model>]``, which Rich would otherwise parse as markup.
            console.print(Text(text), highlight=False)
    else:
        from oc_ui.terminal.presenter import ConsolePresenter
        presenter = ConsolePresenter()
        emit = print
 
    presenter.bind_status(_status_state)
 
    stdout, sys.stdout = sys.stdout, buf
    try:
        presenter.show_welcome(session)
        presenter.show_info(SECURITY_LINE)
        presenter.show_info(PROMPT_TOOLKIT_LINE)
 
        _frozen_clock(presenter, SESSION_START_TS)
        session_start = getattr(presenter, "show_session_start", None)
        if session_start is not None:
            session_start()
 
        from oc_ui.terminal.input import build_prompt_prefix
        emit(build_prompt_prefix(session) + "Hello.")
 
        _frozen_clock(presenter, TURN_TS)
        presenter.start_turn()
        _frozen_clock(presenter, TURN_END_TS)
        with presenter.turn():
            presenter.show_waiting()
            presenter.show_content(ANSWER)
        presenter.show_iteration_stat(_stat())
        presenter.end_turn()
        presenter.show_turn_summary(
            prompt=7148, completion=83, total=7231, iterations=1, tool_calls=0,
            model=MODEL, context_used_pct=11.0, duration_ms=2900,
        )
    finally:
        sys.stdout = stdout
    return buf.getvalue()
 
 
def main(argv: list[str] | None = None) -> int:
    """Write the rich + plain captures to ``--out`` and report the path."""
    func = "main"
    parser = argparse.ArgumentParser(
        description="Capture the scripted plan-218 turn render.")
    parser.add_argument("--out", required=True, help="UTF-8 capture file")
    parser.add_argument("--width", type=int, default=120,
                        help="terminal width to render at")
    args = parser.parse_args(argv)
 
    # Set BEFORE the presenters are imported (they read both at import
    # time): NO_COLOR keeps the capture readable as plain text, COLUMNS is
    # what shutil.get_terminal_size reports to the plain presenter, so both
    # presenters render at the SAME requested width.
    os.environ["NO_COLOR"] = "1"
    os.environ["COLUMNS"] = str(args.width)
    os.environ["LINES"] = "40"
 
    chunks = []
    for kind in ("rich", "plain"):
        chunks.append(f"===== {kind} presenter @ width {args.width} =====\n")
        chunks.append(render(kind, args.width))
        chunks.append("\n")
 
    out = Path(args.out)
    out.parent.mkdir(parents=True, exist_ok=True)
    out.write_text("".join(chunks), encoding="utf-8")
    _dbg("OC_CHAT.MAIN", func, f"wrote {out}", 2)
    print(f"wrote capture: {out}")
    return 0
 
 
if __name__ == "__main__":
    raise SystemExit(main())