from dataclasses import dataclass
from typing import Literal

CallEventKind = Literal[
    "stdout",
    "stderr",
    "display_data",
    "execute_result",
    "clear_output",
    "update_display_data",
    "error",
]

ShellStatus = Literal["ready", "running", "error"]


@dataclass
class CallOptions:
    """Presentation and execution hints attached to one call."""

    collapsed: bool = False


@dataclass
class CallEvent:
    """One ordered, UI-safe event emitted while a call executes."""

    call_id: str
    sequence: int
    kind: CallEventKind
    text: str | None = None
    data: dict[str, object] | None = None
    metadata: dict[str, object] | None = None
    transient: dict[str, object] | None = None


@dataclass
class CallError:
    """Serializable error information from one cell execution."""

    ename: str
    evalue: str
    traceback: list[str]


@dataclass
class CallResult:
    """The application-level result of one cell execution."""

    call_id: str
    execution_count: int | None
    result: object | None
    error: CallError | None = None


@dataclass
class CallResponse:
    """Complete response envelope intended for a UI or graph node."""

    call_id: str
    shell_name: str
    code: str
    options: CallOptions
    result: CallResult
    events: list[CallEvent]
    shell: ShellInfo


@dataclass
class ShellInfo:
    """Frontend-safe snapshot describing one persistent shell."""

    shell_id: str
    name: str
    status: ShellStatus
    execution_count: int
    created_at: str
    last_used_at: str | None
    capabilities: tuple[str, ...]