Skip to content

Use Claude Code, Codex, VSCode, Pi, and OpenCode (and 6 other harnesses) for free (1.3B+ free tokens) from your terminal, app, IDE, or phone, and now from the browser with native browser sessions (multi-harness + multi-model) like OpenClaw (voice supported + ToS friendly)

Python
10.2 KB
Raw Blame
"""Task execution for claims returned by messaging tree aggregates."""

import asyncio
import contextlib
from collections.abc import Awaitable, Callable
from dataclasses import dataclass

from loguru import logger

from ..safe_diagnostics import format_exception_for_log
from .ports import MessagingStorageError
from .runtime import MessageTree
from .transitions import CancellationReason, NodeClaim, QueueEntry

NodeProcessor = Callable[[NodeClaim], Awaitable[None]]
QueueUpdateCallback = Callable[[tuple[QueueEntry, ...]], Awaitable[None]]
NodeStartedCallback = Callable[[NodeClaim], Awaitable[None]]
ClaimFailureCallback = Callable[[NodeClaim], Awaitable[None]]
ClaimFinishedCallback = Callable[[MessageTree, NodeClaim], Awaitable[None]]


@dataclass(slots=True)
class _TaskSlot:
    tree: MessageTree
    claim: NodeClaim
    task: asyncio.Task[None] | None = None
    runner_started: bool = False
    transitioned: bool = False
    recovery_task: asyncio.Task[None] | None = None
    cancellation_requested: bool = False
    cancellation_reason: CancellationReason | None = None


@dataclass(frozen=True, slots=True)
class CancelledTask:
    """Task handle plus whether the node runner owns cancellation UI."""

    task: asyncio.Task[None]
    runner_started: bool


class TreeQueueProcessor:
    """Own asyncio tasks while MessageTree owns scheduling state."""

    def __init__(
        self,
        node_processor: NodeProcessor,
        *,
        claim_failure_callback: ClaimFailureCallback,
        claim_finished_callback: ClaimFinishedCallback,
        queue_update_callback: QueueUpdateCallback | None = None,
        node_started_callback: NodeStartedCallback | None = None,
        log_messaging_error_details: bool = False,
    ) -> None:
        self._node_processor = node_processor
        self._claim_failure_callback = claim_failure_callback
        self._claim_finished_callback = claim_finished_callback
        self._queue_update_callback = queue_update_callback
        self._node_started_callback = node_started_callback
        self._log_messaging_error_details = log_messaging_error_details
        self._tasks: dict[str, _TaskSlot] = {}
        self._completion_failures: list[Exception] = []
        self._idle = asyncio.Event()
        self._idle.set()

    @staticmethod
    def _key(claim: NodeClaim) -> str:
        return claim.claim_id

    def launch(
        self,
        tree: MessageTree,
        claim: NodeClaim,
        *,
        announce_started: bool = False,
        queue: tuple[QueueEntry, ...] = (),
    ) -> None:
        """Attach a task synchronously before another coroutine can cancel it."""
        key = self._key(claim)
        if key in self._tasks:
            raise RuntimeError(f"Claim {key} already has a task")
        slot = _TaskSlot(tree=tree, claim=claim)
        self._tasks[key] = slot
        self._idle.clear()
        ownership_ready = asyncio.Event()
        claim_runner = self._run_claim(
            slot,
            ownership_ready=ownership_ready,
            announce_started=announce_started,
            queue=queue,
        )
        try:
            task = asyncio.create_task(
                claim_runner,
                name=(f"messaging-claim-{claim.identity.root_id}-{claim.claim_id[:8]}"),
            )
        except BaseException:
            claim_runner.close()
            if self._tasks.get(key) is slot:
                self._tasks.pop(key)
            if not self._tasks:
                self._idle.set()
            raise
        slot.task = task
        task.add_done_callback(lambda _task, claim_key=key: self._task_done(claim_key))
        ownership_ready.set()

    def _task_done(self, key: str) -> None:
        """Recover a claim if its task was cancelled before entering its body."""
        slot = self._tasks.get(key)
        if slot is None or slot.transitioned or slot.recovery_task is not None:
            return
        slot.recovery_task = asyncio.create_task(
            self._recover_unentered_task(slot),
            name=f"messaging-claim-recovery-{key[:8]}",
        )

    async def _recover_unentered_task(self, slot: _TaskSlot) -> None:
        task = slot.task
        if task is not None:
            with contextlib.suppress(asyncio.CancelledError, Exception):
                await task
        if not slot.transitioned:
            await self._finish_and_continue(slot)

    async def _notify_queue_updated(self, queue: tuple[QueueEntry, ...]) -> None:
        if self._queue_update_callback is None:
            return
        try:
            await self._queue_update_callback(queue)
        except Exception as exc:
            logger.warning(
                "Queue update callback failed: {}",
                format_exception_for_log(
                    exc,
                    log_full_message=self._log_messaging_error_details,
                ),
            )

    async def notify_queue_updated(self, queue: tuple[QueueEntry, ...]) -> None:
        """Publish a transition-owned queue snapshot."""
        await self._notify_queue_updated(queue)

    async def _notify_node_started(self, claim: NodeClaim) -> None:
        if self._node_started_callback is None:
            return
        try:
            await self._node_started_callback(claim)
        except Exception as exc:
            logger.warning(
                "Node started callback failed: {}",
                format_exception_for_log(
                    exc,
                    log_full_message=self._log_messaging_error_details,
                ),
            )

    async def _run_claim(
        self,
        slot: _TaskSlot,
        *,
        ownership_ready: asyncio.Event,
        announce_started: bool,
        queue: tuple[QueueEntry, ...],
    ) -> None:
        await ownership_ready.wait()
        claim = slot.claim
        try:
            if announce_started:
                await self._notify_node_started(claim)
                await self._notify_queue_updated(queue)
            if slot.cancellation_requested:
                if slot.cancellation_reason is None:
                    raise asyncio.CancelledError
                raise asyncio.CancelledError(slot.cancellation_reason)
            slot.runner_started = True
            await self._node_processor(claim)
        except asyncio.CancelledError:
            logger.info("Task for node {} was cancelled", claim.node.node_id)
            raise
        except Exception as exc:
            logger.error(
                "Error processing node {}: {}",
                claim.node.node_id,
                format_exception_for_log(
                    exc,
                    log_full_message=self._log_messaging_error_details,
                ),
            )
            if not isinstance(exc, MessagingStorageError):
                try:
                    await self._claim_failure_callback(claim)
                except MessagingStorageError:
                    # The manager has gated the tree. Finalization retires it.
                    logger.warning("Messaging failure state could not be saved")
        finally:
            if not slot.transitioned:
                await self._finish_and_continue(slot)

    async def _finish_and_continue(self, slot: _TaskSlot) -> None:
        current = asyncio.current_task()
        if current is not None:
            while current.cancelling():
                current.uncancel()
        try:
            while True:
                try:
                    await self._claim_finished_callback(slot.tree, slot.claim)
                    slot.transitioned = True
                    break
                except asyncio.CancelledError:
                    if current is not None:
                        while current.cancelling():
                            current.uncancel()
                    continue
        except Exception as exc:
            self._completion_failures.append(exc)
            logger.error(
                "Claim completion callback failed for node {}: {}",
                slot.claim.node.node_id,
                format_exception_for_log(
                    exc,
                    log_full_message=self._log_messaging_error_details,
                ),
            )
        finally:
            key = self._key(slot.claim)
            if self._tasks.get(key) is slot:
                self._tasks.pop(key)
            if not self._tasks:
                self._idle.set()

    def cancel(
        self,
        claim: NodeClaim,
        reason: CancellationReason | None,
    ) -> CancelledTask | None:
        """Cancel exactly the task bound to one aggregate claim."""
        slot = self._tasks.get(self._key(claim))
        if slot is None:
            return None
        slot.cancellation_requested = True
        slot.cancellation_reason = reason
        task = slot.task
        if task is None or task.done():
            return None
        if reason is None:
            task.cancel()
        else:
            task.cancel(reason)

        if slot.runner_started:
            return CancelledTask(task=task, runner_started=True)

        if slot.recovery_task is None:
            slot.recovery_task = asyncio.create_task(
                self._recover_unentered_task(slot),
                name=f"messaging-claim-recovery-{claim.claim_id[:8]}",
            )
        return CancelledTask(task=slot.recovery_task, runner_started=False)

    def task_count(self) -> int:
        """Return the number of attached claims for observability."""
        return len(self._tasks)

    def owns_tree(self, tree: MessageTree) -> bool:
        return any(slot.tree is tree for slot in self._tasks.values())

    def cancel_all(self, reason: CancellationReason) -> dict[str, CancelledTask | None]:
        return {
            slot.claim.claim_id: self.cancel(slot.claim, reason)
            for slot in tuple(self._tasks.values())
        }

    async def wait_idle(self) -> None:
        """Wait for every task and hand completion failures to the caller once."""
        await self._idle.wait()
        if not self._completion_failures:
            return
        failures = self._completion_failures
        self._completion_failures = []
        if len(failures) == 1:
            raise failures[0]
        raise ExceptionGroup("Messaging claim completion failures", failures)


__all__ = ["CancelledTask", "TreeQueueProcessor"]