pcode 0.1.0__py3-none-any.whl

pcode/terminal_notify.py

@@ -0,0 +1,383 @@
+"""Escape sequences for the terminal emulator itself, not the screen: desktop
+notifications (OSC 9), tab progress (OSC 9;4), and the tab title (OSC 0).
+
+Ghostty shows both by default (`desktop-notifications`, `progress-style`);
+iTerm2 and WezTerm take OSC 9 too, and terminals that know neither ignore an
+unknown OSC. tmux drops them unless wrapped for passthrough and the server has
+`allow-passthrough on`.
+
+Tab progress is only sent where it is known to be drawn (`progress_transport`):
+iTerm2 before 3.6.6 reads any OSC 9 as a notification and would pop up "4;3"
+on every turn, which is why pytest turned the same feature off by default.
+"""
+
+import asyncio
+import os
+import re
+from collections.abc import Callable, Mapping
+from contextlib import asynccontextmanager
+from time import monotonic
+
+from pcode.plan_sizes import plan_progress
+
+_CONTROL = re.compile(r"[\x00-\x1f\x7f-\x9f]")
+
+# OSC 9;4 states (ConEmu's numbering, which every terminal kept).
+CLEAR, NORMAL, ERROR, INDETERMINATE, PAUSED = 0, 1, 2, 3, 4
+
+# Ghostty drops a report nobody refreshes after about 15 seconds, and
+# recommends re-sending well inside that; other terminals do not mind.
+KEEPALIVE_SECONDS = 5.0
+TICK_SECONDS = 1.0
+
+
+def _passthrough(sequence: str) -> str:
+    """tmux's DCS passthrough: the sequence reaches the outer terminal as is."""
+    return "\x1bPtmux;" + sequence.replace("\x1b", "\x1b\x1b") + "\x1b\\"
+
+
+def _outer(sequence: str) -> str:
+    """Wrap for tmux, which otherwise swallows OSC sequences it does not know."""
+    return _passthrough(sequence) if os.environ.get("TMUX") else sequence
+
+
+def notification(text: str) -> str:
+    # Control characters would end the sequence early; and a body starting
+    # with "4;" would be read as a progress report, which "pcode" never is.
+    body = _CONTROL.sub(" ", text).strip()[:200]
+    return _outer(f"\x1b]9;{body}\x07")
+
+
+def progress(state: int, value: int | None = None) -> str:
+    """One OSC 9;4 report, unwrapped: `progress_transport` says how it travels."""
+    return f"\x1b]9;4;{state}" + ("" if value is None else f";{value}") + "\x07"
+
+
+# Which terminals draw OSC 9;4
+
+
+def _version(text: str) -> tuple[int, ...]:
+    return tuple(int(part) for part in re.findall(r"\d+", text)[:3])
+
+
+def _number(text: str | None) -> int:
+    return int(text) if text and text.isdigit() else 0
+
+
+# kitty is left to `on`: before 0.38 it shows the report as a desktop
+# notification, before 0.47 it draws nothing, and it exports no version.
+_DRAWS = ("ghostty", "wezterm", "vscode", "mintty", "warpterminal")
+
+
+def _iterm(name: str) -> bool:
+    return name.lower() in ("iterm.app", "iterm2")
+
+
+def _known(name: str, version: str = "") -> bool:
+    """A terminal, by the name it gives itself, that draws the bar."""
+    if name.lower() in _DRAWS:
+        return True
+    # Before 3.6.6 iTerm2 shows a notification instead: never guess its version.
+    return _iterm(name) and _version(version) >= (3, 6, 6)
+
+
+def _old_iterm(name: str, version: str) -> bool:
+    return _iterm(name) and not _known(name, version)
+
+
+def _progress_feature(features: str) -> bool:
+    """iTerm2's TERM_FEATURES is a run of capitalised codes; "P" is progress."""
+    return "P" in re.findall(r"[A-Z][a-z0-9]*", features.split()[0] if features else "")
+
+
+def environment_supports(env: Mapping[str, str]) -> bool:
+    """Whether the terminal pcode runs in directly draws the bar.
+
+    The same checks as Cargo's (anstyle-progress), plus variables that survive
+    where TERM_PROGRAM does not: ssh keeps TERM, and inside tmux both TERM and
+    TERM_PROGRAM name tmux while the server's environment still names the
+    terminal it was started from.
+    """
+    # A terminal that says it is an iTerm2 too old for the bar would show a
+    # notification, whatever else a tmux server's stale environment claims.
+    if _old_iterm(env.get("TERM_PROGRAM", ""), env.get("TERM_PROGRAM_VERSION", "")):
+        return False
+    if _old_iterm(env.get("LC_TERMINAL", ""), env.get("LC_TERMINAL_VERSION", "")):
+        return False
+    if _progress_feature(env.get("TERM_FEATURES", "")):
+        return True
+    if _known(env.get("TERM_PROGRAM", ""), env.get("TERM_PROGRAM_VERSION", "")):
+        return True
+    # iTerm2 sets these too, and ssh forwards LC_* by default.
+    if _known(env.get("LC_TERMINAL", ""), env.get("LC_TERMINAL_VERSION", "")):
+        return True
+    if env.get("TERM") == "xterm-ghostty" or env.get("GHOSTTY_RESOURCES_DIR"):
+        return True
+    if env.get("WEZTERM_EXECUTABLE"):
+        return True
+    if env.get("WT_SESSION") or env.get("ConEmuANSI") == "ON":
+        return True
+    # VTE 0.79 (GNOME Terminal, Ptyxis) and Konsole 26.04 added it.
+    return _number(env.get("VTE_VERSION")) >= 7900 or _number(env.get("KONSOLE_VERSION")) >= 260400
+
+
+def _into_tmux(sequence: str) -> str:
+    """Both ways through tmux, so neither needs asking about.
+
+    The passthrough copy reaches the outer terminal when `allow-passthrough`
+    is on, and is the only one that carries a keep-alive: tmux 3.7 forwards
+    the raw copy itself, but only when the active pane's state changes. Older
+    tmux drops the raw copy, and a terminal that gets both sees one state.
+    """
+    return _passthrough(sequence) + sequence
+
+
+def progress_transport(
+    mode: str, env: Mapping[str, str], *, tty: bool
+) -> Callable[[str], str] | None:
+    """How a report reaches the terminal (a wrapper), or None to send nothing.
+
+    `mode` is the preference: "off", "on" (send whatever the terminal), or
+    "auto" (only where the bar is known to be drawn).
+    """
+    if mode == "off" or not tty or env.get("TERM") == "dumb":
+        return None
+    if mode != "on" and not environment_supports(env):
+        return None
+    return _into_tmux if env.get("TMUX") else str
+
+
+# Keeping the bar in step with the turn
+
+
+class TabProgress:
+    """Mirror the turn into the terminal's tab progress, and keep it alive.
+
+    Blue (indeterminate) while a turn runs, filling as plan steps complete;
+    orange (paused) while a failed provider request is retried; red (error)
+    after a failed turn until a key is pressed here or the next turn starts.
+
+    Sampled from the activity once a second rather than pushed from each hook,
+    so a hosted session's mirrored state needs nothing extra, and written
+    straight to the terminal: an invisible OSC has no reason to wait for, or
+    cause, a repaint, and never lands inside a frame prompt_toolkit is still
+    building. With no terminal (`fd` None) the hooks still work and nothing
+    is sent.
+    """
+
+    def __init__(self, activity, fd: int | None, mode: str, env: Mapping[str, str] | None = None):
+        self.activity = activity
+        self.fd = fd
+        self.mode = mode
+        self.env = os.environ if env is None else env
+        self.retrying = False
+        # The last failure has been seen: its red bar is down.
+        self.dismissed = False
+        self.wrap: Callable[[str], str] | None = None
+        self.sent: str | None = None
+        self.sent_at = 0.0
+
+    def report(self) -> tuple[int, int | None]:
+        activity = self.activity
+        if activity.prompt_state == "running" or activity.user_command:
+            if self.retrying:
+                return PAUSED, None
+            # An empty bar reads as nothing happening; bounce until a step starts.
+            done = plan_progress(activity.plan)
+            if done:
+                return NORMAL, max(1, round(100 * done))
+            return INDETERMINATE, None
+        if activity.prompt_state == "failed" and not self.dismissed:
+            return ERROR, 100
+        return CLEAR, None
+
+    # The turn's hooks, from the terminal's view.
+
+    def turn_started(self) -> None:
+        self.retrying = False
+        self.dismissed = False
+
+    def turn_retry(self) -> None:
+        self.retrying = True
+
+    def turn_event(self) -> None:
+        self.retrying = False
+
+    def turn_ended(self) -> None:
+        # A turn that failed mid-retry never sends the event that ends it.
+        self.retrying = False
+
+    def switched(self) -> None:
+        """Another session is on screen: nothing seen or retried here is its."""
+        self.retrying = False
+        self.dismissed = False
+
+    def key_pressed(self, _event=None) -> None:
+        # Only once the red bar is up: typing ahead while a turn fails must
+        # not dismiss it before it was ever shown.
+        if self.sent == progress(ERROR, 100):
+            self.dismissed = True
+
+    def tick(self, now: float) -> None:
+        sequence = progress(*self.report())
+        idle = sequence == progress(CLEAR)
+        if sequence != self.sent or (not idle and now - self.sent_at >= KEEPALIVE_SECONDS):
+            self._write(sequence, now)
+
+    def close(self) -> None:
+        """Take the bar down on the way out; a dead pcode must not look busy."""
+        if self.sent not in (None, progress(CLEAR)):
+            self._write(progress(CLEAR), monotonic())
+
+    async def run(self) -> None:
+        tty = self.fd is not None and _isatty(self.fd)
+        self.wrap = progress_transport(self.mode, self.env, tty=tty)
+        if self.wrap is None:
+            return
+        try:
+            while True:
+                self.tick(monotonic())
+                await asyncio.sleep(TICK_SECONDS)
+        finally:
+            self.close()
+
+    @asynccontextmanager
+    async def shown(self):
+        """Keep the bar in step while the block runs, for a caller with no event loop of its own."""
+        task = asyncio.create_task(self.run())
+        try:
+            yield self
+        finally:
+            task.cancel()
+            # Now, not when the cancelled task next runs: the loop may be closing.
+            self.close()
+
+    def _write(self, sequence: str, now: float) -> None:
+        if self.wrap is None:
+            return
+        # On failure the terminal is gone; the next tick tries again.
+        if _write_all(self.fd, self.wrap(sequence).encode()):
+            self.sent, self.sent_at = sequence, now
+
+
+# The tab title
+
+# xterm's title stack (XTWINOPS 22/23): save the title the shell left, put it
+# back on the way out. xterm, iTerm2, kitty, Ghostty and VTE keep one;
+# elsewhere the title stays until the shell's prompt next sets its own.
+SAVE_TITLE = "\x1b[22;0t"
+RESTORE_TITLE = "\x1b[23;0t"
+
+
+def title(text: str) -> str:
+    """OSC 0, which sets the tab (icon) title and the window title alike.
+
+    OSC 2 alone leaves iTerm2's tab as it was, and OSC 1 alone is not read
+    by most other terminals. Inside tmux it names the pane, unwrapped: the
+    outer tab belongs to tmux, which shows it with `set-titles on`.
+    """
+    return f"\x1b]0;{' '.join(_CONTROL.sub(' ', text).split())[:120]}\x07"
+
+
+class TabTitle:
+    """Keep the terminal's title on the session's name, sampled once a second.
+
+    `source` is read on each tick, so a name given by /rename, by the model
+    during the first turn, or by the host a hosted terminal follows needs no
+    hook of its own. Nothing is sent until there is a name, so a session
+    without one leaves the title to the shell.
+    """
+
+    def __init__(self, source: Callable[[], str], fd: int | None, mode: str = "on") -> None:
+        self.source = source
+        self.fd = fd
+        self.mode = mode
+        self.sent = ""
+        self.saved = False
+
+    def tick(self) -> None:
+        try:
+            text = " ".join((self.source() or "").split())
+        except Exception:  # noqa: BLE001 - a title is never worth an error.
+            return
+        if text == self.sent:
+            return
+        if text:
+            data = ("" if self.saved else SAVE_TITLE) + title(text)
+        else:
+            # The name went (/new): hand the shell's title back, and keep it
+            # saved for the next name.
+            data = RESTORE_TITLE + SAVE_TITLE
+        if _write_all(self.fd, data.encode()):
+            self.sent, self.saved = text, True
+
+    def close(self) -> None:
+        if self.saved and _write_all(self.fd, RESTORE_TITLE.encode()):
+            self.saved, self.sent = False, ""
+
+    async def run(self) -> None:
+        if self.mode != "on" or self.fd is None or not _isatty(self.fd):
+            return
+        if os.environ.get("TERM") == "dumb":
+            return
+        try:
+            while True:
+                self.tick()
+                await asyncio.sleep(TICK_SECONDS)
+        finally:
+            self.close()
+
+
+def _write_all(fd: int | None, data: bytes) -> bool:
+    """Write all of `data` or report failure; False when the terminal is gone.
+
+    All of it or nothing: a truncated OSC leaves the terminal inside a string
+    that swallows the next frame. The fd may have been made non-blocking under
+    us; prompt_toolkit flushes frames the same way.
+    """
+    if fd is None:
+        return False
+    try:
+        blocking = os.get_blocking(fd)
+        os.set_blocking(fd, True)
+        try:
+            while data:
+                data = data[os.write(fd, data) :]
+        finally:
+            os.set_blocking(fd, blocking)
+    except OSError:
+        return False
+    return True
+
+
+def _isatty(fd: int) -> bool:
+    try:
+        return os.isatty(fd)
+    except OSError:
+        return False
+
+
+def terminal_fd(*streams) -> int | None:
+    """The descriptor of the first stream that is a terminal, or None."""
+    for stream in streams:
+        try:
+            fd = stream.fileno()
+        except (AttributeError, OSError, ValueError):
+            continue  # In memory (StringIO), or closed.
+        if _isatty(fd):
+            return fd
+    return None
+
+
+def send(output, sequence: str) -> None:
+    """Queue on a prompt_toolkit output; it goes out with the next repaint.
+
+    Never flushed here: scrollback handoffs build one atomic write across
+    awaits, and flushing in the middle of one sends half a frame early (the
+    tmux cursor tests caught exactly that). An invisible OSC riding along
+    with a repaint changes nothing on screen.
+    """
+    try:
+        output.write_raw(sequence)
+    except Exception:  # noqa: BLE001 - a notification is never worth an error.
+        pass

pcode/theme.py

@@ -0,0 +1,135 @@
+"""Best-effort startup detection of the terminal's default background.
+
+OSC 11 is an xterm query, not a command to change the terminal's colors.
+Never query while prompt_toolkit owns input; cache the result at startup.
+"""
+
+import os
+import re
+import select
+import sys
+import time
+
+THEMES = ("dark", "light", "auto")
+_pending_input = bytearray()
+_BACKGROUND = re.compile(
+    rb"\x1b\]11;rgb:([0-9a-fA-F]{1,4})/([0-9a-fA-F]{1,4})/([0-9a-fA-F]{1,4})(?:\x07|\x1b\\)"
+)
+
+
+def background_theme(response: bytes) -> str | None:
+    """Classify an OSC 11 RGB response (components may use 1–4 hex digits)."""
+    match = _BACKGROUND.search(response)
+    if match is None:
+        return None
+    rgb = [int(value, 16) / (16 ** len(value) - 1) for value in match.groups()]
+    # Perceived brightness, rather than the unweighted RGB average.
+    brightness = sum(value * weight for value, weight in zip(rgb, (0.299, 0.587, 0.114)))
+    return "light" if brightness >= 0.5 else "dark"
+
+
+def _terminal():
+    """Descriptors to read the reply on and write the query to, plus any handle to close.
+
+    Standard streams first, so an ordinary session queries exactly what it
+    talks to. `--print` can be fed its prompt on stdin and still render to a
+    terminal, so a redirected stream falls back to the controlling terminal
+    instead of costing detection. Reading and writing are separate because
+    stdin is not always opened for writing.
+    """
+    if sys.stdin.isatty() and sys.stdout.isatty():
+        return sys.stdin.fileno(), sys.stdout.fileno(), None
+    try:
+        handle = open("/dev/tty", "r+b", buffering=0)
+    except OSError:  # No controlling terminal: a daemon, or a CI runner.
+        return None, None, None
+    return handle.fileno(), handle.fileno(), handle
+
+
+def _query_background(timeout: float = 0.15) -> str | None:
+    # Nothing will be colored, so there is no palette to match: stay quiet
+    # rather than write an escape sequence into whatever stdout is.
+    if os.environ.get("TERM") == "dumb" or not (sys.stdout.isatty() or sys.stderr.isatty()):
+        return None
+    try:
+        import termios
+    except ImportError:
+        return None
+    fd, query_fd, handle = _terminal()
+    if fd is None:
+        return None
+    response = bytearray()
+    try:
+        # Don't steal already queued input, or flush it on entering/leaving cbreak.
+        if select.select([fd], [], [], 0)[0]:
+            return None
+        original = termios.tcgetattr(fd)
+        mode = termios.tcgetattr(fd)
+        mode[3] &= ~(termios.ICANON | termios.ECHO)
+        mode[6][termios.VMIN] = 0
+        mode[6][termios.VTIME] = 0
+        try:
+            termios.tcsetattr(fd, termios.TCSANOW, mode)
+            # Canonical mode hides an unfinished line from select(). Check again
+            # now that every queued character is visible, without consuming it.
+            if select.select([fd], [], [], 0)[0]:
+                return None
+            if handle is None:
+                # Keep the query behind any text already queued on stdout.
+                sys.stdout.flush()
+            os.write(query_fd, b"\x1b]11;?\x1b\\")
+            deadline = time.monotonic() + timeout
+            while True:
+                remaining = deadline - time.monotonic()
+                if remaining <= 0 or not select.select([fd], [], [], remaining)[0]:
+                    break
+                chunk = os.read(fd, 1)
+                if not chunk:
+                    break
+                response.extend(chunk)
+                result = background_theme(response)
+                if result is not None:
+                    response[:] = _BACKGROUND.sub(b"", response)
+                    return result
+        finally:
+            termios.tcsetattr(fd, termios.TCSANOW, original)
+    except (OSError, ValueError, termios.error):
+        pass
+    finally:
+        if handle is not None:
+            handle.close()
+        else:
+            # Typing can race the query. Only the OSC reply belongs to us;
+            # replay everything else through the editor's normal input parser.
+            _pending_input.extend(response)
+    return None
+
+
+def replay_pending_input(app, on_theme=None) -> None:
+    """Return bytes read during the probe before the editor reads newer input.
+
+    Also keeps filtering appearance replies out of typing for the whole
+    session, passing each to `on_theme`: a late answer to the startup probe,
+    and every later one `pcode.appearance` asks for.
+    """
+    from prompt_toolkit.input.vt100 import Vt100Input
+
+    from pcode.startup_input import StartupInput
+
+    if not isinstance(app.input, Vt100Input):
+        return
+    app.input = StartupInput(app.input.stdin, bytes(_pending_input), on_theme)
+    _pending_input.clear()
+
+
+def detect_theme() -> str:
+    """Use OSC 11, then COLORFGBG (when supplied by the terminal), then dark."""
+    detected = _query_background()
+    if detected is not None:
+        return detected
+    try:
+        background = int(os.environ.get("COLORFGBG", "").split(";")[-1])
+    except ValueError:
+        return "dark"
+    # COLORFGBG describes ANSI palette indices, not RGB values.
+    return "light" if background in (7, 15) else "dark"

pcode/theme_gallery.py

@@ -0,0 +1,88 @@
+"""One-line samples of every installed Pygments style, plus how to select one."""
+
+from dataclasses import dataclass
+from functools import cache
+
+from rich.console import Console, ConsoleOptions, RenderResult
+from rich.syntax import Syntax
+from rich.text import Text
+
+from pcode.syntax import transparent_theme
+
+# Short enough to survive a narrow terminal, wide enough to show a keyword, a
+# function name, a string, a number, and a comment in one row.
+SAMPLE = 'def greet(name="world", times=2):  # sample'
+
+
+@cache
+def _sample(style: str) -> Text:
+    """The sample line highlighted by one style, with its background dropped.
+
+    Fenced code is rendered on the terminal's own background, so the gallery
+    has to preview the same transparent rendering rather than each style's
+    designed background: a row that looked right on its own block could still
+    be unreadable in the transcript.
+    """
+    try:
+        text = Syntax(SAMPLE, "python", theme=transparent_theme(style)).highlight(SAMPLE)
+    except Exception:  # A broken plugin style must not take the gallery with it.
+        return Text(SAMPLE)
+    text.rstrip()
+    return text
+
+
+@dataclass(frozen=True)
+class SyntaxGallery:
+    """Every selectable syntax style, marking the one the transcript is using."""
+
+    styles: tuple[str, ...]
+    palette: str = "dark"
+    dark: str = ""
+    light: str = ""
+
+    def __rich_console__(self, console: Console, options: ConsoleOptions) -> RenderResult:
+        yield Text("Syntax styles", style="pcode.accent")
+        yield Text(
+            f"dark: {self.dark} · light: {self.light}",
+            style="pcode.muted",
+            no_wrap=True,
+            overflow="ellipsis",
+        )
+        yield from self._samples()
+        yield Text()
+        yield from self._instructions()
+
+    def _samples(self) -> RenderResult:
+        current = self.dark if self.palette == "dark" else self.light
+        width = max(len(name) for name in self.styles) + 2
+        for name in self.styles:
+            active = name == current
+            row = Text(
+                "▸ " if active else "  ",
+                style="pcode.accent",
+                no_wrap=True,
+                overflow="ellipsis",
+            )
+            row.append(name.ljust(width), style="pcode.accent" if active else "pcode.muted")
+            # `terminal` is not a Pygments style; it renders with the ANSI one.
+            row.append_text(_sample(f"ansi_{self.palette}" if name == "terminal" else name))
+            yield row
+
+    def _instructions(self) -> RenderResult:
+        for command, note in (
+            ("/syntax NAME", f"style the palette in use ({self.palette})"),
+            ("/theme dark|light", "switch palettes, then /syntax for that one"),
+            ("/syntax terminal", "use the terminal's own colors everywhere"),
+            ("/config set syntax_dark NAME", "save the dark-palette style"),
+            ("/config set syntax_light NAME", "save the light-palette style"),
+        ):
+            line = Text("  ", no_wrap=True, overflow="ellipsis")
+            line.append(command.ljust(30), style="pcode.accent")
+            line.append(note, style="pcode.muted")
+            yield line
+        yield Text(
+            "  Outside the editor: pcode config set syntax_dark NAME",
+            style="pcode.muted",
+            no_wrap=True,
+            overflow="ellipsis",
+        )

pcode/thinking_markdown.py

@@ -0,0 +1,41 @@
+"""Muted Markdown for readable thinking with normal block spacing."""
+
+from dataclasses import dataclass
+
+from rich.markdown import Markdown
+from rich.segment import Segment
+
+
+@dataclass
+class ThinkingMarkdown:
+    source: str
+    code_theme: str = "monokai"
+    style: str = "pcode.thinking"
+
+    def __rich_console__(self, console, options):
+        # Codex also emits heading-only Markdown summaries:
+        # https://github.com/openai/codex/issues/34873
+        markdown = Markdown(self.source, code_theme=self.code_theme)
+        # Keep provider line boundaries rather than folding adjacent thoughts
+        # into a single paragraph. Markdown's other inline/block rules still apply.
+        for token in markdown.parsed:
+            for child in token.children or ():
+                if child.type == "softbreak":
+                    child.type = "hardbreak"
+        style = console.get_style(self.style)
+        # Keep one spacer row between blocks, including streamed commits. Rich
+        # also pads lists/code with blank rows; don't double those on replay.
+        pending_blank = False
+        rendered = False
+        for line in Segment.split_lines(console.render(markdown, options)):
+            if not any(segment.text.strip() for segment in line):
+                pending_blank = rendered
+                continue
+            if pending_blank:
+                yield Segment.line()
+            yield from Segment.apply_style(line, post_style=style)
+            yield Segment.line()
+            rendered = True
+            pending_blank = False
+        if rendered:
+            yield Segment.line()