Real-time Data Streaming (SSE)

Relevant source files

The following files were used as context for generating this wiki page:

• ARCHITECTURE.md
• README.md
• packages/server/src/server.ts
• packages/headless/src/cli.ts
• packages/app/src/app/components/part-view.tsx
• packages/app/progress.json

Real-time Data Streaming in OpenWork is implemented using Server-Sent Events (SSE) to provide a responsive, live-updating user interface. This system allows the OpenWork UI to receive asynchronous updates from the OpenCode engine regarding session progress, tool executions, and state changes without constant polling.

The primary purpose of this streaming architecture is to drive high-fidelity UI features such as streaming assistant responses, step-level tool execution timelines, and immediate permission prompts. This ensures that the application meets performance targets of less than 100ms interaction latency and zero blocking spinners.
Sources: ARCHITECTURE.md:83-91, PRODUCT.md:57-61, README.md:83-88

Architecture and Data Flow

OpenWork utilizes the @opencode-ai/sdk/v2/client to establish SSE subscriptions. The flow originates from the OpenCode server, which emits events that the OpenWork UI consumes to update its internal state.

Streaming Pipeline

The following diagram illustrates the lifecycle of a real-time event from the engine to the user interface:

The UI subscribes to events using client.event.subscribe(), which handles the connection to the /event endpoint on the OpenCode server.
Sources: ARCHITECTURE.md:83-91, README.md:143-149

Event Types and UI Mapping

The streaming system handles several critical event categories that dictate the behavior of the frontend:

Event Type	UI Impact	Source File
Streaming Responses	Renders incremental text in chat bubbles.	ARCHITECTURE.md:86
Tool Execution	Updates the step-level timeline and progress bars.	ARCHITECTURE.md:87
Permission Requests	Triggers modal prompts for user approval.	ARCHITECTURE.md:88
Lifecycle Changes	Updates session status (running, completed, failed).	ARCHITECTURE.md:89

Backend Implementation

The OpenWork server and headless CLI manage the underlying connections to the OpenCode engine's event stream. In host mode, OpenWork spawns opencode serve, which provides the SSE source.

Event Polling and Cursor Management

The server implementation includes a ReloadEventStore to track and serve events to clients with cursor support, allowing clients to resume streams or catch up on missed updates.

Implementation Detail: Headless CLI Check

The headless CLI performs health checks by explicitly verifying that SSE events are being observed during a test session.

if (input.checkEvents) {
  const events: { type: string }[] = [];
  const controller = new AbortController();
  const subscription = await input.opencodeClient.event.subscribe(undefined, { signal: controller.signal });
  // ... reader logic
  if (!events.length) {
    throw new Error("No SSE events observed during check");
  }
}

Sources: packages/headless/src/cli.ts:553-575

Frontend Rendering (PartView)

The PartView component is the primary consumer of streamed data, responsible for rendering different types of "parts" (text, tool, file, reasoning) as they arrive via the SSE stream.

Throttled Rendering

To maintain 60fps performance and avoid UI "jank" during high-frequency text streaming, the system uses throttled values for markdown rendering.
Sources: packages/app/src/app/components/part-view.tsx:18-40, PRODUCT.md:58-61

Tool Timeline State Mapping

When tool type parts are streamed, the UI maps their internal states to specific visual components:

Tool State	UI Representation
running	Blue status badge, active progress indicators.
completed	Green status badge, result output or diff view.
error	Red status badge, error message display.
Sources: packages/app/src/app/components/part-view.tsx:288-301

Key API Endpoints

The streaming infrastructure relies on the following endpoints provided by the OpenWork server and the OpenCode engine:

• GET /workspace/:id/events: Client-facing endpoint to retrieve workspace-specific events with a since cursor. Sources: packages/server/src/server.ts:221-228
• client.event.subscribe(): SDK method used by the UI to open the SSE connection. Sources: ARCHITECTURE.md:91

Conclusion

Real-time Data Streaming (SSE) is the backbone of the OpenWork "Premium UX," enabling the application to feel like a live, collaborative environment rather than a static command-line wrapper. By leveraging cursors on the server and throttled rendering on the frontend, the system balances technical accuracy with high-performance UI requirements.
Sources: packages/app/progress.json:20-24, PRODUCT.md:33-35