shikiru-cli 0.2.0__py3-none-any.whl

shikiru/domain/motion.py

@@ -0,0 +1,199 @@
+"""Pure dashboard timing rules for live task and quota views."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import StrEnum, auto
+from math import ceil
+from typing import TYPE_CHECKING
+
+from shikiru.config.settings import MAX_MOTION_REFRESH_HZ
+from shikiru.domain.activity import is_stalled
+
+if TYPE_CHECKING:
+    from datetime import datetime
+
+    from shikiru.config.settings import TimeoutsConfig
+
+PULSE_PHASES = 2
+
+
+class MotionStampKind(StrEnum):
+    """A task outcome that briefly stamps its comic strip."""
+
+    VERDICT = auto()
+    MERGED = auto()
+
+
+@dataclass(frozen=True)
+class MotionStamp:
+    """A verdict or merge event that may briefly stamp its task strip."""
+
+    at: datetime
+    kind: MotionStampKind
+    detail: str = ""
+
+
+@dataclass(frozen=True)
+class TaskMotionState:
+    """Timing evidence for the task's current panel and most recent outcome."""
+
+    task_id: str
+    step_started_at: datetime
+    actual_step_started_at: datetime | None = None
+    turn_started_at: datetime | None = None
+    last_signal_at: datetime | None = None
+    last_signal: str | None = None
+    last_words: str | None = None
+    tool_running: bool = False
+    turn_active: bool = False
+    engine_driven: bool = False
+    held: bool = False
+    ended_at: datetime | None = None
+    stamp: MotionStamp | None = None
+
+
+@dataclass(frozen=True)
+class QuotaMotionState:
+    """One quota reset deadline rendered as a live countdown."""
+
+    agent: str
+    window: str
+    resets_at: datetime | None
+
+
+@dataclass(frozen=True)
+class MotionState:
+    """The immutable inputs needed to render one dashboard frame."""
+
+    animations: bool
+    timeouts: TimeoutsConfig
+    refresh_hz: int
+    stamp_flash_seconds: float
+    escalation_pulse_hz: int
+    tasks: tuple[TaskMotionState, ...] = ()
+    quotas: tuple[QuotaMotionState, ...] = ()
+    escalations_open: bool = False
+    engine_running: bool = True
+
+
+@dataclass(frozen=True)
+class TaskMotionFrame:
+    """Timing output for one task strip, without presentation glyphs or colours."""
+
+    task_id: str
+    spinner_phase: int
+    spinner_visible: bool
+    signal_observed: bool
+    agent_processing: bool
+    stalled: bool
+    elapsed_seconds: int
+    actual_step_started_at: datetime | None
+    last_signal_at: datetime | None
+    last_signal: str | None
+    last_words: str | None
+    stamp_kind: MotionStampKind | None
+    stamp_detail: str
+    stamp_flash: bool
+
+
+@dataclass(frozen=True)
+class QuotaMotionFrame:
+    """Remaining seconds for one provider-reported quota reset."""
+
+    agent: str
+    window: str
+    remaining_seconds: int | None
+
+
+@dataclass(frozen=True)
+class MotionFrame:
+    """All time-derived values for a dashboard render at `now`."""
+
+    tasks: tuple[TaskMotionFrame, ...]
+    quotas: tuple[QuotaMotionFrame, ...]
+    escalation_red: bool
+
+
+def frame(state: MotionState, now: datetime) -> MotionFrame:
+    """Calculate stream motion, outcome flashes, escalation pulse and live counters."""
+    return MotionFrame(
+        tasks=tuple(_task_frame(task, state, now) for task in state.tasks),
+        quotas=tuple(_quota_frame(quota, now) for quota in state.quotas),
+        escalation_red=(
+            state.escalations_open
+            and (
+                not state.animations
+                or int(now.timestamp() * state.escalation_pulse_hz * PULSE_PHASES) % PULSE_PHASES
+                == 0
+            )
+        ),
+    )
+
+
+def is_in_progress_animated(
+    *, engine_running: bool, held: bool, stalled: bool, turn_active: bool, engine_driven: bool
+) -> bool:
+    """Whether a task is actively progressing: a live turn or the engine's own work, unheld."""
+    return engine_running and not held and not stalled and (turn_active or engine_driven)
+
+
+def _task_frame(task: TaskMotionState, state: MotionState, now: datetime) -> TaskMotionFrame:
+    activity_at = task.last_signal_at or task.turn_started_at
+    stalled = (
+        task.turn_active
+        and activity_at is not None
+        and not task.held
+        and is_stalled(activity_at, task.tool_running, now, state.timeouts)
+    )
+    in_progress = is_in_progress_animated(
+        engine_running=state.engine_running,
+        held=task.held,
+        stalled=stalled,
+        turn_active=task.turn_active,
+        engine_driven=task.engine_driven,
+    )
+    signal_observed = in_progress and task.last_signal_at is not None
+    spinner_phase = 0
+    if in_progress and state.animations:
+        spinner_phase = int(now.timestamp() * min(state.refresh_hz, MAX_MOTION_REFRESH_HZ))
+    elapsed_end = task.ended_at or now
+    elapsed_seconds = max(int((elapsed_end - task.step_started_at).total_seconds()), 0)
+    stamp_kind = None
+    stamp_detail = ""
+    stamp_flash = False
+    if state.animations and task.stamp is not None:
+        age = (now - task.stamp.at).total_seconds()
+        if 0 <= age < state.stamp_flash_seconds:
+            stamp_kind = task.stamp.kind
+            stamp_detail = task.stamp.detail
+            stamp_flash = True
+    return TaskMotionFrame(
+        task_id=task.task_id,
+        spinner_phase=spinner_phase,
+        spinner_visible=in_progress and (signal_observed or task.engine_driven),
+        signal_observed=signal_observed,
+        agent_processing=in_progress,
+        stalled=stalled,
+        elapsed_seconds=elapsed_seconds,
+        actual_step_started_at=task.actual_step_started_at,
+        last_signal_at=task.last_signal_at,
+        last_signal=task.last_signal,
+        last_words=task.last_words,
+        stamp_kind=stamp_kind,
+        stamp_detail=stamp_detail,
+        stamp_flash=stamp_flash,
+    )
+
+
+def _quota_frame(quota: QuotaMotionState, now: datetime) -> QuotaMotionFrame:
+    remaining = (
+        max(ceil((quota.resets_at - now).total_seconds()), 0)
+        if quota.resets_at is not None
+        else None
+    )
+    return QuotaMotionFrame(
+        agent=quota.agent,
+        window=quota.window,
+        remaining_seconds=remaining,
+    )

shikiru/domain/packet_evidence.py

@@ -0,0 +1,377 @@
+"""Structured, toned rows for the reports and recent turn signals of an escalation packet."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from datetime import datetime
+from typing import TYPE_CHECKING, cast
+
+from pydantic import TypeAdapter, ValidationError
+
+from shikiru.agents.contracts import (
+    Compacted,
+    QuotaReported,
+    SessionStarted,
+    UsageReported,
+)
+from shikiru.domain.reports import (
+    ConsultAnswer,
+    EscalationRequest,
+    FeedbackAnalysis,
+    FeedbackVerdict,
+    ImplementationReport,
+    NewTask,
+    PlanReport,
+    Report,
+    TriageReport,
+    Verdict,
+)
+from shikiru.domain.timeline_phrases import (
+    PHRASE_SEPARATOR,
+    SIGNAL_MESSAGE,
+    SIGNAL_TOOL_FINISHED,
+    SIGNAL_TOOL_STARTED,
+    SIGNAL_TURN_ENDED,
+    SIGNAL_TURN_FAILED,
+    Tone,
+    signal_phrase,
+    tool_target,
+    verdict_phrase,
+)
+from shikiru.view_log import VIEW_RUNG_KEY, VIEW_SIGNAL_KEY, VIEW_TIME_KEY, VIEW_TURN_KEY
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+    from shikiru.domain.reports import Commit, Issue, Option, TestRun
+
+_REPORT: TypeAdapter[Report] = TypeAdapter(Report | FeedbackVerdict)
+_LABEL_OPEN = "**"
+_LABEL_CLOSE = "**\n\n"
+_BLOCK_SEPARATOR = "\n\n"
+_LABEL_SEPARATOR = "-"
+_SIGNAL_TIME_FORMAT = "%H:%M:%S"
+_RECOMMENDED_STAR = "\N{BLACK STAR} "
+_LOCATION_SEPARATOR = " @ "
+_RUNG_SEPARATOR = " \N{MIDDLE DOT} "
+_FIRST_LINE_SEPARATOR = "\n"
+_OLD_SCHEMA_INDENT = 2
+_REPORT_LABEL = "Report"
+_TEXT_LABEL = "Text"
+_LINE_LABEL = "Line"
+_STATUS_TONES = {"completed": Tone.SUCCESS, "needs_decision": Tone.WARNING, "blocked": Tone.FAILURE}
+_RESULT_TONES = {"passed": Tone.SUCCESS, "failed": Tone.FAILURE}
+_SEVERITY_TONES = {"blocker": Tone.FAILURE, "major": Tone.WARNING}
+_SIGNAL_KINDS = {
+    SIGNAL_MESSAGE: "message",
+    SIGNAL_TOOL_STARTED: "tool",
+    SIGNAL_TOOL_FINISHED: "tool done",
+    SIGNAL_TURN_ENDED: "turn end",
+    SIGNAL_TURN_FAILED: "failed",
+    UsageReported.__name__: "usage",
+    SessionStarted.__name__: "session",
+    QuotaReported.__name__: "quota",
+    Compacted.__name__: "compacted",
+}
+_REPORT_KINDS = {
+    TriageReport: "triage",
+    ImplementationReport: "implement",
+    PlanReport: "plan",
+    ConsultAnswer: "consult",
+    Verdict: "verify",
+    FeedbackAnalysis: "feedback analysis",
+    FeedbackVerdict: "feedback verify",
+}
+
+
+@dataclass(frozen=True)
+class Part:
+    """A run of text in one tone, optionally in the accent colour."""
+
+    text: str
+    tone: Tone = Tone.PLAIN
+    accent: bool = False
+
+
+@dataclass(frozen=True)
+class DetailRow:
+    """One labelled line of a details block; an empty label continues the row above."""
+
+    label: str
+    parts: tuple[Part, ...]
+
+
+@dataclass(frozen=True)
+class EvidenceEntry:
+    """One table row (lead, kind, one-line outcome) and the structured block that explains it."""
+
+    lead: str
+    kind: str
+    outcome: Part
+    details: tuple[DetailRow, ...]
+
+
+def _raw(label: str, text: str) -> tuple[DetailRow, ...]:
+    return (DetailRow(label, (Part(text),)),)
+
+
+def _row(label: str, text: str, tone: Tone = Tone.PLAIN) -> list[DetailRow]:
+    return [DetailRow(label, (Part(text, tone),))] if text else []
+
+
+def _listed(label: str, items: Sequence[tuple[Part, ...]]) -> list[DetailRow]:
+    return [DetailRow(label if index == 0 else "", parts) for index, parts in enumerate(items)]
+
+
+def _plain_items(label: str, items: Sequence[str]) -> list[DetailRow]:
+    return _listed(label, [(Part(item),) for item in items])
+
+
+def _counted(count: int, noun: str) -> str:
+    return f"{count} {noun}" if count == 1 else f"{count} {noun}s"
+
+
+def _commit(commit: Commit) -> tuple[Part, ...]:
+    return (Part(commit.sha, accent=True), Part(f" {commit.subject}"))
+
+
+def _test(test: TestRun) -> tuple[Part, ...]:
+    parts = [Part(f"{test.name} "), Part(test.result, _RESULT_TONES.get(test.result, Tone.PLAIN))]
+    if test.details:
+        parts.append(Part(f" {test.details}"))
+    return tuple(parts)
+
+
+def _issue(issue: Issue) -> tuple[Part, ...]:
+    parts = [
+        Part(issue.severity, _SEVERITY_TONES.get(issue.severity, Tone.PLAIN)),
+        Part(f" {issue.description}"),
+    ]
+    if issue.location:
+        parts.append(Part(f"{_LOCATION_SEPARATOR}{issue.location}"))
+    return tuple(parts)
+
+
+def _option(option: Option) -> tuple[Part, ...]:
+    star = _RECOMMENDED_STAR if option.recommended else ""
+    return (
+        Part(f"{star}{option.label}", accent=option.recommended),
+        Part(f" {option.consequences}"),
+    )
+
+
+def _new_task(task: NewTask) -> tuple[Part, ...]:
+    return (Part(task.title),)
+
+
+def _escalation(request: EscalationRequest | None) -> list[DetailRow]:
+    if request is None:
+        return []
+    return [
+        *_row("Escalation question", request.question),
+        *_listed("Escalation options", [_option(option) for option in request.options]),
+    ]
+
+
+def _implementation(report: ImplementationReport) -> tuple[Part, list[DetailRow]]:
+    tone = _STATUS_TONES[report.status]
+    status = report.status.replace("_", " ")
+    failed = sum(_RESULT_TONES.get(test.result) is Tone.FAILURE for test in report.tests)
+    bits = [status]
+    if report.commits:
+        bits.append(_counted(len(report.commits), "commit"))
+    if failed:
+        bits.append(f"{failed} failed")
+    return Part(PHRASE_SEPARATOR.join(bits), tone), [
+        *_row("Status", status, tone),
+        *_row("Summary", report.summary),
+        *_listed("Commits", [_commit(commit) for commit in report.commits]),
+        *_listed("Tests", [_test(test) for test in report.tests]),
+        *_plain_items("Risks", report.risks),
+        *_row("Question", report.question),
+    ]
+
+
+def _feedback_analysis(report: FeedbackAnalysis) -> tuple[Part, list[DetailRow]]:
+    decisions = [
+        (
+            Part(decision.source_id, accent=True),
+            Part(f" {decision.action.value}: {decision.detail}"),
+        )
+        for decision in report.decisions
+    ]
+    return Part(report.summary), [
+        *_row("Summary", report.summary),
+        *_listed("Decisions", decisions),
+        *_plain_items("Work", [work.instruction for work in report.work]),
+    ]
+
+
+def _verdict(report: Verdict) -> tuple[Part, list[DetailRow]]:
+    phrase = verdict_phrase(report.decision)
+    text, tone = (phrase.text, phrase.tone) if phrase is not None else (report.decision, Tone.PLAIN)
+    outcome = f"{text} ({_counted(len(report.issues), 'issue')})" if report.issues else text
+    return Part(outcome, tone), [
+        *_row("Decision", text, tone),
+        *_row("Summary", report.summary),
+        *_listed("Issues", [_issue(issue) for issue in report.issues]),
+        *_plain_items("Residual risks", report.residual_risks),
+        *_listed("New tasks", [_new_task(task) for task in report.new_tasks]),
+        *_plain_items("Scope changes", report.scope_changes),
+        *_escalation(report.escalation),
+    ]
+
+
+def _triage(report: TriageReport) -> tuple[Part, list[DetailRow]]:
+    return Part(report.title), [
+        *_row("Title", report.title),
+        *_row("Mode", report.mode.value),
+        *_row("Complexity", report.complexity),
+        *_plain_items("Acceptance criteria", report.acceptance_criteria),
+        *_plain_items("References", report.references),
+    ]
+
+
+def _plan(report: PlanReport) -> tuple[Part, list[DetailRow]]:
+    return Part(report.summary), [
+        *_row("Summary", report.summary),
+        *_listed("Commits", [_commit(commit) for commit in report.commits]),
+        *_listed("New tasks", [_new_task(task) for task in report.new_tasks]),
+        *_plain_items("Scope changes", report.scope_changes),
+    ]
+
+
+def _consult(report: ConsultAnswer) -> tuple[Part, list[DetailRow]]:
+    tone = Tone.WARNING if report.escalation is not None else Tone.PLAIN
+    return Part(report.answer or report.decision, tone), [
+        *_row("Decision", report.decision, tone),
+        *_row("Answer", report.answer),
+        *_escalation(report.escalation),
+    ]
+
+
+def _report_content(report: Report) -> tuple[Part, list[DetailRow]]:
+    match report:
+        case ImplementationReport():
+            return _implementation(report)
+        case Verdict():
+            return _verdict(report)
+        case TriageReport():
+            return _triage(report)
+        case PlanReport():
+            return _plan(report)
+        case ConsultAnswer():
+            return _consult(report)
+        case FeedbackAnalysis():
+            return _feedback_analysis(report)
+
+
+def _first_line(text: str) -> str:
+    return text.strip().partition(_FIRST_LINE_SEPARATOR)[0]
+
+
+def _readable_json(text: str) -> str:
+    try:
+        return json.dumps(json.loads(text), indent=_OLD_SCHEMA_INDENT, ensure_ascii=False)
+    except json.JSONDecodeError:
+        return text
+
+
+def _label_parts(label: str) -> tuple[str, str]:
+    number, separator, rest = label.partition(_LABEL_SEPARATOR)
+    if not (separator and number.isdigit()):
+        return "", label
+    return number, rest.partition(_LABEL_SEPARATOR)[0]
+
+
+def _report_entry(label: str, body: str) -> EvidenceEntry:
+    lead, step = _label_parts(label)
+    try:
+        report = _REPORT.validate_json(body)
+    except ValidationError:
+        return EvidenceEntry(
+            lead, step, Part(_first_line(body)), _raw(_REPORT_LABEL, _readable_json(body))
+        )
+    outcome, details = _report_content(report)
+    return EvidenceEntry(lead, step or _REPORT_KINDS[type(report)], outcome, tuple(details))
+
+
+def _plain_entry(text: str) -> EvidenceEntry:
+    return EvidenceEntry("", "", Part(_first_line(text)), _raw(_TEXT_LABEL, text.strip()))
+
+
+def parse_reports(content: str) -> tuple[EvidenceEntry, ...]:
+    """Read the packet's `**label**` + JSON report blocks; unreadable ones stay as readable text."""
+    entries: list[EvidenceEntry] = []
+    for block in content.split(_BLOCK_SEPARATOR + _LABEL_OPEN):
+        label, separator, body = block.removeprefix(_LABEL_OPEN).partition(_LABEL_CLOSE)
+        entries.append(_report_entry(label, body) if separator else _plain_entry(block))
+    return tuple(entries)
+
+
+def _signal_time(value: object) -> str:
+    try:
+        return datetime.fromisoformat(str(value)).strftime(_SIGNAL_TIME_FORMAT)
+    except ValueError:
+        return ""
+
+
+def _signal_details(signal: str, data: dict[str, object], tone: Tone) -> list[DetailRow]:
+    if signal == SIGNAL_MESSAGE:
+        return _row("Message", str(data.get("text") or ""))
+    if signal == SIGNAL_TURN_ENDED:
+        return _row("Last message", str(data.get("last_message") or ""))
+    if signal == SIGNAL_TOOL_STARTED:
+        return [
+            *_row("Tool", str(data.get("name") or "")),
+            *_row("Detail", tool_target(str(data.get("detail") or ""))),
+        ]
+    if signal == SIGNAL_TOOL_FINISHED:
+        exit_code = data.get("exit_code")
+        result = PHRASE_SEPARATOR.join(
+            str(part) for part in (data.get("outcome"), exit_code) if part is not None
+        )
+        return [*_row("Tool", str(data.get("name") or "")), *_row("Result", result, tone)]
+    if signal == SIGNAL_TURN_FAILED:
+        return [
+            *_row("Failure", str(data.get("kind") or ""), tone),
+            *_row("Message", str(data.get("message") or "")),
+        ]
+    return []
+
+
+def _rung(value: object) -> str:
+    if not isinstance(value, dict):
+        return ""
+    rung = cast("dict[str, object]", value)
+    return _RUNG_SEPARATOR.join(
+        str(rung[key]) for key in ("agent", "model", "effort") if rung.get(key)
+    )
+
+
+def _signal_entry(line: str) -> EvidenceEntry:
+    try:
+        decoded: object = json.loads(line)
+    except json.JSONDecodeError:
+        decoded = None
+    if not isinstance(decoded, dict) or VIEW_SIGNAL_KEY not in decoded:
+        return EvidenceEntry("", "", Part(line.strip()), _raw(_LINE_LABEL, line.strip()))
+    data = cast("dict[str, object]", decoded)
+    signal = str(data[VIEW_SIGNAL_KEY])
+    phrase = signal_phrase(signal, data)
+    tone = phrase.tone if phrase is not None else Tone.PLAIN
+    kind = _SIGNAL_KINDS.get(signal, signal)
+    details = [
+        *_row("Signal", kind),
+        *_row("Rung", _rung(data.get(VIEW_RUNG_KEY))),
+        *_row("Turn", str(data.get(VIEW_TURN_KEY) or "")),
+        *_signal_details(signal, data, tone),
+    ]
+    outcome = Part(phrase.text if phrase is not None else "", tone)
+    return EvidenceEntry(_signal_time(data.get(VIEW_TIME_KEY)), kind, outcome, tuple(details))
+
+
+def parse_signals(content: str) -> tuple[EvidenceEntry, ...]:
+    """Read the packet's view.jsonl lines; a non-JSON or truncated line stays as a plain entry."""
+    return tuple(_signal_entry(line) for line in content.splitlines() if line.strip())

shikiru/domain/pushes.py

@@ -0,0 +1,47 @@
+"""Scheduling rules for pushing locally integrated base branches."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from datetime import datetime, timedelta
+
+
+@dataclass(frozen=True, slots=True)
+class PushTarget:
+    """A base branch with integrations to publish and the scheduling facts of its pushes."""
+
+    base: str
+    registered: int
+    pushed: int
+    due_at: datetime | None
+    last_pushed_at: datetime | None
+
+    @property
+    def pending(self) -> bool:
+        """Return whether an integration was registered that no push has acknowledged."""
+        return self.registered > self.pushed
+
+    @property
+    def scheduled_at(self) -> datetime | None:
+        """Return when the pending integrations are due, or `None` when nothing is pending."""
+        return self.due_at if self.pending else None
+
+
+def pending_deadline(*, last_pushed_at: datetime | None, now: datetime, interval: int) -> datetime:
+    """Return when work that becomes pending at `now` is due, given `interval` seconds.
+
+    Without an earlier push the interval starts now; after one, the work is due an interval
+    after it, or at once when that moment has passed. Zero means due at once.
+    """
+    if interval == 0:
+        return now
+    if last_pushed_at is None:
+        return now + timedelta(seconds=interval)
+    return max(last_pushed_at + timedelta(seconds=interval), now)
+
+
+def is_due(target: PushTarget, *, now: datetime, interval: int) -> bool:
+    """Return whether `target` has pending work whose deadline has come."""
+    if not target.pending or target.due_at is None:
+        return False
+    return interval == 0 or now >= target.due_at

shikiru/domain/quota_blocks.py

@@ -0,0 +1,44 @@
+"""The rule deciding when fresh quota evidence releases a provider quota block."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from shikiru.agents.contracts import is_exhausted
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+    from datetime import datetime
+
+    from shikiru.agents.contracts import QuotaWindow
+
+
+def block_released(
+    *,
+    blocked_at: datetime,
+    stored: Sequence[QuotaWindow],
+    reading: Sequence[QuotaWindow],
+    now: datetime,
+) -> bool:
+    """Return whether `reading` proves the block set at `blocked_at` no longer holds.
+
+    Only samples observed after the block and no earlier than the stored sample of the same
+    window count. The fresh reading must have a usable window, show none exhausted and cover
+    every window `stored` holds exhausted, unless its known reset has already passed. A missing
+    reset does not show an exhausted window expired.
+    """
+    latest = {window.name: window.observed_at for window in stored}
+    fresh = [
+        window
+        for window in reading
+        if window.observed_at > blocked_at
+        and window.observed_at >= latest.get(window.name, window.observed_at)
+    ]
+    if not fresh or any(is_exhausted(window) for window in fresh):
+        return False
+    covered = {window.name for window in fresh}
+    return all(
+        window.name in covered
+        for window in stored
+        if is_exhausted(window) and (window.resets_at is None or window.resets_at > now)
+    )