shikiru-cli 0.2.0__py3-none-any.whl

shikiru/domain/__init__.py

@@ -0,0 +1 @@
+"""Pure domain rules: models, transitions and policies with no I/O."""

shikiru/domain/acceptance.py

@@ -0,0 +1,130 @@
+"""Acceptance criteria a task request states under its acceptance-criteria heading."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from typing import Final
+
+ACCEPTANCE_CRITERIA_HEADING: Final = "Acceptance criteria"
+
+_PHRASE: Final = re.escape(ACCEPTANCE_CRITERIA_HEADING)
+_HEADING: Final = re.compile(
+    rf"(?:#{{1,6}}\s+)?(?:\*\*{_PHRASE}(?::\*\*|\*\*:?)|{_PHRASE}:?)\s*", re.IGNORECASE
+)
+_ANY_HEADING: Final = re.compile(r"\s*#{1,6}\s")
+_FENCE: Final = re.compile(r"\s{0,3}(?P<marker>`{3,}|~{3,})")
+_CRITERION: Final = re.compile(r"\s*(?:[-*+]|\d+[.)])\s+(?P<text>\S.*?)\s*")
+_INDENTED: Final = re.compile(r"\s+\S.*")
+
+
+@dataclass(frozen=True)
+class _Section:
+    start: int
+    end: int
+    criteria: tuple[str, ...]
+
+
+def acceptance_criteria_from_request(request: str) -> tuple[str, ...]:
+    """Return the bullets under the request's acceptance-criteria heading, in order.
+
+    Fenced code is an example, not a requirement, so its lines are never read as a heading or
+    a criterion. The section starts after the first line that is only the heading
+    `ACCEPTANCE_CRITERIA_HEADING`, written with optional `#` marks, optional bold markers and an
+    optional trailing colon, in any letter case. An indented line continues the bullet above it.
+    The section ends at the first other non-blank line: prose, a heading or a code fence. A request
+    without that heading has no criteria.
+    """
+    section = _section(request.splitlines(keepends=True))
+    return () if section is None else section.criteria
+
+
+def request_without_criteria_section(request: str) -> str:
+    """Return the request without its acceptance-criteria section, keeping all other text.
+
+    The removed section is the one `acceptance_criteria_from_request` reads: its heading line,
+    its bullets and their continuations, and the blank lines among them. Every other character
+    and line ending is kept. Blank lines left at either end of the request by the removal are
+    dropped. A request without criteria is returned unchanged.
+    """
+    lines = request.splitlines(keepends=True)
+    section = _section(lines)
+    if section is None:
+        return request
+    before = lines[: section.start]
+    after = lines[section.end :]
+    if not after:
+        before = _without_trailing_blank_lines(before)
+    if not before:
+        after = _without_leading_blank_lines(after)
+    return "".join([*before, *after])
+
+
+def _without_trailing_blank_lines(lines: list[str]) -> list[str]:
+    kept = list(lines)
+    while kept and not kept[-1].strip():
+        kept.pop()
+    return kept
+
+
+def _without_leading_blank_lines(lines: list[str]) -> list[str]:
+    kept = list(lines)
+    while kept and not kept[0].strip():
+        kept.pop(0)
+    return kept
+
+
+def _section(lines: list[str]) -> _Section | None:
+    visible = _blank_code_blocks(lines)
+    start = next(
+        (index for index, line in enumerate(visible) if _HEADING.fullmatch(line)),
+        None,
+    )
+    if start is None:
+        return None
+    criteria: list[str] = []
+    end = len(visible)
+    for index in range(start + 1, len(visible)):
+        line = visible[index]
+        if not line.strip():
+            continue
+        match = _CRITERION.fullmatch(line)
+        if match is not None:
+            criteria.append(match["text"])
+        elif criteria and _is_continuation(line):
+            criteria[-1] = f"{criteria[-1]} {line.strip()}"
+        else:
+            end = index
+            break
+    if not criteria:
+        return None
+    return _Section(start=start, end=end, criteria=tuple(criteria))
+
+
+def _blank_code_blocks(lines: list[str]) -> list[str]:
+    visible: list[str] = []
+    fence: str | None = None
+    for line in lines:
+        if fence is not None:
+            visible.append("")
+            if _closes_fence(line, fence):
+                fence = None
+            continue
+        visible.append(line.rstrip())
+        opening = _FENCE.match(line)
+        if opening is not None:
+            fence = opening["marker"]
+    return visible
+
+
+def _closes_fence(line: str, fence: str) -> bool:
+    stripped = line.strip()
+    return len(stripped) >= len(fence) and stripped == fence[0] * len(stripped)
+
+
+def _is_continuation(line: str) -> bool:
+    return (
+        _INDENTED.fullmatch(line) is not None
+        and _ANY_HEADING.match(line) is None
+        and _FENCE.match(line) is None
+    )

shikiru/domain/activity.py

@@ -0,0 +1,28 @@
+"""Stall detection."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from datetime import datetime
+
+    from shikiru.config.settings import TimeoutsConfig
+
+
+def seconds_until_stall(
+    last_activity: datetime, tool_running: bool, now: datetime, timeouts: TimeoutsConfig
+) -> float:
+    """Return how long past `now` the activity last seen may stay silent.
+
+    A running tool gets the longer `timeouts.tool` budget; anything else uses `timeouts.stall`.
+    """
+    threshold = timeouts.tool if tool_running else timeouts.stall
+    return threshold - (now - last_activity).total_seconds()
+
+
+def is_stalled(
+    last_activity: datetime, tool_running: bool, now: datetime, timeouts: TimeoutsConfig
+) -> bool:
+    """Decide whether `now` is past the timeout for the kind of activity last seen."""
+    return seconds_until_stall(last_activity, tool_running, now, timeouts) <= 0

shikiru/domain/attempts.py

@@ -0,0 +1,333 @@
+"""The capped digest of what a task did before it escalated."""
+
+from __future__ import annotations
+
+import re
+from collections import Counter
+from dataclasses import dataclass
+from enum import StrEnum, auto
+from typing import TYPE_CHECKING
+
+from shikiru.domain.briefing import one_line, parse_produced, reported_tests, verdict_counts
+from shikiru.domain.events import EventKind
+from shikiru.domain.reports import ImplementationReport, Verdict
+from shikiru.domain.tasks import Step
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping, Sequence
+
+    from shikiru.domain.events import Event
+    from shikiru.domain.reports import Report
+    from shikiru.domain.tasks import Task
+
+TURN_FIELD = "turn"
+ROLE_FIELD = "role"
+STEP_FIELD = "step"
+OUTCOME_FIELD = "outcome"
+TIMES = "\N{MULTIPLICATION SIGN}"
+PART_SEPARATOR = " \N{MIDDLE DOT} "
+MINUS = "\N{MINUS SIGN}"
+EARLIER_TEMPLATE = "+{count} earlier"
+LABEL_SEPARATOR = ": "
+VERDICT_SUFFIX = " verdict"
+TURN_FAILED_PREFIXES = ("failed", "turn failed")
+TRIAGE_TEXT = "triaged as"
+PLAN_READY = "plan ready"
+NO_COMMITS = "no commits"
+COMPLETED = "completed"
+NEEDS_DECISION = "needs_decision"
+BLOCKED = "blocked"
+LABEL_ROUNDS = "Rounds"
+LABEL_RECOVERY = "Recovery"
+LABEL_PRODUCED = "Produced"
+LABEL_OPERATOR = "Operator"
+FAILURE_MESSAGE_LIMIT = 80
+_OUTCOME_WORDS = {
+    "answer": "answered",
+    "accept": "accepted",
+    "changes_requested": "changes requested",
+    "escalate": "escalated",
+    "supersede": "superseded",
+    NEEDS_DECISION: "needs a decision",
+}
+_RECOVERY_NOUNS = (
+    (EventKind.NUDGE, "nudge"),
+    (EventKind.HELPER_ACTION, "helper action"),
+    (EventKind.RUNG_CHANGED, "rung change"),
+)
+_OPERATOR_NOUNS = (
+    (EventKind.OPERATOR_MESSAGE, "message"),
+    (EventKind.TASK_RETRIED, "earlier retry"),
+)
+
+
+class AttemptKind(StrEnum):
+    """What one row of the escalation details shows."""
+
+    REASON = auto()
+    ROUNDS = auto()
+    TURN_OK = auto()
+    TURN_FAILED = auto()
+    VERDICT = auto()
+    RECOVERY = auto()
+    PRODUCED = auto()
+    OPERATOR = auto()
+    EARLIER = auto()
+
+
+class AttemptTone(StrEnum):
+    """How a piece of a row reads: plain, a step name, success, failure or rework."""
+
+    PLAIN = auto()
+    STEP = auto()
+    SUCCESS = auto()
+    FAILURE = auto()
+    REWORK = auto()
+
+
+@dataclass(frozen=True)
+class AttemptPart:
+    """A run of row text with its tone."""
+
+    text: str
+    tone: AttemptTone
+
+
+@dataclass(frozen=True)
+class AttemptItem:
+    """One row of the details: a kind, its label (a section or role name) and toned parts."""
+
+    kind: AttemptKind
+    label: str
+    parts: tuple[AttemptPart, ...]
+
+    @property
+    def text(self) -> str:
+        """The row text without its label."""
+        return "".join(part.text for part in self.parts)
+
+    @property
+    def line(self) -> str:
+        """The `Label: text` packet line of this row."""
+        if self.kind in _UNLABELLED:
+            return self.text
+        label = self.label + VERDICT_SUFFIX if self.kind is AttemptKind.VERDICT else self.label
+        return label + LABEL_SEPARATOR + self.text
+
+
+_UNLABELLED = frozenset({AttemptKind.REASON, AttemptKind.EARLIER})
+_SECTION_KINDS = {
+    LABEL_ROUNDS: AttemptKind.ROUNDS,
+    LABEL_RECOVERY: AttemptKind.RECOVERY,
+    LABEL_PRODUCED: AttemptKind.PRODUCED,
+    LABEL_OPERATOR: AttemptKind.OPERATOR,
+}
+_STEP_NAME = "|".join(step.value for step in Step)
+_EARLIER = re.compile(r"\+\d+ earlier")
+_TONES: dict[AttemptKind, tuple[tuple[re.Pattern[str], AttemptTone], ...]] = {
+    AttemptKind.ROUNDS: (
+        (re.compile(rf"\b(?:{_STEP_NAME})(?= {TIMES})"), AttemptTone.STEP),
+        (re.compile(r"\(?iteration \d+ of \d+\)?"), AttemptTone.REWORK),
+    ),
+    AttemptKind.TURN_OK: (
+        (re.compile(r"\d+ commits?|\d+ tests? passed|\baccepted?\b"), AttemptTone.SUCCESS),
+        (re.compile(r"\d+ failed|no commits|\bblocked\b|\d+ blockers?"), AttemptTone.FAILURE),
+        (
+            re.compile(r"needs a decision|changes requested|\bescalated?\b|\bsuperseded\b"),
+            AttemptTone.REWORK,
+        ),
+        (re.compile(rf"^(?:{_STEP_NAME})\b"), AttemptTone.STEP),
+    ),
+    AttemptKind.TURN_FAILED: ((re.compile(r".+"), AttemptTone.FAILURE),),
+    AttemptKind.VERDICT: (
+        (re.compile(r"\baccept\b"), AttemptTone.SUCCESS),
+        (re.compile(r"changes requested"), AttemptTone.REWORK),
+        (re.compile(r"\d+ blockers?"), AttemptTone.FAILURE),
+    ),
+    AttemptKind.RECOVERY: ((re.compile(r".+"), AttemptTone.REWORK),),
+    AttemptKind.PRODUCED: (
+        (re.compile(r"\+\d+"), AttemptTone.SUCCESS),
+        (re.compile(rf"[-{MINUS}]\d+"), AttemptTone.FAILURE),
+    ),
+}
+
+
+def _toned(kind: AttemptKind, text: str) -> tuple[AttemptPart, ...]:
+    marks = sorted(
+        (match.start(), match.end(), tone)
+        for pattern, tone in _TONES.get(kind, ())
+        for match in pattern.finditer(text)
+    )
+    parts: list[AttemptPart] = []
+    cursor = 0
+    for start, end, tone in marks:
+        if start < cursor:
+            continue
+        if start > cursor:
+            parts.append(AttemptPart(text[cursor:start], AttemptTone.PLAIN))
+        parts.append(AttemptPart(text[start:end], tone))
+        cursor = end
+    if cursor < len(text):
+        parts.append(AttemptPart(text[cursor:], AttemptTone.PLAIN))
+    return tuple(parts)
+
+
+def _item(kind: AttemptKind, label: str, text: str) -> AttemptItem:
+    return AttemptItem(kind, label, _toned(kind, text))
+
+
+def parse_attempt_lines(content: str) -> tuple[AttemptItem, ...]:
+    """Rebuild the details rows from a packet's `What was tried` text.
+
+    The first line is the reason; a canned one-sentence packet is a single reason row.
+    """
+    lines = [line.strip() for line in content.splitlines() if line.strip()]
+    if not lines:
+        return ()
+    return (_item(AttemptKind.REASON, "", lines[0]), *map(_parse_line, lines[1:]))
+
+
+def _parse_line(line: str) -> AttemptItem:
+    if _EARLIER.fullmatch(line):
+        return _item(AttemptKind.EARLIER, "", line)
+    label, separator, text = line.partition(LABEL_SEPARATOR)
+    if not separator:
+        return _item(AttemptKind.REASON, "", line)
+    if label in _SECTION_KINDS:
+        return _item(_SECTION_KINDS[label], label, text)
+    if label.endswith(VERDICT_SUFFIX):
+        return _item(AttemptKind.VERDICT, label.removesuffix(VERDICT_SUFFIX), text)
+    failed = text.startswith(TURN_FAILED_PREFIXES)
+    return _item(AttemptKind.TURN_FAILED if failed else AttemptKind.TURN_OK, label, text)
+
+
+def _count(count: int, noun: str) -> str:
+    return f"{count} {noun}{'' if count == 1 else 's'}"
+
+
+def _counted(counts: Counter[EventKind], nouns: tuple[tuple[EventKind, str], ...]) -> str:
+    return ", ".join(_count(counts[kind], noun) for kind, noun in nouns if counts[kind])
+
+
+def _rounds(events: Sequence[Event], task: Task, max_iterations: int) -> AttemptItem | None:
+    steps = Counter(
+        str(event.data.get(STEP_FIELD)) for event in events if event.kind is EventKind.STEP_STARTED
+    )
+    if not steps:
+        return None
+    text = PART_SEPARATOR.join(f"{step} {TIMES}{count}" for step, count in steps.items())
+    if task.iteration > 0:
+        text += f" (iteration {task.iteration} of {max_iterations})"
+    return _item(AttemptKind.ROUNDS, LABEL_ROUNDS, text)
+
+
+def _implementation_phrase(outcome: str, report: ImplementationReport) -> str:
+    tests = reported_tests(report.tests)
+    if outcome == BLOCKED:
+        return BLOCKED
+    commits = [_count(len(report.commits), "commit")] if report.commits else []
+    parts = list(commits)
+    if tests.passed:
+        parts.append(f"{_count(tests.passed, 'test')} passed")
+    if tests.failed:
+        parts.append(f"{tests.failed} failed")
+    if outcome == NEEDS_DECISION:
+        return ", ".join([_OUTCOME_WORDS[NEEDS_DECISION], *commits])
+    return ", ".join(parts) or NO_COMMITS
+
+
+def _verdict_phrase(report: Verdict) -> str:
+    counts = verdict_counts(report)
+    text = _OUTCOME_WORDS.get(counts.decision, counts.decision)
+    if counts.blocker:
+        text += f" ({_count(counts.blocker, 'blocker')})"
+    return text
+
+
+def _outcome_phrase(step: object, outcome: str, report: Report | None) -> str:
+    if isinstance(report, ImplementationReport):
+        return _implementation_phrase(outcome, report)
+    if isinstance(report, Verdict):
+        return _verdict_phrase(report)
+    if step == Step.TRIAGE:
+        return f"{TRIAGE_TEXT} {outcome}"
+    if step == Step.PLAN and outcome == COMPLETED:
+        return PLAN_READY
+    return _OUTCOME_WORDS.get(outcome, outcome)
+
+
+def _turn_item(event: Event, reports: Mapping[str, Report]) -> AttemptItem:
+    role = str(event.data.get(ROLE_FIELD, "agent")).capitalize()
+    if event.kind is EventKind.TURN_FAILED:
+        message = one_line(event.message, FAILURE_MESSAGE_LIMIT) or "no message"
+        return _item(AttemptKind.TURN_FAILED, role, f"{TURN_FAILED_PREFIXES[0]} ({message})")
+    step = event.data.get(STEP_FIELD)
+    report = reports.get(str(event.data.get(TURN_FIELD)))
+    phrase = _outcome_phrase(step, str(event.data.get(OUTCOME_FIELD)), report)
+    return _item(AttemptKind.TURN_OK, role, f"{step}{PART_SEPARATOR}{phrase}" if step else phrase)
+
+
+def _turn_items(
+    events: Sequence[Event], reports: Mapping[str, Report], room: int
+) -> list[AttemptItem]:
+    items = [
+        _turn_item(event, reports)
+        for event in events
+        if event.kind in (EventKind.TURN_COMPLETED, EventKind.TURN_FAILED)
+    ]
+    if len(items) <= room:
+        return items
+    kept = max(room - 1, 0)
+    earlier = _item(AttemptKind.EARLIER, "", EARLIER_TEMPLATE.format(count=len(items) - kept))
+    return [earlier, *items[len(items) - kept :]][:room]
+
+
+def _produced(facts: str) -> AttemptItem | None:
+    produced = parse_produced(facts)
+    if produced is None:
+        return None
+    text = (
+        f"{_count(produced.commits, 'commit')}, {_count(produced.files, 'file')}, "
+        f"+{produced.insertions} {MINUS}{produced.deletions}"
+    )
+    return _item(AttemptKind.PRODUCED, LABEL_PRODUCED, text)
+
+
+def _section(kind: AttemptKind, label: str, text: str) -> AttemptItem | None:
+    return _item(kind, label, text) if text else None
+
+
+def attempt_lines(items: Sequence[AttemptItem]) -> str:
+    """Return the packet text of `items`, one `Label: text` line per row."""
+    return "\n".join(item.line for item in items)
+
+
+def summarise_attempts(
+    reason: str,
+    events: Sequence[Event],
+    reports: Mapping[str, Report],
+    task: Task,
+    facts: str,
+    *,
+    max_iterations: int,
+    limit: int,
+) -> tuple[AttemptItem, ...]:
+    """Return at most `limit` chronological rows of what `task` did, `reason` first.
+
+    Rounds, the latest turns with their outcome, recovery, produced numbers and Operator input
+    appear only when recorded; the oldest turns collapse into a `+N earlier` row.
+    """
+    counts = Counter(event.kind for event in events)
+    head = [
+        _item(AttemptKind.REASON, "", reason),
+        _rounds(events, task, max_iterations),
+    ]
+    tail = [
+        _section(AttemptKind.RECOVERY, LABEL_RECOVERY, _counted(counts, _RECOVERY_NOUNS)),
+        _produced(facts),
+        _section(AttemptKind.OPERATOR, LABEL_OPERATOR, _counted(counts, _OPERATOR_NOUNS)),
+    ]
+    leading = [item for item in head if item is not None]
+    trailing = [item for item in tail if item is not None]
+    room = max(limit - len(leading) - len(trailing), 0)
+    return (*leading, *_turn_items(events, reports, room), *trailing)[:limit]