shikiru-cli 0.2.0__py3-none-any.whl

shikiru/ui/session.py

@@ -0,0 +1,65 @@
+"""Shared facts for session listings and attach options."""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from rich.text import Text
+
+from shikiru.ui.glyphs import GLYPH_ENGINE
+from shikiru.ui.section import BOLD_PRIMARY, number
+from shikiru.ui.tokens import AMBER, SECONDARY_TEXT_COLOR, STYLE_BOLD, SUCCESS_COLOR
+
+_SessionEngineState = Literal["up", "down"]
+
+
+def session_identity(session: str) -> Text:
+    """Return a session identity as bold literal text."""
+    return Text(session, style=BOLD_PRIMARY, overflow="fold")
+
+
+def session_engine_value(engine_state: _SessionEngineState) -> Text:
+    """Return the engine glyph and muted or active state word."""
+    match engine_state:
+        case "up":
+            style = f"{STYLE_BOLD} {SUCCESS_COLOR}"
+        case "down":
+            style = SECONDARY_TEXT_COLOR
+    return Text.assemble(
+        (GLYPH_ENGINE, style),
+        (" ", SECONDARY_TEXT_COLOR),
+        (engine_state, style),
+    )
+
+
+def session_engine_fact(engine_state: _SessionEngineState) -> Text:
+    """Return the labeled engine state used in a stacked session row."""
+    text = Text("Engine ", style=SECONDARY_TEXT_COLOR)
+    text.append_text(session_engine_value(engine_state))
+    return text
+
+
+def session_count(label: str, count: int) -> Text:
+    """Return one labeled session count."""
+    return Text.assemble((f"{label} ", SECONDARY_TEXT_COLOR), number(str(count)))
+
+
+def escalation_count(count: int) -> Text:
+    """Return an amber nonzero escalation count or a muted zero."""
+    style = f"{STYLE_BOLD} {AMBER}" if count else SECONDARY_TEXT_COLOR
+    return Text(str(count), style=style)
+
+
+def session_facts(
+    engine_state: _SessionEngineState,
+    running: int,
+    queued: int,
+    escalated: int,
+) -> tuple[Text, ...]:
+    """Return engine and progress facts in their shared display order."""
+    return (
+        session_engine_fact(engine_state),
+        session_count("running", running),
+        session_count("queued", queued),
+        Text.assemble(("escalated ", SECONDARY_TEXT_COLOR), escalation_count(escalated)),
+    )

shikiru/ui/size.py

@@ -0,0 +1,17 @@
+"""Human-readable byte counts."""
+
+from __future__ import annotations
+
+_UNITS = ("B", "KiB", "MiB", "GiB", "TiB")
+_UNIT_STEP = 1024
+
+
+def format_size(size_bytes: int) -> str:
+    """Return `size_bytes` in the largest binary unit that keeps it at or above one."""
+    value = float(size_bytes)
+    unit = _UNITS[0]
+    for unit in _UNITS:
+        if value < _UNIT_STEP or unit == _UNITS[-1]:
+            break
+        value /= _UNIT_STEP
+    return f"{value:.0f} {unit}" if unit == _UNITS[0] else f"{value:.1f} {unit}"

shikiru/ui/splash.py

@@ -0,0 +1,42 @@
+"""Escalation splash panels."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from rich.text import Text
+
+from shikiru.ui.tokens import ALERT_COLOR, STYLE_BOLD, STYLE_DIM
+
+_SPEED_LINE = "\N{BOX DRAWINGS LIGHT DIAGONAL UPPER RIGHT TO LOWER LEFT}"
+_OPTION_PREFIX = "  "
+
+
+@dataclass(frozen=True)
+class SplashPanel:
+    """Render an escalation headline, question and packet options in an alert frame."""
+
+    headline: str
+    question: str
+    options: tuple[str, ...]
+    pulse_red: bool = True
+
+    def render(self) -> Text:
+        """Render the panel with numbered options and red speed-line framing."""
+        lines = Text()
+        prefix = f"{_SPEED_LINE} {_SPEED_LINE} "
+        suffix = f" {_SPEED_LINE} {_SPEED_LINE}"
+        top = f"{prefix}{self.headline}{suffix}"
+        lines.append(f"{top}\n")
+        lines.append(self.question)
+        for number, option in enumerate(self.options, start=1):
+            lines.append(f"\n{_OPTION_PREFIX}{number}. {option}")
+        bottom = f"{_SPEED_LINE} {_SPEED_LINE} {_SPEED_LINE}"
+        lines.append(f"\n{bottom}")
+        border_style = f"{STYLE_BOLD} {ALERT_COLOR}" if self.pulse_red else STYLE_DIM
+        lines.stylize(border_style, 0, len(prefix))
+        suffix_start = len(prefix) + len(self.headline)
+        lines.stylize(border_style, suffix_start, len(top))
+        bottom_start = len(lines.plain) - len(bottom)
+        lines.stylize(border_style, bottom_start, len(lines.plain))
+        return lines

shikiru/ui/status.py

@@ -0,0 +1,47 @@
+"""Shared task-status visuals for operator surfaces."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from shikiru.domain.tasks import Status
+from shikiru.ui.glyphs import (
+    GLYPH_BLOCKED,
+    GLYPH_DONE,
+    GLYPH_ENGINE,
+    GLYPH_ESCALATED,
+    GLYPH_PENDING,
+)
+from shikiru.ui.tokens import (
+    ALERT_COLOR,
+    ENGINE_COLOR,
+    IDLE_COLOR,
+    REWORK_COLOR,
+    STYLE_BOLD,
+    STYLE_DIM,
+    STYLE_REVERSE,
+    SUCCESS_COLOR,
+)
+
+
+@dataclass(frozen=True, slots=True)
+class StatusVisual:
+    """The glyph and Rich style representing one task status."""
+
+    glyph: str
+    style: str
+
+
+_STATUS_VISUALS: dict[Status, StatusVisual] = {
+    Status.QUEUED: StatusVisual(GLYPH_PENDING, f"{STYLE_DIM} {IDLE_COLOR}"),
+    Status.RUNNING: StatusVisual(GLYPH_ENGINE, f"{STYLE_BOLD} {ENGINE_COLOR}"),
+    Status.INTEGRATING: StatusVisual(GLYPH_ENGINE, f"{STYLE_BOLD} {ENGINE_COLOR}"),
+    Status.ESCALATED: StatusVisual(GLYPH_ESCALATED, f"{STYLE_REVERSE} {ALERT_COLOR}"),
+    Status.DONE: StatusVisual(GLYPH_DONE, f"{STYLE_BOLD} {SUCCESS_COLOR}"),
+    Status.CANCELLED: StatusVisual(GLYPH_BLOCKED, f"{STYLE_BOLD} {REWORK_COLOR}"),
+}
+
+
+def status_visual(status: Status) -> StatusVisual:
+    """Return the shared glyph and style for `status`."""
+    return _STATUS_VISUALS[status]

shikiru/ui/status_strip.py

@@ -0,0 +1,149 @@
+"""A status strip pinned above a scrolling terminal view, without touching the output below it."""
+
+from __future__ import annotations
+
+import os
+import re
+import select
+import termios
+import textwrap
+import tty
+from typing import TYPE_CHECKING
+
+from rich.text import Text
+
+if TYPE_CHECKING:
+    from typing import TextIO
+
+    from rich.console import Console
+
+_ESCAPE = "\x1b"
+_CSI = f"{_ESCAPE}["
+_SAVE_CURSOR = f"{_ESCAPE}7"
+_RESTORE_CURSOR = f"{_ESCAPE}8"
+_RESET_REGION = f"{_CSI}r"
+_ERASE_LINE = f"{_CSI}2K"
+_CURSOR_REPORT_REQUEST = f"{_CSI}6n"
+_CURSOR_REPORT = re.compile(rf"{_ESCAPE}\[(\d+);\d+R")
+_CURSOR_REPORT_TIMEOUT_SECONDS = 2.0
+_REPORT_READ_BYTES = 64
+_FIRST_COLUMN = 1
+_FIRST_ROW = 1
+_NO_ROWS: tuple[str, ...] = ()
+_CLEAR_SCROLLBACK = f"{_CSI}3J"
+_CLEAR_SCREEN = f"{_CSI}2J"
+_HOME = f"{_CSI}H"
+
+
+class CursorReportError(RuntimeError):
+    """The terminal did not report where its cursor is."""
+
+
+def _go_to(row: int) -> str:
+    return f"{_CSI}{row};{_FIRST_COLUMN}H"
+
+
+class StatusStrip:
+    """Reserves the top rows of a terminal for a status text and keeps the output below it.
+
+    The strip sits in rows `1..height`; output scrolls in the rows beneath it through a scroll
+    region, so it never overwrites or duplicates the strip. Showing or hiding the strip shifts
+    the visible output by its height instead of overwriting it; the rows pushed off the top
+    stay in the terminal's scrollback. A horizontal resize clears the reflowed terminal buffer;
+    the view then restores its output from the event log under the newly sized strip.
+    """
+
+    def __init__(self, console: Console, keyboard: TextIO, style: str) -> None:
+        """Draw onto `console` in `style`, asking the terminal behind `keyboard` for its cursor."""
+        self._console = console
+        self._keyboard = keyboard
+        self._style = style
+        self._rows: tuple[str, ...] = _NO_ROWS
+        self._width: int = console.size.width
+        self._height: int = console.size.height
+
+    def sync(self, text: str | None) -> bool:
+        """Draw `text` unless its row count changed; return whether output must be replayed."""
+        size = self._console.size
+        rows = self._wrap(text, size.width, size.height)
+        if rows == self._rows and size.width == self._width and size.height == self._height:
+            return False
+        if self._rows and len(rows) != len(self._rows):
+            return True
+        self._width = size.width
+        self._height = size.height
+        self._apply(rows, size.height)
+        return False
+
+    @property
+    def active(self) -> bool:
+        """Return whether a status currently reserves terminal rows."""
+        return bool(self._rows)
+
+    def reset_for_replay(self) -> None:
+        """Clear the screen and scrollback before the view restores its logged output."""
+        out = self._console.file
+        out.write(_CLEAR_SCREEN + _CLEAR_SCROLLBACK + _RESET_REGION + _HOME)
+        out.flush()
+        self._rows = _NO_ROWS
+        self._width = self._console.size.width
+        self._height = self._console.size.height
+
+    def _wrap(self, text: str | None, width: int, height: int) -> tuple[str, ...]:
+        if text is None:
+            return _NO_ROWS
+        return tuple(textwrap.wrap(text, width) or [""])[: max(height - 1, 1)]
+
+    def _apply(self, rows: tuple[str, ...], terminal_height: int) -> None:
+        previous = len(self._rows)
+        row = min(self._cursor_row(), terminal_height)
+        out = self._console.file
+        out.write(_RESET_REGION)
+        if len(rows) > previous:
+            grown = len(rows) - previous
+            overflow = max(row + grown - terminal_height, 0)
+            out.write(_go_to(terminal_height) + "\n" * overflow)
+            out.write(_go_to(previous + 1) + f"{_CSI}{grown}L")
+            row = min(row + grown, terminal_height)
+        elif len(rows) < previous:
+            shrunk = previous - len(rows)
+            out.write(_go_to(len(rows) + 1) + f"{_CSI}{shrunk}M")
+            row = max(row - shrunk, _FIRST_ROW)
+        if rows:
+            out.write(f"{_CSI}{len(rows) + 1};{terminal_height}r")
+        out.write(_go_to(row))
+        out.flush()
+        self._rows = rows
+        self._draw(rows)
+
+    def _draw(self, rows: tuple[str, ...]) -> None:
+        out = self._console.file
+        out.write(_SAVE_CURSOR)
+        for index, line in enumerate(rows):
+            out.write(_go_to(index + 1) + _ERASE_LINE)
+            self._console.print(Text(line, style=self._style), end="")
+        out.write(_RESTORE_CURSOR)
+        out.flush()
+
+    def _cursor_row(self) -> int:
+        descriptor = self._keyboard.fileno()
+        saved = termios.tcgetattr(descriptor)
+        try:
+            tty.setcbreak(descriptor)
+            self._console.file.write(_CURSOR_REPORT_REQUEST)
+            self._console.file.flush()
+            received = ""
+            while True:
+                ready, _, _ = select.select([descriptor], [], [], _CURSOR_REPORT_TIMEOUT_SECONDS)
+                if not ready:
+                    message = "the terminal did not answer the cursor position request"
+                    raise CursorReportError(message)
+                received += self._read(descriptor)
+                report = _CURSOR_REPORT.search(received)
+                if report is not None:
+                    return int(report.group(1))
+        finally:
+            termios.tcsetattr(descriptor, termios.TCSADRAIN, saved)
+
+    def _read(self, descriptor: int) -> str:
+        return os.read(descriptor, _REPORT_READ_BYTES).decode(errors="ignore")

shikiru/ui/stream.py

@@ -0,0 +1,152 @@
+"""Renders a role's `view.jsonl` rows as terminal lines."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from rich.text import Text
+
+from shikiru.agents.contracts import (
+    Compacted,
+    Message,
+    QuotaReported,
+    SessionStarted,
+    ToolFinished,
+    ToolOutcome,
+    ToolStarted,
+    TurnEnded,
+    TurnFailed,
+    UsageReported,
+)
+from shikiru.ui.glyphs import GLYPH_DONE, GLYPH_ESCALATED, GLYPH_PENDING, ROLE_GLYPHS
+from shikiru.ui.tokens import ALERT_COLOR, IDLE_COLOR, ROLE_COLORS, STYLE_BOLD, STYLE_DIM
+from shikiru.view_log import VIEW_RUNG_KEY, VIEW_SIGNAL_KEY, VIEW_TURN_KEY
+
+if TYPE_CHECKING:
+    from collections.abc import Callable, Mapping
+
+    from shikiru.domain.tasks import Role
+
+type ViewRow = Mapping[str, Any]
+
+_TOOL_GLYPH = "▸"
+_RUNG_SEPARATOR = ":"
+_EFFORT_SEPARATOR = "/"
+_DETAIL_SEPARATOR = " · "
+_OUTCOME_FIELD = "outcome"
+_EXIT_CODE_FIELD = "exit_code"
+_EXIT_LABEL = "exit"
+
+
+class UnknownViewSignalError(ValueError):
+    """A `view.jsonl` row names a signal this renderer does not know."""
+
+
+class StreamLine:
+    """Turns view rows into Rich lines, opening each new turn with its step and rung."""
+
+    def __init__(self, role: Role) -> None:
+        """Render rows for `role`, whose colour and glyph mark turn boundaries."""
+        self._role = role
+        self._turn: str | None = None
+        self._renderers: dict[str, Callable[[ViewRow], Text | None]] = {
+            SessionStarted.__name__: _session_started,
+            Message.__name__: _message,
+            ToolStarted.__name__: _tool_started,
+            ToolFinished.__name__: _tool_finished,
+            UsageReported.__name__: _usage,
+            QuotaReported.__name__: _silent,
+            Compacted.__name__: _compacted,
+            TurnEnded.__name__: _turn_ended,
+            TurnFailed.__name__: _turn_failed,
+        }
+
+    def reset(self) -> None:
+        """Reset turn-boundary tracking before replaying a view log from its start."""
+        self._turn = None
+
+    def render(self, row: ViewRow) -> list[Text]:
+        """Return the lines `row` adds to the view, headed by a boundary on a new turn."""
+        signal = row[VIEW_SIGNAL_KEY]
+        renderer = self._renderers.get(signal)
+        if renderer is None:
+            message = f"unknown view signal {signal!r}"
+            raise UnknownViewSignalError(message)
+        lines: list[Text] = []
+        if row[VIEW_TURN_KEY] != self._turn:
+            self._turn = row[VIEW_TURN_KEY]
+            lines.append(self._boundary(row))
+        line = renderer(row)
+        if line is not None:
+            lines.append(line)
+        return lines
+
+    def _boundary(self, row: ViewRow) -> Text:
+        rung = row[VIEW_RUNG_KEY]
+        label = _RUNG_SEPARATOR.join((rung["agent"], rung["model"]))
+        if rung["effort"]:
+            label = f"{label}{_EFFORT_SEPARATOR}{rung['effort']}"
+        return Text(
+            f"{ROLE_GLYPHS[self._role]} {row[VIEW_TURN_KEY]} · {label}",
+            style=f"{STYLE_BOLD} {ROLE_COLORS[self._role]}",
+        )
+
+
+def _silent(_row: ViewRow) -> None:
+    return None
+
+
+def _session_started(row: ViewRow) -> Text:
+    return Text(f"{GLYPH_PENDING} session {row['session_id']}", style=STYLE_DIM)
+
+
+def _message(row: ViewRow) -> Text:
+    return Text(row["text"])
+
+
+def _tool_started(row: ViewRow) -> Text:
+    detail = f" {row['detail']}" if row["detail"] else ""
+    return Text(f"{_TOOL_GLYPH} {row['name']}{detail}", style=IDLE_COLOR)
+
+
+def _tool_finished(row: ViewRow) -> Text | None:
+    outcome = row.get(_OUTCOME_FIELD)
+    exit_code = row.get(_EXIT_CODE_FIELD)
+    if (
+        outcome not in (ToolOutcome.SUCCESS.value, ToolOutcome.FAILURE.value)
+        and type(exit_code) is not int
+    ):
+        return None
+    details = [row["name"]]
+    if outcome in (ToolOutcome.SUCCESS.value, ToolOutcome.FAILURE.value):
+        details.append(outcome)
+    if type(exit_code) is int:
+        details.append(f"{_EXIT_LABEL} {exit_code}")
+    style = _tool_outcome_style(outcome)
+    return Text(f"{_TOOL_GLYPH} {_DETAIL_SEPARATOR.join(details)}", style=style)
+
+
+def _tool_outcome_style(outcome: object) -> str:
+    if outcome == ToolOutcome.FAILURE.value:
+        return ALERT_COLOR
+    if outcome == ToolOutcome.SUCCESS.value:
+        return IDLE_COLOR
+    return STYLE_DIM
+
+
+def _usage(row: ViewRow) -> Text:
+    usage = row["usage"]
+    tokens = usage["input_tokens"] + usage["output_tokens"]
+    return Text(f"{GLYPH_PENDING} {tokens} tokens", style=STYLE_DIM)
+
+
+def _compacted(_row: ViewRow) -> Text:
+    return Text(f"{GLYPH_PENDING} context compacted", style=STYLE_DIM)
+
+
+def _turn_ended(_row: ViewRow) -> Text:
+    return Text(f"{GLYPH_DONE} turn ended", style=STYLE_DIM)
+
+
+def _turn_failed(row: ViewRow) -> Text:
+    return Text(f"{GLYPH_ESCALATED} {row['kind']}: {row['message']}", style=ALERT_COLOR)