Concepts
Sessions and timeline
How sessions, acts, items, drafts, and semantic timeline entries relate.
Work in progress. This documentation is actively being written and may change.
A session is the conversation resource. Its history is composed of acts and items; an active response can also have drafts and live overlays. The UI should render the semantic output of useTimeline(sessionId) rather than rebuilding a timeline from raw session items.
This boundary preserves ordering, tool grouping, reasoning visibility, background-task state, and the distinction between persisted history and the active streaming turn.
Use the right layer
@hyperflow/client: wire-level session data and WebSocket events.@hyperflow/react: reconciles events into session state and timeline entries.@hyperflow/chakra-ui: renders the resulting timeline and controls.