shikiru-cli 0.2.0__py3-none-any.whl

shikiru/plugins/agents/codex/usage.py

@@ -0,0 +1,106 @@
+"""Codex rollout token usage parsing."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Mapping
+from typing import Any, cast
+
+from shikiru.agents.contracts import Usage
+from shikiru.plugins.agents.codex.options import USAGE_EVENT_TYPE
+
+_EVENT_MESSAGE_TYPE = "event_msg"
+_INFO_FIELD = "info"
+_TOTAL_USAGE_FIELD = "total_token_usage"
+_LAST_USAGE_FIELD = "last_token_usage"
+_INPUT_TOKENS_FIELD = "input_tokens"
+_OUTPUT_TOKENS_FIELD = "output_tokens"
+_CACHE_READ_TOKENS_FIELD = "cached_input_tokens"
+_CACHE_WRITE_TOKENS_FIELD = "cache_write_input_tokens"
+_CONTEXT_WINDOW_FIELD = "model_context_window"
+_PERCENT = 100
+_ZERO_TOKENS = 0
+_UNKNOWN_COST = "unknown"
+
+
+def rollout_usage(
+    entries: Iterable[Mapping[str, Any]],
+) -> Usage:
+    """Report the latest rollout token count; context from its window, no priced cost."""
+    latest = _latest_token_count(entries)
+    if latest is None:
+        return Usage(
+            _ZERO_TOKENS,
+            _ZERO_TOKENS,
+            _ZERO_TOKENS,
+            _ZERO_TOKENS,
+            None,
+            _UNKNOWN_COST,
+            None,
+        )
+    total, last, context_window = latest
+    input_tokens = _integer(total, _INPUT_TOKENS_FIELD)
+    output_tokens = _integer(total, _OUTPUT_TOKENS_FIELD)
+    cache_read_tokens = _integer(total, _CACHE_READ_TOKENS_FIELD)
+    cache_write_tokens = _integer(total, _CACHE_WRITE_TOKENS_FIELD)
+    context_used_pct = _context_used_pct(last, context_window)
+    return Usage(
+        input_tokens=input_tokens,
+        output_tokens=output_tokens,
+        cache_read_tokens=cache_read_tokens,
+        cache_write_tokens=cache_write_tokens,
+        cost_usd=None,
+        cost_basis="unknown",
+        context_used_pct=context_used_pct,
+    )
+
+
+def latest_token_count(
+    entries: Iterable[Mapping[str, Any]],
+) -> tuple[Mapping[str, Any], Mapping[str, Any], int | None] | None:
+    """Return the latest total and per-turn token usage records."""
+    return _latest_token_count(entries)
+
+
+def _latest_token_count(
+    entries: Iterable[Mapping[str, Any]],
+) -> tuple[Mapping[str, Any], Mapping[str, Any], int | None] | None:
+    latest: tuple[Mapping[str, Any], Mapping[str, Any], int | None] | None = None
+    for entry in entries:
+        payload = _payload(entry)
+        if payload.get("type") != USAGE_EVENT_TYPE:
+            continue
+        info = payload.get(_INFO_FIELD)
+        if not isinstance(info, Mapping):
+            continue
+        typed_info = cast("Mapping[str, Any]", info)
+        total = typed_info.get(_TOTAL_USAGE_FIELD)
+        last = typed_info.get(_LAST_USAGE_FIELD)
+        if isinstance(total, Mapping) and isinstance(last, Mapping):
+            context_window = typed_info.get(_CONTEXT_WINDOW_FIELD)
+            latest = (
+                cast("Mapping[str, Any]", total),
+                cast("Mapping[str, Any]", last),
+                context_window if isinstance(context_window, int) else None,
+            )
+    return latest
+
+
+def _payload(entry: Mapping[str, Any]) -> Mapping[str, Any]:
+    if entry.get("type") != _EVENT_MESSAGE_TYPE:
+        return {}
+    payload = entry.get("payload")
+    return cast("Mapping[str, Any]", payload) if isinstance(payload, Mapping) else {}
+
+
+def _integer(entry: Mapping[str, Any], key: str) -> int:
+    value = entry.get(key, 0)
+    if not isinstance(value, int | float):
+        return 0
+    return int(value)
+
+
+def _context_used_pct(last: Mapping[str, Any], context_window: int | None) -> float | None:
+    if context_window is None or context_window <= 0 or _INPUT_TOKENS_FIELD not in last:
+        return None
+    tokens = _integer(last, _INPUT_TOKENS_FIELD)
+    return tokens / context_window * _PERCENT

shikiru/plugins/agents/shared_settings.py

@@ -0,0 +1,62 @@
+"""Option definitions and validation shared by the built-in agent plugins."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from shikiru.agents.contracts import BILLING_MODE_API, BILLING_MODE_SUBSCRIPTION, PERCENT
+from shikiru.agents.settings import AgentOptionsError, AgentSetting, SettingKind
+
+if TYPE_CHECKING:
+    from pydantic import ValidationError
+
+COMPACT_AT_PCT_KEY = "compact_at_pct"
+BILLING_MODE_KEY = "billing_mode"
+ARGS_KEY = "args"
+
+
+def compact_threshold_setting(default: float) -> AgentSetting:
+    """Return the context-compaction threshold setting with the plugin's `default`."""
+    return AgentSetting(
+        key=COMPACT_AT_PCT_KEY,
+        label="Compact at",
+        help="Context use at which the agent is asked to compact its session; 0 compacts at once.",
+        kind=SettingKind.NUMBER,
+        default=default,
+        unit="percent",
+        minimum=0,
+        maximum=PERCENT,
+    )
+
+
+def billing_declaration_setting() -> AgentSetting:
+    """Return the billing declaration setting; unset declares nothing."""
+    return AgentSetting(
+        key=BILLING_MODE_KEY,
+        label="Billing mode",
+        help=(
+            "How this agent is billed, used to label cost as billed or API-equivalent; "
+            "leaving it blank declares nothing."
+        ),
+        kind=SettingKind.CHOICE,
+        default=None,
+        choices=(BILLING_MODE_API, BILLING_MODE_SUBSCRIPTION),
+    )
+
+
+def cli_args_setting(default: tuple[str, ...]) -> AgentSetting:
+    """Return the extra CLI arguments setting with the plugin's `default`."""
+    return AgentSetting(
+        key=ARGS_KEY,
+        label="CLI arguments",
+        help="Arguments added to every agent CLI call, split like a shell command line.",
+        kind=SettingKind.ARGS,
+        default=default,
+    )
+
+
+def options_error(agent: str, error: ValidationError) -> AgentOptionsError:
+    """Return the options rejection for `agent`, naming the first option pydantic refused."""
+    first = error.errors()[0]
+    key = str(first["loc"][0]) if first["loc"] else None
+    return AgentOptionsError(f"invalid options for the {agent} agent: {error}", key)

shikiru/plugins/widgets/__init__.py

@@ -0,0 +1,3 @@
+"""Dashboard widget plugins, registered under `shikiru.widgets`."""
+
+from __future__ import annotations

shikiru/plugins/widgets/dialogue.py

@@ -0,0 +1,144 @@
+"""The `dialogue` widget: recent speech bubbles."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, ClassVar, cast
+
+from textual.containers import Horizontal, VerticalScroll
+from textual.screen import ModalScreen
+from textual.widgets import Button, DataTable, Label, Rule, Static
+
+from shikiru.dashboard.contract import WidgetPlacement
+from shikiru.ui import SpeechBubble
+from shikiru.ui.popup import (
+    POPUP_BODY_CLASS,
+    POPUP_CLOSE_CLASS,
+    POPUP_CSS,
+    POPUP_FRAME_CLASS,
+    POPUP_HEADER_CLASS,
+    POPUP_RULE_CLASS,
+    POPUP_TITLE_CLASS,
+    PopupFrame,
+    popup_close_label,
+    prepare_popup,
+)
+from shikiru.ui.screen import widget_is_attached
+
+if TYPE_CHECKING:
+    from textual.app import App, ComposeResult
+    from textual.widget import Widget
+
+    from shikiru.dashboard.contract import DialogueBubbleView, WidgetContext
+
+_DIALOGUE_TEXT_CLOSE_BUTTON = "dialogue-text-close"
+
+
+class DialogueTextScreen(ModalScreen[None]):
+    """Show the full text of one dialogue bubble."""
+
+    BINDINGS: ClassVar[list[tuple[str, str, str]]] = [("escape", "close", "Close")]
+    DEFAULT_CSS = (
+        POPUP_CSS
+        + """
+    #dialogue-text-scroll { max-height: 1fr; min-height: 0; }
+    #dialogue-full-text {
+        background: $surface;
+        color: $foreground;
+    }
+    """
+    )
+
+    def __init__(self, text: str) -> None:
+        """Hold the full event text to display."""
+        super().__init__()
+        prepare_popup(self)
+        self._text = text
+
+    def compose(self) -> ComposeResult:
+        """Render the complete bubble text in a scrollable modal."""
+        with PopupFrame(widget_id="dialogue-text-frame", classes=POPUP_FRAME_CLASS):
+            with Horizontal(id="dialogue-text-header", classes=POPUP_HEADER_CLASS):
+                yield Label("Dialogue", id="dialogue-text-title", classes=POPUP_TITLE_CLASS)
+                yield Button(
+                    popup_close_label(),
+                    id=_DIALOGUE_TEXT_CLOSE_BUTTON,
+                    classes=POPUP_CLOSE_CLASS,
+                )
+            yield Rule(classes=POPUP_RULE_CLASS)
+            with VerticalScroll(id="dialogue-text-scroll", classes=POPUP_BODY_CLASS):
+                yield Static(self._text, markup=False, id="dialogue-full-text")
+
+    def on_mount(self) -> None:
+        self.set_focus(self.query_one("#dialogue-text-scroll", VerticalScroll))
+        self.call_after_refresh(self.query_one("#dialogue-text-frame", PopupFrame).content_ready)
+
+    async def on_button_pressed(self, event: Button.Pressed) -> None:
+        if event.button.id == _DIALOGUE_TEXT_CLOSE_BUTTON:
+            self.dismiss()
+
+    async def action_close(self) -> None:
+        """Close the full-text modal."""
+        self.dismiss()
+
+
+class DialoguePanel(Static):
+    """List the latest twenty bubbles and open a selected bubble's full text on Enter."""
+
+    DEFAULT_CSS = """
+    DialoguePanel { height: auto; }
+    #dialogue-table { height: auto; }
+    """
+
+    def __init__(self, context: WidgetContext) -> None:
+        """Hold `context`; the event list is read on mount and on state changes."""
+        super().__init__(id="dialogue")
+        self._widget_context = context
+        self._bubbles: list[DialogueBubbleView] = []
+
+    def compose(self) -> ComposeResult:
+        """Reserve a table with one row per recent speech bubble."""
+        yield DataTable(show_header=False, cursor_type="row", id="dialogue-table")
+
+    async def on_mount(self) -> None:
+        """Render recent events and refresh after each state change."""
+        await self._refresh()
+        self.run_worker(self._widget_context.on_change(self._refresh_if_attached), exclusive=True)
+
+    def on_data_table_row_selected(self, event: DataTable.RowSelected) -> None:
+        """Show the complete text of the selected event."""
+        if self._bubbles:
+            bubble = self._bubbles[event.cursor_row]
+            cast("App[None]", self.app).push_screen(DialogueTextScreen(bubble.text))
+
+    async def _refresh(self) -> None:
+        self._bubbles = self._widget_context.views.dialogue(self._widget_context.focus_task)
+        table = cast("DataTable[object]", self.query_one("#dialogue-table", DataTable))
+        table.clear(columns=True)
+        table.add_column("dialogue")
+        if not self._bubbles:
+            table.add_row("no dialogue yet")
+            return
+        for bubble in self._bubbles:
+            table.add_row(
+                SpeechBubble(
+                    role=bubble.role,
+                    text=bubble.text,
+                    task_id=bubble.task_id,
+                    age=bubble.age,
+                ).render()
+            )
+
+    async def _refresh_if_attached(self) -> None:
+        if widget_is_attached(self):
+            await self._refresh()
+
+
+class DialogueWidget:
+    """The `dialogue` dashboard widget plugin."""
+
+    name = "dialogue"
+    placement = WidgetPlacement.ACTIVITY
+
+    def create(self, context: WidgetContext) -> Widget:
+        """Build the dialogue panel for `context`."""
+        return DialoguePanel(context)

shikiru/plugins/widgets/disk.py

@@ -0,0 +1,123 @@
+"""The `disk` widget: free space of the project filesystem and the `.shikiru` size."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from rich.cells import cell_len
+from rich.text import Text
+
+from shikiru.dashboard.contract import DiagnosticSampleState, WidgetPlacement
+from shikiru.ui.compact import free_space_text
+from shikiru.ui.gated_static import GatedStatic
+from shikiru.ui.live_interval import LiveInterval
+from shikiru.ui.screen import is_first_child, widget_is_attached
+from shikiru.ui.section import (
+    FAILED_WORD,
+    GROUP_SEPARATOR,
+    UNAVAILABLE_WORD,
+    UNKNOWN_AGE,
+    Row,
+    Section,
+    grey,
+    labelled_rows,
+    number,
+    observation,
+    state_line,
+)
+from shikiru.ui.size import format_size
+from shikiru.ui.tokens import ALERT_COLOR, AMBER, SECONDARY_TEXT_COLOR
+
+if TYPE_CHECKING:
+    from rich.console import Console, ConsoleOptions, RenderResult
+    from textual.widget import Widget
+
+    from shikiru.dashboard.contract import DiskView, WidgetContext
+
+SECTION_TITLE = "Disk"
+LABEL_FREE = "Free"
+LABEL_SHIKIRU = ".shikiru"
+MEASURING_WORD = "measuring…"
+LABEL_REFRESH = "Refresh"
+
+
+@dataclass(frozen=True)
+class _DiskBody:
+    view: DiskView
+    refresh_error: str | None
+
+    def __rich_console__(self, console: Console, options: ConsoleOptions) -> RenderResult:
+        del console
+        view = self.view
+        rows: list[Row] = []
+        if view.free_bytes is not None and view.total_bytes is not None:
+            free = free_space_text(view.free_bytes, view.total_bytes, view.free_level)
+            rows.append((grey(LABEL_FREE), (free,)))
+        if view.shikiru_bytes is not None:
+            rows.append((grey(LABEL_SHIKIRU), (number(format_size(view.shikiru_bytes)),)))
+        elif self.refresh_error is None:
+            rows.append((grey(LABEL_SHIKIRU), (grey(MEASURING_WORD),)))
+        if self.refresh_error is not None:
+            failure = Text(f"{FAILED_WORD}{GROUP_SEPARATOR}{self.refresh_error}", style=AMBER)
+            rows.append((grey(LABEL_REFRESH), (failure,)))
+        label_width = max((cell_len(label.plain) for label, _ in rows), default=0)
+        yield labelled_rows(rows, options.max_width, label_width)
+
+
+def disk_section(view: DiskView) -> Section:
+    """Render `view` as the Disk section in every state."""
+    ago = view.sampled_ago or UNKNOWN_AGE
+    if view.state is DiagnosticSampleState.UNAVAILABLE:
+        return Section(
+            SECTION_TITLE, state_line(UNAVAILABLE_WORD, SECONDARY_TEXT_COLOR, view.error)
+        )
+    if view.state is DiagnosticSampleState.FAILED:
+        return Section(SECTION_TITLE, state_line(FAILED_WORD, ALERT_COLOR, view.error))
+    stale = view.state is DiagnosticSampleState.STALE
+    return Section(
+        SECTION_TITLE, _DiskBody(view, view.error if stale else None), observation(ago, stale=stale)
+    )
+
+
+class DiskPanel(GatedStatic):
+    """Show the Disk section and re-render only when its content changed."""
+
+    def __init__(self, context: WidgetContext) -> None:
+        """Hold `context`; disk sampling starts on mount."""
+        super().__init__(id="disk")
+        self._widget_context = context
+        self._interval = LiveInterval(
+            self,
+            lambda: context.settings.current().dashboard.disk_refresh_seconds,
+            self._refresh,
+        )
+
+    async def on_mount(self) -> None:
+        """Render and refresh disk state at the configured cadence."""
+        await self._refresh()
+        self._interval.apply()
+        self.run_worker(self._widget_context.on_change(self._interval.reapply), exclusive=True)
+
+    async def _refresh(self) -> None:
+        if not widget_is_attached(self):
+            return
+        view = await self._widget_context.views.disk()
+        if not widget_is_attached(self):
+            return
+        if view.shikiru_bytes is None and view.state is DiagnosticSampleState.AVAILABLE:
+            resources = self._widget_context.settings.current().orchestration.resources
+            self.set_timer(resources.sample_seconds, self._refresh)
+        ruled = not is_first_child(self)
+        self.update_if_changed(disk_section(view).with_ruled(ruled=ruled), key=(view, ruled))
+
+
+class DiskWidget:
+    """The `disk` dashboard widget plugin."""
+
+    name = "disk"
+    placement = WidgetPlacement.DIAGNOSTICS
+
+    def create(self, context: WidgetContext) -> Widget:
+        """Build the Disk panel for `context`."""
+        return DiskPanel(context)

shikiru/plugins/widgets/docker.py

@@ -0,0 +1,225 @@
+"""The `docker` widget: container counts, problems and the top five by CPU."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from rich.cells import cell_len
+from rich.console import Group, RenderableType
+from rich.table import Table
+from rich.text import Text
+
+from shikiru.dashboard.contract import DiagnosticSampleState, WidgetPlacement
+from shikiru.ui.compact import format_cpu_pct, format_memory
+from shikiru.ui.gated_static import GatedStatic
+from shikiru.ui.live_interval import LiveInterval
+from shikiru.ui.screen import is_first_child, widget_is_attached
+from shikiru.ui.section import (
+    BOLD_PRIMARY,
+    FAILED_WORD,
+    GROUP_SEPARATOR,
+    UNAVAILABLE_WORD,
+    UNKNOWN_AGE,
+    Row,
+    Section,
+    grey,
+    labelled_rows,
+    number,
+    observation,
+    state_line,
+)
+from shikiru.ui.tokens import (
+    ALERT_COLOR,
+    AMBER,
+    SECONDARY_TEXT_COLOR,
+)
+
+if TYPE_CHECKING:
+    from rich.console import Console, ConsoleOptions, RenderResult
+    from textual.widget import Widget
+
+    from shikiru.dashboard.contract import (
+        ContainerProblemView,
+        ContainerView,
+        DockerSummaryView,
+        DockerView,
+        WidgetContext,
+    )
+
+SECTION_TITLE = "Docker"
+LABEL_RUNNING = "Running"
+LABEL_PROBLEMS = "Problems"
+LABEL_ELSEWHERE = "Elsewhere"
+LABEL_REFRESH = "Refresh"
+TOP_HEADING = "Top 5 by CPU"
+TOP_INDENT = 2
+TOP_COLUMN_GAP = 1
+TOP_GAP_COUNT = 2
+RIGHT = "right"
+ELLIPSIS = "ellipsis"
+CPU_WORD = "CPU"
+RAM_WORD = "RAM"
+OF_WORD = "of"
+RUNNING_WORD = "running"
+USAGE_UNAVAILABLE = "usage unavailable"
+NO_CONTAINERS = "No containers"
+PROBLEM_UNHEALTHY = "unhealthy"
+PROBLEM_RESTARTING = "restarting"
+_WARNING_REASONS = frozenset({PROBLEM_UNHEALTHY, PROBLEM_RESTARTING})
+
+
+def _measure(label: str, value: str) -> Text:
+    return Text.assemble(grey(f"{label} "), number(value))
+
+
+def _usage_groups(cpu_pct: float | None, memory_bytes: int | None) -> list[Text]:
+    groups: list[Text] = []
+    if cpu_pct is not None:
+        groups.append(_measure(CPU_WORD, format_cpu_pct(cpu_pct)))
+    if memory_bytes is not None:
+        groups.append(_measure(RAM_WORD, format_memory(memory_bytes)))
+    return groups
+
+
+def _running_groups(summary: DockerSummaryView) -> list[Text]:
+    counts = Text.assemble(
+        number(str(summary.running)), grey(f" {OF_WORD} "), number(str(summary.total))
+    )
+    if not summary.usage_available:
+        return [counts, Text(USAGE_UNAVAILABLE, style=AMBER)]
+    return [counts, *_usage_groups(summary.cpu_pct, summary.memory_bytes)]
+
+
+def _problem_group(problem: ContainerProblemView) -> Text:
+    colour = AMBER if problem.reason in _WARNING_REASONS else ALERT_COLOR
+    reason = (
+        problem.reason if problem.exit_code is None else f"{problem.reason} ({problem.exit_code})"
+    )
+    return Text.assemble((problem.name, BOLD_PRIMARY), " ", (reason, colour))
+
+
+def _elsewhere_groups(summary: DockerSummaryView) -> list[Text]:
+    elsewhere = summary.elsewhere
+    count = Text.assemble(number(str(elsewhere.running)), grey(f" {RUNNING_WORD}"))
+    return [count, *_usage_groups(elsewhere.cpu_pct, elsewhere.memory_bytes)]
+
+
+@dataclass(frozen=True)
+class _TopContainers:
+    containers: tuple[ContainerView, ...]
+
+    def __rich_console__(self, console: Console, options: ConsoleOptions) -> RenderResult:
+        del console
+        cpus = [format_cpu_pct(container.cpu_pct) for container in self.containers]
+        memories = [format_memory(container.memory_bytes) for container in self.containers]
+        cpu_width = max(map(len, cpus))
+        memory_width = max(map(len, memories))
+        name_width = max(
+            1,
+            options.max_width
+            - TOP_INDENT
+            - cpu_width
+            - memory_width
+            - TOP_GAP_COUNT * TOP_COLUMN_GAP,
+        )
+        grid = Table.grid(padding=(0, TOP_COLUMN_GAP, 0, 0))
+        grid.add_column(width=TOP_INDENT - TOP_COLUMN_GAP)
+        grid.add_column(width=min(name_width, max(len(c.name) for c in self.containers)))
+        grid.add_column(justify=RIGHT, width=cpu_width)
+        grid.add_column(justify=RIGHT, width=memory_width)
+        for container, cpu, memory in zip(self.containers, cpus, memories, strict=True):
+            name = Text(container.name, style=BOLD_PRIMARY, no_wrap=True)
+            name.truncate(name_width, overflow=ELLIPSIS)
+            grid.add_row("", name, number(cpu), number(memory))
+        yield grid
+
+
+@dataclass(frozen=True)
+class _SummaryBody:
+    summary: DockerSummaryView
+    refresh_error: str | None
+
+    def __rich_console__(self, console: Console, options: ConsoleOptions) -> RenderResult:
+        del console
+        summary = self.summary
+        head: list[Row] = [(grey(LABEL_RUNNING), tuple(_running_groups(summary)))]
+        if summary.problems:
+            problems = tuple(_problem_group(problem) for problem in summary.problems)
+            head.append((grey(LABEL_PROBLEMS), problems))
+        if self.refresh_error is not None:
+            failure = Text(f"{FAILED_WORD}{GROUP_SEPARATOR}{self.refresh_error}", style=AMBER)
+            head.append((grey(LABEL_REFRESH), (failure,)))
+        tail: list[Row] = []
+        if summary.elsewhere.running:
+            tail.append((grey(LABEL_ELSEWHERE), tuple(_elsewhere_groups(summary))))
+        label_width = max(cell_len(label.plain) for label, _ in [*head, *tail])
+        yield labelled_rows(head, options.max_width, label_width)
+        if summary.usage_available and summary.top:
+            yield grey(TOP_HEADING)
+            yield _TopContainers(summary.top)
+        if tail:
+            yield labelled_rows(tail, options.max_width, label_width)
+
+
+def docker_section(snapshot: DockerView) -> Section:
+    """Render `snapshot` as the Docker section in every state."""
+    state = snapshot.state or (
+        DiagnosticSampleState.AVAILABLE if snapshot.available else DiagnosticSampleState.UNAVAILABLE
+    )
+    ago = snapshot.sampled_ago or UNKNOWN_AGE
+    if state is DiagnosticSampleState.UNAVAILABLE:
+        return Section(
+            SECTION_TITLE, state_line(UNAVAILABLE_WORD, SECONDARY_TEXT_COLOR, snapshot.error)
+        )
+    if state is DiagnosticSampleState.FAILED:
+        return Section(SECTION_TITLE, state_line(FAILED_WORD, ALERT_COLOR, snapshot.error))
+    if state is DiagnosticSampleState.EMPTY:
+        return Section(SECTION_TITLE, grey(NO_CONTAINERS), observation(ago, stale=False))
+    stale = state is DiagnosticSampleState.STALE
+    body: RenderableType = Group()
+    if snapshot.summary is not None:
+        body = _SummaryBody(snapshot.summary, snapshot.error if stale else None)
+    return Section(SECTION_TITLE, body, observation(ago, stale=stale))
+
+
+class DockerPanel(GatedStatic):
+    """Show the Docker section and re-render only when its content changed."""
+
+    def __init__(self, context: WidgetContext) -> None:
+        """Hold `context`; Docker sampling starts on mount."""
+        super().__init__(id="docker")
+        self._widget_context = context
+        self._interval = LiveInterval(
+            self,
+            lambda: context.settings.current().dashboard.docker_refresh_seconds,
+            self._refresh,
+        )
+
+    async def on_mount(self) -> None:
+        """Render and refresh Docker state at the configured cadence."""
+        await self._refresh()
+        self._interval.apply()
+        self.run_worker(self._widget_context.on_change(self._interval.reapply), exclusive=True)
+
+    async def _refresh(self) -> None:
+        if not widget_is_attached(self):
+            return
+        snapshot = await self._widget_context.views.containers()
+        if not widget_is_attached(self):
+            return
+        ruled = not is_first_child(self)
+        self.update_if_changed(
+            docker_section(snapshot).with_ruled(ruled=ruled), key=(snapshot, ruled)
+        )
+
+
+class DockerWidget:
+    """The `docker` dashboard widget plugin."""
+
+    name = "docker"
+    placement = WidgetPlacement.DIAGNOSTICS
+
+    def create(self, context: WidgetContext) -> Widget:
+        """Build the Docker panel for `context`."""
+        return DockerPanel(context)