| 1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283 |
- """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",
- ]
|