@@ -95,12 +95,25 @@ func (c *ExperimentalClient) CreateTask(ctx context.Context, user string, reques
9595type TaskStatus string
9696
9797const (
98- TaskStatusPending TaskStatus = "pending"
98+ // TaskStatusPending indicates the task has been created but no workspace
99+ // has been provisioned yet, or the workspace build job status is unknown.
100+ TaskStatusPending TaskStatus = "pending"
101+ // TaskStatusInitializing indicates the workspace build is pending/running,
102+ // the agent is connecting, or apps are initializing.
99103TaskStatusInitializing TaskStatus = "initializing"
100- TaskStatusActive TaskStatus = "active"
101- TaskStatusPaused TaskStatus = "paused"
102- TaskStatusUnknown TaskStatus = "unknown"
103- TaskStatusError TaskStatus = "error"
104+ // TaskStatusActive indicates the task's workspace is running with a
105+ // successful start transition, the agent is connected, and all workspace
106+ // apps are either healthy or disabled.
107+ TaskStatusActive TaskStatus = "active"
108+ // TaskStatusPaused indicates the task's workspace has been stopped or
109+ // deleted (stop/delete transition with successful job status).
110+ TaskStatusPaused TaskStatus = "paused"
111+ // TaskStatusUnknown indicates the task's status cannot be determined
112+ // based on the workspace build, agent lifecycle, or app health states.
113+ TaskStatusUnknown TaskStatus = "unknown"
114+ // TaskStatusError indicates the task's workspace build job has failed,
115+ // or the workspace apps are reporting unhealthy status.
116+ TaskStatusError TaskStatus = "error"
104117)
105118
106119func AllTaskStatuses () []TaskStatus {
@@ -121,10 +134,18 @@ type TaskState string
121134
122135// TaskState enums.
123136const (
124- TaskStateWorking TaskState = "working"
125- TaskStateIdle TaskState = "idle"
137+ // TaskStateWorking indicates the AI agent is actively processing work.
138+ // Reported when the agent is performing actions or the screen is changing.
139+ TaskStateWorking TaskState = "working"
140+ // TaskStateIdle indicates the AI agent's screen is stable and no work
141+ // is being performed. Reported automatically by the screen watcher.
142+ TaskStateIdle TaskState = "idle"
143+ // TaskStateComplete indicates the AI agent has successfully completed
144+ // the task. Reported via the workspace app status.
126145TaskStateComplete TaskState = "complete"
127- TaskStateFailed TaskState = "failed"
146+ // TaskStateFailed indicates the AI agent reported a failure state.
147+ // Reported via the workspace app status.
148+ TaskStateFailed TaskState = "failed"
128149)
129150
130151// Task represents a task.