shikiru-cli 0.2.0__py3-none-any.whl

shikiru/engine/handlers/escalations.py

@@ -0,0 +1,174 @@
+"""Handlers for escalation resolution options."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from shikiru.domain.commands import (
+    COMMAND_ID_KEY,
+    EVENT_TEXT_KEY,
+    AcceptResolution,
+    AnswerResolution,
+    CancelResolution,
+    ResolutionKind,
+    Resolve,
+    RetryResolution,
+)
+from shikiru.domain.escalation import EscalationStatus, transition_for_resolution
+from shikiru.domain.events import EventKind
+from shikiru.domain.steps import ACTING_ROLE, Transition
+from shikiru.domain.tasks import EscalationReason, Status
+from shikiru.engine.handlers.base import (
+    HandlerContext,
+    command_replayed,
+    finish_task_quietly,
+    interrupt_task,
+    kept_worktree_result,
+    refresh_titles,
+    require_command_id,
+    require_task,
+)
+from shikiru.errors import CommandRejectedError
+
+if TYPE_CHECKING:
+    from shikiru.domain.escalation import Escalation
+    from shikiru.domain.tasks import Task
+
+
+class ResolveHandler:
+    """Apply `answer`, `retry`, `accept` or `cancel` to an open escalation."""
+
+    command_type: type[Resolve] = Resolve
+
+    def __init__(self, context: HandlerContext) -> None:
+        self._context = context
+
+    async def handle(self, command: Resolve) -> dict[str, object]:
+        if command_replayed(self._context, EventKind.ESCALATION_RESOLVED, command):
+            escalation = self._escalation(command.escalation_id)
+        else:
+            escalation = self._open_escalation(command)
+            await self._apply(command, escalation)
+        task = require_task(self._context, escalation.task_id)
+        await refresh_titles(self._context, task.id)
+        kept = (
+            await finish_task_quietly(self._context, task)
+            if isinstance(command.resolution, CancelResolution)
+            else None
+        )
+        return {
+            "escalation_id": escalation.id,
+            "task_id": task.id,
+            "status": task.status.value,
+            **kept_worktree_result(kept),
+        }
+
+    async def _apply(self, command: Resolve, escalation: Escalation) -> None:
+        task = require_task(self._context, escalation.task_id)
+        if task.status is not Status.ESCALATED:
+            message = (
+                f"{escalation.id} no longer applies: {task.id} is {task.status.value}, "
+                "not escalated"
+            )
+            raise CommandRejectedError(message)
+        transition = self._transition(task, escalation, command)
+        if not isinstance(command.resolution, AnswerResolution):
+            await interrupt_task(self._context, task, even_if_inactive=True)
+        with self._context.atomically():
+            self._apply_transition(task, escalation, command, transition)
+            self._context.escalations.resolve(escalation.id, self._resolution_text(command))
+            self._context.events.append(
+                EventKind.ESCALATION_RESOLVED,
+                task_id=task.id,
+                message=f"{escalation.id} resolved with {command.resolution.kind.value}",
+                data={
+                    "escalation_id": escalation.id,
+                    "resolution": command.resolution.kind.value,
+                    **self._answer_text(command),
+                    COMMAND_ID_KEY: require_command_id(command),
+                },
+            )
+
+    def _escalation(self, escalation_id: str) -> Escalation:
+        escalation = self._context.escalations.get(escalation_id)
+        if escalation is None:
+            message = f"escalation {escalation_id} does not exist"
+            raise CommandRejectedError(message)
+        return escalation
+
+    def _open_escalation(self, command: Resolve) -> Escalation:
+        escalation = self._escalation(command.escalation_id)
+        if escalation.status is not EscalationStatus.OPEN:
+            message = f"escalation {command.escalation_id} is already resolved"
+            raise CommandRejectedError(message)
+        if command.resolution.kind not in {option.label for option in escalation.options}:
+            message = (
+                f"resolution {command.resolution.kind.value} is not valid for "
+                f"{escalation.reason.value}"
+            )
+            raise CommandRejectedError(message)
+        return escalation
+
+    def _transition(self, task: Task, escalation: Escalation, command: Resolve) -> Transition:
+        acting_role = ACTING_ROLE.get(escalation.step) if escalation.step is not None else None
+        rung = command.resolution.rung if isinstance(command.resolution, RetryResolution) else None
+        try:
+            return transition_for_resolution(
+                task,
+                escalation.reason,
+                step=escalation.step,
+                resolution=command.resolution.kind,
+                rung=rung,
+                role=acting_role,
+            )
+        except ValueError as error:
+            raise CommandRejectedError(str(error)) from error
+
+    def _apply_transition(
+        self,
+        task: Task,
+        escalation: Escalation,
+        command: Resolve,
+        transition: Transition,
+    ) -> None:
+        if (
+            isinstance(command.resolution, RetryResolution)
+            and escalation.reason is EscalationReason.DEPENDENCY_CANCELLED
+        ):
+            self._drop_cancelled_dependencies(task.id, task.depends_on)
+        if transition.status is Status.CANCELLED:
+            self._context.tasks.finish(
+                task.id,
+                transition,
+                EventKind.TASK_CANCELLED,
+                message=f"{task.id} cancelled",
+                data={"reason": "cancelled by operator"},
+            )
+            return
+        self._context.tasks.apply_transition(task.id, transition)
+        self._context.tasks.set_requeued(task.id)
+
+    def _drop_cancelled_dependencies(self, task_id: str, dependencies: list[str]) -> None:
+        keep: list[str] = []
+        for dependency_id in dependencies:
+            dependency = self._context.tasks.get(dependency_id)
+            if dependency is not None and dependency.status is not Status.CANCELLED:
+                keep.append(dependency_id)
+        self._context.tasks.set_depends_on(task_id, keep)
+
+    @staticmethod
+    def _answer_text(command: Resolve) -> dict[str, str]:
+        resolution = command.resolution
+        return {EVENT_TEXT_KEY: resolution.text} if isinstance(resolution, AnswerResolution) else {}
+
+    @staticmethod
+    def _resolution_text(command: Resolve) -> str:
+        resolution = command.resolution
+        if isinstance(resolution, AnswerResolution):
+            return f"{ResolutionKind.ANSWER.value} {resolution.text}"
+        if isinstance(resolution, RetryResolution):
+            rung = resolution.rung
+            return "retry" + (f" {rung.agent}:{rung.model}" if rung else "")
+        if isinstance(resolution, AcceptResolution):
+            return "accept"
+        return "cancel"

shikiru/engine/handlers/operator.py

@@ -0,0 +1,81 @@
+"""Handlers for the Operator's direct access to a task's agents."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from shikiru.domain.commands import COMMAND_ID_KEY, EVENT_TEXT_KEY, HandBack, Say, TakeOver
+from shikiru.domain.events import EventKind
+from shikiru.engine.handlers.base import (
+    HandlerContext,
+    reject_terminal,
+    require_command_id,
+    require_task,
+)
+from shikiru.workspace.messages import command_message_key
+
+if TYPE_CHECKING:
+    from shikiru.engine.takeover import Takeover
+    from shikiru.workspace.messages import OperatorMessages
+
+
+class SayHandler:
+    """Queue an Operator message for a role's next turn without holding the task."""
+
+    command_type: type[Say] = Say
+
+    def __init__(self, context: HandlerContext, messages: OperatorMessages) -> None:
+        self._context = context
+        self._messages = messages
+
+    async def handle(self, command: Say) -> dict[str, object]:
+        task = require_task(self._context, command.task_id)
+        reject_terminal(task)
+        command_id = require_command_id(command)
+        path = self._messages.queue(
+            task.id, command.role, command.text, command_message_key(command_id)
+        )
+        if not self._context.events.command_applied(EventKind.OPERATOR_MESSAGE, command_id):
+            self._context.events.append(
+                EventKind.OPERATOR_MESSAGE,
+                task_id=task.id,
+                message=f"{task.id} message queued for {command.role.value}",
+                data={
+                    "role": command.role.value,
+                    "path": str(path),
+                    EVENT_TEXT_KEY: command.text,
+                    COMMAND_ID_KEY: command_id,
+                },
+            )
+        return {"task_id": task.id, "role": command.role.value, "path": str(path)}
+
+
+class TakeOverHandler:
+    """Hand a role's session to the Operator in its pane, holding only that task."""
+
+    command_type: type[TakeOver] = TakeOver
+
+    def __init__(self, context: HandlerContext, takeover: Takeover) -> None:
+        self._context = context
+        self._takeover = takeover
+
+    async def handle(self, command: TakeOver) -> dict[str, object]:
+        task = require_task(self._context, command.task_id)
+        reject_terminal(task)
+        await self._takeover.take_over(task, command.role, require_command_id(command))
+        return {"task_id": task.id, "role": command.role.value}
+
+
+class HandBackHandler:
+    """Return a taken-over role's session to the engine."""
+
+    command_type: type[HandBack] = HandBack
+
+    def __init__(self, context: HandlerContext, takeover: Takeover) -> None:
+        self._context = context
+        self._takeover = takeover
+
+    async def handle(self, command: HandBack) -> dict[str, object]:
+        task = require_task(self._context, command.task_id)
+        await self._takeover.hand_back(task, command.role, require_command_id(command))
+        return {"task_id": task.id, "role": command.role.value}

shikiru/engine/handlers/tasks.py

@@ -0,0 +1,237 @@
+"""Handlers for task lifecycle and scheduling commands."""
+
+from __future__ import annotations
+
+import dataclasses
+
+from shikiru.domain.commands import (
+    COMMAND_ID_KEY,
+    Cancel,
+    Pause,
+    Prioritize,
+    ResolutionKind,
+    Resume,
+    Retry,
+    SetRung,
+    Submit,
+)
+from shikiru.domain.events import EventKind
+from shikiru.domain.ladder import reset_for_rung_change
+from shikiru.domain.steps import Transition
+from shikiru.domain.tasks import Hold, Role, Status
+from shikiru.engine.handlers.base import (
+    HandlerContext,
+    command_replayed,
+    finish_task_quietly,
+    interrupt_task,
+    kept_worktree_result,
+    refresh_titles,
+    reject_terminal,
+    require_command_id,
+    require_task,
+)
+from shikiru.errors import CommandRejectedError
+
+
+class SubmitHandler:
+    """Insert a submitted task and emit its queue event."""
+
+    command_type: type[Submit] = Submit
+
+    def __init__(self, context: HandlerContext) -> None:
+        self._context = context
+
+    async def handle(self, command: Submit) -> dict[str, object]:
+        task = self._context.tasks.get(command.task_id) if command.task_id is not None else None
+        if task is None:
+            with self._context.atomically():
+                task = self._context.tasks.insert_from_submit(command)
+                self._context.events.append(
+                    EventKind.TASK_QUEUED,
+                    task_id=task.id,
+                    message=f"{task.id} queued",
+                    data={"priority": task.priority},
+                )
+        return {"task_id": task.id}
+
+
+class PrioritizeHandler:
+    """Change one queued task's dispatch priority."""
+
+    command_type: type[Prioritize] = Prioritize
+
+    def __init__(self, context: HandlerContext) -> None:
+        self._context = context
+
+    async def handle(self, command: Prioritize) -> dict[str, object]:
+        task = require_task(self._context, command.task_id)
+        if task.status is not Status.QUEUED:
+            message = f"{task.id} can only be prioritized while queued"
+            raise CommandRejectedError(message)
+        self._context.tasks.set_priority(task.id, command.priority)
+        return {"task_id": task.id, "priority": command.priority}
+
+
+class PauseHandler:
+    """Set a task pause hold, optionally interrupting its current turn."""
+
+    command_type: type[Pause] = Pause
+
+    def __init__(self, context: HandlerContext) -> None:
+        self._context = context
+
+    async def handle(self, command: Pause) -> dict[str, object]:
+        task = require_task(self._context, command.task_id)
+        reject_terminal(task)
+        if command.now:
+            await interrupt_task(self._context, task)
+        if Hold.PAUSED not in task.holds:
+            with self._context.atomically():
+                self._context.tasks.set_holds(task.id, task.holds | {Hold.PAUSED})
+                self._context.events.append(
+                    EventKind.HOLD_SET,
+                    task_id=task.id,
+                    message=f"{task.id} paused",
+                    data={"hold": Hold.PAUSED.value, "now": command.now},
+                )
+        await refresh_titles(self._context, task.id)
+        return {"task_id": task.id, "paused": True, "now": command.now}
+
+
+class ResumeHandler:
+    """Clear task holds and resume the task flow, unless a role is taken over."""
+
+    command_type: type[Resume] = Resume
+
+    def __init__(self, context: HandlerContext) -> None:
+        self._context = context
+
+    async def handle(self, command: Resume) -> dict[str, object]:
+        task = require_task(self._context, command.task_id)
+        reject_terminal(task)
+        if self._context.runs.has_taken_over(task.id):
+            message = f"{task.id} has a role taken over; hand it back before resuming"
+            raise CommandRejectedError(message)
+        holds = task.holds
+        self._context.tasks.set_holds(task.id, frozenset())
+        for hold in holds:
+            self._context.events.append(
+                EventKind.HOLD_CLEARED,
+                task_id=task.id,
+                message=f"{task.id} {hold.value} hold cleared",
+                data={"hold": hold.value},
+            )
+        if holds & {Hold.PAUSED, Hold.INTERVENTION} and task.status in (
+            Status.RUNNING,
+            Status.INTEGRATING,
+        ):
+            await self._context.start_task(task.id)
+        await refresh_titles(self._context, task.id)
+        return {"task_id": task.id, "paused": False, "intervention": False}
+
+
+class CancelHandler:
+    """Cancel a task, interrupting its current turn and retaining its branch."""
+
+    command_type: type[Cancel] = Cancel
+
+    def __init__(self, context: HandlerContext) -> None:
+        self._context = context
+
+    async def handle(self, command: Cancel) -> dict[str, object]:
+        task = require_task(self._context, command.task_id)
+        if not command_replayed(self._context, EventKind.TASK_CANCELLED, command):
+            reject_terminal(task)
+            await interrupt_task(self._context, task)
+            current = require_task(self._context, task.id)
+            with self._context.atomically():
+                self._context.tasks.finish(
+                    task.id,
+                    Transition.stay(current, step=current.step, status=Status.CANCELLED),
+                    EventKind.TASK_CANCELLED,
+                    message=f"{task.id} cancelled",
+                    data={
+                        "reason": "cancelled by operator",
+                        COMMAND_ID_KEY: require_command_id(command),
+                    },
+                )
+                self._context.escalations.settle_open(task.id, ResolutionKind.CANCEL.value)
+        updated = require_task(self._context, task.id)
+        await refresh_titles(self._context, updated.id)
+        kept = await finish_task_quietly(self._context, updated)
+        return {
+            "task_id": task.id,
+            "status": Status.CANCELLED.value,
+            **kept_worktree_result(kept),
+        }
+
+
+class RetryHandler:
+    """Cancel the current step and requeue it for an idempotent retry."""
+
+    command_type: type[Retry] = Retry
+
+    def __init__(self, context: HandlerContext) -> None:
+        self._context = context
+
+    async def handle(self, command: Retry) -> dict[str, object]:
+        task = require_task(self._context, command.task_id)
+        if not command_replayed(self._context, EventKind.TASK_RETRIED, command):
+            reject_terminal(task)
+            await interrupt_task(self._context, task)
+            current = require_task(self._context, task.id)
+            counters = current.counters.model_copy(update={"consults": 0, "conflict_rounds": 0})
+            transition = dataclasses.replace(
+                Transition.stay(current, step=current.step, status=Status.QUEUED),
+                counters=counters,
+            )
+            with self._context.atomically():
+                self._context.tasks.apply_transition(current.id, transition)
+                self._context.tasks.set_requeued(current.id)
+                self._context.escalations.settle_open(current.id, ResolutionKind.RETRY.value)
+                self._context.events.append(
+                    EventKind.TASK_RETRIED,
+                    task_id=current.id,
+                    message=f"{current.id} retried",
+                    data={COMMAND_ID_KEY: require_command_id(command)},
+                )
+        await refresh_titles(self._context, task.id)
+        return {"task_id": task.id, "status": require_task(self._context, task.id).status.value}
+
+
+class SetRungHandler:
+    """Apply a role rung override to the next task turn."""
+
+    command_type: type[SetRung] = SetRung
+
+    def __init__(self, context: HandlerContext) -> None:
+        self._context = context
+
+    async def handle(self, command: SetRung) -> dict[str, object]:
+        task = require_task(self._context, command.task_id)
+        reject_terminal(task)
+        old = task.overrides.get(command.role)
+        if old != command.rung:
+            counters = task.counters
+            if command.role is Role.IMPLEMENTER:
+                counters = reset_for_rung_change(counters)
+            transition = dataclasses.replace(
+                Transition.stay(task, step=task.step, status=task.status),
+                counters=counters,
+                set_overrides={command.role: command.rung},
+            )
+            with self._context.atomically():
+                self._context.tasks.apply_transition(task.id, transition)
+                self._context.events.append(
+                    EventKind.RUNG_CHANGED,
+                    task_id=task.id,
+                    message=f"{task.id} {command.role.value} rung set to {command.rung.model}",
+                    data={
+                        "role": command.role.value,
+                        "from": old.model if old is not None else None,
+                        "to": command.rung.model,
+                        "operator": True,
+                    },
+                )
+        await refresh_titles(self._context, task.id)
+        return {"task_id": task.id, "role": command.role.value, "model": command.rung.model}

shikiru/engine/history.py

@@ -0,0 +1,128 @@
+"""Read and select the reports recorded for a task's turns."""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING
+
+from shikiru.domain.reports import (
+    DECISION_ACCEPT,
+    ConsultAnswer,
+    FeedbackVerdict,
+    ImplementationReport,
+    PlanReport,
+    Report,
+    Verdict,
+)
+from shikiru.engine.integration import IntegrationMetadata
+from shikiru.engine.turns import read_turn_report
+from shikiru.paths import turns_dir
+from shikiru.view_log import ordered_turn_dirs
+from shikiru.workspace.reports import ENGINE_VERDICT_FILENAME as _ENGINE_VERDICT_FILENAME
+from shikiru.workspace.reports import (
+    LEGACY_COMMIT_SUBJECT,
+    InvalidTurnReportError,
+    load_engine_verdict,
+)
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+    from pathlib import Path
+
+    from shikiru.domain.tasks import Task
+
+_LOGGER = logging.getLogger(__name__)
+ENGINE_VERDICT_FILENAME = _ENGINE_VERDICT_FILENAME
+FALLBACK_COMMIT_TYPE = "chore"
+
+
+class ReportHistory:
+    """Load reports in turn order and derive the contexts used by task flows."""
+
+    def __init__(self, project_root: Path) -> None:
+        """Read reports from the project's task run directories."""
+        self._project_root = project_root
+
+    def load(self, task_id: str) -> list[tuple[str, Report]]:
+        """Load valid reports for `task_id`, logging and omitting invalid reports."""
+        turns_root = turns_dir(self._project_root, task_id)
+        if not turns_root.is_dir():
+            return []
+        history: list[tuple[str, Report]] = []
+        for turn_dir in ordered_turn_dirs(turns_root):
+            try:
+                report = read_turn_report(turn_dir)
+            except InvalidTurnReportError:
+                _LOGGER.exception("invalid report in %s", turn_dir)
+                report = None
+            if report is not None:
+                history.append((turn_dir.name, report))
+            try:
+                engine_verdict = load_engine_verdict(turn_dir)
+            except InvalidTurnReportError:
+                _LOGGER.exception("invalid engine verdict in %s", turn_dir)
+                engine_verdict = None
+            if engine_verdict is not None:
+                history.append(
+                    (
+                        turn_dir.name,
+                        engine_verdict,
+                    )
+                )
+        return history
+
+    @staticmethod
+    def context(history: Sequence[tuple[str, Report]]) -> list[dict[str, str]]:
+        """Serialize reports into the ordered prompt and escalation context."""
+        return [{"label": label, "json": report.model_dump_json()} for label, report in history]
+
+    @staticmethod
+    def latest_question(history: Sequence[tuple[str, Report]]) -> str:
+        """Return the Implementer question behind the latest consult, if it has one.
+
+        The Leader's answers and escalations follow the question's report, so they are skipped.
+        """
+        for _, report in reversed(history):
+            if isinstance(report, ConsultAnswer):
+                continue
+            return report.question if isinstance(report, ImplementationReport) else ""
+        return ""
+
+    def latest_report(self, task_id: str) -> Report | None:
+        """Return the newest valid report for `task_id`."""
+        history = self.load(task_id)
+        return history[-1][1] if history else None
+
+    def integration_metadata(self, task: Task) -> IntegrationMetadata:
+        """Choose the accepted change's subject and summary, falling back to the latest plan.
+
+        A task with neither gets a `chore` subject named after its title, summarized by it.
+        """
+        history = self.load(task.id)
+        fallback_subject = f"{FALLBACK_COMMIT_TYPE}: {' '.join(task.title.split())}"
+        for _, report in reversed(history):
+            if (
+                isinstance(report, Verdict)
+                and not isinstance(report, FeedbackVerdict)
+                and report.decision == DECISION_ACCEPT
+            ):
+                return IntegrationMetadata(
+                    subject=(
+                        fallback_subject
+                        if report.commit_subject == LEGACY_COMMIT_SUBJECT
+                        else report.commit_subject
+                    ),
+                    summary=report.summary,
+                    residual_risks=tuple(report.residual_risks),
+                )
+        for _, report in reversed(history):
+            if isinstance(report, PlanReport):
+                return IntegrationMetadata(
+                    subject=(
+                        fallback_subject
+                        if report.commit_subject == LEGACY_COMMIT_SUBJECT
+                        else report.commit_subject
+                    ),
+                    summary=report.summary,
+                )
+        return IntegrationMetadata(subject=fallback_subject, summary=task.title)