Frontend State Management
Relevant source files
The following files were used as context for generating this wiki page:
Introduction
Frontend state management in Agent Cowork is primarily handled through a centralized store built with Zustand. This system manages the lifecycle of AI collaboration sessions, tracking everything from real-time message streams and tool-use permissions to application-level UI states like modal visibility and global error handling.
The architecture ensures that the React frontend remains synchronized with the Electron backend's IPC events. By utilizing a reactive store, components across the application—such as the Sidebar, PromptInput, and MessageWindow—can access and modify session data consistently without complex prop-drilling.
Sources: src/ui/store/useAppStore.ts, README_ZH.md:120-125
Core Store Architecture
The application state is encapsulated in the useAppStore, which maintains a registry of sessions and various UI control flags. The state is structured to handle asynchronous updates from the backend, specifically through the handleServerEvent reducer-like function.
Session Data Model
Each session is represented as a SessionView object, which tracks the conversation history and metadata.
| Field | Type | Description |
|---|---|---|
id | string | Unique identifier for the session. |
title | string | Generated or user-defined title for the task. |
status | SessionStatus | Current state (idle, running, completed, error). |
messages | StreamMessage[] | Array of all messages in the conversation. |
permissionRequests | PermissionRequest[] | Pending tool-use authorizations from the AI. |
hydrated | boolean | Indicates if history has been loaded from the database. |
Sources: src/ui/store/useAppStore.ts:10-22, src/ui/store/useAppStore.ts:46-48
State Management Flow
The following diagram illustrates how the store interacts with UI components and the Electron IPC layer to manage state updates.
The flow ensures that any event originating from the backend (like a new stream chunk) is funneled through the store before being rendered.
Sources: src/ui/App.tsx:75-78, src/ui/store/useAppStore.ts:85-188
Session Lifecycle Management
Initialization and Hydration
When the application starts or a session is selected, the store manages the retrieval of historical data. The activeSessionId determines which session's messages are currently visible. If a session is selected but not yet "hydrated," the UI triggers a session.history request to the backend.
Sources: src/ui/App.tsx:115-121, src/ui/store/useAppStore.ts:121-131
Real-time Streaming
Real-time interaction with the Claude Agent SDK is handled via stream events. The store appends new message blocks or updates user prompts as they arrive.
Tool Permission State
A critical aspect of the state management is handling permission.request events. When the AI attempts to use a tool (e.g., Bash, Edit), the store intercepts the request and populates the permissionRequests array for the specific session.
- Request Capture: The
handleServerEventfunction pushes new requests into the session view. - Resolution: The
resolvePermissionRequestaction removes the request from the store once the user provides an "Allow" or "Deny" response via theDecisionPanel.
Sources: src/ui/store/useAppStore.ts:181-193, src/ui/components/DecisionPanel.tsx:129-145, src/ui/store/useAppStore.ts:65-79
UI Control State
The store also manages global UI elements that are independent of specific sessions:
- Prompt Management: Tracks the current input text in the
promptstate and the targetcwd(current working directory). - Modal Visibility: Boolean flags like
showStartModalandshowSettingsModalcontrol the visibility of configuration overlays. - Error Handling: The
globalErrorstate displays toast notifications for runner errors or validation failures.
Sources: src/ui/store/useAppStore.ts:30-44, src/ui/components/PromptInput.tsx:18-24
Summary
The frontend state management system provides a robust backbone for the Agent Cowork desktop experience. By centralizing session data and tool permissions in a Zustand store, the application maintains a consistent view of complex AI interactions, ensuring that long-running tasks, streaming outputs, and user interventions are handled predictably across the React component tree.