pal-code 0.1.0__py3-none-any.whl

pal/terminal/ui.py

@@ -0,0 +1,647 @@
+"""The Pal screen: a centred column in the terminal, a prompt box with a red bar, and a status line under it.
+
+The box is a small prompt_toolkit application that disappears when you press Enter; what you said and what Pal answered are then printed with rich,
+so they stay in the terminal's own scroll-back and can be selected and copied. Colours are black, red and white.
+"""
+from __future__ import annotations
+
+import os
+import shutil
+from collections.abc import Callable
+from pathlib import Path
+
+from prompt_toolkit import Application
+from prompt_toolkit.buffer import Buffer
+from prompt_toolkit.filters import Condition
+from prompt_toolkit.formatted_text import FormattedText
+from prompt_toolkit.key_binding import KeyBindings
+from prompt_toolkit.layout import Dimension, HSplit, Layout, VSplit, Window, WindowAlign
+from prompt_toolkit.layout.containers import ConditionalContainer
+from prompt_toolkit.layout.controls import BufferControl, FormattedTextControl
+from prompt_toolkit.layout.processors import AfterInput, ConditionalProcessor
+from prompt_toolkit.styles import Style
+from rich.console import Console, Group, RenderableType
+from rich.markdown import Markdown
+from rich.padding import Padding
+from rich.table import Table
+from rich.text import Text
+from rich.theme import Theme
+
+from pal.terminal import theme
+from pal.terminal.logo import BRAILLE, braille_lines, logo_lines, ptk_style
+from pal.terminal.security import SEVERITIES, Finding, clean_terminal
+from pal.terminal.session import Change, PalSession, Turn
+
+COMMANDS: list[tuple[str, str]] = [
+    ("/help", "show the commands"), ("/mode", "switch agent: build, plan or ask (or press tab)"), ("/model", "show or switch the model"),
+    ("/files", "list the files Pal can see in this folder"), ("/security", "check this folder for security problems (add 'ai' for a model review)"),
+    ("/budget", "cap the tokens this session may use: /budget 50000, /budget off"), ("/key", "use an API key for this session: /key openrouter sk-..."),
+    ("/add", "attach a file from anywhere (PDF, Word, code ...); dropping a file on the window works too"), ("/tokens", "tokens saved, and where (last, turns, help)"),
+    ("/project", "this folder's setup: project map, code graph, documents as markdown, local model (/project rebuild)"),
+    ("/exit", "leave Pal"),
+]
+PLACEHOLDER = 'Ask anything\u2026  "Fix a TODO in the codebase"   (@file adds a file, \\+Enter a new line)'
+RICH_THEME = Theme({"markdown.code": f"bold {theme.WHITE} on {theme.PANEL}", "markdown.code_block": f"{theme.INK} on {theme.PANEL}", "markdown.h1": f"bold {theme.RED_HI}",
+                    "markdown.h2": f"bold {theme.WHITE}", "markdown.h3": f"bold {theme.WHITE}", "markdown.link": f"underline {theme.WHITE}", "markdown.item.bullet": theme.RED, "markdown.item.number": theme.RED_HI})
+STYLE = Style.from_dict({
+    "screen": f"bg:{theme.BG}", "placeholder": theme.MUTED, "prompt": f"{theme.RED} bold", "frame.border": "#8C8C8C",
+    "mode.build": f"{theme.RED_HI} bold", "mode.plan": f"{theme.WHITE} bold", "mode.ask": "#D9D9D9 bold", "model": theme.WHITE, "muted": theme.MUTED, "hint": theme.MUTED,
+    "hintkey": f"{theme.WHITE} bold", "ok": f"{theme.RED_HI} bold", "cmd": f"{theme.WHITE} bold", "cmddesc": theme.MUTED, "warn": f"{theme.RED_HI}",
+})
+
+
+def metrics(cols: int | None = None) -> tuple[int, int]:
+    """(width of the conversation column, spaces on its left): the full width of the terminal, inside a small margin, like the input box."""
+    cols = cols or shutil.get_terminal_size((100, 30)).columns
+    return max(40, min(cols - 6, 140)), 3
+
+
+def make_console() -> Console:
+    return Console(theme=RICH_THEME, highlight=False, soft_wrap=False)
+
+
+def short_path(p: Path) -> str:
+    home = Path.home()
+    try:
+        return "~" + os.sep + str(p.relative_to(home)) if p != home else "~"
+    except ValueError:
+        return str(p)
+
+
+def say(console: Console, renderable: RenderableType) -> None:
+    """Print inside the centred column."""
+    width, pad = metrics(console.width)
+    console.print(Padding(renderable, (0, 0, 0, pad)), width=pad + width)
+
+
+def show_user(console: Console, text: str) -> None:
+    out = Text()
+    lines = text.split("\n")
+    for i, line in enumerate(lines):
+        out.append("▌ ", style=theme.RED)
+        out.append(line, style=f"bold {theme.WHITE}")
+        out.append("\n" if i < len(lines) - 1 else "")
+    say(console, out)
+    console.print()
+
+
+def show_reply(console: Console, turn: Turn, session: PalSession) -> None:
+    for w in turn.warnings:
+        say(console, Text(clean_terminal(w), style=theme.MUTED))
+    if turn.text:
+        grid = Table.grid(padding=0)
+        grid.add_column(width=2)
+        grid.add_column(ratio=1)
+        grid.add_row(Text("✻", style=theme.RED), Markdown(clean_terminal(turn.text), code_theme="ansi_dark"))
+        say(console, grid)
+    for path, why in turn.refused:
+        say(console, Text(f"  refused {path}: {why}", style=theme.RED_HI))
+    used = turn.prompt_tokens + turn.completion_tokens
+    saved = turn.plain_estimate - used
+    line = Text("  \u21B3 ", style=theme.MUTED)
+    line.append(f"{used:,} used" + (f" (+{turn.helper_tokens:,} helper)" if turn.helper_tokens else ""), style=theme.MUTED)
+    line.append(" \u00B7 ", style=theme.MUTED)
+    if saved > 0:
+        line.append(f"saved ~{saved:,}", style=f"bold {theme.RED_HI}")
+    else:
+        line.append("no saving here", style=theme.MUTED)
+    if session.saved > 0 and session.turns > 1:
+        line.append(f" \u00B7 total ~{session.saved:,} ({session.saved_pct:g}%)", style=theme.WHITE)
+    line.append(f" \u00B7 {turn.seconds:.1f}s" + ("  \u00B7  /tokens" if session.turns <= 2 else ""), style=theme.MUTED)
+    say(console, line)
+    console.print()
+
+
+def show_changes(console: Console, changes: list[Change], limit: int = 60) -> None:
+    for c in changes:
+        say(console, Text.assemble(("  ", ""), ("+ " if c.is_new else "~ ", theme.RED), (c.path, f"bold {theme.WHITE}"), ("  (new file)" if c.is_new else "", theme.MUTED)))
+        shown = c.diff[:limit]
+        body = Text()
+        for tag, raw in shown:
+            text = clean_terminal(raw)
+            if tag == "add":
+                body.append(f"    + {text}\n", style=f"{theme.WHITE}")
+            elif tag == "del":
+                body.append(f"    - {text}\n", style=f"{theme.RED_HI}")
+            elif tag == "hunk":
+                body.append(f"    {text}\n", style=theme.MUTED)
+            else:
+                body.append(f"      {text}\n", style=theme.MUTED)
+        if len(c.diff) > limit:
+            body.append(f"    … {len(c.diff) - limit} more lines\n", style=theme.MUTED)
+        say(console, body)
+    found = [f for c in changes for f in c.findings]
+    if found:
+        say(console, Text("  Security check on these changes", style=f"bold {theme.WHITE}"))
+        show_findings(console, found, indent=4)
+    else:
+        say(console, Text("  Security check: nothing found in these changes (pattern checks, not a proof)", style=theme.MUTED))
+
+
+SEV_STYLE = {"critical": f"bold {theme.WHITE} on {theme.RED}", "high": f"bold {theme.RED_HI}", "medium": theme.WHITE, "low": theme.MUTED}
+
+
+def _flow_commands() -> list[tuple[str, str]]:
+    from pal.terminal.flow_cli import FLOW_COMMANDS
+    return FLOW_COMMANDS
+
+
+def show_findings(console: Console, findings: list[Finding], indent: int = 0, limit: int = 40) -> None:
+    pad = " " * indent
+    for f in sorted(findings, key=lambda x: SEVERITIES.index(x.severity))[:limit]:
+        where = f"{f.path}:{f.line}" if f.line else f.path
+        say(console, Text.assemble((pad, ""), (f" {f.severity.upper()} ", SEV_STYLE[f.severity]), ("  ", ""), (f.title, f"bold {theme.WHITE}"), (f"  {where}", theme.MUTED)))
+        say(console, Padding(Text(f.why, style=theme.INK), (0, 0, 0, indent + 11)))
+    if len(findings) > limit:
+        say(console, Text(f"{pad}… and {len(findings) - limit} more", style=theme.MUTED))
+
+
+def confirm(console: Console, question: str) -> bool:
+    try:
+        answer = console.input(Text.assemble((" " * (metrics(console.width)[1] + 2) + question + " ", theme.WHITE), ("[y/N] ", theme.MUTED))).strip().lower()
+    except (EOFError, KeyboardInterrupt):
+        console.print()
+        return False
+    return answer in ("y", "yes")
+
+
+def show_help(console: Console) -> None:
+    grid = Table.grid(padding=(0, 2))
+    for name, desc in all_commands():
+        grid.add_row(Text(name, style=f"bold {theme.WHITE}"), Text(desc, style=theme.MUTED))
+    say(console, Group(grid, Text(""), Text("tab switches agent (Build / Plan / Ask) · @file adds a file · \\ then Enter (or Alt+Enter) for a new line · Ctrl+D exits", style=theme.MUTED)))
+    console.print()
+
+
+LABELS = {
+    "input": "Trimmed filler from your message",
+    "history": "Left out old turns this request did not need",
+    "compression": "Shortened old replies (names, numbers and code signatures kept)",
+    "documents": "Sent only the relevant parts of indexed files",
+    "code": "Sent only the relevant code from the project map",
+    "files": "Did not resend @files the model already had",
+    "carried": "Kept earlier @files out of the conversation history",
+}
+SHORT = {"input": "message trimmed", "history": "old turns left out", "compression": "old replies shortened", "documents": "only relevant file parts",
+         "code": "only relevant code", "files": "@files not resent", "carried": "@files kept out of history"}
+HELP_TOKENS = """How Pal counts tokens
+  used     what the main model really read and wrote (its own counts when it reports them, else characters / 4)
+  helper   Pal's small local jobs (trimming, checking): an extra cost, shown on its own
+  plain    an estimate of what a plain chat would have used for the same request: it resends the whole
+           conversation and pastes every @file again each time
+  saved    plain minus used. Every saving here is an estimate, not a measurement.
+
+Where savings come from
+""" + "\n".join(f"  {v}" for v in LABELS.values()) + """
+  Other    the part of the gap no stage reports by itself
+  Pal's own additions (negative)   the answer rules and notices Pal adds to each request: why tiny chats can cost more
+
+Commands:  /tokens   /tokens last   /tokens turns   /tokens help"""
+
+
+def _bars(console: Console, saved_by: dict, gap: int) -> None:
+    """One row per stage, with a bar scaled to the largest saving, plus what no stage explains."""
+    rows = sorted(((LABELS.get(k, k), v) for k, v in saved_by.items() if v > 0), key=lambda r: -r[1])
+    rest = gap - sum(v for _, v in rows)
+    if rest > 0:
+        rows.append(("Other (not itemized)", rest))
+    top = max([v for _, v in rows] + [1])
+    grid = Table.grid(padding=(0, 2))
+    grid.add_column(width=24, no_wrap=True)
+    grid.add_column(justify="right", no_wrap=True)
+    grid.add_column(ratio=1)
+    for label, v in rows:
+        grid.add_row(Text("\u2588" * max(1, round(22 * v / top)), style=theme.RED), Text(f"{v:,}", style=f"bold {theme.WHITE}"), Text(label, style=theme.INK))
+    if rest < 0:
+        grid.add_row(Text(""), Text(f"{rest:,}", style=theme.MUTED), Text("Pal's own additions (answer rules and notices)", style=theme.MUTED))
+    if not rows and rest >= 0:
+        grid.add_row(Text(""), Text("0", style=theme.MUTED), Text("nothing saved yet", style=theme.MUTED))
+    say(console, grid)
+
+
+def _head(used: int, helper: int, plain: int) -> Table:
+    saved = plain - used
+    pct = round(100.0 * saved / plain, 1) if plain else 0.0
+    grid = Table.grid(padding=(0, 3))
+    for k, v, style in (("used", f"{used:,}" + (f"  (+{helper:,} helper)" if helper else ""), theme.WHITE), ("plain chat (est.)", f"{plain:,}", theme.INK),
+                        ("saved", f"{saved:,}  ({pct:g}%)" if saved > 0 else f"{saved:,}  (Pal used more here)", f"bold {theme.RED_HI}" if saved > 0 else theme.MUTED)):
+        grid.add_row(Text(k, style=theme.MUTED), Text(v, style=style))
+    return grid
+
+
+def show_tokens(console: Console, session: PalSession, arg: str = "") -> None:
+    """/tokens: the session; /tokens last: the last request; /tokens turns: every request; /tokens help: how it is counted."""
+    arg = arg.strip().lower()
+    if arg == "help":
+        say(console, Text(HELP_TOKENS, style=theme.INK))
+    elif not session.records:
+        say(console, Text("No requests yet. Ask Pal something, then type /tokens.", style=theme.MUTED))
+    elif arg == "last":
+        r = session.records[-1]
+        say(console, Text.assemble(("Last request  ", f"bold {theme.WHITE}"), (r.text[:70] + ("\u2026" if len(r.text) > 70 else ""), theme.MUTED)))
+        say(console, _head(r.used, r.helper, r.plain))
+        console.print()
+        _bars(console, r.saved_by, r.saved)
+    elif arg == "turns":
+        grid = Table.grid(padding=(0, 2))
+        for width, just in ((3, "right"), (26, "left"), (8, "right"), (8, "right"), (8, "right"), (24, "left")):
+            grid.add_column(width=width, justify=just, no_wrap=True, overflow="ellipsis")
+        grid.add_row(*(Text(h, style=theme.MUTED) for h in ("#", "request", "used", "plain", "saved", "biggest saving")))
+        for i, r in enumerate(session.records, 1):
+            best = max(r.saved_by.items(), key=lambda kv: kv[1])[0] if r.saved_by else ""
+            grid.add_row(Text(str(i), style=theme.MUTED), Text(r.text.replace("\n", " "), style=theme.INK), Text(f"{r.used:,}", style=theme.WHITE),
+                         Text(f"{r.plain:,}", style=theme.INK), Text(f"{r.saved:,}", style=f"bold {theme.RED_HI}" if r.saved > 0 else theme.MUTED),
+                         Text(SHORT.get(best, ""), style=theme.MUTED))
+        say(console, grid)
+    else:
+        say(console, Text.assemble(("This session  ", f"bold {theme.WHITE}"), (f"{session.turns} request{'s' if session.turns != 1 else ''}, {session.seconds:.1f}s", theme.MUTED)))
+        say(console, _head(session.pal_tokens, session.helper_tokens, session.plain_tokens))
+        console.print()
+        _bars(console, session.saved_by_total(), session.saved)
+        console.print()
+        say(console, Text("/tokens last  the last request \u00B7 /tokens turns  every request \u00B7 /tokens help  how it is counted", style=theme.MUTED))
+    console.print()
+
+
+def show_models(console: Console, session: PalSession, info: dict, hw, keyed: list[str]) -> None:
+    """/model: the model in use, the installed local models with how each fits this computer, what setup recommends, and API providers with a key."""
+    from pal.terminal.local_models import FIT_LABEL, installed_fit, recommend, tier_name
+    say(console, Text.assemble(("Now  ", theme.MUTED), (model_label(session), f"bold {theme.WHITE}"),
+                               (f"   helper: {session.helper_model}" if session.helper_model else
+                                "   no local helper (no GPU: API only)" if not session.local else "   helper: the main model (run pal setup for a small local helper)", theme.MUTED)))
+    say(console, Text(f"This computer: {hw.summary()}  ({tier_name(hw)})", style=theme.MUTED))
+    console.print()
+    rows = installed_fit(info.get("models", []), hw) if info.get("ok") else []
+    if rows:
+        grid = Table.grid(padding=(0, 2))
+        for r in sorted(rows, key=lambda r: -r["rank"]):
+            grid.add_row(Text(r["name"], style=f"bold {theme.WHITE}" if r["name"] == session.model else theme.INK), Text(f"{r['need_gb']:g} GB", style=theme.MUTED),
+                         Text(FIT_LABEL[r["fit"]], style=f"bold {theme.RED_HI}" if r["fit"] == "gpu" else theme.MUTED))
+        say(console, Text("Installed", style=f"bold {theme.WHITE}"))
+        say(console, Padding(grid, (0, 0, 0, 2)))
+    else:
+        say(console, Text("No local models found (is Ollama running?).", style=theme.MUTED))
+    rec = recommend(hw)
+    names = {r["name"] for r in rows}
+    if rec is None:
+        say(console, Text("This computer has no GPU, so Pal uses API models only.", style=theme.INK))
+    elif rec.main.tag not in names:
+        say(console, Text(f"Best for this computer: {rec.main.tag} ({rec.main.size_gb:g} GB). Get it with  ollama pull {rec.main.tag}  or  pal setup", style=theme.INK))
+    say(console, Text(f"API providers with a key: {', '.join(keyed) or 'none (add one with /key <provider> <key>)'}", style=theme.MUTED))
+    say(console, Text("Switch with  /model <name>  or  /model openrouter:<name>   \u00B7   every local model by GPU:  pal setup --list", style=theme.MUTED))
+    console.print()
+
+
+def all_commands() -> list[tuple[str, str]]:
+    from pal.terminal.commands import COMMANDS as MORE
+    seen: set[str] = set()
+    out = []
+    for name, desc in COMMANDS[:-1] + MORE + _flow_commands() + COMMANDS[-1:]:
+        if name not in seen:
+            seen.add(name)
+            out.append((name, desc))
+    return out
+
+
+def matching(text: str) -> list[tuple[str, str]]:
+    return [(n, d) for n, d in all_commands() if text.startswith("/") and " " not in text and n.startswith(text)][:10]
+
+
+def model_label(session: PalSession) -> str:
+    return session.model + ("  local" if session.provider == "local" else f"  {session.provider}")
+
+
+def brand_block() -> list[tuple[str, str]]:
+    """The logo with the wordmark beside it, centred on the logo's height (kept for wide screens and the tests)."""
+    art, word = logo_lines(), theme.wordmark()
+    top = (len(art) - len(word)) // 2
+    width = sum(len(c) for c, _ in word[0])
+    frags: list[tuple[str, str]] = []
+    for i, line in enumerate(art):
+        frags += [(ptk_style(st), ch) for ch, st in line]
+        frags.append(("", "    "))
+        w = word[i - top] if 0 <= i - top < len(word) else [(" " * width, "")]
+        frags += [(f"fg:{colour}" if colour else "", chars) for chars, colour in w]
+        if i < len(art) - 1:
+            frags.append(("", "\n"))
+    return frags
+
+
+def dot_logo() -> list[tuple[str, str]]:
+    """The logo in braille dots, as prompt_toolkit fragments: the start screen's dot-matrix mark."""
+    frags: list[tuple[str, str]] = []
+    lines = braille_lines()
+    for i, runs in enumerate(lines):
+        frags += [(f"fg:{colour}" if colour else "", chars) for chars, colour in runs]
+        if i < len(lines) - 1:
+            frags.append(("", "\n"))
+    return frags
+
+
+def agent_line(session: PalSession) -> list[tuple[str, str]]:
+    helper = session.helper_model
+    provider, model = session.model_for() if hasattr(session, "model_for") else (session.provider, session.model)
+    return [("class:mode." + session.mode, f"{session.mode.capitalize()} agent"), ("class:hint", "  \u00B7  "), ("class:model", model),
+            ("class:hint", " (local)" if provider == "local" else f" ({provider})"),
+            ("class:hint", f"  \u00B7  helper {helper}" if helper else ""),
+            ("class:hint", "  \u00B7  no GPU: API only" if not getattr(session, "local", True) else ""),
+            ("class:ok", f"  \u00B7  {note()}" if (note := getattr(session, "status_note", None)) else "")]
+
+
+def _k(n: int) -> str:
+    return f"{n / 1000:.1f}k" if n >= 1000 else str(n)
+
+
+def project_line(session: PalSession) -> list[tuple[str, str]]:
+    """One line about the prepared folder, for the first screen: files, the map, documents, the graph, the local model."""
+    project = getattr(session, "project", None)
+    if project is None:
+        return []
+    r = project.report
+    bits = [f"{r.code_files} files"]
+    if r.map_tokens:
+        bits.append(f"map {_k(r.map_tokens)} tokens")
+    if r.converted:
+        bits.append(f"{len(r.converted)} doc{'s' if len(r.converted) != 1 else ''} → markdown")
+    graph = r.graph.replace("ready: ", "graph ") if r.graph.startswith("ready") else ("graph building…" if r.graph == "building" else "")
+    if graph:
+        bits.append(graph)
+    local = getattr(session, "local_status", "")
+    out = [("class:hint", "this folder: "), ("class:ok", "  ·  ".join(bits))]
+    if local:
+        out += [("class:hint", "  ·  "), ("class:hint", local)]
+    return out
+
+
+def show_project(console: Console, session: PalSession) -> None:
+    """/project, and the summary printed while the folder is set up."""
+    project = getattr(session, "project", None)
+    if project is None:
+        say(console, Text("This session has no prepared folder.", style=theme.MUTED))
+        return
+    r = project.report
+
+    def row(ok: bool | None, name: str, text: str, note: str = "") -> None:
+        mark = ("✓", theme.RED_HI) if ok else ("…", theme.MUTED) if ok is None else ("✗", theme.MUTED)
+        say(console, Text.assemble((f"{mark[0]} ", mark[1]), (f"{name:<13}", f"bold {theme.WHITE}"), (text, theme.INK), (f"   {note}" if note else "", theme.MUTED)))
+    local = getattr(session, "local_status", "")
+    if local:
+        row(not local.startswith(("Ollama is not", "Ollama did not", "no GPU")) or None, "Local LLM", local)
+    row(bool(r.code_files), "Project map", f"{r.code_files} files, {_k(r.map_tokens)} tokens" if r.code_files else "no source files here",
+        f"(the code itself is about {_k(r.source_tokens)})" if r.source_tokens else "")
+    g = r.graph
+    row(True if g.startswith("ready") else None if g == "building" else False, "Code graph",
+        g.replace("ready: ", "") + (" (graphify, no model involved)" if g.startswith("ready") else ""),
+        "built in the background; the session can start now" if g == "building" else "pip install graphifyy" if g == "needs graphify" else "")
+    conv = r.converted
+    text_docs = [d for d in r.docs if not d.converted and not d.error]
+    failed = [d for d in r.docs if d.error]
+    if r.docs:
+        row(True, "Documents", (f"{len(conv)} converted to markdown" if conv else "") + (", " if conv and text_docs else "")
+            + (f"{len(text_docs)} text file{'s' if len(text_docs) != 1 else ''}" if text_docs else ""), "indexed: only matching passages are sent")
+        for d in conv[:6]:
+            say(console, Text(f"                {d.path} → {short_path(Path(d.markdown))}", style=theme.MUTED))
+        for d in failed[:4]:
+            say(console, Text(f"                {d.path}: {d.error}", style=theme.MUTED))
+    else:
+        row(False, "Documents", "none in this folder", "PDF, Word, PowerPoint and Excel files are converted to markdown")
+    if r.tests:
+        row(True, "Tests", r.tests)
+
+
+def read_input(session: PalSession, console: Console, save_mode: Callable[..., None] | None = None, landing: bool = False, version: str = "",
+               history=None, initial: str = "", on_shift_tab: Callable[[], str] | None = None) -> str | None:
+    """Show the input box and return what was typed, or None when the person leaves (Ctrl+Q, or Ctrl+D on an empty box).
+
+    `landing` draws the whole first screen full-screen: the folder at the top left, the dot-matrix logo, what Pal is set to, a full-width input
+    box and the key hints. Otherwise a status line, the box and the hints appear under the conversation and disappear on Enter."""
+    from prompt_toolkit.application import get_app
+    from prompt_toolkit.widgets import Frame
+    buf = Buffer(multiline=True)
+    if initial:
+        buf.text = initial
+        buf.cursor_position = len(initial)
+    empty = Condition(lambda: not buf.text)
+    result: dict[str, str | None] = {"text": None}
+    from pal.terminal.history import Browser
+    browse = Browser(history) if history is not None else None
+    ui_state: dict = {"sel": 0, "search": None, "flash": "", "recalled": False, "setting": False}   # menu, Ctrl+R, a note, text from history
+    menu_open = Condition(lambda: bool(matching(buf.text)) and not ui_state["recalled"])
+
+    def size():
+        try:
+            return get_app().output.get_size()
+        except Exception:  # noqa: BLE001  (no app yet)
+            return None
+
+    def status_left():
+        files = len(session.pending)
+        if ui_state["search"] is not None:
+            return FormattedText([("class:ok", "reverse search: "), ("class:model", ui_state["search"] or "…"), ("class:hint", "   ctrl+r older · enter use · esc esc clear")])
+        if ui_state["flash"]:
+            return FormattedText([("class:ok", ui_state["flash"])])
+        return FormattedText(agent_line(session) + ([("class:ok", f"   {files} file{'s' if files != 1 else ''} attached")] if files else []))
+
+    def status_right():
+        if not session.turns:
+            return FormattedText([("class:hint", "fewer tokens on every request")])
+        if session.saved > 0:
+            return FormattedText([("class:ok", f"saved {session.saved:,} tok"), ("class:hint", f"  \u00B7  {session.saved_pct:g}%  \u00B7  {session.pal_tokens:,} used")])
+        return FormattedText([("class:model", f"{session.pal_tokens:,} tok used")])
+
+    def menu():
+        rows: list[tuple[str, str]] = []
+        for i, (n, d) in enumerate(matching(buf.text)):
+            on = i == min(ui_state["sel"], len(matching(buf.text)) - 1)
+            rows += [("class:ok" if on else "class:cmd", f"{'❯ ' if on else '  '}{n:<14}"), ("class:cmddesc", d + "\n")]
+        if rows:
+            rows[-1] = (rows[-1][0], rows[-1][1].rstrip("\n"))
+        return FormattedText(rows)
+
+    def keys():
+        out: list[tuple[str, str]] = []
+        for k, label in (("enter", "send"), ("tab", "agent"), ("↑↓", "history"), ("/", "commands"), ("esc esc", "clear"), ("?", "shortcuts")):
+            out += [("class:hintkey", k), ("class:hint", f"  {label}       ")]
+        out[-1] = (out[-1][0], out[-1][1].rstrip())
+        return FormattedText(out)
+
+    kb = KeyBindings()
+
+    def pick() -> str | None:
+        m = matching(buf.text)
+        return m[min(ui_state["sel"], len(m) - 1)][0] if m else None
+
+    @kb.add("enter")
+    def _(event):
+        ui_state["search"] = None
+        chosen = pick() if not ui_state["recalled"] else None
+        if chosen and buf.text != chosen and buf.text.strip() != chosen:      # Enter on the command menu takes the highlighted command
+            buf.text = chosen + " "
+            buf.cursor_position = len(buf.text)
+            ui_state["sel"] = 0
+            return
+        if buf.text.endswith("\\"):
+            buf.delete_before_cursor(1)
+            buf.insert_text("\n")
+            return
+        if buf.text.strip():
+            result["text"] = buf.text
+            event.app.exit()
+
+    @kb.add("escape", "enter")
+    @kb.add("c-j")
+    def _(event):
+        buf.insert_text("\n")
+
+    @kb.add("tab")
+    def _(event):
+        chosen = pick()
+        if chosen:
+            buf.text = chosen + " "
+            buf.cursor_position = len(buf.text)
+            ui_state["sel"] = 0
+        else:
+            session.toggle_mode()
+            if save_mode:
+                save_mode(mode=session.mode)
+
+    @kb.add("up", filter=menu_open)
+    def _(event):
+        ui_state["sel"] = max(0, ui_state["sel"] - 1)
+
+    @kb.add("down", filter=menu_open)
+    def _(event):
+        ui_state["sel"] = min(len(matching(buf.text)) - 1, ui_state["sel"] + 1)
+
+    def set_text(text: str) -> None:
+        ui_state["setting"] = True
+        buf.text = text
+        buf.cursor_position = len(text)
+        ui_state.update(setting=False, recalled=True)            # a recalled line does not open the command menu
+
+    @kb.add("up", filter=~menu_open)
+    def _(event):
+        if buf.document.cursor_position_row > 0 or browse is None:     # inside a multi-line message: move up a line
+            buf.cursor_up()
+            return
+        older = browse.older(buf.text)
+        if older is not None:
+            set_text(older)
+
+    @kb.add("down", filter=~menu_open)
+    def _(event):
+        if buf.document.cursor_position_row < buf.document.line_count - 1 or browse is None:
+            buf.cursor_down()
+            return
+        newer = browse.newer()
+        if newer is not None:
+            set_text(newer)
+
+    @kb.add("escape", "escape")
+    def _(event):
+        buf.reset()
+        ui_state.update(search=None, sel=0)
+
+    @kb.add("c-r")
+    def _(event):
+        if browse is None:
+            return
+        if ui_state["search"] is None:
+            ui_state["search"] = buf.text
+            browse.pos = len(browse.h.items)
+        found = browse.find(ui_state["search"])
+        if found is not None:
+            set_text(found)
+        else:
+            ui_state["flash"] = f"no older match for {ui_state['search']!r}"
+
+    @kb.add("s-tab")
+    def _(event):
+        if on_shift_tab:
+            ui_state["flash"] = on_shift_tab()
+
+    @kb.add("c-l")
+    def _(event):
+        event.app.renderer.clear()
+
+    @kb.add("?", filter=empty)
+    def _(event):
+        result["text"] = "/shortcuts"
+        event.app.exit()
+
+    @kb.add("c-space")
+    @kb.add("c-@")
+    def _(event):
+        result["text"] = "\x00voice\x00" + buf.text                      # the caller records, then opens the box again with the words
+        event.app.exit()
+
+    buf.on_text_changed += lambda _b: None if ui_state["setting"] else ui_state.update(sel=0, flash="", recalled=False)
+
+    @kb.add("c-p")
+    def _(event):
+        if not buf.text:
+            buf.insert_text("/")
+
+    @kb.add("c-c")
+    def _(event):
+        if buf.text:
+            buf.reset()
+        else:
+            event.app.exit()
+
+    @kb.add("c-q")
+    def _(event):
+        event.app.exit()
+
+    @kb.add("c-d")
+    def _(event):
+        if not buf.text:
+            event.app.exit()
+
+    input_win = Window(BufferControl(buf, input_processors=[ConditionalProcessor(AfterInput(PLACEHOLDER, style="class:placeholder"), filter=empty)]),
+                       height=lambda: Dimension.exact(min(8, max(2, buf.text.count("\n") + 2))), wrap_lines=True)
+    prompt = Window(FormattedTextControl([("class:prompt", " \u276F ")]), width=3, dont_extend_width=True)
+    box = Frame(VSplit([prompt, input_win, Window(width=1)]), style="class:frame")
+    hints = Window(FormattedTextControl(keys), height=1, align=WindowAlign.CENTER)
+    menu_box = ConditionalContainer(Window(FormattedTextControl(menu), height=Dimension(min=1, max=12)), filter=menu_open)
+
+    def margins(container):
+        return VSplit([Window(width=1), container, Window(width=1)])
+    if not landing:
+        status = VSplit([Window(width=2), Window(FormattedTextControl(status_left), dont_extend_width=True), Window(FormattedTextControl(status_right), align=WindowAlign.RIGHT), Window(width=2)], height=1)
+        root = HSplit([status, margins(box), hints, margins(menu_box)])
+    else:
+        tall = Condition(lambda: (size().rows if size() else 30) >= 30)          # a short terminal leaves the logo out, so the box still fits
+
+        def blurb():
+            return FormattedText([("class:hint", "Build and plan with fewer tokens.  ") , ("class:hint", f"pal {version}")])
+
+        def setup_line():
+            return FormattedText(agent_line(session))
+
+        def folder_line():
+            return FormattedText(project_line(session))
+
+        def notice_line():
+            note = getattr(session, "notice", "")
+            return FormattedText([("class:warn", note[:160])] if note else [])
+
+        root = HSplit([Window(FormattedTextControl(lambda: FormattedText([("class:hint", "  " + short_path(session.cwd))])), height=1),
+                       Window(height=Dimension(weight=2)),
+                       ConditionalContainer(HSplit([Window(FormattedTextControl(FormattedText(dot_logo())), height=len(BRAILLE), align=WindowAlign.CENTER), Window(height=2)]), filter=tall),
+                       Window(FormattedTextControl(blurb), height=1, align=WindowAlign.CENTER),
+                       Window(height=1),
+                       Window(FormattedTextControl(setup_line), height=1, align=WindowAlign.CENTER),
+                       Window(FormattedTextControl(folder_line), height=1, align=WindowAlign.CENTER),
+                       ConditionalContainer(Window(FormattedTextControl(notice_line), height=1, align=WindowAlign.CENTER),
+                                            filter=Condition(lambda: bool(getattr(session, "notice", "")))),
+                       Window(height=Dimension(weight=2)),
+                       margins(box),
+                       Window(height=1),
+                       hints,
+                       margins(menu_box),
+                       Window(height=Dimension(weight=1))], style="class:screen")
+    app: Application = Application(layout=Layout(root, focused_element=input_win), key_bindings=kb, style=STYLE, full_screen=landing, erase_when_done=True, mouse_support=False,
+                               refresh_interval=1.0 if landing else None)   # the graph finishes in the background
+    app.run()
+    return result["text"]