shikiru-cli 0.2.0__py3-none-any.whl

shikiru/engine/scheduler.py

@@ -0,0 +1,320 @@
+"""Task dispatch, gate evaluation and slot ownership."""
+
+from __future__ import annotations
+
+import dataclasses
+import logging
+from collections.abc import Awaitable, Callable
+from datetime import timedelta
+from typing import TYPE_CHECKING
+
+from shikiru.domain.events import EventKind
+from shikiru.domain.faults import next_backoff
+from shikiru.domain.ladder import move_up, pick_rung
+from shikiru.domain.scheduling import (
+    Dispatch,
+    ReadySchedule,
+    SchedulingGates,
+    WaitReason,
+    occupied_slot_ids,
+    pick_ready,
+    task_agents,
+)
+from shikiru.domain.steps import Transition
+from shikiru.domain.tasks import Role, Status, StatusReason, Step, Task
+from shikiru.engine.events import emit_step_started
+from shikiru.errors import InvariantError
+from shikiru.workspace.base_refs import BaseFetchFailed
+
+if TYPE_CHECKING:
+    from datetime import datetime
+
+    from shikiru.clock import Clock
+    from shikiru.config.settings import Settings
+    from shikiru.engine.fault_reporter import FaultReporter
+    from shikiru.engine.layout_guard import LayoutGuard
+    from shikiru.engine.quota_reconciler import QuotaReconciler
+    from shikiru.engine.root_preparation import RootPreparation
+    from shikiru.engine.titles import TaskTitles
+    from shikiru.store.events import EventLog
+    from shikiru.store.quotas import QuotaStore
+    from shikiru.store.tasks import TaskStore
+    from shikiru.telemetry.resources import ResourceSampler
+
+DependencyCallback = Callable[[Task], Awaitable[None]]
+DispatchFailureCallback = Callable[[Task, Exception], Awaitable[None]]
+MAX_DISPATCH_FAILURES = 3
+FETCH_FAULT_SCOPE = "dispatch fetch"
+_QUOTA_DECORATED_STATUSES = (Status.QUEUED, Status.RUNNING, Status.INTEGRATING)
+
+
+class Scheduler:
+    """Builds the ready set, persists wait reasons and dispatches eligible tasks."""
+
+    def __init__(
+        self,
+        *,
+        tasks: TaskStore,
+        settings: Settings,
+        quotas: QuotaStore,
+        reconciler: QuotaReconciler,
+        resources: ResourceSampler,
+        clock: Clock,
+        layout: LayoutGuard,
+        roots: RootPreparation,
+        events: EventLog,
+        on_dependency_cancelled: DependencyCallback,
+        on_dispatch_failure: DispatchFailureCallback,
+        titles: TaskTitles,
+        faults: FaultReporter,
+    ) -> None:
+        """Inject state stores, gates, and the task-window dispatch boundary.
+
+        A dispatch whose base fetch fails is retried on a growing backoff, recorded through
+        `faults`, and never counts toward `MAX_DISPATCH_FAILURES`.
+        """
+        self._tasks = tasks
+        self._settings = settings
+        self._quotas = quotas
+        self._reconciler = reconciler
+        self._resources = resources
+        self._clock = clock
+        self._layout = layout
+        self._roots = roots
+        self._events = events
+        self._on_dependency_cancelled = on_dependency_cancelled
+        self._on_dispatch_failure = on_dispatch_failure
+        self._titles = titles
+        self._faults = faults
+        self._dispatch_failures: dict[str, int] = {}
+        self._fetch_backoffs: dict[str, float] = {}
+        self._fetch_retry_at: dict[str, datetime] = {}
+        self._logger = logging.getLogger(__name__)
+
+    async def run_once(self) -> ReadySchedule:
+        """Evaluate gates, persist wait reasons and dispatch every eligible task."""
+        all_tasks = self._tasks.list_all()
+        self._request_quota_refreshes(all_tasks)
+        gates = self._gates(all_tasks)
+        schedule = pick_ready(all_tasks, gates)
+        if self._advance_quota_blocked(all_tasks, schedule):
+            all_tasks = self._tasks.list_all()
+            schedule = pick_ready(all_tasks, self._gates(all_tasks))
+        self._roots.begin_tick({task.id for task in all_tasks if task.status is Status.QUEUED})
+        self._persist_wait_reasons(all_tasks, schedule)
+        await self._sync_quota_decorations()
+        for task_id in schedule.dependency_cancelled:
+            task = self._tasks.get(task_id)
+            if task is None:
+                message = f"{task_id} vanished before dependency cancellation"
+                raise InvariantError(message)
+            await self._on_dependency_cancelled(task)
+        successful_dispatches: list[Dispatch] = []
+        for dispatch in schedule.dispatches:
+            task = self._tasks.get(dispatch.task_id)
+            if task is None:
+                message = f"{dispatch.task_id} vanished before dispatch"
+                raise InvariantError(message)
+            if self._awaits_fetch_retry(task.id):
+                continue
+            if await self._dispatch(task, dispatch.slot):
+                successful_dispatches.append(dispatch)
+        return dataclasses.replace(schedule, dispatches=tuple(successful_dispatches))
+
+    async def shutdown(self) -> None:
+        """Stop the quota probes and the task root builds still in flight."""
+        await self._reconciler.shutdown()
+        await self._roots.shutdown()
+
+    def _request_quota_refreshes(self, tasks: list[Task]) -> None:
+        now = self._clock.now()
+        demands: dict[str, datetime | None] = {}
+        for block in self._quotas.active_blocks(now):
+            queued = [
+                task
+                for task in tasks
+                if task.status is Status.QUEUED
+                and block.agent in dataclasses.astuple(task_agents(task, self._settings))
+            ]
+            if queued:
+                requeues = [task.requeued_at for task in queued if task.requeued_at is not None]
+                demands[block.agent] = max(requeues, default=None)
+        for agent, demanded_at in demands.items():
+            self._reconciler.request_refresh(agent, demanded_at=demanded_at)
+
+    def _advance_quota_blocked(self, tasks: list[Task], schedule: ReadySchedule) -> bool:
+        now = self._clock.now()
+        blocks = {block.agent: block for block in self._quotas.active_blocks(now)}
+        blocked_agents = frozenset(blocks)
+        wait_limit = now + timedelta(seconds=self._settings.orchestration.timeouts.max_quota_wait)
+        changed = False
+        for queued in tasks:
+            if schedule.wait_reasons.get(queued.id) is not WaitReason.QUOTA:
+                continue
+            task = queued
+            for role in (Role.LEADER, Role.IMPLEMENTER):
+                old_rung = pick_rung(task, role, self._settings)
+                block = blocks.get(old_rung.agent)
+                if block is None or block.until <= wait_limit:
+                    continue
+                if self._reconciler.awaiting_demanded_probe(block):
+                    continue
+                move = move_up(
+                    task, role, self._settings, different_agent=True, blocked_agents=blocked_agents
+                )
+                if move is None:
+                    continue
+                transition = dataclasses.replace(
+                    Transition.stay(task, step=task.step, status=task.status),
+                    counters=move.counters,
+                    rung_index=move.rung_index,
+                    cleared_overrides=move.cleared_overrides,
+                )
+                self._tasks.apply_transition(task.id, transition)
+                task = self._tasks.require(task.id)
+                new_rung = pick_rung(task, role, self._settings)
+                self._events.append(
+                    EventKind.RUNG_CHANGED,
+                    task_id=task.id,
+                    message=(
+                        f"{task.id} {role.value} moved from {old_rung.model} to {new_rung.model}"
+                    ),
+                    data={
+                        "role": role.value,
+                        "from": old_rung.model,
+                        "to": new_rung.model,
+                        "different_agent": True,
+                        "reason": WaitReason.QUOTA.value,
+                    },
+                )
+                changed = True
+        return changed
+
+    async def _sync_quota_decorations(self) -> None:
+        for task in self._tasks.list_all():
+            if task.window_id is not None and task.status in _QUOTA_DECORATED_STATUSES:
+                await self._titles.sync_quota(task)
+
+    def _gates(self, tasks: list[Task]) -> SchedulingGates:
+        slots = frozenset(range(self._settings.orchestration.max_parallel)) - occupied_slot_ids(
+            tasks
+        )
+        blocked = frozenset(block.agent for block in self._quotas.active_blocks(self._clock.now()))
+        agents = {
+            task.id: task_agents(task, self._settings)
+            for task in tasks
+            if task.status is Status.QUEUED
+        }
+        return SchedulingGates(
+            free_slots=slots,
+            resources_ok=self._resources.resources_ok(self._settings.orchestration.resources),
+            blocked_agents=blocked,
+            agents=agents,
+        )
+
+    def _persist_wait_reasons(self, tasks: list[Task], schedule: ReadySchedule) -> None:
+        reasons = schedule.wait_reasons
+        for task in tasks:
+            if task.status is not Status.QUEUED:
+                continue
+            reason = reasons.get(task.id)
+            if task.wait_reason != (reason.value if reason is not None else None):
+                self._tasks.set_wait_reason(task.id, reason)
+
+    async def _dispatch(self, task: Task, slot: int) -> bool:
+        current = task
+        try:
+            repo = task.repo
+            if repo is None:
+                repo = await self._roots.prepare(task.id, task.title, self._seed_branch(task))
+                if repo is None:
+                    return False
+            self._tasks.set_slot(task.id, slot)
+            self._tasks.set_wait_reason(task.id, None)
+            status = Status.INTEGRATING if task.step is Step.INTEGRATE else Status.RUNNING
+            self._tasks.apply_transition(
+                task.id, Transition.stay(task, step=task.step, status=status)
+            )
+            current = self._require_task(task.id, "slot assignment")
+            if current.repo is None:
+                self._tasks.set_repo(current.id, repo)
+                current = self._require_task(task.id, "task-root creation")
+            await self._layout.ensure(current)
+            current = self._require_task(task.id, "layout creation")
+            await self._titles.refresh(current)
+        except BaseFetchFailed as error:
+            self._logger.warning("dispatch of %s waits for the remote: %s", task.id, error)
+            await self._rollback_dispatch(task)
+            self._back_off_fetch(task.id, error)
+            return False
+        except Exception as error:
+            self._logger.exception("dispatch setup failed for %s", task.id)
+            await self._rollback_dispatch(task)
+            failures = self._dispatch_failures.get(task.id, 0) + 1
+            self._dispatch_failures[task.id] = failures
+            self._events.append(
+                EventKind.DISPATCH_FAILED,
+                task_id=task.id,
+                message=f"{task.id} dispatch failed",
+                data={"attempt": failures, "error": str(error)},
+            )
+            if failures >= MAX_DISPATCH_FAILURES:
+                current = self._require_task(task.id, "dispatch failure")
+                await self._on_dispatch_failure(current, error)
+                self._dispatch_failures.pop(task.id, None)
+            return False
+        self._dispatch_failures.pop(task.id, None)
+        self._fetch_backoffs.pop(task.id, None)
+        self._fetch_retry_at.pop(task.id, None)
+        self._faults.resolve(FETCH_FAULT_SCOPE, task_id=task.id)
+        self._events.append(
+            EventKind.TASK_STARTED,
+            task_id=current.id,
+            message=f"{current.id} started in slot {slot}",
+            data={"slot": slot},
+        )
+        emit_step_started(self._events, current, self._settings)
+        return True
+
+    def _awaits_fetch_retry(self, task_id: str) -> bool:
+        retry_at = self._fetch_retry_at.get(task_id)
+        return retry_at is not None and self._clock.now() < retry_at
+
+    def _back_off_fetch(self, task_id: str, error: BaseFetchFailed) -> None:
+        faults = self._settings.orchestration.faults
+        delay = next_backoff(
+            self._fetch_backoffs.get(task_id, 0.0),
+            initial=faults.backoff_initial_seconds,
+            maximum=faults.backoff_max_seconds,
+        )
+        self._fetch_backoffs[task_id] = delay
+        self._fetch_retry_at[task_id] = self._clock.now() + timedelta(seconds=delay)
+        self._faults.report(error, scope=FETCH_FAULT_SCOPE, task_id=task_id)
+
+    def _seed_branch(self, task: Task) -> str | None:
+        parent = self._tasks.get(task.parent_id) if task.parent_id is not None else None
+        if parent is None or parent.status_reason is not StatusReason.SUPERSEDED:
+            return None
+        return parent.repo.branch if parent.repo is not None else None
+
+    async def _rollback_dispatch(self, task: Task) -> None:
+        current = self._tasks.get(task.id)
+        if current is None:
+            return
+        if task.window_id is None and current.window_id is not None:
+            try:
+                await self._layout.close(current)
+            except Exception:
+                self._logger.exception("dispatch cleanup failed for %s", task.id)
+        self._tasks.apply_transition(
+            current.id, Transition.stay(current, step=current.step, status=Status.QUEUED)
+        )
+        self._tasks.set_slot(current.id, None)
+        self._tasks.set_wait_reason(current.id, None)
+
+    def _require_task(self, task_id: str, operation: str) -> Task:
+        current = self._tasks.get(task_id)
+        if current is None:
+            message = f"{task_id} vanished after {operation}"
+            raise InvariantError(message)
+        return current

shikiru/engine/session_guard.py

@@ -0,0 +1,46 @@
+"""Recreates the project's tmux session after the tmux server or session is lost."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from collections.abc import Sequence
+    from logging import Logger
+    from pathlib import Path
+
+    from shikiru.tmux.client import Tmux
+    from shikiru.tmux.session import SessionView
+
+
+class SessionGuard:
+    """Brings back the session and its home window when they have vanished."""
+
+    def __init__(
+        self,
+        *,
+        tmux: Tmux,
+        view: SessionView,
+        session_target: str,
+        project_name: str,
+        project_root: Path,
+        home_command: Sequence[str],
+        logger: Logger,
+    ) -> None:
+        """Probe `session_target` through `tmux` and recreate it through `view`."""
+        self._tmux = tmux
+        self._view = view
+        self._session_target = session_target
+        self._project_name = project_name
+        self._project_root = project_root
+        self._home_command = home_command
+        self._logger = logger
+
+    async def ensure(self) -> None:
+        """Recreate the session with its home window when it does not exist."""
+        if await self._tmux.target_exists(self._session_target):
+            return
+        self._logger.warning("tmux session %s is gone; recreating it", self._session_target)
+        await self._view.ensure(
+            self._project_name, self._project_root, home_command=self._home_command
+        )

shikiru/engine/sessions.py

@@ -0,0 +1,95 @@
+"""Session selection for resumed process-per-turn agent sessions."""
+
+from __future__ import annotations
+
+import shlex
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+from shikiru.domain.ladder import pick_rung
+from shikiru.domain.runs import Run, RunStatus
+from shikiru.errors import InvariantError
+from shikiru.paths import turns_dir
+from shikiru.workspace.reports import load_turn_report
+
+if TYPE_CHECKING:
+    from pathlib import Path
+
+    from shikiru.agents.contracts import Agent, Rung
+    from shikiru.config.settings import Settings
+    from shikiru.domain.tasks import Role, Task
+    from shikiru.engine.agents import AgentPool
+    from shikiru.store.runs import RunStore
+
+
+@dataclass(frozen=True)
+class SessionSelection:
+    """The rung, resumable session and run row selected for one role turn."""
+
+    rung: Rung
+    session_id: str | None
+    handoff: bool
+    run: Run
+
+
+class SessionManager:
+    """Select and persist the session lineage for the next turn of a task role."""
+
+    def __init__(
+        self,
+        *,
+        runs: RunStore,
+        agents: AgentPool,
+        project_root: Path,
+        settings: Settings,
+    ) -> None:
+        self._runs = runs
+        self._agents = agents
+        self._project_root = project_root
+        self._settings = settings
+
+    def session_for(self, task: Task, role: Role) -> SessionSelection:
+        """Choose a session, resuming it across turns and same-agent rung changes."""
+        rung = pick_rung(task, role, self._settings)
+        current = self._runs.get_live(task.id, role)
+        if current is not None and current.agent == rung.agent:
+            self._runs.set_rung(current.id, rung)
+            refreshed = self._runs.get_live(task.id, role)
+            if refreshed is None:
+                message = f"{task.id} {role.value} run disappeared during session selection"
+                raise InvariantError(message)
+            return SessionSelection(rung, refreshed.session_id, False, refreshed)
+
+        if current is not None:
+            self._runs.close(current.id)
+        history_exists = self._has_reports(task.id)
+        run = self._runs.start(
+            task.id,
+            role,
+            rung,
+            billing_declaration=self._agents.billing_declaration(rung.agent),
+        )
+        return SessionSelection(rung, None, history_exists, run)
+
+    def record_session_started(
+        self, *, run_id: int, agent: Agent, session_id: str, run_dir: Path, rung: Rung
+    ) -> None:
+        """Persist the session id and the command an operator can use to resume it."""
+        command = shlex.join(agent.interactive_command(session_id, run_dir, rung))
+        self._runs.set_session(run_id, session_id, command)
+
+    def close_task(self, task_id: str) -> None:
+        """Close every role session after its task ends."""
+        for run in self._runs.for_task(task_id):
+            if run.status is not RunStatus.CLOSED:
+                self._runs.close(run.id)
+
+    def _has_reports(self, task_id: str) -> bool:
+        task_turns_dir = turns_dir(self._project_root, task_id)
+        if not task_turns_dir.is_dir():
+            return False
+        return any(
+            load_turn_report(turn_dir) is not None
+            for turn_dir in task_turns_dir.iterdir()
+            if turn_dir.is_dir()
+        )

shikiru/engine/signalled.py

@@ -0,0 +1,75 @@
+"""Runs the engine so that SIGTERM and SIGINT stop it gracefully, within a bound."""
+
+from __future__ import annotations
+
+import asyncio
+import signal
+from typing import TYPE_CHECKING
+
+from shikiru.errors import ShikiruError
+
+if TYPE_CHECKING:
+    from shikiru.clock import Clock
+    from shikiru.engine.daemon import Engine
+    from shikiru.engine.turn_processes import TurnProcesses
+
+STOP_SIGNALS = (signal.SIGTERM, signal.SIGINT)
+
+
+class ForcedShutdownError(ShikiruError):
+    """The engine was signalled twice or outlived its shutdown bound and was ended by force."""
+
+
+class SignalledEngine:
+    """Run an `Engine` until it stops, turning the first stop signal into `Engine.request_stop`."""
+
+    def __init__(
+        self,
+        *,
+        engine: Engine,
+        turn_processes: TurnProcesses,
+        clock: Clock,
+        shutdown_seconds: float,
+    ) -> None:
+        """Bound the graceful shutdown by `shutdown_seconds` on `clock`."""
+        self._engine = engine
+        self._turn_processes = turn_processes
+        self._clock = clock
+        self._shutdown_seconds = shutdown_seconds
+        self._deadline: asyncio.Task[None] | None = None
+        self._forced = False
+
+    async def run(self) -> None:
+        """Run the engine; a second signal or the bound cancels it and ends every turn process."""
+        loop = asyncio.get_running_loop()
+        engine = asyncio.create_task(self._engine.run())
+        for signum in STOP_SIGNALS:
+            loop.add_signal_handler(signum, self._on_signal, engine)
+        try:
+            await engine
+        except asyncio.CancelledError:
+            if not self._forced:
+                raise
+            await self._turn_processes.end_orphans()
+            message = f"engine ended by force after {self._shutdown_seconds:g} s or a second signal"
+            raise ForcedShutdownError(message) from None
+        finally:
+            for signum in STOP_SIGNALS:
+                loop.remove_signal_handler(signum)
+            if self._deadline is not None:
+                self._deadline.cancel()
+
+    def _on_signal(self, engine: asyncio.Task[None]) -> None:
+        if self._deadline is not None:
+            self._force(engine)
+            return
+        self._engine.request_stop()
+        self._deadline = asyncio.create_task(self._expire(engine))
+
+    async def _expire(self, engine: asyncio.Task[None]) -> None:
+        await self._clock.sleep(self._shutdown_seconds)
+        self._force(engine)
+
+    def _force(self, engine: asyncio.Task[None]) -> None:
+        self._forced = True
+        engine.cancel()

shikiru/engine/step_runner.py

@@ -0,0 +1,140 @@
+"""Runs a step's turn to its transition, the boundary every turn shares."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from shikiru.domain.recovery import ProtocolError, TurnCounters
+from shikiru.domain.reports import FeedbackAnalysis, ImplementationReport, Verdict
+from shikiru.domain.steps import Transition, next_step
+from shikiru.domain.tasks import EscalationReason, Status, Step
+from shikiru.engine.events import emit_turn_failed
+from shikiru.engine.turn_loop import TurnOverrides, TurnsStopped
+from shikiru.errors import InvariantError, UsageError
+
+if TYPE_CHECKING:
+    from shikiru.config.settings import Settings
+    from shikiru.domain.feedback import FeedbackInput
+    from shikiru.domain.reports import Report, ReportKind
+    from shikiru.domain.steps import Outcome
+    from shikiru.domain.tasks import Role, Task
+    from shikiru.engine.acceptance import AcceptanceGuard
+    from shikiru.engine.escalation_filing import EscalationFiler
+    from shikiru.engine.transitions import TransitionWriter
+    from shikiru.engine.turn_execution import TurnExecution
+    from shikiru.engine.turn_loop import TurnLoop
+    from shikiru.prompts.renderer import PromptName
+    from shikiru.store.events import EventLog
+
+
+class TurnStopped(Exception):
+    """Stop a caller's sequence after its task escalates or pauses."""
+
+
+class StepRunner:
+    """Runs a step's turn, settles its report and applies the transition the report earns."""
+
+    def __init__(
+        self,
+        *,
+        loop: TurnLoop,
+        acceptance: AcceptanceGuard,
+        escalations: EscalationFiler,
+        writer: TransitionWriter,
+        events: EventLog,
+        settings: Settings,
+    ) -> None:
+        """Run turns through `loop`, guard acceptance, then transition or escalate."""
+        self._loop = loop
+        self._acceptance = acceptance
+        self._escalations = escalations
+        self._writer = writer
+        self._events = events
+        self._settings = settings
+
+    async def run_step(
+        self,
+        task: Task,
+        step: Step,
+        counters: TurnCounters,
+        *,
+        conflict_context: str | None = None,
+        force_new_turn: bool = False,
+    ) -> tuple[Task, TurnCounters, bool]:
+        """Run one domain step through its turn and recovery loop; report whether it stopped."""
+        if force_new_turn:
+            self._loop.forget_resume(task.id)
+        result = await self._loop.run(
+            task, step, counters, TurnOverrides(conflict_context=conflict_context)
+        )
+        if isinstance(result, TurnsStopped):
+            return result.task, result.counters, True
+        outcome = await self._acceptance.settle(result.task, result.report, result.execution)
+        try:
+            current, escalated = await self.advance(result.task, outcome)
+        except UsageError as error:
+            escalated_task = await self._escalate_scope_change_protocol(
+                result.task,
+                step,
+                outcome,
+                error,
+                execution=result.execution,
+            )
+            return escalated_task, TurnCounters(), True
+        return current, TurnCounters(), escalated
+
+    async def run_report_turn(
+        self,
+        task: Task,
+        *,
+        role: Role,
+        template: PromptName,
+        kind: ReportKind,
+        feedback: FeedbackInput | None = None,
+    ) -> tuple[Task, ImplementationReport | Verdict | FeedbackAnalysis]:
+        """Run one integration report through the shared turn and recovery loop."""
+        result = await self._loop.run(
+            task,
+            Step.INTEGRATE,
+            TurnCounters(),
+            TurnOverrides(role=role, template=template, kind=kind, feedback=feedback),
+        )
+        if isinstance(result, TurnsStopped):
+            raise TurnStopped
+        report: Report = result.report
+        if not isinstance(report, ImplementationReport | Verdict | FeedbackAnalysis):
+            message = f"{result.task.id} integration turn returned an unexpected report"
+            raise InvariantError(message)
+        return result.task, await self._acceptance.settle(result.task, report, result.execution)
+
+    async def advance(
+        self, task: Task, outcome: Outcome, *, role: Role | None = None
+    ) -> tuple[Task, bool]:
+        """Apply the transition `outcome` earns `task`; report whether it escalated."""
+        transition = next_step(task, outcome, self._settings)
+        if transition.status is Status.ESCALATED:
+            escalated = await self._escalations.escalate(task, transition, outcome, role=role)
+            return escalated, True
+        return await self._writer.apply(task, transition, outcome), False
+
+    async def _escalate_scope_change_protocol(
+        self,
+        task: Task,
+        step: Step,
+        outcome: Outcome,
+        error: UsageError,
+        *,
+        execution: TurnExecution,
+    ) -> Task:
+        emit_turn_failed(
+            self._events,
+            task,
+            step,
+            ProtocolError(),
+            rung=execution.rung,
+            run_id=execution.run_id,
+            turn=execution.turn_dir.name,
+            role=execution.role,
+        )
+        transition = Transition.escalate(task, EscalationReason.AGENT_PROTOCOL, step=step)
+        return await self._escalations.escalate(task, transition, outcome, question=str(error))