shikiru-cli 0.2.0__py3-none-any.whl

shikiru/domain/escalation_evidence.py

@@ -0,0 +1,186 @@
+"""Read structured decision details from Shikiru's escalation packet format."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from pydantic import ValidationError
+
+from shikiru.domain.commands import ResolutionKind
+from shikiru.domain.reports import EscalationRequest
+
+_QUESTION = "Question"
+_AGENT_ALTERNATIVES = "Agent alternatives"
+_RESOLUTIONS = "Options"
+_TIMELINE = "Timeline"
+_WHAT_WAS_TRIED = "What was tried"
+_EVIDENCE = "Evidence"
+_REPORTS = "Reports"
+_FACTS = "Facts"
+_RECENT_SIGNALS = "Recent turn signals"
+_SESSIONS = "Sessions"
+_NONE_RECORDED = "(none recorded)"
+NO_AGENT_PROPOSAL = "No agent proposal was recorded. Engine recovery actions are listed separately."
+_TOP_LEVEL_PREFIX = "## "
+_SUBSECTION_PREFIX = "### "
+_OPTION_PREFIX = "- `"
+_OPTION_KIND_DELIMITER = "`"
+_RECOMMENDED_MARKER = " ★"
+_CONSEQUENCE_PREFIX = ": "
+_EMPTY_PACKET = "escalation packet is empty"
+_SECTION_MISSING = "escalation packet has no {heading!r} section"
+_SECTION_AMBIGUOUS = "escalation packet has ambiguous {heading!r} section boundaries"
+_SECTION_EMPTY = "escalation packet has an empty {heading!r} section"
+_ALTERNATIVES_INVALID = "escalation packet has malformed 'Agent alternatives' data"
+_OPTIONS_INVALID = "escalation packet has malformed 'Options' entry"
+_OPTIONS_EMPTY = "escalation packet has no options"
+
+
+@dataclass(frozen=True)
+class PacketResolution:
+    """One engine-allowed resolution and its recorded consequences."""
+
+    kind: ResolutionKind
+    consequences: str
+
+
+@dataclass(frozen=True)
+class EscalationPacket:
+    """Structured information recognized in the built-in escalation packet format."""
+
+    question: str | None
+    agent_request: EscalationRequest | None
+    resolutions: tuple[PacketResolution, ...]
+    evidence_sections: tuple[tuple[str, str], ...]
+    errors: tuple[str, ...]
+
+
+def parse_escalation_packet(packet: str) -> EscalationPacket:
+    """Read the decision and evidence sections used by the built-in packet renderer."""
+    if not packet:
+        return EscalationPacket(None, None, (), (), (_EMPTY_PACKET,))
+
+    errors: list[str] = []
+    question_end = (
+        _AGENT_ALTERNATIVES if _section_exists(packet, _AGENT_ALTERNATIVES) else _RESOLUTIONS
+    )
+    question = _section(packet, _QUESTION, question_end, errors)
+    if question is None:
+        errors.append(_SECTION_MISSING.format(heading=_QUESTION))
+    elif not question:
+        errors.append(_SECTION_EMPTY.format(heading=_QUESTION))
+        question = None
+
+    agent_request = _agent_request(packet, errors)
+    resolutions = _resolutions(packet, errors)
+    evidence_sections = tuple(
+        (label, content)
+        for heading, following, label, subsection, following_subsection in (
+            (_TIMELINE, _WHAT_WAS_TRIED, _TIMELINE, False, False),
+            (_WHAT_WAS_TRIED, _EVIDENCE, _WHAT_WAS_TRIED, False, False),
+            (_REPORTS, _FACTS, _REPORTS, True, True),
+            (_FACTS, _RECENT_SIGNALS, _FACTS, True, True),
+            (_RECENT_SIGNALS, _SESSIONS, _RECENT_SIGNALS, True, True),
+            (_SESSIONS, _QUESTION, _SESSIONS, True, False),
+        )
+        if (
+            content := _section(
+                packet,
+                heading,
+                following,
+                errors,
+                subsection=subsection,
+                following_subsection=following_subsection,
+            )
+        )
+        is not None
+    )
+    return EscalationPacket(
+        question,
+        agent_request,
+        resolutions,
+        evidence_sections,
+        tuple(errors),
+    )
+
+
+def _agent_request(packet: str, errors: list[str]) -> EscalationRequest | None:
+    if not _section_exists(packet, _AGENT_ALTERNATIVES):
+        return None
+    section = _section(packet, _AGENT_ALTERNATIVES, _RESOLUTIONS, errors)
+    if section in {_NONE_RECORDED, NO_AGENT_PROPOSAL}:
+        return None
+    if section is None:
+        return None
+    try:
+        return EscalationRequest.model_validate_json(section)
+    except ValidationError:
+        errors.append(_ALTERNATIVES_INVALID)
+        return None
+
+
+def _resolutions(packet: str, errors: list[str]) -> tuple[PacketResolution, ...]:
+    section = _section(packet, _RESOLUTIONS, None, errors)
+    if section is None:
+        return ()
+    resolutions: list[PacketResolution] = []
+    for line in section.splitlines():
+        if not line.startswith(_OPTION_PREFIX):
+            continue
+        entry = line.removeprefix(_OPTION_PREFIX)
+        kind_text, separator, details = entry.partition(_OPTION_KIND_DELIMITER)
+        if not separator:
+            errors.append(_OPTIONS_INVALID)
+            continue
+        details = details.removeprefix(_RECOMMENDED_MARKER)
+        if not details.startswith(_CONSEQUENCE_PREFIX):
+            errors.append(_OPTIONS_INVALID)
+            continue
+        try:
+            kind = ResolutionKind(kind_text)
+        except ValueError:
+            errors.append(_OPTIONS_INVALID)
+            continue
+        resolutions.append(PacketResolution(kind, details.removeprefix(_CONSEQUENCE_PREFIX)))
+    if not resolutions:
+        errors.append(_OPTIONS_EMPTY)
+    return tuple(resolutions)
+
+
+def _section_exists(packet: str, heading: str) -> bool:
+    return f"{_TOP_LEVEL_PREFIX}{heading}" in packet.splitlines()
+
+
+def _section(
+    packet: str,
+    heading: str,
+    following: str | None,
+    errors: list[str],
+    *,
+    subsection: bool = False,
+    following_subsection: bool | None = None,
+) -> str | None:
+    lines = packet.splitlines()
+    prefix = _SUBSECTION_PREFIX if subsection else _TOP_LEVEL_PREFIX
+    marker = f"{prefix}{heading}"
+    matches = [index for index, line in enumerate(lines) if line == marker]
+    if not matches:
+        errors.append(_SECTION_MISSING.format(heading=heading))
+        return None
+    if len(matches) != 1:
+        errors.append(_SECTION_AMBIGUOUS.format(heading=heading))
+        return None
+    start = matches[0] + 1
+    if following is None:
+        end = len(lines)
+    else:
+        end_prefix = _SUBSECTION_PREFIX if following_subsection is True else _TOP_LEVEL_PREFIX
+        if following_subsection is None:
+            end_prefix = prefix
+        following_marker = f"{end_prefix}{following}"
+        following_matches = [index for index, line in enumerate(lines) if line == following_marker]
+        if len(following_matches) != 1 or following_matches[0] < start:
+            errors.append(_SECTION_AMBIGUOUS.format(heading=heading))
+            return None
+        end = following_matches[0]
+    return "\n".join(lines[start:end]).strip()

shikiru/domain/escalation_panel.py

@@ -0,0 +1,144 @@
+"""The escalation resolution panel model: who, why, ordered choices and the preselection."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from enum import StrEnum, auto
+from typing import TYPE_CHECKING
+
+from shikiru.domain.attempts import AttemptItem, parse_attempt_lines
+from shikiru.domain.commands import ResolutionKind
+from shikiru.domain.escalation import (
+    ESCALATION_CAUSES,
+    RESOLUTION_CONSEQUENCES,
+    EscalationOption,
+    escalation_reason_label,
+)
+from shikiru.domain.tasks import DomainModel, EscalationReason
+
+if TYPE_CHECKING:
+    from shikiru.domain.escalation import Escalation
+    from shikiru.domain.escalation_evidence import EscalationPacket
+
+_WHAT_WAS_TRIED = "What was tried"
+_ENGINE_ORDER = (ResolutionKind.ACCEPT, ResolutionKind.RETRY, ResolutionKind.CANCEL)
+
+
+class ChoiceKind(StrEnum):
+    """What sending a choice does."""
+
+    ANSWER_OPTION = auto()
+    OWN_ANSWER = auto()
+    ACCEPT = auto()
+    RETRY = auto()
+    CANCEL = auto()
+
+
+_CHOICE_BY_RESOLUTION = {
+    ResolutionKind.ANSWER: ChoiceKind.OWN_ANSWER,
+    ResolutionKind.ACCEPT: ChoiceKind.ACCEPT,
+    ResolutionKind.RETRY: ChoiceKind.RETRY,
+    ResolutionKind.CANCEL: ChoiceKind.CANCEL,
+}
+
+
+class PanelChoice(DomainModel):
+    """One selectable row; `label` is set only for a Leader alternative."""
+
+    kind: ChoiceKind
+    consequence: str
+    recommended: bool = False
+    label: str | None = None
+    needs_input: bool = False
+
+
+class ResolutionPanel(DomainModel):
+    """Everything the panel shows for one escalation; age is derived from `created_at`."""
+
+    escalation_id: str
+    task_id: str
+    task_title: str
+    reason: EscalationReason
+    reason_label: str
+    cause: str | None
+    question: str | None
+    created_at: datetime
+    choices: tuple[PanelChoice, ...]
+    preselected: int
+    details: tuple[AttemptItem, ...]
+    disabled_reason: str | None
+
+
+def build_resolution_panel(
+    escalation: Escalation,
+    packet: EscalationPacket | None,
+    task_title: str,
+    disabled_reason: str | None,
+) -> ResolutionPanel:
+    """Build the panel for `escalation`; `packet` is `None` when it is missing or unreadable."""
+    answerable = any(option.label is ResolutionKind.ANSWER for option in escalation.options)
+    request = packet.agent_request if packet is not None and answerable else None
+    choices = (
+        *(
+            PanelChoice(
+                kind=ChoiceKind.ANSWER_OPTION,
+                consequence=option.consequences,
+                recommended=option.recommended,
+                label=option.label,
+                needs_input=option.needs_input,
+            )
+            for option in (request.options if request else ())
+        ),
+        *_engine_choices(escalation.options),
+    )
+    return ResolutionPanel(
+        escalation_id=escalation.id,
+        task_id=escalation.task_id,
+        task_title=task_title,
+        reason=escalation.reason,
+        reason_label=escalation_reason_label(escalation.reason),
+        cause=None
+        if escalation.reason is EscalationReason.DECISION_REQUIRED
+        else ESCALATION_CAUSES[escalation.reason],
+        question=_question(packet, request.question if request else None) if answerable else None,
+        created_at=escalation.created_at,
+        choices=choices,
+        preselected=_preselected(choices),
+        details=_details(packet),
+        disabled_reason=disabled_reason,
+    )
+
+
+def _engine_choices(options: tuple[EscalationOption, ...]) -> tuple[PanelChoice, ...]:
+    by_kind = {option.label: option for option in options}
+    ordered = (ResolutionKind.ANSWER, *_ENGINE_ORDER)
+    return tuple(
+        PanelChoice(
+            kind=_CHOICE_BY_RESOLUTION[kind],
+            consequence=RESOLUTION_CONSEQUENCES[kind],
+            recommended=by_kind[kind].recommended,
+        )
+        for kind in ordered
+        if kind in by_kind
+    )
+
+
+def _question(packet: EscalationPacket | None, request_question: str | None) -> str | None:
+    return request_question or (packet.question if packet is not None else None)
+
+
+def _preselected(choices: tuple[PanelChoice, ...]) -> int:
+    for wanted in (ChoiceKind.ANSWER_OPTION, None):
+        for index, choice in enumerate(choices):
+            if choice.recommended and (wanted is None or choice.kind is wanted):
+                return index
+    return 0
+
+
+def _details(packet: EscalationPacket | None) -> tuple[AttemptItem, ...]:
+    if packet is None:
+        return ()
+    for label, content in packet.evidence_sections:
+        if label == _WHAT_WAS_TRIED:
+            return parse_attempt_lines(content)
+    return ()

shikiru/domain/events.py

@@ -0,0 +1,71 @@
+"""`EventKind`, the closed set of event kinds written to `events`."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from enum import StrEnum, auto
+from typing import Any
+
+from pydantic import Field
+
+from shikiru.domain.tasks import DomainModel
+
+STOP_REASON_KEY = "reason"
+
+
+class EventKind(StrEnum):
+    """Every event kind the engine can emit."""
+
+    TASK_QUEUED = auto()
+    TASK_STARTED = auto()
+    DISPATCH_FAILED = auto()
+    STEP_STARTED = auto()
+    TURN_STARTED = auto()
+    TURN_COMPLETED = auto()
+    TURN_FAILED = auto()
+    TURN_STOPPED = auto()
+    NUDGE = auto()
+    HELPER_ACTION = auto()
+    RUNG_CHANGED = auto()
+    COMPACTED = auto()
+    QUOTA_BLOCKED = auto()
+    QUOTA_CLEARED = auto()
+    VERDICT = auto()
+    SCOPE_CHANGE = auto()
+    HOLD_SET = auto()
+    HOLD_CLEARED = auto()
+    TAKEN_OVER = auto()
+    HANDED_BACK = auto()
+    TAKEOVER_LOST = auto()
+    OPERATOR_MESSAGE = auto()
+    ESCALATION = auto()
+    ESCALATION_RESOLVED = auto()
+    INTEGRATION_STARTED = auto()
+    INTEGRATION_APPLYING = auto()
+    INTEGRATION_WAITING = auto()
+    PR_OPENED = auto()
+    PR_WITHDRAWN = auto()
+    FEEDBACK_STARTED = auto()
+    FEEDBACK_REBASE_STARTED = auto()
+    FEEDBACK_PREPARED = auto()
+    FEEDBACK_PUBLISHED = auto()
+    FEEDBACK_HANDLED = auto()
+    TASK_DONE = auto()
+    TASK_RETRIED = auto()
+    TASK_CANCELLED = auto()
+    PANE_RESTORED = auto()
+    ENGINE_STARTED = auto()
+    ENGINE_STOPPED = auto()
+    ENGINE_FAULT = auto()
+    ENGINE_RECOVERED = auto()
+
+
+class Event(DomainModel):
+    """One recorded event (mirrors the `events` table)."""
+
+    id: int
+    ts: datetime
+    task_id: str | None = None
+    kind: EventKind
+    message: str
+    data: dict[str, Any] = Field(default_factory=dict)

shikiru/domain/evidence_export.py

@@ -0,0 +1,89 @@
+"""Versioned Markdown and JSON rendering for a task evidence export."""
+
+from __future__ import annotations
+
+import json
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping
+
+EVIDENCE_EXPORT_FORMAT = "shikiru.task-evidence"
+EVIDENCE_EXPORT_VERSION = 1
+JSON_INDENT = 2
+MINIMUM_MARKDOWN_FENCE = 3
+MARKDOWN_NEWLINE = "\n"
+MARKDOWN_FENCE_CHARACTER = "`"
+
+
+def render_evidence_json(document: Mapping[str, object]) -> str:
+    """Render a JSON-safe task evidence document with stable, readable indentation."""
+    return f"{json.dumps(document, ensure_ascii=False, indent=JSON_INDENT, allow_nan=False)}\n"
+
+
+def render_evidence_markdown(document: Mapping[str, object]) -> str:
+    """Render an evidence document while keeping recorded text inside safe code fences."""
+    lines = [
+        "# Shikiru task evidence export",
+        "",
+        "## Export metadata",
+        _code_block(document.get("metadata")),
+        "",
+        "## Request",
+        _code_block(document.get("request")),
+        "",
+        "## Recorded outcome",
+        _code_block(document.get("outcome")),
+        "",
+        "## Task and rung metadata",
+        _code_block(document.get("task")),
+        "",
+        "## Relationships",
+        _code_block(document.get("relationships")),
+        "",
+        "## Validated reports and verdicts",
+        _code_block(document.get("reports")),
+        "",
+        "## Recorded git facts",
+        _code_block(document.get("facts")),
+        "",
+        "## Recorded timeline",
+        _code_block(document.get("timeline")),
+        "",
+        "## Recorded sessions",
+        _code_block(document.get("sessions")),
+        "",
+        "## Task usage summary",
+        _code_block(document.get("usage")),
+        "",
+        "## Unavailable sections",
+        _code_block(document.get("unavailable_sections")),
+        "",
+        (
+            "This export contains retained Shikiru evidence. It is not a complete agent transcript "
+            "and does not recreate a removed worktree."
+        ),
+        "",
+    ]
+    return MARKDOWN_NEWLINE.join(lines)
+
+
+def _code_block(value: object) -> str:
+    content = json.dumps(value, ensure_ascii=False, indent=JSON_INDENT, allow_nan=False)
+    fence = MARKDOWN_FENCE_CHARACTER * max(
+        MINIMUM_MARKDOWN_FENCE,
+        _longest_backtick_run(content) + 1,
+    )
+    return f"{fence}json\n{content}\n{fence}"
+
+
+def _longest_backtick_run(value: str) -> int:
+    longest = 0
+    current = 0
+    for character in value:
+        if character == MARKDOWN_FENCE_CHARACTER:
+            current += 1
+            longest = max(longest, current)
+        else:
+            current = 0
+    return longest

shikiru/domain/faults.py

@@ -0,0 +1,86 @@
+"""Open engine fault streaks derived from `engine_fault` and `engine_recovered` events."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import TYPE_CHECKING
+
+from shikiru.domain.events import Event, EventKind
+from shikiru.domain.tasks import DomainModel
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable
+
+SCOPE_KEY = "scope"
+ERROR_KEY = "error"
+RECOVERABLE_KEY = "recoverable"
+REPEAT_KEY = "repeat"
+DETAIL_KEY = "detail"
+COMMAND_KEY = "command"
+EXIT_CODE_KEY = "exit_code"
+STDERR_KEY = "stderr"
+TRACEBACK_KEY = "traceback"
+_BACKOFF_FACTOR = 2
+
+
+class FaultStreak(DomainModel):
+    """A fault that is still failing: when it began, was last recorded and how often it failed."""
+
+    scope: str
+    task_id: str | None
+    error: str
+    recoverable: bool
+    first_seen: datetime
+    last_seen: datetime
+    repeat: int
+    event_id: int
+    message: str
+    detail: str | None = None
+    command: tuple[str, ...] | None = None
+    exit_code: int | None = None
+    stderr: str | None = None
+    traceback: str | None = None
+
+
+def open_fault_streaks(events: Iterable[Event]) -> list[FaultStreak]:
+    """Fold chronological fault and recovery `events` into the streaks that were never recovered.
+
+    A fault without a `scope` is a one-off record, not a streak, and is ignored. A streak keeps
+    the evidence of its latest record; evidence that record did not carry stays `None`.
+    """
+    open_streaks: dict[tuple[str, str | None], FaultStreak] = {}
+    for event in events:
+        scope = event.data.get(SCOPE_KEY)
+        if scope is None:
+            continue
+        key = (scope, event.task_id)
+        if event.kind is EventKind.ENGINE_RECOVERED:
+            open_streaks.pop(key, None)
+        elif event.kind is EventKind.ENGINE_FAULT:
+            previous = open_streaks.get(key)
+            open_streaks[key] = FaultStreak(
+                scope=scope,
+                task_id=event.task_id,
+                error=event.data[ERROR_KEY],
+                recoverable=event.data[RECOVERABLE_KEY],
+                first_seen=previous.first_seen if previous else event.ts,
+                last_seen=event.ts,
+                repeat=(previous.repeat if previous else 0) + event.data[REPEAT_KEY],
+                event_id=event.id,
+                message=event.message,
+                detail=event.data.get(DETAIL_KEY),
+                command=_command(event.data.get(COMMAND_KEY)),
+                exit_code=event.data.get(EXIT_CODE_KEY),
+                stderr=event.data.get(STDERR_KEY),
+                traceback=event.data.get(TRACEBACK_KEY),
+            )
+    return list(open_streaks.values())
+
+
+def _command(recorded: list[str] | None) -> tuple[str, ...] | None:
+    return None if recorded is None else tuple(recorded)
+
+
+def next_backoff(previous: float, *, initial: float, maximum: float) -> float:
+    """Return the retry delay after `previous` (0 before the first failure): doubled, capped."""
+    return initial if previous <= 0 else min(previous * _BACKOFF_FACTOR, maximum)