fix: show progress for workspace actions (#361)

Workspace actions could appear idle while blocking operations were still
running. In particular, the Coder CLI start command can wait for
external authentication, while its detached coroutine returned
immediately and separated the command from the action's progress and
error handling. This was especially confusing when a workspace start
paused for external authentication or when an update, restart, or stop
continued after the initial request had completed.

Toolbox now keeps the environment description in sync with the active
workspace action. Workspace starts display live output from the Coder
CLI, while other ongoing builds use the status and latest provisioner
output retrieved during workspace polling. Once the build finishes, the
normal environment description is restored.

Failures while retrieving progress are recorded without interrupting
workspace monitoring. They retain the SSH session correlation when a
session is available and remain ordinary logs when the workspace has no
active session.

- resolves https://linear.app/codercom/issue/JET-1

Author: fioan89

CHANGELOG.md

@@ -5,6 +5,8 @@
 ### Changed
 
 - upgraded the Toolbox plugin API, dropping support for Toolbox versions older than 3.7.2
+- display live workspace start output from the Coder CLI and poll build status and provisioner output while updating,
+  restarting, or stopping workspaces
 
 ## 0.9.4 - 2026-08-26
 

src/main/kotlin/com/coder/toolbox/CoderRemoteEnvironment.kt

@@ -10,6 +10,7 @@ import com.coder.toolbox.sdk.ex.APIResponseException
 import com.coder.toolbox.sdk.v2.models.NetworkMetrics
 import com.coder.toolbox.sdk.v2.models.Workspace
 import com.coder.toolbox.sdk.v2.models.WorkspaceAgent
+import com.coder.toolbox.sdk.v2.models.WorkspaceStatus
 import com.coder.toolbox.session.SessionId
 import com.coder.toolbox.session.SessionIdRegistry
 import com.coder.toolbox.util.OS
@@ -40,13 +41,23 @@ import kotlinx.coroutines.flow.StateFlow
 import kotlinx.coroutines.flow.update
 import kotlinx.coroutines.isActive
 import kotlinx.coroutines.launch
+import kotlinx.coroutines.withContext
 import kotlinx.coroutines.withTimeout
 import java.io.File
 import java.nio.file.Path
+import kotlin.coroutines.cancellation.CancellationException
 import kotlin.time.Duration.Companion.minutes
 import kotlin.time.Duration.Companion.seconds
 
 private val POLL_INTERVAL = 5.seconds
+private val ANSI_ESCAPE_SEQUENCE = Regex("\u001B\\[[0-?]*[ -/]*[@-~]")
+private val IN_PROGRESS_BUILD_STATUSES = setOf(
+    WorkspaceStatus.PENDING,
+    WorkspaceStatus.STARTING,
+    WorkspaceStatus.STOPPING,
+)
+
+private fun String.stripAnsiEscapeSequences(): String = replace(ANSI_ESCAPE_SEQUENCE, "")
 
 private fun environmentId(workspace: Workspace, agent: WorkspaceAgent?): String =
     agent?.let { "${workspace.name}.${it.name}" } ?: workspace.name
@@ -58,6 +69,20 @@ private fun OS?.displayName(): String = when (this) {
     null -> "unknown-OS"
 }
 
+private fun WorkspaceAndAgentStatus.toEnvironmentDescription(
+    context: CoderToolboxContext,
+): EnvironmentDescription {
+    val buildStatus = workspace.latestBuild.status
+    return if (buildStatus in IN_PROGRESS_BUILD_STATUSES) {
+        EnvironmentDescription.Progress(
+            context.i18n.pnotr("Building ${workspace.name} (${buildStatus.name.lowercase()})…"),
+            indeterminate = true,
+        )
+    } else {
+        EnvironmentDescription.General(context.i18n.pnotr(workspace.templateDisplayName))
+    }
+}
+
 /**
  * Represents a workspace, or a workspace and agent combination when an agent is available.
  *
@@ -80,7 +105,7 @@ class CoderRemoteEnvironment(
     override val state: MutableStateFlow<RemoteEnvironmentState> =
         MutableStateFlow(environmentStatus.toRemoteEnvironmentState(context))
     override val description: MutableStateFlow<EnvironmentDescription> =
-        MutableStateFlow(EnvironmentDescription.General(context.i18n.pnotr(workspace.templateDisplayName)))
+        MutableStateFlow(environmentStatus.toEnvironmentDescription(context))
     override val additionalEnvironmentInformation: MutableMap<LocalizableString, String> = mutableMapOf()
     override val actionsList: MutableStateFlow<List<ActionDescription>> = MutableStateFlow(emptyList())
 
@@ -101,6 +126,24 @@ class CoderRemoteEnvironment(
     internal fun currentSessionId(): SessionId? =
         agent?.let { SessionIdRegistry.findSession(workspace.name, it.name) }
 
+    private suspend fun <T> withProgress(message: String, action: suspend () -> T): T {
+        description.value = EnvironmentDescription.Progress(context.i18n.ptrl(message), indeterminate = true)
+        return try {
+            action()
+        } finally {
+            description.value = environmentStatus.toEnvironmentDescription(context)
+        }
+    }
+
+    private fun showProgress(output: String) {
+        val progressMessage = output.stripAnsiEscapeSequences().trim()
+        if (progressMessage.isEmpty()) return
+        description.value = EnvironmentDescription.Progress(
+            context.i18n.pnotr(progressMessage),
+            indeterminate = true,
+        )
+    }
+
     private fun refreshAvailableActions() {
         val actions = mutableListOf<ActionDescription>()
         context.logger.debug("Refreshing available actions for workspace $id with status: $environmentStatus")
@@ -139,45 +182,64 @@ class CoderRemoteEnvironment(
         if (environmentStatus.canStart()) {
             if (workspace.outdated) {
                 actions.add(Action(context, "Update and start") {
-                    context.logger.debug("Updating and starting $id...")
-                    val build = client.updateWorkspace(workspace)
-                    update(workspace.copy(latestBuild = build), agent)
-                    workspaceRefreshTrigger.trySend(true)
+                    withProgress("Updating and starting workspace…") {
+                        context.logger.debug("Updating and starting $id...")
+                        val build = client.updateWorkspace(workspace)
+                        applyWorkspaceSnapshot(workspace.copy(latestBuild = build), agent)
+                        workspaceRefreshTrigger.trySend(true)
+                    }
                 })
             } else {
                 actions.add(Action(context, "Start") {
-                    context.logger.debug("Starting $id... ")
-                    context.cs
-                        .launch(CoroutineName("Start Workspace Action CLI Runner") + Dispatchers.IO) {
-                            cli.startWorkspace(WorkspaceAddress.from(workspace))
+                    withProgress("Starting workspace…") {
+                        context.logger.debug("Starting $id... ")
+                        val previousStatus = environmentStatus
+                        // The CLI can take a while before Coder reports a new workspace state. Show
+                        // the pending state immediately and remove the Start action in the meantime.
+                        updateStatus(WorkspaceAndAgentStatus.Queued(workspace))
+                        refreshAvailableActions()
+                        var commandSucceeded = false
+                        try {
+                            withContext(Dispatchers.IO) {
+                                cli.startWorkspace(
+                                    WorkspaceAddress.from(workspace),
+                                    showTextProgress = ::showProgress,
+                                )
+                            }
+                            commandSucceeded = true
                             workspaceRefreshTrigger.trySend(true)
+                        } finally {
+                            if (!commandSucceeded) {
+                                updateStatus(previousStatus)
+                                refreshAvailableActions()
+                            }
                         }
-                    // cli takes 15 seconds to move the workspace in queueing/starting state
-                    // while the user won't see anything happening in TBX after start is clicked
-                    // During those 15 seconds we work around by forcing a `Queuing` state
-                    updateStatus(WorkspaceAndAgentStatus.Queued(workspace))
-                    // force refresh of the actions list (Start should no longer be available)
-                    refreshAvailableActions()
+                    }
                 })
             }
         }
         if (environmentStatus.canStop()) {
             if (workspace.outdated) {
                 actions.add(
                     Action(context, "Update and restart") {
-                        context.logger.debug(currentSessionId(), "Updating and re-starting $id...")
-                        val build = client.updateWorkspace(workspace)
-                        update(workspace.copy(latestBuild = build), agent)
-                        workspaceRefreshTrigger.trySend(true)
+                        withProgress("Updating and restarting workspace…") {
+                            context.logger.debug(currentSessionId(), "Updating and re-starting $id...")
+                            val build = client.updateWorkspace(workspace)
+                            applyWorkspaceSnapshot(workspace.copy(latestBuild = build), agent)
+                            workspaceRefreshTrigger.trySend(true)
+                        }
                     }.withCurrentSessionId(::currentSessionId)
                 )
             }
             actions.add(
                 Action(context, "Stop") {
-                    tryStopSshConnection()
-                    context.logger.debug(currentSessionId(), "Stopping $id...")
-                    val build = client.stopWorkspace(workspace)
-                    update(workspace.copy(latestBuild = build), agent)
+                    withProgress("Stopping workspace…") {
+                        tryStopSshConnection()
+                        context.logger.debug(currentSessionId(), "Stopping $id...")
+                        val build = client.stopWorkspace(workspace)
+                        applyWorkspaceSnapshot(workspace.copy(latestBuild = build), agent)
+                        workspaceRefreshTrigger.trySend(true)
+                    }
                 }.withCurrentSessionId(::currentSessionId)
             )
         }
@@ -199,8 +261,10 @@ class CoderRemoteEnvironment(
                     context.i18n.ptrl("Cancel")
                 )
                 if (confirmation == workspace.name) {
-                    context.logger.debug(currentSessionId(), "Deleting $id...")
-                    deleteWorkspace()
+                    withProgress("Deleting workspace…") {
+                        context.logger.debug(currentSessionId(), "Deleting $id...")
+                        deleteWorkspace()
+                    }
                 }
             }.withCurrentSessionId(::currentSessionId)
         )
@@ -346,7 +410,12 @@ class CoderRemoteEnvironment(
     /**
      * Update the workspace/agent status to the listeners, if it has changed.
      */
-    fun update(newWorkspace: Workspace, newAgent: WorkspaceAgent?) {
+    suspend fun update(newWorkspace: Workspace, newAgent: WorkspaceAgent?) {
+        applyWorkspaceSnapshot(newWorkspace, newAgent)
+        updateBuildProgress(newWorkspace)
+    }
+
+    private fun applyWorkspaceSnapshot(newWorkspace: Workspace, newAgent: WorkspaceAgent?) {
         if (workspace.latestBuild == newWorkspace.latestBuild) {
             return
         }
@@ -363,6 +432,23 @@ class CoderRemoteEnvironment(
         refreshAvailableActions()
     }
 
+    private suspend fun updateBuildProgress(newWorkspace: Workspace) {
+        val build = newWorkspace.latestBuild
+        if (build.status !in IN_PROGRESS_BUILD_STATUSES) return
+        val latestLog = try {
+            client.workspaceBuildLogs(build.id).lastOrNull()
+        } catch (ex: CancellationException) {
+            throw ex
+        } catch (ex: Exception) {
+            context.logger.warn(
+                currentSessionId(),
+                ex,
+                "Failed to retrieve progress for workspace build ${build.id}",
+            )
+            return
+        }
+        latestLog?.output?.let(::showProgress)
+    }
 
     private fun updateStatus(
         newState: WorkspaceAndAgentStatus,
@@ -380,6 +466,9 @@ class CoderRemoteEnvironment(
         state.update {
             environmentStatus.toRemoteEnvironmentState(context)
         }
+        description.update {
+            environmentStatus.toEnvironmentDescription(context)
+        }
         val message =
             "Overall status for workspace $id changed from ${previousEnvironmentStatus.label} " +
                     "to ${environmentStatus.label}. " +

src/main/kotlin/com/coder/toolbox/cli/CoderCLIManager.kt

@@ -274,7 +274,11 @@ class CoderCLIManager(
     /**
      * Start a workspace. Throws if the command execution fails.
      */
-    internal fun startWorkspace(wsAddress: WorkspaceAddress, feats: Features = features): String {
+    internal fun startWorkspace(
+        wsAddress: WorkspaceAddress,
+        feats: Features = features,
+        showTextProgress: (String) -> Unit = {},
+    ): String {
         val args = mutableListOf(
             "--global-config",
             coderConfigPath.toString(),
@@ -288,7 +292,7 @@ class CoderCLIManager(
         args.add("--")
         args.add(wsAddress.ownerAndWsName)
 
-        return exec(*args.toTypedArray())
+        return exec(*args.toTypedArray(), showTextProgress = showTextProgress)
     }
 
     /**
@@ -571,12 +575,22 @@ class CoderCLIManager(
         return matches
     }
 
-    private fun exec(vararg args: String): String {
-        val stdout =
+    private fun exec(
+        vararg args: String,
+        showTextProgress: ((String) -> Unit)? = null,
+    ): String {
+        val processExecutor =
             ProcessExecutor()
                 .command(localBinaryPath.toString(), *args)
                 .environment("CODER_HEADER_COMMAND", context.settingsStore.headerCommand)
                 .exitValues(0)
+
+        showTextProgress?.let { reportProgress ->
+            processExecutor.redirectOutput(reportProgress::invoke)
+        }
+
+        val stdout =
+            processExecutor
                 .readOutput(true)
                 .execute()
                 .outputUTF8()

src/main/kotlin/com/coder/toolbox/diagnostics/CoderLogger.kt

@@ -59,6 +59,10 @@ class CoderLogger(
         delegate.warn(withSessionId(sessionId, message))
     }
 
+    inline fun warn(sessionId: SessionId?, exception: Throwable, message: String) {
+        delegate.warn(exception, withSessionId(sessionId, message))
+    }
+
     inline fun warn(sessionIds: Set<SessionId>, exception: Throwable, message: String) {
         sessionIds.onceOrForEach { delegate.warn(exception, withSessionId(it, message)) }
     }

src/main/kotlin/com/coder/toolbox/sdk/CoderRestClient.kt

@@ -18,6 +18,7 @@ import com.coder.toolbox.sdk.v2.models.BuildInfo
 import com.coder.toolbox.sdk.v2.models.CoderIdentifierPolicy
 import com.coder.toolbox.sdk.v2.models.CreateWorkspaceBuildRequest
 import com.coder.toolbox.sdk.v2.models.InvalidCoderIdentifierException
+import com.coder.toolbox.sdk.v2.models.ProvisionerJobLog
 import com.coder.toolbox.sdk.v2.models.Template
 import com.coder.toolbox.sdk.v2.models.User
 import com.coder.toolbox.sdk.v2.models.Workspace
@@ -317,6 +318,25 @@ open class CoderRestClient(
         }.withoutUnsafeAgents()
     }
 
+    /** Retrieves the provisioner logs for [workspaceBuildID]. */
+    suspend fun workspaceBuildLogs(workspaceBuildID: UUID): List<ProvisionerJobLog> {
+        val logsResponse = callWithRetry {
+            retroRestClient.workspaceBuildLogs(workspaceBuildID)
+        }
+        if (!logsResponse.isSuccessful) {
+            throw APIResponseException(
+                "retrieve logs for workspace build $workspaceBuildID",
+                url,
+                logsResponse.code(),
+                logsResponse.parseErrorBody(moshi),
+            )
+        }
+
+        return requireNotNull(logsResponse.body()) {
+            "Successful response returned null body for workspace build logs"
+        }
+    }
+
     /**
      * @throws [APIResponseException] if issues are encountered during deletion
      */

src/main/kotlin/com/coder/toolbox/sdk/v2/CoderV2RestFacade.kt

@@ -3,6 +3,7 @@ package com.coder.toolbox.sdk.v2
 import com.coder.toolbox.sdk.v2.models.Appearance
 import com.coder.toolbox.sdk.v2.models.BuildInfo
 import com.coder.toolbox.sdk.v2.models.CreateWorkspaceBuildRequest
+import com.coder.toolbox.sdk.v2.models.ProvisionerJobLog
 import com.coder.toolbox.sdk.v2.models.Template
 import com.coder.toolbox.sdk.v2.models.User
 import com.coder.toolbox.sdk.v2.models.Workspace
@@ -57,6 +58,12 @@ interface CoderV2RestFacade {
         @Body createWorkspaceBuildRequest: CreateWorkspaceBuildRequest,
     ): Response<WorkspaceBuild>
 
+    /** Retrieves the provisioner logs for a workspace build. */
+    @GET("api/v2/workspacebuilds/{workspaceBuildID}/logs")
+    suspend fun workspaceBuildLogs(
+        @Path("workspaceBuildID") workspaceBuildID: UUID,
+    ): Response<List<ProvisionerJobLog>>
+
     /**
      * Retrieves all templates the authenticated user can access.
      */

src/main/kotlin/com/coder/toolbox/sdk/v2/models/ProvisionerJobLog.kt

@@ -0,0 +1,15 @@
+package com.coder.toolbox.sdk.v2.models
+
+import com.squareup.moshi.Json
+import com.squareup.moshi.JsonClass
+import java.time.Instant
+
+@JsonClass(generateAdapter = true)
+data class ProvisionerJobLog(
+    @property:Json(name = "id") val id: Long,
+    @property:Json(name = "created_at") val createdAt: Instant,
+    @property:Json(name = "log_source") val source: String,
+    @property:Json(name = "log_level") val level: String,
+    @property:Json(name = "stage") val stage: String,
+    @property:Json(name = "output") val output: String,
+)