shikiru-cli 0.2.0__py3-none-any.whl

shikiru/domain/docker.py

@@ -0,0 +1,262 @@
+"""Pure Docker container parsing, scoping and ranking."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from enum import StrEnum
+from pathlib import PurePath
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping, Sequence
+
+DOCKER_TOP_COUNT = 5
+PS_ID_FIELD = "ID"
+PS_NAMES_FIELD = "Names"
+PS_STATE_FIELD = "State"
+PS_STATUS_FIELD = "Status"
+PS_LABELS_FIELD = "Labels"
+STATS_ID_FIELD = "ID"
+STATS_NAME_FIELD = "Name"
+STATS_CPU_FIELD = "CPUPerc"
+STATS_MEMORY_FIELD = "MemUsage"
+NOT_RUNNING_READING = "--"
+COMPOSE_WORKING_DIR_LABEL = "com.docker.compose.project.working_dir"
+STATE_RUNNING = "running"
+STATE_RESTARTING = "restarting"
+STATE_EXITED = "exited"
+UNHEALTHY_MARKER = "(unhealthy)"
+NAME_SEPARATOR = ","
+LABEL_SEPARATOR = ","
+LABEL_ASSIGNMENT = "="
+MEMORY_SEPARATOR = "/"
+PERCENT_SUFFIX = "%"
+BYTES_PER_KILO = 1000
+BYTES_PER_KIBI = 1024
+BYTES_PER_MEBIBYTE = BYTES_PER_KIBI**2
+MEMORY_UNIT_BYTES = {
+    "B": 1,
+    "kB": BYTES_PER_KILO,
+    "KB": BYTES_PER_KILO,
+    "MB": BYTES_PER_KILO**2,
+    "GB": BYTES_PER_KILO**3,
+    "TB": BYTES_PER_KILO**4,
+    "KiB": BYTES_PER_KIBI,
+    "MiB": BYTES_PER_MEBIBYTE,
+    "GiB": BYTES_PER_KIBI**3,
+    "TiB": BYTES_PER_KIBI**4,
+}
+_MEMORY_READING = re.compile(r"(?P<value>\d+(?:\.\d+)?)\s*(?P<unit>[A-Za-z]+)")
+_EXIT_STATUS = re.compile(r"Exited \((?P<code>\d+)\)")
+
+
+class DockerParseError(ValueError):
+    """A Docker record does not match the documented CLI output."""
+
+
+class ProblemKind(StrEnum):
+    """Why a container needs attention."""
+
+    UNHEALTHY = "unhealthy"
+    RESTARTING = "restarting"
+    EXITED = "exited"
+
+
+@dataclass(frozen=True)
+class ContainerProblem:
+    """One container that is unhealthy, restarting or exited non-zero."""
+
+    name: str
+    kind: ProblemKind
+    exit_code: int | None = None
+
+
+@dataclass(frozen=True)
+class ContainerInfo:
+    """One `docker ps -a` record reduced to the facts the dashboard uses."""
+
+    id: str
+    name: str
+    running: bool
+    problem: ContainerProblem | None
+    working_dir: str | None
+
+
+@dataclass(frozen=True)
+class ContainerUsage:
+    """One running container's CPU and memory as numbers."""
+
+    id: str
+    name: str
+    cpu_pct: float
+    memory_bytes: int
+
+
+@dataclass(frozen=True)
+class ElsewhereTotals:
+    """Running containers outside the scope; usage is `None` when unavailable."""
+
+    running: int
+    cpu_pct: float | None
+    memory_bytes: int | None
+
+
+@dataclass(frozen=True)
+class DockerSummary:
+    """Scoped counts, usage totals, problems, the CPU ranking and the rest of the host."""
+
+    running: int
+    total: int
+    cpu_pct: float | None
+    memory_bytes: int | None
+    problems: tuple[ContainerProblem, ...]
+    top: tuple[ContainerUsage, ...]
+    elsewhere: ElsewhereTotals
+    usage_available: bool
+
+    @property
+    def is_empty(self) -> bool:
+        """Whether the host has no scoped container and no running one elsewhere."""
+        return not self.total and not self.elsewhere.running
+
+
+def parse_cpu_percent(text: str) -> float | None:
+    """Return the percentage in `1.23%`, or `None` for the not-running reading."""
+    stripped = text.strip()
+    if stripped == NOT_RUNNING_READING:
+        return None
+    try:
+        return float(stripped.removesuffix(PERCENT_SUFFIX))
+    except ValueError as error:
+        message = f"docker CPU reading is not a percentage: {text!r}"
+        raise DockerParseError(message) from error
+
+
+def parse_memory_usage(text: str) -> int | None:
+    """Return the used bytes in `12MiB / 1.9GiB`, or `None` for the not-running reading."""
+    used = text.partition(MEMORY_SEPARATOR)[0].strip()
+    if used == NOT_RUNNING_READING:
+        return None
+    match = _MEMORY_READING.fullmatch(used)
+    if match is None or match["unit"] not in MEMORY_UNIT_BYTES:
+        message = f"docker memory reading is not a size: {text!r}"
+        raise DockerParseError(message)
+    return round(float(match["value"]) * MEMORY_UNIT_BYTES[match["unit"]])
+
+
+def parse_labels(text: str) -> dict[str, str]:
+    """Return the `k=v,k=v` label string as a mapping; fragments without `=` are skipped."""
+    labels: dict[str, str] = {}
+    for fragment in text.split(LABEL_SEPARATOR):
+        key, assignment, value = fragment.partition(LABEL_ASSIGNMENT)
+        if assignment:
+            labels[key] = value
+    return labels
+
+
+def parse_ps_record(record: Mapping[str, object]) -> ContainerInfo:
+    """Return a `docker ps -a --format json` record as a `ContainerInfo`."""
+    name = _text(record, PS_NAMES_FIELD).split(NAME_SEPARATOR)[0]
+    state = _text(record, PS_STATE_FIELD)
+    status = _text(record, PS_STATUS_FIELD)
+    working_dir = parse_labels(_text(record, PS_LABELS_FIELD)).get(COMPOSE_WORKING_DIR_LABEL)
+    return ContainerInfo(
+        id=_text(record, PS_ID_FIELD),
+        name=name,
+        running=state == STATE_RUNNING,
+        problem=_problem(name, state, status),
+        working_dir=working_dir,
+    )
+
+
+def parse_stats_record(record: Mapping[str, object]) -> ContainerUsage | None:
+    """Return a `docker stats` record as numbers, or `None` while it has no reading yet."""
+    cpu_pct = parse_cpu_percent(_text(record, STATS_CPU_FIELD))
+    memory_bytes = parse_memory_usage(_text(record, STATS_MEMORY_FIELD))
+    if cpu_pct is None or memory_bytes is None:
+        return None
+    return ContainerUsage(
+        id=_text(record, STATS_ID_FIELD),
+        name=_text(record, STATS_NAME_FIELD),
+        cpu_pct=cpu_pct,
+        memory_bytes=memory_bytes,
+    )
+
+
+def rank_by_cpu(usages: Sequence[ContainerUsage], limit: int) -> tuple[ContainerUsage, ...]:
+    """Return the `limit` busiest containers: CPU descending, then memory descending, then name."""
+    ranked = sorted(usages, key=lambda usage: (-usage.cpu_pct, -usage.memory_bytes, usage.name))
+    return tuple(ranked[:limit])
+
+
+def in_project(info: ContainerInfo, project_roots: Sequence[PurePath]) -> bool:
+    """Return whether the container's compose working directory is inside a project root."""
+    if info.working_dir is None:
+        return False
+    working_dir = PurePath(info.working_dir)
+    return any(working_dir.is_relative_to(root) for root in project_roots)
+
+
+def summarize(
+    containers: Sequence[ContainerInfo],
+    usages: Sequence[ContainerUsage] | None,
+    project_roots: Sequence[PurePath] | None,
+) -> DockerSummary:
+    """Summarize the scoped containers; `None` usages mean unavailable, `None` roots mean all."""
+    scoped = [c for c in containers if project_roots is None or in_project(c, project_roots)]
+    scoped_ids = {c.id for c in scoped}
+    other_running = [c for c in containers if c.running and c.id not in scoped_ids]
+    problems = tuple(c.problem for c in scoped if c.problem is not None)
+    running = [c for c in scoped if c.running]
+    if usages is None:
+        return DockerSummary(
+            running=len(running),
+            total=len(scoped),
+            cpu_pct=None,
+            memory_bytes=None,
+            problems=problems,
+            top=(),
+            elsewhere=ElsewhereTotals(len(other_running), None, None),
+            usage_available=False,
+        )
+    usage_by_id = {usage.id: usage for usage in usages}
+    scoped_usage = [usage_by_id[c.id] for c in running if c.id in usage_by_id]
+    other_usage = [usage_by_id[c.id] for c in other_running if c.id in usage_by_id]
+    return DockerSummary(
+        running=len(running),
+        total=len(scoped),
+        cpu_pct=sum(usage.cpu_pct for usage in scoped_usage),
+        memory_bytes=sum(usage.memory_bytes for usage in scoped_usage),
+        problems=problems,
+        top=rank_by_cpu(scoped_usage, DOCKER_TOP_COUNT),
+        elsewhere=ElsewhereTotals(
+            len(other_running),
+            sum(usage.cpu_pct for usage in other_usage),
+            sum(usage.memory_bytes for usage in other_usage),
+        ),
+        usage_available=True,
+    )
+
+
+def _text(record: Mapping[str, object], field: str) -> str:
+    value = record.get(field)
+    if not isinstance(value, str):
+        message = f"docker record field {field} is missing or not a string"
+        raise DockerParseError(message)
+    return value
+
+
+def _problem(name: str, state: str, status: str) -> ContainerProblem | None:
+    if state == STATE_RESTARTING:
+        return ContainerProblem(name, ProblemKind.RESTARTING)
+    if state == STATE_RUNNING and UNHEALTHY_MARKER in status:
+        return ContainerProblem(name, ProblemKind.UNHEALTHY)
+    if state != STATE_EXITED:
+        return None
+    match = _EXIT_STATUS.match(status)
+    if match is None:
+        message = f"docker exited status has no exit code: {status!r}"
+        raise DockerParseError(message)
+    code = int(match["code"])
+    return ContainerProblem(name, ProblemKind.EXITED, code) if code != 0 else None

shikiru/domain/engine_uptime.py

@@ -0,0 +1,87 @@
+"""Pure projections of recorded engine start and stop evidence."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from shikiru.domain.events import Event, EventKind
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+    from datetime import datetime
+
+ENGINE_PID_FIELD = "engine_pid"
+ENGINE_PROCESS_STARTED_AT_FIELD = "engine_process_started_at"
+ENGINE_LIFECYCLE_PAIR_SIZE = 2
+
+
+@dataclass(frozen=True)
+class EngineUptime:
+    running_seconds: float | None
+    previous_run_seconds: float | None
+
+
+def project_engine_uptime(
+    events: Sequence[Event],
+    *,
+    now: datetime,
+    running: bool,
+    identity: tuple[int, float] | None,
+) -> EngineUptime:
+    """Return live or previous-run duration only when lifecycle evidence is consistent."""
+    ordered_events = tuple(sorted(events, key=lambda event: event.id))
+    if running:
+        return EngineUptime(
+            running_seconds=_running_duration(ordered_events, now, identity),
+            previous_run_seconds=None,
+        )
+    return EngineUptime(
+        running_seconds=None,
+        previous_run_seconds=_previous_duration(ordered_events, now),
+    )
+
+
+def _running_duration(
+    events: Sequence[Event], now: datetime, identity: tuple[int, float] | None
+) -> float | None:
+    if identity is None or not events:
+        return None
+    latest = events[-1]
+    if (
+        latest.kind is not EventKind.ENGINE_STARTED
+        or _event_identity(latest) != identity
+        or latest.ts > now
+    ):
+        return None
+    seconds = (now - latest.ts).total_seconds()
+    return seconds if seconds >= 0 else None
+
+
+def _previous_duration(events: Sequence[Event], now: datetime) -> float | None:
+    if len(events) < ENGINE_LIFECYCLE_PAIR_SIZE:
+        return None
+    started, stopped = events[len(events) - ENGINE_LIFECYCLE_PAIR_SIZE :]
+    if (
+        started.kind is not EventKind.ENGINE_STARTED
+        or stopped.kind is not EventKind.ENGINE_STOPPED
+        or _event_identity(started) is None
+        or _event_identity(started) != _event_identity(stopped)
+        or started.ts > stopped.ts
+        or stopped.ts > now
+    ):
+        return None
+    return (stopped.ts - started.ts).total_seconds()
+
+
+def _event_identity(event: Event) -> tuple[int, float] | None:
+    pid = event.data.get(ENGINE_PID_FIELD)
+    started_at = event.data.get(ENGINE_PROCESS_STARTED_AT_FIELD)
+    if (
+        isinstance(pid, bool)
+        or not isinstance(pid, int)
+        or isinstance(started_at, bool)
+        or not isinstance(started_at, int | float)
+    ):
+        return None
+    return pid, float(started_at)

shikiru/domain/escalation.py

@@ -0,0 +1,194 @@
+"""Escalation options and their recommended default."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime
+from enum import StrEnum, auto
+from typing import TYPE_CHECKING
+
+from shikiru.domain.commands import ResolutionKind
+from shikiru.domain.ladder import reset_for_integration_attempt, reset_for_rung_change
+from shikiru.domain.steps import Transition
+from shikiru.domain.tasks import Counters, DomainModel, EscalationReason, Role, Status, Step, Task
+
+if TYPE_CHECKING:
+    from shikiru.agents.contracts import Rung
+
+
+ESCALATION_REASON_LABELS: dict[EscalationReason, str] = {
+    EscalationReason.DECISION_REQUIRED: "Decision required",
+    EscalationReason.ITERATIONS_EXHAUSTED: "Iterations exhausted",
+    EscalationReason.INTEGRATION_CONFLICT: "Integration conflict",
+    EscalationReason.INTEGRATION_BLOCKED: "Integration blocked",
+    EscalationReason.UNCOMMITTED_WORK: "Uncommitted work",
+    EscalationReason.OFF_TASK_BRANCH: "Off task branch",
+    EscalationReason.PR_CLOSED: "Pull request closed",
+    EscalationReason.AGENT_AUTH: "Agent authentication",
+    EscalationReason.AGENT_ERROR: "Agent error",
+    EscalationReason.AGENT_STUCK: "Agent stuck",
+    EscalationReason.AGENT_PROTOCOL: "Agent protocol error",
+    EscalationReason.LADDER_EXHAUSTED: "Ladder exhausted",
+    EscalationReason.QUOTA_EXHAUSTED: "Quota exhausted",
+    EscalationReason.DEPENDENCY_CANCELLED: "Dependency cancelled",
+    EscalationReason.ENGINE_ERROR: "Engine error",
+}
+
+
+ESCALATION_CAUSES: dict[EscalationReason, str] = {
+    EscalationReason.DECISION_REQUIRED: "The Leader needs an Operator decision to continue.",
+    EscalationReason.ITERATIONS_EXHAUSTED: "The final review round still requested changes.",
+    EscalationReason.INTEGRATION_CONFLICT: "Rebase conflicts could not be resolved automatically.",
+    EscalationReason.INTEGRATION_BLOCKED: "Integration is blocked: see the question.",
+    EscalationReason.UNCOMMITTED_WORK: (
+        "The task workspace has uncommitted changes; commit or discard them, then retry."
+    ),
+    EscalationReason.OFF_TASK_BRANCH: (
+        "The task workspace is not on its task branch; move its work onto the branch, then retry."
+    ),
+    EscalationReason.PR_CLOSED: "The pull request was closed without merging.",
+    EscalationReason.AGENT_AUTH: (
+        "The agent cannot access its provider; check credentials, billing, or account status."
+    ),
+    EscalationReason.AGENT_ERROR: "The agent kept failing after every automatic retry.",
+    EscalationReason.AGENT_STUCK: "The agent's screen stayed stuck after every automatic recovery.",
+    EscalationReason.AGENT_PROTOCOL: "The turn never produced a report, even with a Helper rebuild",
+    EscalationReason.LADDER_EXHAUSTED: "Every rung on the ladder was tried without success.",
+    EscalationReason.QUOTA_EXHAUSTED: "The agent's quota stayed exhausted past the wait budget.",
+    EscalationReason.DEPENDENCY_CANCELLED: "A dependency of this task was cancelled.",
+    EscalationReason.ENGINE_ERROR: "The engine hit an unexpected error while running this task.",
+}
+
+RESOLUTION_CONSEQUENCES: dict[ResolutionKind, str] = {
+    ResolutionKind.ANSWER: "Give the Leader guidance; the task continues from a consult turn.",
+    ResolutionKind.RETRY: "Re-run the step that raised this escalation.",
+    ResolutionKind.ACCEPT: "Integrate the work as it stands.",
+    ResolutionKind.CANCEL: (
+        "Cancel the task and keep its branch; preserve its worktree when uncommitted work remains "
+        "or it is off its task branch."
+    ),
+}
+
+
+def escalation_reason_label(reason: EscalationReason) -> str:
+    """Return the Operator-facing name of `reason`."""
+    return ESCALATION_REASON_LABELS[reason]
+
+
+@dataclass(frozen=True)
+class EscalationOption:
+    """One option `resolve` accepts; exactly one option per reason is `recommended`."""
+
+    label: ResolutionKind
+    recommended: bool = False
+
+
+_ANSWER_OR_CANCEL = (
+    EscalationOption(ResolutionKind.ANSWER, recommended=True),
+    EscalationOption(ResolutionKind.CANCEL),
+)
+_RETRY_OR_CANCEL = (
+    EscalationOption(ResolutionKind.RETRY, recommended=True),
+    EscalationOption(ResolutionKind.CANCEL),
+)
+
+_OPTIONS_BY_REASON: dict[EscalationReason, tuple[EscalationOption, ...]] = {
+    EscalationReason.DECISION_REQUIRED: _ANSWER_OR_CANCEL,
+    EscalationReason.ITERATIONS_EXHAUSTED: (
+        EscalationOption(ResolutionKind.ANSWER, recommended=True),
+        EscalationOption(ResolutionKind.ACCEPT),
+        EscalationOption(ResolutionKind.CANCEL),
+    ),
+    EscalationReason.INTEGRATION_CONFLICT: _RETRY_OR_CANCEL,
+    EscalationReason.INTEGRATION_BLOCKED: _RETRY_OR_CANCEL,
+    EscalationReason.UNCOMMITTED_WORK: _RETRY_OR_CANCEL,
+    EscalationReason.OFF_TASK_BRANCH: _RETRY_OR_CANCEL,
+    EscalationReason.PR_CLOSED: _RETRY_OR_CANCEL,
+    EscalationReason.AGENT_AUTH: _RETRY_OR_CANCEL,
+    EscalationReason.AGENT_ERROR: _RETRY_OR_CANCEL,
+    EscalationReason.AGENT_STUCK: _RETRY_OR_CANCEL,
+    EscalationReason.AGENT_PROTOCOL: _RETRY_OR_CANCEL,
+    EscalationReason.LADDER_EXHAUSTED: _RETRY_OR_CANCEL,
+    EscalationReason.QUOTA_EXHAUSTED: _RETRY_OR_CANCEL,
+    EscalationReason.DEPENDENCY_CANCELLED: _RETRY_OR_CANCEL,
+    EscalationReason.ENGINE_ERROR: _RETRY_OR_CANCEL,
+}
+
+
+def options_for(reason: EscalationReason) -> tuple[EscalationOption, ...]:
+    """Return the resolution options for `reason`, with exactly one recommended default."""
+    return _OPTIONS_BY_REASON[reason]
+
+
+def reset_for_resolution(counters: Counters, reason: EscalationReason) -> Counters:
+    """Reset the persisted counter represented by `reason` when it is resolved."""
+    if reason in (EscalationReason.DECISION_REQUIRED, EscalationReason.ITERATIONS_EXHAUSTED):
+        return counters.model_copy(update={"consults": 0})
+    if reason in (
+        EscalationReason.INTEGRATION_CONFLICT,
+        EscalationReason.INTEGRATION_BLOCKED,
+        EscalationReason.PR_CLOSED,
+    ):
+        return counters.model_copy(update={"conflict_rounds": 0})
+    return counters
+
+
+def transition_for_resolution(
+    task: Task,
+    reason: EscalationReason,
+    *,
+    step: Step | None,
+    resolution: ResolutionKind,
+    rung: Rung | None = None,
+    role: Role | None = None,
+) -> Transition:
+    """Build the state transition for one validated escalation resolution."""
+    counters = reset_for_resolution(task.counters, reason)
+    set_overrides: dict[Role, Rung] = {}
+    target_step = step or task.step
+    status = Status.QUEUED
+    if resolution is ResolutionKind.ANSWER:
+        target_step = Step.CONSULT
+    elif resolution is ResolutionKind.ACCEPT:
+        target_step = Step.INTEGRATE
+        counters = reset_for_integration_attempt(counters)
+    elif resolution is ResolutionKind.CANCEL:
+        status = Status.CANCELLED
+    if rung is not None:
+        if role is None:
+            message = "a rung resolution requires its acting role"
+            raise ValueError(message)
+        set_overrides[role] = rung
+        counters = reset_for_rung_change(counters)
+    return Transition(
+        base=task,
+        step=target_step,
+        status=status,
+        iteration=task.iteration,
+        counters=counters,
+        rung_index=dict(task.rung_index),
+        set_overrides=set_overrides,
+    )
+
+
+class EscalationStatus(StrEnum):
+    """An escalation's lifecycle."""
+
+    OPEN = auto()
+    RESOLVED = auto()
+
+
+class Escalation(DomainModel):
+    """One raised escalation (mirrors the `escalations` table)."""
+
+    id: str
+    task_id: str
+    step: Step | None = None
+    reason: EscalationReason
+    headline: str
+    packet_path: str
+    options: tuple[EscalationOption, ...]
+    status: EscalationStatus
+    resolution: str | None = None
+    created_at: datetime
+    resolved_at: datetime | None = None