"""Stream event types for token-level streaming.

The discriminated union ``StreamEvent`` is yielded by ``Session.stream()``
as LLM tokens arrive and tools execute.
"""

from __future__ import annotations

from typing import Annotated, Literal

from pydantic import BaseModel, Field


class TokenDelta(BaseModel):
    """Incremental LLM text token."""

    type: Literal["token"] = "token"
    content: str


class ToolCallStarted(BaseModel):
    """A tool call has begun executing."""

    type: Literal["tool_start"] = "tool_start"
    tool_name: str
    tool_call_id: str


class ToolCallCompleted(BaseModel):
    """A tool call has finished."""

    type: Literal["tool_done"] = "tool_done"
    tool_call_id: str
    tool_name: str
    output: str
    success: bool = True


class TurnComplete(BaseModel):
    """The full turn has completed — carries the final ``ExecutionResult``."""

    type: Literal["done"] = "done"
    result: object  # ExecutionResult (avoid circular import at module level)


StreamEvent = Annotated[
    TokenDelta | ToolCallStarted | ToolCallCompleted | TurnComplete,
    Field(discriminator="type"),
]

__all__ = [
    "StreamEvent",
    "TokenDelta",
    "ToolCallCompleted",
    "ToolCallStarted",
    "TurnComplete",
]
