Session & Chat Mechanics
Relevant source files
The following files were used as context for generating this wiki page:
Session and Chat Mechanics in OpenWork encompass the lifecycle of agentic workflows, ranging from prompt submission and event-driven streaming to transcript persistence and artifact resolution. The system is built on a React-based domain architecture that communicates with an OpenCode server to manage local-first, agentic task execution.
Core Architecture and Data Flow
The session mechanics are governed by a domain-driven React architecture where domains/session/ owns the route frame, status bar, and transcript surfaces. Data flow is primarily managed through ReactSessionRuntime, which subscribes to an OpenCode event stream to populate local transcript caches.
The following diagram illustrates the interaction between the User Interface, the React Session Runtime, and the OpenCode Server:
Key Components
| Component | Description |
|---|---|
SessionSurface | The primary React component managing the transcript, composer, and status for a specific session. |
ReactSessionRuntime | Subscribes to OpenCode event streams and synchronizes the local TanStack Query cache. |
Composer | A Lexical-based editor handling multi-line text, mentions, and "paste chips" for large text blocks. |
OpenCode Client | The underlying SDK used to interact with the workspace filesystem and session API. |
Sources: apps/app/src/react-app/ARCHITECTURE.md, apps/app/src/react-app/domains/session/surface/session-surface.tsx:80-120, evals/react-session-flows.md:360-370
Message and Streaming Mechanics
Streaming in OpenWork uses Server-Sent Events (SSE) to provide progressive updates to the assistant's responses. The SessionSurface tracks an "awaiting assistant baseline" to determine when the assistant has started responding and transitions the UI through various activity states.
Session Activity States
- Thinking: The model is processing or reasoning before generating output.
- Responding: The assistant is actively streaming text or tool calls.
- Idle/Ready: The session is awaiting user input.
- Busy/Running: A general state for active execution.
Sources: apps/app/src/react-app/domains/session/surface/session-surface.tsx:244-255, apps/server/src/toy-ui.ts:460-480
Prompt Submission Logic
When a user clicks "Run task", the system builds a ComposerDraft containing text parts, attachments, and command metadata. This is sent to the /prompt_async endpoint. To handle follow-up messages while the agent is busy, the client maintains a local queuedDrafts array, which is merged and sent as a single message once the session returns to an idle state.
Artifact and File Resolution
A critical mechanic of the session is identifying and resolving "artifacts"—files or URLs mentioned by the agent during execution. The server provides a /workspace/:workspaceId/artifacts/resolve endpoint to verify the existence and preview type of these targets.
Target Classification
The system extracts targets from live transcript messages and classifies them based on their extension or protocol:
- Sheet:
.csv,.xlsx - Markdown:
.md - HTML:
.html(sandboxed preview) - Browser:
http://,ws://
Workspace Integration
Sessions are strictly scoped to workspaces. Every session interaction relies on a workspaceId derived from the URL or application state.
Session Lifecycle API
| Endpoint | Method | Description |
|---|---|---|
/w/:id/opencode/session | POST | Creates a new session in the specified workspace. |
/w/:id/opencode/session/:sid/prompt_async | POST | Submits a prompt to an existing session. |
/workspace/:id/sessions/:sid | DELETE | Permanently removes a session and its transcript. |
/w/:id/opencode/event | GET | Connects to the SSE stream for workspace and session events. |
Sources: apps/server/src/toy-ui.ts:310-330, apps/server/src/toy-ui.ts:450-480, apps/app/src/react-app/ARCHITECTURE.md
Keyboard and Command Palette Mechanics
OpenWork provides keyboard-driven mechanics for session management:
- Cmd+N / Ctrl+N: Instantly creates a new session in the current workspace and focuses the composer.
- Cmd+K / Ctrl+K: Opens the Command Palette, allowing users to search sessions across all workspaces or navigate to settings.
- Slash Commands: Typing
/in the composer triggers a menu of fuzzy-matched commands (e.g.,/review,/init). Selecting a command creates a "purple pill" chip in the composer that is removed atomically on backspace.
Sources: evals/react-session-flows.md:210-230, evals/react-session-flows.md:320-335
Summary
Session & Chat Mechanics in OpenWork provide a robust framework for asynchronous agent interaction. By combining SSE-based streaming, a persistent TanStack Query transcript cache, and deterministic artifact resolution, the system ensures that complex agentic tasks are visible and manageable within a local-first desktop environment. Performance and stability are maintained through mechanisms like draft queuing and atomic command handling.