# CorpusFetch Method Slice (Zero-Prose Python Stdlib Reference)
# Canonical Residual: https://corpusfetch.com/c/when-must-an-instance-treat-an-a2a-v1-0-task-as-terminal-despite-a-peer-advertising-input-required.md
# Remnant Warrant:    https://corpusfetch.com/c/when-must-an-instance-treat-an-a2a-v1-0-task-as-terminal-despite-a-peer-advertising-input-required.warrant.json
# Markdown SHA-256:   d6f4aae603a9b2cde7ca9d0329f6815881fb847e2d6337460203a50abb276af1
# Code AST SHA-256:   3211b18ee62952e152cd325efd699d03240a2502d108e994407b4fe634ff7ef0
# Verified Classes:   InputRequiredMismatchError, TaskDisposition, SkillCard, AgentCard, StatusUpdate
# Defensive Guards:   3 fail-closed invariants (zero external deps)

from __future__ import annotations

from dataclasses import dataclass, field
from enum import Enum


class InputRequiredMismatchError(RuntimeError):
    """Raised when a remote's `input-required` state cannot be resumed by this client."""


class TaskDisposition(Enum):
    RESUMABLE = "resumable"
    OPERATIONALLY_TERMINAL = "operationally_terminal"


@dataclass
class SkillCard:
    skill_id: str
    input_modes: list[str] = field(default_factory=list)


@dataclass
class AgentCard:
    protocol_version: str
    default_input_modes: list[str]
    streaming: bool
    skills: list[SkillCard] = field(default_factory=list)

    def input_modes_for(self, skill_id: str | None) -> list[str]:
        if skill_id is not None:
            for s in self.skills:
                if s.skill_id == skill_id and s.input_modes:
                    return s.input_modes
        return self.default_input_modes


@dataclass
class StatusUpdate:
    state: str
    part_mimes: list[str]  # mimeType / kind coverage of the input-required message
    message_present: bool


def classify_input_required(
    card: AgentCard,
    update: StatusUpdate,
    skill_id: str | None,
    has_continuation_channel: bool,
) -> TaskDisposition:
    if update.state != "input-required":
        return TaskDisposition.RESUMABLE

    if card.protocol_version != "1.0":
        # Out of scope for this record; caller must use v0.x logic.
        return TaskDisposition.RESUMABLE

    if not has_continuation_channel:
        raise InputRequiredMismatchError(
            "task entered input-required but client holds no continuation channel "
            f"(streaming={card.streaming}); task is operationally terminal"
        )

    if not update.message_present:
        allowed = card.input_modes_for(skill_id)
        if not allowed:
            raise InputRequiredMismatchError(
                "input-required status carried no message and card advertises no "
                f"input modes for skill={skill_id!r}; cannot construct continuation"
            )
        return TaskDisposition.RESUMABLE

    allowed = set(card.input_modes_for(skill_id))
    required = set(update.part_mimes)
    if not required.issubset(allowed):
        missing = required - allowed
        raise InputRequiredMismatchError(
            "input-required demands modalities outside the peer's advertised set: "
            f"required={sorted(required)} allowed={sorted(allowed)} "
            f"missing={sorted(missing)} skill={skill_id!r}"
        )

    return TaskDisposition.RESUMABLE
