Sessions & Tasks Management
Relevant source files
The following files were used as context for generating this wiki page:
Sessions and Tasks Management forms the core execution engine of OpenWork. In this system, a Task represents a user-described outcome, while a Run or Session represents the actual execution lifecycle, encompassing the event stream, tool calls, and plan updates derived from the OpenCode engine. The system is designed to provide a premium, mobile-first experience that abstracts complex terminal interactions into a visual timeline of steps, artifacts, and audit logs.
OpenWork maps every "Task Run" directly to an OpenCode Session primitive, utilizing a real-time Server-Sent Events (SSE) subscription to drive UI updates such as assistant responses and permission prompts.
Sources: PRODUCT.md:17-21, ARCHITECTURE.md:46-47, ARCHITECTURE.md:58-60
Session Lifecycle and State
A session transitions through multiple internal phases during its execution. The UI tracks these phases to provide immediate feedback to the user via "Thinking," "Sending," and "Responding" indicators.
Execution Phases
| Phase | Description |
|---|---|
| Idle | The session is inactive, awaiting user input. |
| Sending | The prompt is being transmitted to the engine. |
| Thinking | The engine is processing context, tools, or reasoning parts. |
| Responding | The assistant is actively streaming text or tool outputs to the UI. |
| Completed | The task has reached a successful outcome. |
| Failed | The engine encountered an unrecoverable error during execution. |
Sources: packages/app/src/app/pages/session.tsx:289-305, packages/app/src/app/pages/dashboard.tsx:55-58
State Transition Flow
The following diagram illustrates how a session moves from a user prompt to a completed state, incorporating the asynchronous response loop.
The diagram shows the iterative nature of the OpenCode engine where tool calls may transition the state back to "Thinking" multiple times before reaching a final result.
Sources: packages/app/src/app/pages/session.tsx:290-310, ARCHITECTURE.md:62-67
Core Primitives: Plans, Steps, and Artifacts
OpenWork treats tasks as structured data, moving beyond simple chat interfaces to expose the underlying engine logic.
1. Plans and Todo Lists
A Plan is a structured artifact (JSON) generated before or during execution. It contains a list of todo items that the UI mirrors to show progress. Plans are editable and updated in real-time with step statuses and timestamps.
Sources: PRODUCT.md:23-29, packages/app/src/app/pages/session.tsx:107
2. Steps
Every tool call initiated by the engine becomes a Step in the UI timeline. Each step includes:
- Tool name (e.g.,
bash,edit,webfetch). - Arguments summary and permission state.
- Output preview or error details.
Sources: PRODUCT.md:33-39, packages/app/src/app/pages/session.tsx:325-345
3. Artifacts
Artifacts are the user-visible outputs of a session, such as files created, modified documents, or exported summaries. OpenWork tracks these per run and supports desktop-native actions like "Open" or "Reveal in Finder."
Sources: PRODUCT.md:41-46, packages/app/src/app/pages/session.tsx:115
SDK Integration and API Routes
The management of sessions relies on the @opencode-ai/sdk/v2 for client-side operations and Bun-based routes for server-side persistence and auditing.
Key SDK Methods
| Method | Description |
|---|---|
session.create() | Initializes a new execution context. |
session.prompt() | Sends user instructions to the session. |
session.abort() | Terminates an active run. |
session.summarize() | Generates a structured summary artifact of the session. |
session.list() | Retrieves session history for the current workspace. |
Sources: ARCHITECTURE.md:69-75, AGENTS.md:61-64
Server-Side Session Management
The server manages session persistence and workspace activation through dedicated API endpoints.
This sequence shows the activation of a workspace before session creation, ensuring that tasks run within the correct authorized folder context.
Sources: packages/server/src/server.ts:182-198, packages/app/src/app/pages/session.tsx:555-570
Security and Permissions
Sessions are bound by a strict folder authorization model. OpenWork enforces two layers of security:
- UI Authorization: The user selects allowed roots via a native folder picker.
- Engine Permissions: The OpenCode engine requests specific permissions for filesystem or network access via
client.permission.reply.
When a session requires a sensitive action, it enters a "Permission Required" state. The user must explicitly choose:
- Allow Once: One-time permission for the specific tool call.
- Allow for Session: Persistent permission for the current session ID only.
- Deny: Rejects the request, potentially causing the task to fail gracefully.
Sources: ARCHITECTURE.md:129-145, packages/app/src/app/pages/session.tsx:840-880, PRODUCT.md:85-89
Audit Logging
Every session run generates an exportable audit log to ensure transparency. This log is stored as an artifact and includes:
- User prompts and engine plans.
- A full timeline of tool calls.
- Permission decisions made by the user.
- Final outputs and modified file paths.
Sources: PRODUCT.md:48-53, packages/server/src/server.ts:213-220