script-build-and-framework-tmp/agent/agent/orchestration/protocols.py

"""Ports used by the orchestration domain."""

from __future__ import annotations

from dataclasses import dataclass
from typing import Any, Dict, List, Optional, Protocol, Sequence

from .models import (
    ArtifactSnapshot,
    AttemptSubmission,
    BackgroundOperation,
    EventDraft,
    EventPage,
    ExecutionStats,
    TaskLedger,
)


@dataclass(frozen=True)
class CommitResult:
    revision: int
    ledger: TaskLedger


@dataclass(frozen=True)
class WorkerRunResult:
    trace_id: str
    status: str
    summary: str = ""
    error: Optional[str] = None
    execution_stats: Optional[ExecutionStats] = None


@dataclass(frozen=True)
class ValidatorRunResult:
    trace_id: str
    status: str
    summary: str = ""
    error: Optional[str] = None
    execution_stats: Optional[ExecutionStats] = None


class TaskStore(Protocol):
    async def load(self, root_trace_id: str) -> TaskLedger: ...
    async def commit(
        self,
        ledger: TaskLedger,
        expected_revision: int,
        idempotency_key: Optional[str] = None,
        event: Optional[EventDraft] = None,
    ) -> CommitResult: ...
    async def list_events(
        self,
        root_trace_id: str,
        cursor: Optional[str] = None,
        limit: int = 100,
    ) -> EventPage: ...
    async def list_recoverable(self, root_trace_id: str) -> List[BackgroundOperation]: ...


class ArtifactStore(Protocol):
    async def freeze(
        self,
        root_trace_id: str,
        attempt_id: str,
        submission: AttemptSubmission,
    ) -> ArtifactSnapshot: ...
    async def get(self, root_trace_id: str, snapshot_id: str) -> ArtifactSnapshot: ...
    async def get_for_attempt(self, root_trace_id: str, attempt_id: str) -> Optional[ArtifactSnapshot]: ...
    async def list_orphans(
        self,
        root_trace_id: str,
        known_attempt_ids: Sequence[str],
    ) -> List[ArtifactSnapshot]: ...
    async def cleanup_orphans(
        self,
        root_trace_id: str,
        known_attempt_ids: Sequence[str],
    ) -> List[str]: ...


class AgentExecutor(Protocol):
    async def run_worker(self, context: Dict[str, Any]) -> WorkerRunResult: ...
    async def run_validator(self, context: Dict[str, Any]) -> ValidatorRunResult: ...
    async def stop(self, trace_id: str) -> bool: ...


class ToolPolicy(Protocol):
    def resolve(self, config: Any, preset: Any, registry: Any) -> Any: ...
    def authorize(self, role: Any, tool_name: str, resolved_policy: Any) -> Any: ...


class EventSink(Protocol):
    async def emit(self, root_trace_id: str, event_type: str, payload: Dict[str, Any]) -> None: ...


__all__ = [
    "CommitResult", "WorkerRunResult", "ValidatorRunResult", "TaskStore",
    "ArtifactStore", "AgentExecutor", "ToolPolicy", "EventSink",
]