State Management
Relevant source files
The following files were used as context for generating this wiki page:
State management in this project is decentralized into specialized stores using Zustand for client-side reactivity and real-time synchronization. The system distinguishes between long-form conversational history (transcripts), immediate live session feedback (voice/UI metrics), and tool execution states.
The architecture is designed to handle high-frequency updates from on-device voice engines and streaming LLM responses while maintaining visual synchronization across the UI.
Sources: apps/web/src/lib/chatStore.ts, apps/web/src/lib/live/liveStore.ts, apps/web/src/lib/live/useLiveSession.ts
Transcript and Message State
The chatStore manages the transcript of active and past conversations. It is optimized for the "Live" experience, where assistant turns are not just static text but a sequence of interleaved parts including reasoning, tool usage, and spoken responses.
Data Structure: ChatMsg and Parts
The store represents an assistant's response as an ordered list of Part objects. This allows the UI to render the turn exactly as it occurred chronologically.
| Part Type | Description | Content |
|---|---|---|
text | Spoken response | The literal string spoken or being spoken. |
reasoning | Internal LLM logic | Thought process/hidden reasoning from the model. |
tool | Execution data | Tool name, summary of arguments, and status (done/pending). |
Sources: apps/web/src/lib/chatStore.ts:16-29
Live Update Flow
The useLiveSession hook drives the chatStore imperatively during a call. Unlike standard chat applications, the spoken text is set word-by-word, paced to the actual Voice Engine output rather than the LLM generation stream.
Live Session State
The liveStore (accessed via useLiveStore) handles the volatile state of an active call. This includes device configurations, download progress for on-device models, and real-time feedback like user captions and "Study Tutor" status.
Store Properties
| Property | Type | Usage |
|---|---|---|
phase | LivePhase | Current state: idle, listening, thinking, speaking, etc. |
userCaption | string | Interim/Final transcript from on-device STT. |
agentCaption | string | The current sentence being voiced by the assistant. |
warming | boolean | Indicates if the on-device voice model is initializing. |
tutorStatus | string | Tracks if the tutor is "watching" or "observing" the screen. |
Sources: apps/web/src/lib/live/liveStore.ts, apps/web/src/lib/live/useLiveSession.ts:40-45
Phase Management
The session transitions through various phases managed by the VoiceEngine and LiveClient. The state updates drive the central "Orb" visualization and the status labels in the UI.
Tool and Delegate State
State regarding tool execution is handled through SSE (Server-Sent Events). The main agent can delegate tasks to worker subagents, which run their own tool loops (e.g., web_search).
Execution State Tracking
When a tool starts, the system emits a tool_start event containing a unique ID and a summary. This is folded into the chatStore as a tool part with done: false. When completed, a tool_done event updates that specific part with details and marks it finished.
Persistence and Rehydration
While session state is volatile, the chatStore supports preload functionality to seed transcripts from saved conversation history. This process reconstructs the interleaved parts (text and tools) from a standard message content array.
Key rehydration logic:
- User Messages: Filters for text blocks and joins them.
- Assistant Messages: Iterates through content blocks;
textblocks become text parts, andtoolblocks become completed tool parts.
Sources: apps/web/src/lib/chatStore.ts:88-111
Conclusion
State management in this system is a hybrid of imperative updates for high-precision synchronization (voice-to-text) and reactive store updates for UI consistency. By separating conversation history (chatStore) from ephemeral session data (liveStore), the application maintains performance during intensive AI tasks like on-device STT/TTS and multi-agent tool delegation.