`gjdZddlmZddlmZmZddlmZmZm Z m Z edGddZ edGd d Z edGd d Z edGd dZedGddZedGddZedGddZe e e e eeeefZgdZy)uStructured streaming events — the agent→gateway delivery contract. Historically the agent drove gateway delivery through a fan of loosely-typed callbacks (``stream_delta_callback(text)``, ``tool_progress_callback(event_type, tool_name, preview, args)``, ``interim_assistant_callback(text)`` …) and each gateway callback decided *both* what to render and how to send it. That coupling is why tool-progress bubbles and the streaming draft raced each other on Telegram, and why tool-call formatting lived agent-side even though only the gateway knows what a given platform can render. This module defines a small, typed event vocabulary that names *what happened* without prescribing *how it is delivered*. The gateway's stream consumer (``GatewayStreamConsumer``) is the single sink; the platform adapter decides how to render each event (Telegram can stream a MarkdownV2 ```bash``` block as a native draft; iMessage has no rich formatting and may collapse or drop tool chrome). Separation of concerns: smart agent emits structured data, smart gateway decides delivery. These are intentionally plain frozen dataclasses — no behavior, no platform knowledge, no I/O. They are cheap to construct on the agent's worker thread and safe to hand across the thread/async boundary into the consumer queue. Design constraints (see hermes-agent-dev skill — message-flow + cache invariants): * Events describe *transport*, never *context*. Nothing here is persisted to conversation history; what the gateway chooses to "eat" (e.g. tool chrome on a platform that can't render it) must never diverge from the bytes stored in the agent's message history. History is owned by the agent; these events are a presentation-layer stream only. * Backward compatible by construction. The gateway adapts its existing callbacks into these events at the boundary; adapters that don't opt into event-native rendering get identical behavior via the base-class default. ) annotations) dataclassfield)AnyDictOptionalUnionT)frozenceZdZUdZded<y) MessageChunkaMA delta of streamed assistant text. ``text`` is the incremental content as it arrives from the model. The consumer accumulates chunks and progressively renders them (native draft on Telegram DMs, edit-in-place elsewhere). Reasoning/think-block content is filtered upstream and never arrives as a MessageChunk. strtextN__name__ __module__ __qualname____doc____annotations__H/root/.hermes/venv/lib/python3.12/site-packages/gateway/stream_events.pyr r +s Irr c eZdZUdZdZded<y) MessageStopu"The current assistant message segment is complete. Emitted when a contiguous run of assistant text ends — either the whole response finished, or a tool boundary interrupts the text so the next segment should render as a fresh message *below* any tool chrome. ``final`` is True only for the terminal stop of the whole turn; an intermediate stop (text → tool call → more text) carries ``final=False`` so the consumer finalizes the current bubble and prepares a new segment without treating the turn as done. FboolfinalN)rrrrrrrrrrr7s E4rrceZdZUdZded<y) Commentarya9A complete interim assistant message emitted between tool iterations. Example: the model says "I'll inspect the repo first." before issuing a tool call. Unlike a MessageChunk this is already-complete text (not a delta); the consumer renders it as its own message so it reads as a distinct beat. r rNrrrrrrGs IrrcFeZdZUdZded<dZded<dZded<d Zd ed <y) ToolCallChunkuA tool invocation has started (or its in-progress state changed). Carries the raw facts about the call — name, a short argument ``preview``, and the full ``args`` dict — and lets the *gateway* decide presentation (emoji, truncation, verbose vs compact, or eat it entirely on platforms that don't show tool chrome). Previously the agent's gateway callback baked the emoji + preview formatting in; that decision now belongs to the adapter. r tool_nameNz Optional[str]previewzOptional[Dict[str, Any]]argsrintindex)rrrrrr!r"r$rrrrrTs.N!G]!%)D ")E3NrrcFeZdZUdZded<dZded<dZded <d Zd ed <y )ToolCallFinisheduA tool invocation completed. ``duration`` is wall-clock seconds. ``ok`` reflects whether the tool returned without raising. The gateway uses this to clear/settle a progress bubble and to drive one-time onboarding hints (e.g. suggest /verbose after a long tool run). No tool *output* travels here — output is the agent's concern and is persisted to history, not streamed as presentation. r r floatdurationTrokrr#r$N)rrrrrr)r*r$rrrr&r&gs*NHeBOE3Nrr&c.eZdZUdZdZded<dZded<y) LongToolHintaMOne-shot onboarding nudge when a tool runs longer than the threshold. The gateway gates this on platform capability (the /verbose command must be usable) and on the user not having seen the hint before. Modeled as an event so the *gateway* owns the "should I surface this here?" decision rather than the agent. r r r'r(r)N)rrrrr rr)rrrr,r,ysIsHerr,cFeZdZUdZded<dZded<eeZded<y ) GatewayNoticeu>A gateway-originated control message (restart, online, long-run notice). ``kind`` is a stable string the adapter can switch on (``"restart"`` / ``"online"`` / ``"long_run"`` / …). ``text`` is the human-readable default the base class renders when an adapter has no platform-specific treatment. r kindr-r)default_factoryzDict[str, Any]extraN) rrrrrrrdictr2rrrr/r/s& ID#N!$7E>7rr/)r rrrr&r,r/ StreamEventN)r __future__r dataclassesrrtypingrrrr r rrrr&r,r/r4__all__rrrr9s D#(--  $ $    $ $$ $   " $    $ 8 8 8    r