shikiru-cli 0.2.0__py3-none-any.whl

shikiru/domain/steps.py

@@ -0,0 +1,325 @@
+"""Step transitions for the task workflow."""
+
+from __future__ import annotations
+
+import dataclasses
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+from shikiru.domain.ladder import (
+    REJECTIONS_FIELD,
+    move_up,
+    pick_rung,
+    reset_for_integration_attempt,
+    reset_for_new_iteration,
+)
+from shikiru.domain.reports import (
+    DECISION_ESCALATE,
+    STATUS_COMPLETED,
+    ConsultAnswer,
+    FeedbackAnalysis,
+    ImplementationReport,
+    PlanReport,
+    TriageReport,
+    Verdict,
+)
+from shikiru.domain.tasks import (
+    DEFAULT_COMPLEXITY,
+    Counters,
+    EscalationReason,
+    Mode,
+    Role,
+    Status,
+    StatusReason,
+    Step,
+    Task,
+)
+
+if TYPE_CHECKING:
+    from shikiru.agents.contracts import Rung
+    from shikiru.config.settings import ComplexityName, Settings
+
+CONSULT_LIMIT = 3
+CONFLICT_ROUNDS = 2
+
+Outcome = (
+    TriageReport | PlanReport | ImplementationReport | ConsultAnswer | Verdict | FeedbackAnalysis
+)
+
+ACTING_ROLE: dict[Step, Role] = {
+    Step.TRIAGE: Role.LEADER,
+    Step.PLAN: Role.LEADER,
+    Step.IMPLEMENT: Role.IMPLEMENTER,
+    Step.CONSULT: Role.LEADER,
+    Step.VERIFY: Role.LEADER,
+    Step.INTEGRATE: Role.IMPLEMENTER,
+}
+"""Which role acts at each step: the Implementer only acts in `integrate` on conflicts."""
+
+
+@dataclass(frozen=True)
+class Transition:
+    """The task's new step/status/iteration/counters/rungs, plus side effects as data.
+
+    `base` is the task snapshot the decision was computed from; `rebased_onto` reconciles the
+    decision with the row as it is when the decision is written.
+    """
+
+    base: Task
+    step: Step | None
+    status: Status
+    iteration: int
+    counters: Counters
+    rung_index: dict[Role, int]
+    set_overrides: dict[Role, Rung] = field(default_factory=dict)
+    cleared_overrides: dict[Role, Rung] = field(default_factory=dict)
+    complexity: ComplexityName | None = None
+    mode: Mode | None = None
+    title: str | None = None
+    status_reason: StatusReason | None = None
+    escalation_reason: EscalationReason | None = None
+    repoint_dependents: bool = False
+    enqueue_new_tasks: bool = False
+
+    def rebased_onto(self, current: Task) -> Transition:
+        """Keep what changed since `base` and apply only what this decision itself changed.
+
+        A role whose override differs between `base` and `current` was repinned by the operator
+        while the turn ran: its rung index and, for the Implementer, `rejections_on_rung` stay as
+        stored, so neither the turn's rejection nor an automatic move undoes the pin. Every other
+        iteration, counter and rung index takes the decision's value only where the decision
+        changed it relative to `base`.
+        """
+        repinned = {
+            role for role in Role if current.overrides.get(role) != self.base.overrides.get(role)
+        }
+        changed = {
+            name: value
+            for name, value in self.counters
+            if value != getattr(self.base.counters, name)
+            and not (name == REJECTIONS_FIELD and Role.IMPLEMENTER in repinned)
+        }
+        rung_index = dict(current.rung_index)
+        rung_index.update(
+            {
+                role: index
+                for role, index in self.rung_index.items()
+                if role not in repinned and index != self.base.rung_index.get(role)
+            }
+        )
+        return dataclasses.replace(
+            self,
+            iteration=self.iteration
+            if self.iteration != self.base.iteration
+            else current.iteration,
+            counters=current.counters.model_copy(update=changed),
+            rung_index=rung_index,
+        )
+
+    @staticmethod
+    def stay(task: Task, *, step: Step | None, status: Status = Status.RUNNING) -> Transition:
+        """Build a transition that keeps every field of `task` except `step` and `status`."""
+        return Transition(
+            base=task,
+            step=step,
+            status=status,
+            iteration=task.iteration,
+            counters=task.counters,
+            rung_index=dict(task.rung_index),
+        )
+
+    @staticmethod
+    def escalate(task: Task, reason: EscalationReason, *, step: Step) -> Transition:
+        """Build an escalation transition while preserving the task's other state."""
+        base = Transition.stay(task, step=step, status=Status.ESCALATED)
+        return dataclasses.replace(base, escalation_reason=reason)
+
+    @staticmethod
+    def escalate_current(task: Task, reason: EscalationReason) -> Transition:
+        """Escalate at the current step, preserving a missing step for an unstarted task."""
+        if task.step is None:
+            base = Transition.stay(task, step=None, status=Status.ESCALATED)
+            return dataclasses.replace(base, escalation_reason=reason)
+        return Transition.escalate(task, reason, step=task.step)
+
+
+def first_step(task: Task) -> Transition:
+    """Compute the transition for a task's very first turn (submit flags).
+
+    A task with no `mode` starts at `triage`. `submit --mode implement|plan` skips triage
+    straight into that step; `implement` also starts numbering from iteration 1, matching the
+    turn dirs (`NN-<step>-i<iteration>`) and the `implement` iteration-1 convention.
+    """
+    if task.mode is None:
+        return Transition.stay(task, step=Step.TRIAGE)
+    if task.mode is Mode.PLAN:
+        return Transition.stay(task, step=Step.PLAN)
+    return dataclasses.replace(Transition.stay(task, step=Step.IMPLEMENT), iteration=1)
+
+
+def task_acting_role(task: Task) -> Role:
+    """Return the role for the current step or the task's first scheduled step."""
+    step = task.step if task.step is not None else first_step(task).step
+    return Role.LEADER if step is None else ACTING_ROLE[step]
+
+
+def _triaged_complexity(task: Task, outcome: TriageReport) -> ComplexityName | None:
+    return outcome.complexity if task.complexity is None else None
+
+
+def _from_triage(task: Task, outcome: TriageReport, settings: Settings) -> Transition:
+    if outcome.mode is Mode.IMPLEMENT:
+        base = dataclasses.replace(Transition.stay(task, step=Step.IMPLEMENT), iteration=1)
+    else:
+        base = Transition.stay(task, step=Step.PLAN)
+    complexity = _triaged_complexity(task, outcome)
+    implementer = settings.roles.implementer
+    if complexity is not None and implementer.ladder_for(complexity) != implementer.ladder_for(
+        task.complexity or DEFAULT_COMPLEXITY
+    ):
+        index = 0
+        if task.rung_index.get(Role.IMPLEMENTER, 0) > 0:
+            agent = pick_rung(task, Role.IMPLEMENTER, settings).agent
+            index = next(
+                (
+                    index
+                    for index, rung in enumerate(implementer.ladder_for(complexity))
+                    if rung.agent == agent
+                ),
+                0,
+            )
+        base = dataclasses.replace(base, rung_index={**base.rung_index, Role.IMPLEMENTER: index})
+    return dataclasses.replace(
+        base,
+        complexity=complexity,
+        mode=outcome.mode,
+        title=outcome.title,
+    )
+
+
+def _from_plan(task: Task) -> Transition:
+    base = Transition.stay(task, step=Step.INTEGRATE, status=Status.INTEGRATING)
+    return dataclasses.replace(
+        base, counters=reset_for_integration_attempt(task.counters), enqueue_new_tasks=True
+    )
+
+
+def _from_implement(task: Task, outcome: ImplementationReport) -> Transition:
+    if outcome.status == STATUS_COMPLETED:
+        return Transition.stay(task, step=Step.VERIFY)
+    return _consult_or_escalate(task, Status.RUNNING)
+
+
+def _consult_or_escalate(task: Task, status: Status) -> Transition:
+    if task.counters.consults >= CONSULT_LIMIT:
+        return Transition.escalate(task, EscalationReason.DECISION_REQUIRED, step=Step.CONSULT)
+    counters = task.counters.model_copy(update={"consults": task.counters.consults + 1})
+    base = Transition.stay(task, step=Step.CONSULT, status=status)
+    return dataclasses.replace(base, counters=counters)
+
+
+def _from_consult(task: Task, outcome: ConsultAnswer) -> Transition:
+    if outcome.decision == DECISION_ESCALATE:
+        return Transition.escalate(task, EscalationReason.DECISION_REQUIRED, step=Step.CONSULT)
+    if task.status is Status.INTEGRATING:
+        return Transition.stay(task, step=Step.INTEGRATE, status=Status.INTEGRATING)
+    return Transition.stay(task, step=Step.IMPLEMENT)
+
+
+def _changes_requested(task: Task, settings: Settings) -> Transition:
+    if task.iteration >= settings.orchestration.max_iterations:
+        return Transition.escalate(task, EscalationReason.ITERATIONS_EXHAUSTED, step=Step.VERIFY)
+    rejections = task.counters.rejections_on_rung + 1
+    rung_index = dict(task.rung_index)
+    cleared_overrides: dict[Role, Rung] = {}
+    counters = task.counters.model_copy(update={"rejections_on_rung": rejections})
+    if rejections >= settings.roles.implementer.escalate_after:
+        move = move_up(task, Role.IMPLEMENTER, settings)
+        if move is not None:
+            rung_index = move.rung_index
+            cleared_overrides = move.cleared_overrides
+            counters = move.counters
+    counters = reset_for_new_iteration(counters)
+    return Transition(
+        base=task,
+        step=Step.IMPLEMENT,
+        status=Status.RUNNING,
+        iteration=task.iteration + 1,
+        counters=counters,
+        rung_index=rung_index,
+        cleared_overrides=cleared_overrides,
+    )
+
+
+def _conflict_round(task: Task) -> Transition:
+    rounds = task.counters.conflict_rounds + 1
+    counters = task.counters.model_copy(update={"conflict_rounds": rounds})
+    base = dataclasses.replace(Transition.stay(task, step=Step.INTEGRATE), counters=counters)
+    if rounds >= CONFLICT_ROUNDS:
+        return dataclasses.replace(
+            Transition.escalate(task, EscalationReason.INTEGRATION_CONFLICT, step=Step.INTEGRATE),
+            counters=counters,
+        )
+    return dataclasses.replace(base, status=Status.INTEGRATING)
+
+
+def _from_verify(task: Task, outcome: Verdict, settings: Settings) -> Transition:
+    match outcome.decision:
+        case "accept":
+            base = Transition.stay(task, step=Step.INTEGRATE, status=Status.INTEGRATING)
+            return dataclasses.replace(base, counters=reset_for_integration_attempt(task.counters))
+        case "changes_requested":
+            return _changes_requested(task, settings)
+        case "escalate":
+            return Transition.escalate(task, EscalationReason.DECISION_REQUIRED, step=Step.VERIFY)
+        case "supersede":
+            base = Transition.stay(task, step=None, status=Status.CANCELLED)
+            return dataclasses.replace(
+                base,
+                status_reason=StatusReason.SUPERSEDED,
+                repoint_dependents=True,
+                enqueue_new_tasks=True,
+            )
+
+
+def _from_integrate(task: Task, outcome: Verdict) -> Transition:
+    match outcome.decision:
+        case "accept":
+            return Transition.stay(task, step=Step.INTEGRATE, status=Status.INTEGRATING)
+        case "changes_requested":
+            return _conflict_round(task)
+        case "escalate":
+            return Transition.escalate(
+                task, EscalationReason.DECISION_REQUIRED, step=Step.INTEGRATE
+            )
+        case "supersede":
+            message = "a post-rebase conflicts verify cannot supersede the task"
+            raise ValueError(message)
+
+
+def _from_integrate_conflicts(task: Task, outcome: ImplementationReport) -> Transition:
+    if outcome.status == STATUS_COMPLETED:
+        return Transition.stay(task, step=Step.INTEGRATE, status=Status.INTEGRATING)
+    return _consult_or_escalate(task, Status.INTEGRATING)
+
+
+def next_step(task: Task, outcome: Outcome, settings: Settings) -> Transition:
+    """Apply `outcome` to `task`'s current step and return the resulting transition."""
+    match task.step, outcome:
+        case Step.TRIAGE, TriageReport():
+            return _from_triage(task, outcome, settings)
+        case Step.PLAN, PlanReport():
+            return _from_plan(task)
+        case Step.IMPLEMENT, ImplementationReport():
+            return _from_implement(task, outcome)
+        case Step.CONSULT, ConsultAnswer():
+            return _from_consult(task, outcome)
+        case Step.VERIFY, Verdict():
+            return _from_verify(task, outcome, settings)
+        case Step.INTEGRATE, Verdict():
+            return _from_integrate(task, outcome)
+        case Step.INTEGRATE, ImplementationReport():
+            return _from_integrate_conflicts(task, outcome)
+        case _:
+            message = f"no transition for step {task.step!r} with outcome {outcome!r}"
+            raise ValueError(message)

shikiru/domain/tasks.py

@@ -0,0 +1,174 @@
+"""Core task model and its enums."""
+
+from __future__ import annotations
+
+from datetime import datetime
+from enum import StrEnum, auto
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from shikiru.agents.contracts import Rung
+from shikiru.config.settings import ComplexityName
+
+TASK_TITLE_MAX_LENGTH = 60
+TASK_TITLE_ELLIPSIS = "…"
+
+
+class TaskOrigin(StrEnum):
+    """Where a task came from."""
+
+    OPERATOR = auto()
+    LEADER = auto()
+
+
+class Status(StrEnum):
+    """A task's lifecycle status."""
+
+    QUEUED = auto()
+    RUNNING = auto()
+    INTEGRATING = auto()
+    ESCALATED = auto()
+    DONE = auto()
+    CANCELLED = auto()
+
+
+ACTIVE_STATUSES = (Status.RUNNING, Status.INTEGRATING, Status.ESCALATED)
+"""The statuses that remain active in a task window."""
+
+
+class StatusReason(StrEnum):
+    """Why a terminal `status` was reached outside the ordinary happy path."""
+
+    SUPERSEDED = auto()
+
+
+class Step(StrEnum):
+    """The current step of a running task."""
+
+    TRIAGE = auto()
+    PLAN = auto()
+    IMPLEMENT = auto()
+    CONSULT = auto()
+    VERIFY = auto()
+    INTEGRATE = auto()
+
+
+class Mode(StrEnum):
+    """What triage decided the request needs."""
+
+    IMPLEMENT = auto()
+    PLAN = auto()
+
+
+class Hold(StrEnum):
+    """A task-scoped hold."""
+
+    PAUSED = auto()
+    INTERVENTION = auto()
+
+
+class Role(StrEnum):
+    """The three agent roles."""
+
+    LEADER = auto()
+    IMPLEMENTER = auto()
+    HELPER = auto()
+
+
+class EscalationReason(StrEnum):
+    """Why a task was escalated."""
+
+    DECISION_REQUIRED = auto()
+    ITERATIONS_EXHAUSTED = auto()
+    INTEGRATION_CONFLICT = auto()
+    INTEGRATION_BLOCKED = auto()
+    UNCOMMITTED_WORK = auto()
+    OFF_TASK_BRANCH = auto()
+    PR_CLOSED = auto()
+    AGENT_AUTH = auto()
+    AGENT_ERROR = auto()
+    AGENT_STUCK = auto()
+    AGENT_PROTOCOL = auto()
+    LADDER_EXHAUSTED = auto()
+    QUOTA_EXHAUSTED = auto()
+    DEPENDENCY_CANCELLED = auto()
+    ENGINE_ERROR = auto()
+
+
+class DomainModel(BaseModel):
+    """Base for domain models: unknown keys are rejected, fields can't be reassigned.
+
+    `frozen=True` only blocks assigning a new value to a field; a mutable field's own `list` or
+    `dict` can still be mutated in place, which is why callers that need to change one (e.g.
+    `Transition.stay`) copy it first rather than relying on the model to be deeply immutable.
+    """
+
+    model_config = ConfigDict(extra="forbid", frozen=True)
+
+
+class Counters(DomainModel):
+    """Persisted per-task counters and their reset rules."""
+
+    rejections_on_rung: int = 0
+    consults: int = 0
+    conflict_rounds: int = 0
+
+
+class RepoState(DomainModel):
+    """The task's checkout state (mirrors `tasks.repo`)."""
+
+    base: str
+    base_ref: str
+    base_sha: str
+    branch: str
+
+
+DEFAULT_COMPLEXITY: ComplexityName = "normal"
+
+
+class Task(DomainModel):
+    """The task fields the domain rules need (mirrors the `tasks` table)."""
+
+    id: str
+    seq: int
+    parent_id: str | None = None
+    origin: TaskOrigin
+    title: str
+    request: str
+    mode: Mode | None = None
+    complexity: ComplexityName | None = None
+    priority: int = 0
+    depends_on: list[str] = Field(default_factory=list)
+    status: Status
+    step: Step | None = None
+    status_reason: StatusReason | None = None
+    holds: frozenset[Hold] = Field(default_factory=frozenset)
+    iteration: int = 0
+    counters: Counters = Field(default_factory=Counters)
+    rung_index: dict[Role, int] = Field(default_factory=dict)
+    overrides: dict[Role, Rung] = Field(default_factory=dict)
+    repo: RepoState | None = None
+    slot: int | None = None
+    window_id: str | None = None
+    panes: dict[Role, str] = Field(default_factory=dict)
+    wait_reason: str | None = None
+    requeued_at: datetime | None = None
+    summary: str | None = None
+    created_at: datetime
+    started_at: datetime | None = None
+    finished_at: datetime | None = None
+
+    @property
+    def held(self) -> bool:
+        """Whether a task-scoped hold forbids starting the task's next external effect."""
+        return bool(self.holds)
+
+
+def title_from_request(request: str) -> str:
+    """Derive a title from the request's first line, cut at a word boundary within the limit."""
+    lines = request.splitlines()
+    first_line = lines[0] if lines else request
+    if len(first_line) <= TASK_TITLE_MAX_LENGTH:
+        return first_line
+    kept = first_line[: TASK_TITLE_MAX_LENGTH - len(TASK_TITLE_ELLIPSIS)]
+    return kept.rsplit(" ", 1)[0] + TASK_TITLE_ELLIPSIS

shikiru/domain/timeline.py

@@ -0,0 +1,208 @@
+"""Pure parsing and classification for the engine's normalized task evidence."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from typing import cast
+
+from shikiru.domain.timeline_phrases import GLYPH_ATTENTION, Phrase, Tone, signal_phrase
+
+TIMELINE_ACTIVITY_CATEGORY = "activity"
+TIMELINE_ALL_CATEGORY = "all"
+TIMELINE_ENGINE_CATEGORY = "engine"
+TIMELINE_SIGNAL_CATEGORY = "signal"
+TIMELINE_AGENT_CATEGORY = "agent"
+TIMELINE_DECISION_CATEGORY = "decision"
+TIMELINE_TRANSITION_CATEGORY = "transition"
+TIMELINE_TOOL_CATEGORY = "tool"
+TIMELINE_MESSAGE_CATEGORY = "message"
+TIMELINE_USAGE_CATEGORY = "usage"
+TIMELINE_EVIDENCE_CATEGORY = "evidence"
+TIMELINE_DEFAULT_CATEGORY = TIMELINE_ACTIVITY_CATEGORY
+TIMELINE_CATEGORIES = frozenset(
+    {
+        TIMELINE_ACTIVITY_CATEGORY,
+        TIMELINE_ALL_CATEGORY,
+        TIMELINE_ENGINE_CATEGORY,
+        TIMELINE_SIGNAL_CATEGORY,
+        TIMELINE_AGENT_CATEGORY,
+        TIMELINE_DECISION_CATEGORY,
+        TIMELINE_TRANSITION_CATEGORY,
+        TIMELINE_TOOL_CATEGORY,
+        TIMELINE_MESSAGE_CATEGORY,
+        TIMELINE_USAGE_CATEGORY,
+        TIMELINE_EVIDENCE_CATEGORY,
+    }
+)
+SIGNAL_TOOL_NAMES = frozenset({"ToolStarted", "ToolFinished"})
+SIGNAL_MESSAGE_NAMES = frozenset({"Message"})
+SIGNAL_USAGE_NAMES = frozenset({"UsageReported", "QuotaReported"})
+SIGNAL_LIFECYCLE_NAMES = frozenset({"SessionStarted", "TurnEnded", "TurnFailed", "Compacted"})
+TIMELINE_DECISION_KINDS = frozenset(
+    {
+        "verdict",
+        "scope_change",
+        "escalation",
+        "escalation_resolved",
+        "task_done",
+        "task_cancelled",
+        "pr_opened",
+        "pr_withdrawn",
+    }
+)
+TIMELINE_SOURCE_ENGINE = "engine"
+TIMELINE_SOURCE_AGENT = "agent"
+INCOMPLETE_SIGNAL_SUMMARY = "Incomplete live JSONL row"
+MALFORMED_SIGNAL_SUMMARY = "Malformed normalized signal evidence"
+MISSING_SIGNAL_SUMMARY = "Normalized signal evidence is unavailable"
+MISSING_TIMESTAMP = "recorded timestamp is missing"
+TIMELINE_JSON_INDENT = 2
+_TOOL_FINISHED_SIGNAL = "ToolFinished"
+_OUTCOME_FIELD = "outcome"
+_EXIT_CODE_FIELD = "exit_code"
+_SUCCESS_OUTCOME = "success"
+_FAILURE_OUTCOME = "failure"
+_SUMMARY_SEPARATOR = " · "
+
+
+@dataclass(frozen=True)
+class ParsedSignal:
+    """One parsed normalized signal row and its recorded evidence identity."""
+
+    role: str
+    turn: str | None
+    signal: str | None
+    category: str
+    timestamp: datetime | None
+    timestamp_error: str | None
+    summary: str
+    phrase: Phrase
+    listed: bool
+    detail: str
+    start_offset: int
+    end_offset: int
+    incomplete: bool
+
+
+def parse_signal_row(
+    raw: bytes,
+    *,
+    role: str,
+    start_offset: int,
+    end_offset: int,
+    incomplete: bool,
+) -> ParsedSignal:
+    """Parse one normalized `view.jsonl` row without interpreting provider formats."""
+    text = raw.decode("utf-8", errors="replace")
+    try:
+        raw_data: object = json.loads(text)
+    except json.JSONDecodeError:
+        summary = INCOMPLETE_SIGNAL_SUMMARY if incomplete else MALFORMED_SIGNAL_SUMMARY
+        return ParsedSignal(
+            role=role,
+            turn=None,
+            signal=None,
+            category=TIMELINE_EVIDENCE_CATEGORY,
+            timestamp=None,
+            timestamp_error=MISSING_TIMESTAMP,
+            summary=summary,
+            phrase=_problem_phrase(summary),
+            listed=True,
+            detail=text,
+            start_offset=start_offset,
+            end_offset=end_offset,
+            incomplete=incomplete,
+        )
+    if not isinstance(raw_data, dict):
+        return ParsedSignal(
+            role=role,
+            turn=None,
+            signal=None,
+            category=TIMELINE_EVIDENCE_CATEGORY,
+            timestamp=None,
+            timestamp_error=MISSING_TIMESTAMP,
+            summary=MALFORMED_SIGNAL_SUMMARY,
+            phrase=_problem_phrase(MALFORMED_SIGNAL_SUMMARY),
+            listed=True,
+            detail=text,
+            start_offset=start_offset,
+            end_offset=end_offset,
+            incomplete=incomplete,
+        )
+    data = cast("dict[str, object]", raw_data)
+    turn = data.get("turn")
+    signal = data.get("signal")
+    timestamp, timestamp_error = _timestamp(data.get("ts"))
+    signal_name = signal if isinstance(signal, str) else None
+    summary = signal_name or MISSING_SIGNAL_SUMMARY
+    if signal_name == _TOOL_FINISHED_SIGNAL:
+        summary = _tool_finished_summary(data)
+    phrase = signal_phrase(signal_name, data) if signal_name else _problem_phrase(summary)
+    return ParsedSignal(
+        role=role,
+        turn=turn if isinstance(turn, str) else None,
+        signal=signal_name,
+        category=signal_category(signal_name),
+        timestamp=timestamp,
+        timestamp_error=timestamp_error,
+        summary=summary,
+        phrase=phrase or Phrase(summary),
+        listed=phrase is not None,
+        detail=json.dumps(data, ensure_ascii=False, sort_keys=True, indent=TIMELINE_JSON_INDENT),
+        start_offset=start_offset,
+        end_offset=end_offset,
+        incomplete=incomplete,
+    )
+
+
+def _problem_phrase(summary: str) -> Phrase:
+    return Phrase(summary, GLYPH_ATTENTION, Tone.WARNING)
+
+
+def _tool_finished_summary(data: dict[str, object]) -> str:
+    values = [_TOOL_FINISHED_SIGNAL]
+    outcome = data.get(_OUTCOME_FIELD)
+    if isinstance(outcome, str) and outcome in (_SUCCESS_OUTCOME, _FAILURE_OUTCOME):
+        values.append(outcome)
+    exit_code = data.get(_EXIT_CODE_FIELD)
+    if type(exit_code) is int:
+        values.append(f"exit {exit_code}")
+    return _SUMMARY_SEPARATOR.join(values)
+
+
+def signal_category(signal: str | None) -> str:
+    """Classify a normalized signal name for evidence filtering."""
+    if signal is None:
+        return TIMELINE_EVIDENCE_CATEGORY
+    if signal in SIGNAL_TOOL_NAMES:
+        return TIMELINE_TOOL_CATEGORY
+    if signal in SIGNAL_MESSAGE_NAMES:
+        return TIMELINE_MESSAGE_CATEGORY
+    if signal in SIGNAL_USAGE_NAMES:
+        return TIMELINE_USAGE_CATEGORY
+    if signal in SIGNAL_LIFECYCLE_NAMES:
+        return TIMELINE_TRANSITION_CATEGORY
+    return TIMELINE_SIGNAL_CATEGORY
+
+
+def event_category(kind: str) -> str:
+    """Return the operator-facing category for one persisted engine event."""
+    return (
+        TIMELINE_DECISION_CATEGORY
+        if kind in TIMELINE_DECISION_KINDS
+        else TIMELINE_TRANSITION_CATEGORY
+    )
+
+
+def _timestamp(value: object) -> tuple[datetime | None, str | None]:
+    if not isinstance(value, str):
+        return None, MISSING_TIMESTAMP
+    try:
+        parsed = datetime.fromisoformat(value)
+    except ValueError:
+        return None, "recorded timestamp is invalid"
+    if parsed.tzinfo is None:
+        return None, "recorded timestamp has no UTC offset"
+    return parsed.astimezone(UTC), None