stcode 0.0.1a0__py3-none-any.whl

stcode/cli/ui/components/status.py

@@ -0,0 +1,95 @@
+"""Session status and its presentation-only spinner."""
+
+from __future__ import annotations
+import contextlib
+from typing import Callable
+from rich.text import Text
+from textual.timer import Timer
+from textual.widgets import Static
+from stcode.cli import labels
+from stcode.cli.logic.state import ClientState
+from stcode.cli.ui.theme import PRIMARY
+
+SPINNER_INTERVAL = 0.1
+
+
+class Status(Static):
+    DEFAULT_CSS = """
+    Status { height: 1; color: $text-muted; }
+    """
+
+    def __init__(
+        self, state: ClientState, *, daemonless: bool, address: Callable[[], str]
+    ) -> None:
+        super().__init__("", id="status")
+        self.state = state
+        self.daemonless = daemonless
+        self.address = address
+        self.working = False
+        self._spinner = 0
+        self._spinner_timer: Timer | None = None
+
+    def on_mount(self) -> None:
+        self.refresh_display()
+
+    def on_unmount(self) -> None:
+        self.stop_working()
+
+    def refresh_display(self) -> None:
+        effective, config = self.state.effective, self.state.config
+        mode = effective.get("mode") or str(config.get("approval_mode", ""))
+        model = effective.get("model") or str(config.get("model", ""))
+        provider = self.state.provider
+
+        text = Text()
+        if self.working:
+            frame = labels.SPINNER_FRAMES[self._spinner % len(labels.SPINNER_FRAMES)]
+            text.append(labels.working_status(frame), style=f"bold {PRIMARY}")
+        text.append("model ", style="dim")
+        text.append(model or labels.STATUS_NO_MODEL, style="bold" if model else "dim")
+        text.append("   provider ", style="dim")
+        text.append(provider)
+        if mode:
+            text.append("   mode ", style="dim")
+            text.append(
+                mode, style=f"bold {labels.APPROVAL_MODE_COLOR.get(mode, 'white')}"
+            )  # type: ignore[call-overload]
+        effort = self.state.effort
+        if effort:
+            text.append("   effort ", style="dim")
+            text.append(effort)
+        if self.daemonless:
+            # The one shape where "which agent am I talking to" is a live question.
+            text.append("   daemon ", style="dim")
+            text.append(self.address())
+        with contextlib.suppress(Exception):
+            self.update(text)
+
+    def start_working(self) -> None:
+        """Spin, from the moment the message is queued.
+
+        The first token can be seconds away — a cold local model, a long system prompt,
+        a retry — and until it arrives the screen is identical to one where nothing
+        happened. A spinner in the status line is the difference between "it is
+        thinking" and "did that send?", which is the only question anybody has in that
+        gap.
+        """
+        if self.working:
+            return
+        self.working = True
+        self._spinner = 0
+        self._spinner_timer = self.set_interval(SPINNER_INTERVAL, self._tick_spinner)
+        self.refresh_display()
+
+    def _tick_spinner(self) -> None:
+        self._spinner += 1
+        self.refresh_display()
+
+    def stop_working(self) -> None:
+        if not self.working:
+            return
+        self.working = False
+        if self._spinner_timer is not None:
+            self._spinner_timer.stop()
+            self._spinner_timer = None
+        self.refresh_display()

stcode/cli/ui/components/transcript/__init__.py

@@ -0,0 +1,51 @@
+"""Transcript components and formatting helpers."""
+
+from .entries import (
+    AgentRow,
+    Message,
+    Notice,
+    PlatformNote,
+    Progress,
+    ShellOutput,
+    Thinking,
+    ToolCall,
+)
+from .view import Transcript
+from .formatting import (
+    AGENT_COLOURS,
+    ARGUMENT_CHARS,
+    PROGRESS_LINES,
+    SHELL_OUTPUT_LINES,
+    THINKING_LINES,
+    TOOL_RESULT_LINES,
+    agent_colour,
+    format_arguments,
+    platform_rule,
+    shell_render,
+    thinking_tail,
+    tool_render,
+)
+
+__all__ = [
+    "AGENT_COLOURS",
+    "ARGUMENT_CHARS",
+    "PROGRESS_LINES",
+    "SHELL_OUTPUT_LINES",
+    "THINKING_LINES",
+    "TOOL_RESULT_LINES",
+    "AgentRow",
+    "Message",
+    "Notice",
+    "PlatformNote",
+    "Progress",
+    "ShellOutput",
+    "Thinking",
+    "ToolCall",
+    "Transcript",
+    "agent_colour",
+    "format_arguments",
+    "platform_rule",
+    "shell_render",
+    "thinking_tail",
+    "tool_render",
+]

stcode/cli/ui/components/transcript/entries.py

@@ -0,0 +1,232 @@
+"""Transcript entry widgets; update in place as frames arrive."""
+
+from __future__ import annotations
+from typing import Any, Mapping
+from rich.text import Text
+from textual.containers import Horizontal, VerticalScroll
+from textual.widget import Widget
+from textual.widgets import Static
+from stcode.cli.ui.theme import brand_text
+from stcode.cli.ui.components.transcript.formatting import (
+    PROGRESS_LINES,
+    agent_colour,
+    thinking_tail,
+    tool_render,
+    shell_render,
+    platform_rule,
+)
+
+
+class Message(Static):
+    """One block of text — the user's, or the model's answer.
+
+    `you` is labelled and the model is not: on a screen where one side is the one
+    typing, only one of them needs saying.
+    """
+
+    def __init__(self, role: str, body: str = "") -> None:
+        super().__init__(classes=f"entry message {role}", markup=False)
+        self._role = role
+        self.body = body
+
+    def on_mount(self) -> None:
+        self._refresh()
+
+    def append(self, text: str) -> None:
+        self.body += text
+        self._refresh()
+
+    def _refresh(self) -> None:
+        if self._role == "user":
+            text = Text()
+            # Resolved here rather than written as `$text-primary`: a Rich style string
+            # is not CSS and cannot reference a theme variable.
+            text.append(
+                "you  ", style=f"bold {brand_text(self.app.current_theme.dark)}"
+            )
+            text.append(self.body.replace("\n", "\n     "))
+            self.update(text)
+        else:
+            self.update(Text(self.body))
+
+
+class Thinking(VerticalScroll):
+    """Reasoning, quoted and dim, showing the last six lines and scrollable.
+
+    Its own scroller rather than a growing block: reasoning can be longer than the
+    answer, and a model that thought for two pages must not push the answer it then
+    gave off the screen.
+    """
+
+    def __init__(self, body: str = "") -> None:
+        super().__init__(classes="entry thinking")
+        self.body = body
+        self._text = Static(markup=False)
+
+    def compose(self) -> Any:
+        yield self._text
+
+    def on_mount(self) -> None:
+        self._refresh()
+
+    def append(self, text: str) -> None:
+        self.body += text
+        self._refresh()
+
+    def _refresh(self) -> None:
+        quoted = "\n".join(
+            f"│ {line}" for line in thinking_tail(self.body).splitlines()
+        )
+        self._text.update(Text(quoted, style="italic dim"))
+        self.scroll_end(animate=False)
+
+
+class Progress(VerticalScroll):
+    """A long-running tool's output while it is still running — `repl`'s cell printing,
+    `bash`'s description, a web fetch saying which URL it is on.
+
+    Plain dim text, in a scroller that shows the last few lines. Deliberately *not* a
+    platform rule: a rule is one line saying what the platform did, and a REPL cell that
+    prints forty lines of an MCP result is neither one line nor the platform. Rendering
+    it as one produced forty dashed rules with a word centred in each.
+
+    It is also not the model talking, so it stays dim and unattributed, and it is never
+    written to the session — `Progress` is advisory, and the tool's own result is the
+    record.
+    """
+
+    def __init__(self, body: str = "") -> None:
+        super().__init__(classes="entry progress")
+        self.body = body
+        self._text = Static(markup=False)
+
+    def compose(self) -> Any:
+        yield self._text
+
+    def on_mount(self) -> None:
+        self._refresh()
+
+    def append(self, text: str) -> None:
+        # One frame per line, so the lines have to be rejoined here rather than run on.
+        self.body = f"{self.body}\n{text}" if self.body else text
+        self._refresh()
+
+    def _refresh(self) -> None:
+        self._text.update(Text(thinking_tail(self.body, PROGRESS_LINES), style="dim"))
+        self.scroll_end(animate=False)
+
+
+class ToolCall(Static):
+    """A tool call, updated in place when its result arrives.
+
+    In place, because `tool_started` and `tool_finished` are the same event to a
+    reader: two boxes for one call would double the transcript and say nothing more.
+    """
+
+    def __init__(self, name: str, arguments: Mapping[str, Any]) -> None:
+        super().__init__(classes="entry tool", markup=False)
+        self._name = name
+        self._arguments = dict(arguments)
+        self._result = ""
+        self._ok = True
+        self._finished = False
+
+    def on_mount(self) -> None:
+        self._refresh()
+
+    def finish(self, *, ok: bool, preview: str) -> None:
+        self._ok, self._result, self._finished = ok, preview, True
+        self._refresh()
+
+    def _refresh(self) -> None:
+        self.update(
+            tool_render(
+                self._name,
+                self._arguments,
+                result=self._result,
+                ok=self._ok,
+                finished=self._finished,
+                colour=self._colour(),
+            )
+        )
+
+    def _colour(self) -> str:
+        return brand_text(self.app.current_theme.dark)
+
+
+class ShellOutput(VerticalScroll):
+    """A `!` command and its output, marked by a rule down the left.
+
+    A rule rather than a box, because this is the one thing on the screen that is
+    neither the model's nor the platform's: **you** ran it, and none of it is in the
+    session. It should not look like anything the agent did.
+    """
+
+    def __init__(self, command: str) -> None:
+        super().__init__(classes="entry shell")
+        self._text = Static(markup=False)
+        self._command = command
+        self._output = ""
+        self._exit_code = 0
+
+    def compose(self) -> Any:
+        yield self._text
+
+    def on_mount(self) -> None:
+        self._refresh()
+
+    def finish(self, output: str, exit_code: int) -> None:
+        self._output, self._exit_code = output, exit_code
+        self._refresh()
+
+    def _refresh(self) -> None:
+        self._text.update(
+            shell_render(self._command, self._output, exit_code=self._exit_code)
+        )
+
+
+class PlatformNote(Static):
+    """What the platform did, as a full-width rule."""
+
+    def __init__(self, text: str) -> None:
+        super().__init__(classes="entry platform", markup=False)
+        self._text = text
+
+    def on_mount(self) -> None:
+        self.update(platform_rule(self._text))
+
+
+class Notice(Static):
+    """A warning or an error: a tinted, full-width box.
+
+    Loud on purpose. "No API key" printed dim among tool output is a message people
+    read after twenty minutes of wondering why nothing happens.
+    """
+
+    def __init__(self, text: str, *, level: str = "error") -> None:
+        super().__init__(classes=f"entry notice {level}", markup=False)
+        self._text = text
+
+    def on_mount(self) -> None:
+        self.update(Text(self._text))
+
+
+class AgentRow(Horizontal):
+    """A sub-agent's entry: its name in the gutter, its content indented."""
+
+    def __init__(self, agent: str, content: Widget) -> None:
+        super().__init__(classes="entry agent-row")
+        self._agent = agent
+        self.content = content
+
+    def compose(self) -> Any:
+        label = Static(
+            Text(self._agent, style=f"bold {agent_colour(self._agent)}"), markup=False
+        )
+        label.add_class("agent-name")
+        label.styles.width = len(self._agent) + 1
+        yield label
+        # The gutter is fixed, so the content takes what is left. Without this the
+        # content keeps its full width and the right-hand border is clipped off.
+        self.content.styles.width = "1fr"
+        yield self.content

stcode/cli/ui/components/transcript/formatting.py

@@ -0,0 +1,188 @@
+"""
+The transcript — eight shapes, each one because it has to be told apart at a glance.
+
+| | |
+| --- | --- |
+| `───── attached to … ─────` | the platform acted. Not the model talking |
+| a tinted block | what **you** said |
+| `│ quoted, dim` | thinking. Capped at the last six lines while it streams |
+| dim, unquoted | a running tool's output. Advisory, never in the session |
+| plain text | the model's answer |
+| a gray block with a green left border | a tool call and its result |
+| a rule down the left | a `!` command you ran. Never in the session |
+| a tinted full-width box | a warning or an error |
+
+A sub-agent renders in exactly the same shapes, with its name in a left gutter and its
+content indented. The colour is **hashed from the name**, not drawn at random: the same
+sub-agent is the same colour in every session and after every restart, which is the only
+way the colour tells you anything.
+
+Nothing here parses markup. Every string in this module came from a model, a file or a
+shell, and a stray `[` in one must not be read as a style tag.
+"""
+
+from __future__ import annotations
+
+import zlib
+from dataclasses import dataclass
+from typing import Any, Mapping
+
+from rich.console import Console, ConsoleOptions, RenderableType, RenderResult
+from rich.rule import Rule
+from rich.text import Text
+
+
+THINKING_LINES = 6
+"""How much reasoning stays on screen while it streams. Six is what fits without the
+answer sliding off the bottom; the rest is scrollable, and all of it is in the session."""
+
+TOOL_RESULT_LINES = 2
+"""Lines of a tool result kept in the box.
+
+Two, because the box is a *receipt* and not a viewer: the interesting thing about a
+finished tool call is that it ran and whether it worked, and a turn with six calls each
+showing six lines is a screen of output with the conversation pushed off the top. The
+full value is in the session, and `ToolFinished` only carries 240 characters of it
+anyway. `todo_write` is the exception: its complete plan is sent and displayed.
+"""
+
+PROGRESS_LINES = 6
+"""Lines of a running tool's output kept on screen.
+
+The same six as `Thinking`, for the same reason: it is a sign of life, not a viewer.
+The tool's result is what gets a box, and the whole value is in the session.
+"""
+
+SHELL_OUTPUT_LINES = 200
+"""Lines of a `!` command's output kept on screen. Generous, because you asked for this
+one by hand — but bounded, because `!cat` on the wrong file should not be how a session
+scrolls away."""
+
+ARGUMENT_CHARS = 160
+
+AGENT_COLOURS = (
+    "cyan",
+    "magenta",
+    "yellow",
+    "bright_blue",
+    "bright_magenta",
+    "bright_cyan",
+    "orange3",
+    "spring_green3",
+)
+"""Eight, none of them the brand green — that one means *the platform*, and a sub-agent
+wearing it would read as one."""
+
+
+def agent_colour(name: str) -> str:
+    """A stable colour for a sub-agent name.
+
+    `crc32` rather than `hash()`: Python salts string hashing per process, so `hash()`
+    would give the same agent a different colour every time stcode starts.
+    """
+    return AGENT_COLOURS[zlib.crc32(name.encode("utf-8")) % len(AGENT_COLOURS)]
+
+
+def format_arguments(arguments: Mapping[str, Any]) -> str:
+    """A tool's arguments as one line, in the terms the tool works in.
+
+    One line, because it is the summary at the top of the box: a `bash` heredoc that
+    wrapped over twelve rows would push the result out of sight.
+    """
+    rendered = " ".join(f"{key}={_flatten(value)}" for key, value in arguments.items())
+    return _shorten(rendered, ARGUMENT_CHARS)
+
+
+def thinking_tail(text: str, limit: int = THINKING_LINES) -> str:
+    """The last `limit` lines. Deltas arrive mid-line, so the line being written counts."""
+    lines = text.splitlines() or [text]
+    return "\n".join(lines[-limit:])
+
+
+def _flatten(value: Any) -> str:
+    return " ".join(str(value).split())
+
+
+def _shorten(text: str, limit: int) -> str:
+    flat = " ".join(text.split())
+    return flat if len(flat) <= limit else flat[: limit - 1] + "…"
+
+
+# ---- renderables ----------------------------------------------------------------
+
+
+def platform_rule(text: str) -> RenderableType:
+    """`───── mode → auto-edit ─────`, full width, light gray.
+
+    A rule rather than a line of text: what the *platform* did is not part of the
+    conversation, and it should not be possible to mistake one for the other.
+
+    Flattened to one line first. Rich draws a rule **per line** of its title, so a
+    multi-line string here comes out as a screen of dashes with a word centred in each
+    — which is what a tool's output looked like when it arrived as progress.
+    """
+    return Rule(
+        Text(" ".join(text.split()), style="#999999"), characters="─", style="#bbbbbb"
+    )
+
+
+@dataclass
+class ToolPreview:
+    name: str
+    arguments: Mapping[str, Any]
+    result: str
+    ok: bool
+    finished: bool
+    colour: str
+
+    def __rich_console__(self, console: Console, options: ConsoleOptions) -> RenderResult:
+        width = max(1, options.max_width)
+        heading = self.name + (" · failed" if self.finished and not self.ok else "")
+        yield Text(heading, style=f"bold {self.colour}", no_wrap=True, overflow="ellipsis")
+        arguments = Text(format_arguments(self.arguments))
+        arguments.truncate(width, overflow="ellipsis")
+        yield arguments
+        if self.result.strip():
+            lines = Text(self.result.strip(), style="dim").wrap(console, width)
+            if self.name != "todo_write" and len(lines) > TOOL_RESULT_LINES:
+                lines = lines[:TOOL_RESULT_LINES]
+                lines[-1].truncate(max(0, width - 1))
+                lines[-1].append("…")
+            for line in lines:
+                yield line
+
+
+def tool_render(
+    name: str,
+    arguments: Mapping[str, Any],
+    *,
+    result: str = "",
+    ok: bool = True,
+    finished: bool = True,
+    colour: str = "",
+) -> RenderableType:
+    """One argument row and two result rows, except todos show their full result."""
+    return ToolPreview(name, arguments, result, ok, finished, colour or "green")
+
+
+def shell_render(command: str, output: str, *, exit_code: int = 0) -> RenderableType:
+    """A `!` command and what it printed. The command bold, the output plain.
+
+    No border of its own — the widget draws the left rule in CSS, where it can be the
+    theme's colour. This is only the contents.
+    """
+    text = Text()
+    text.append(f"! {command}", style="bold")
+    if exit_code:
+        text.append(f"  (exit {exit_code})", style="bold")
+    lines = output.rstrip().splitlines()
+    if len(lines) > SHELL_OUTPUT_LINES:
+        hidden = len(lines) - SHELL_OUTPUT_LINES
+        lines = [*lines[:SHELL_OUTPUT_LINES], f"… {hidden} more lines, not shown"]
+    for line in lines:
+        text.append("\n")
+        text.append(line.rstrip())
+    return text
+
+
+# ---- widgets --------------------------------------------------------------------

stcode/cli/ui/components/transcript/view.py

@@ -0,0 +1,101 @@
+"""Scrollable transcript container."""
+
+from textual.containers import VerticalScroll
+from textual.widget import Widget
+from .entries import AgentRow
+
+
+class Transcript(VerticalScroll):
+    """The conversation. Entries are widgets; a sub-agent's are wrapped in a gutter."""
+
+    DEFAULT_CSS = """
+    Transcript { height: 1fr; scrollbar-size-vertical: 1; }
+    
+    .entry {
+        height: auto;
+        margin-bottom: 1;
+    }
+    
+    .entry.platform {
+        margin-bottom: 1;
+    }
+    
+    /* What you said, tinted. Without it a short prompt is three words of plain text in
+       a column of plain text, and scrolling back to find where you asked something
+       means reading rather than looking. */
+    .entry.message.user {
+        width: 1fr;
+        padding: 1 1;
+        background: $primary 12%;
+    }
+    
+    /* A `!` command: a rule down the left and nothing else. It is neither the model's
+       nor the platform's, and none of it is in the session. */
+    .entry.shell {
+        width: 1fr;
+        padding: 0 1;
+        height: 6;
+        border-left: solid $primary;
+        scrollbar-size-vertical: 1;
+    }
+    
+    .entry.tool {
+        background: $foreground 6%;
+        color: $foreground;
+        border-left: solid $primary;
+        padding: 1 1;
+    }
+
+    .entry.thinking, .entry.progress {
+        max-height: 6;
+        scrollbar-size-vertical: 1;
+    }
+    
+    /* Full width and tinted: "no API key" printed dim among tool output is a message
+       people read twenty minutes after they needed it. */
+    .entry.notice {
+        width: 1fr;
+        padding: 1 2;
+        color: $foreground;
+    }
+    
+    .entry.notice.error {
+        background: $error 12%;
+        border-left: solid $error;
+    }
+    
+    .entry.notice.warning {
+        background: $warning 12%;
+        border-left: solid $warning;
+    }
+    
+    .entry.agent-row {
+        height: auto;
+    }
+    
+    /* The row already carries the gap. Without this the entry inside it adds a second
+       one and a sub-agent's output reads as twice as far apart as the main agent's. */
+    .agent-row .entry {
+        margin-bottom: 0;
+    }
+    
+    .agent-name {
+        height: auto;
+        padding-right: 1;
+    }
+    """
+
+    def add(self, entry: Widget, *, agent: str = "") -> Widget:
+        """Mount one entry and scroll to it. Returns the entry, not the wrapper, so a
+        streaming caller keeps a handle on the thing it appends to."""
+        self.mount(AgentRow(agent, entry) if agent else entry)
+        self.scroll_end(animate=False)
+        return entry
+
+    def clear(self) -> None:
+        self.remove_children()
+
+    @property
+    def scrolls(self) -> bool:
+        """Whether there is more transcript than screen — what hides the banner."""
+        return self.max_scroll_y > 0

stcode/cli/ui/screens/chat/chat.tcss

@@ -0,0 +1,12 @@
+/* Page spacing. Reusable component appearance lives in DEFAULT_CSS. */
+#transcript {
+    padding: 0 2;
+}
+
+#cards, #prompt {
+    margin: 0 2;
+}
+
+#status {
+    padding: 0 3;
+}