"""Structured streaming events — the agent→gateway delivery contract. Typed *what happened* events (frozen dataclasses, no I/O) emitted from the agent's worker thread; ``GatewayStreamConsumer`` is the sink and the adapter decides rendering. Events describe *transport*, never *context*: whatever the gateway "eats" must never diverge from the agent-owned message history. """ from __future__ import annotations from dataclasses import dataclass, field from typing import Any, Dict, Optional, Union @dataclass(frozen=True) class MessageChunk: """A delta of streamed assistant text (think-block content is filtered upstream).""" text: str @dataclass(frozen=True) class MessageStop: """Assistant text segment complete. ``final`` only for the turn's terminal stop; an intermediate stop (text → tool → text) starts a fresh segment below tool chrome.""" final: bool = False @dataclass(frozen=True) class Commentary: """A complete interim assistant message between tool iterations (not a delta).""" text: str @dataclass(frozen=True) class ToolCallChunk: """A tool invocation started. Raw facts only; the adapter decides presentation.""" tool_name: str preview: Optional[str] = None args: Optional[dict[str, Any]] = None index: int = 0 # monotonic per-turn index: correlates a finish with its start @dataclass(frozen=True) class ToolCallFinished: """A tool invocation completed (drives bubble settling + LongToolHint). Tool *output* never travels here — it is history.""" tool_name: str duration: float = 0.0 # wall-clock seconds ok: bool = True # returned without raising index: int = 0 @dataclass(frozen=True) class LongToolHint: """One-shot onboarding nudge for a long tool run; the gateway gates it on platform capability (/verbose usable) and first-time use.""" tool_name: str = "" duration: float = 0.0 @dataclass(frozen=True) class GatewayNotice: """Gateway-originated control message; ``kind`` is a stable string adapters switch on (``"restart"`` / ``"online"`` / ``"long_run"`` / …), ``text`` the default rendering.""" kind: str text: str = "" extra: dict[str, Any] = field(default_factory=dict) # Explicit union (not a marker base class) so a missing ``case`` in an # exhaustive match is a visible type error rather than a silent fall-through. StreamEvent = MessageChunk | MessageStop | Commentary | ToolCallChunk | ToolCallFinished | LongToolHint | GatewayNotice __all__ = [ "Commentary", "GatewayNotice", "LongToolHint", "MessageChunk", "MessageStop", "StreamEvent", "ToolCallChunk", "ToolCallFinished", ]