stream_events.py 2.6 KB

1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283
  1. """Structured streaming events — the agent→gateway delivery contract.
  2. Typed *what happened* events (frozen dataclasses, no I/O) emitted from the agent's
  3. worker thread; ``GatewayStreamConsumer`` is the sink and the adapter decides rendering.
  4. Events describe *transport*, never *context*: whatever the gateway "eats" must never
  5. diverge from the agent-owned message history.
  6. """
  7. from __future__ import annotations
  8. from dataclasses import dataclass, field
  9. from typing import Any, Dict, Optional, Union
  10. @dataclass(frozen=True)
  11. class MessageChunk:
  12. """A delta of streamed assistant text (think-block content is filtered upstream)."""
  13. text: str
  14. @dataclass(frozen=True)
  15. class MessageStop:
  16. """Assistant text segment complete. ``final`` only for the turn's terminal stop; an
  17. intermediate stop (text → tool → text) starts a fresh segment below tool chrome."""
  18. final: bool = False
  19. @dataclass(frozen=True)
  20. class Commentary:
  21. """A complete interim assistant message between tool iterations (not a delta)."""
  22. text: str
  23. @dataclass(frozen=True)
  24. class ToolCallChunk:
  25. """A tool invocation started. Raw facts only; the adapter decides presentation."""
  26. tool_name: str
  27. preview: Optional[str] = None
  28. args: Optional[dict[str, Any]] = None
  29. index: int = 0 # monotonic per-turn index: correlates a finish with its start
  30. @dataclass(frozen=True)
  31. class ToolCallFinished:
  32. """A tool invocation completed (drives bubble settling + LongToolHint). Tool *output*
  33. never travels here — it is history."""
  34. tool_name: str
  35. duration: float = 0.0 # wall-clock seconds
  36. ok: bool = True # returned without raising
  37. index: int = 0
  38. @dataclass(frozen=True)
  39. class LongToolHint:
  40. """One-shot onboarding nudge for a long tool run; the gateway gates it on platform
  41. capability (/verbose usable) and first-time use."""
  42. tool_name: str = ""
  43. duration: float = 0.0
  44. @dataclass(frozen=True)
  45. class GatewayNotice:
  46. """Gateway-originated control message; ``kind`` is a stable string adapters switch on
  47. (``"restart"`` / ``"online"`` / ``"long_run"`` / …), ``text`` the default rendering."""
  48. kind: str
  49. text: str = ""
  50. extra: dict[str, Any] = field(default_factory=dict)
  51. # Explicit union (not a marker base class) so a missing ``case`` in an
  52. # exhaustive match is a visible type error rather than a silent fall-through.
  53. StreamEvent = MessageChunk | MessageStop | Commentary | ToolCallChunk | ToolCallFinished | LongToolHint | GatewayNotice
  54. __all__ = [
  55. "Commentary",
  56. "GatewayNotice",
  57. "LongToolHint",
  58. "MessageChunk",
  59. "MessageStop",
  60. "StreamEvent",
  61. "ToolCallChunk",
  62. "ToolCallFinished",
  63. ]