impl: support for Toolbox 2.6.3 (#124)

Toolbox 2.6.3 comes with a couple of new additions in the API which need
the following changes:

- finish support for URI handling. The available API up to TBX 2.6.3 was
buggy in terms of URI handling. It didn't allow plugins to
programmatically install remote ides and launch them. The launch
operation only worked when the IDE was already installed and a project
was already opened with the IDE.

TBX 2.6.3 adds a new API, _RemoteToolboxHelp_ which provides routines
for listing the available
IDEs on the remote, what is already installed and a command to install
specific versions of the IDE.
Additionally, there were fixes provided to the existing _ClientHelper_
which now launches the JBClient
if a project was not specified. An additional quirk I've discovered is
that if we provide a project, and
that project was not already opened (present in the Projects tab) the
IDE still won't open. And there
  is no API available to query the available projects.
  
  This PR uses the new API to:
  - query the installed ides
  - check if the provided ide is in the list of already installed IDEs.
- if that's not the case we query the available list of IDEs and the
available versions
- if the provided ide and build no., is in the available list we will
schedule it for install
- if not, we select the latest available build number for the provided
product code.
  - wait for the remote IDE to be installed
- and then download and launch the JBClient with a project path if it
was provided.
- update the minimum API requirement. Toolbox API is upgraded to
1.1.41749 which comes with new API additions and some deprecations.
Kotlin stdlib was also increased to a newer patch version

- use new environment state API. The _CustomRemoteEnvironmentState_ is
deprecated, and replaced by a new class _CustomRemoteEnvironmentStateV2_
which now supports i18n state labels

- use the new ssh disconnect callback. Toolbox provides two callbacks,
one before an SSH connection is established and another one which
executes when the ssh connection is stopped. The latter was deprecated
in the favor of a new callback that also provides hints on whether the
user requested the disconnect.

- use the new delete callback API. Toolbox provides a callback for
scenarios that involve the env. deletion. This allows plugins to react
and clean the internal state. With the new TBX API, the delete callback
API is deprecated in the favor of a mutable state flow, a reactive
approach that allows consumers to observe and react to state changes
over time.

Author: fioan89

CHANGELOG.md

@@ -2,6 +2,10 @@
 
 ## Unreleased
 
+### Added
+
+- support for Toolbox 2.6.3 with improved URI handling
+
 ## 0.2.3 - 2025-05-26
 
 ### Changed

README.md

@@ -101,6 +101,11 @@ If `ide_product_code` and `ide_build_number` is missing, Toolbox will only open
 page. Coder Toolbox will attempt to start the workspace if it’s not already running; however, for the most reliable
 experience, it’s recommended to ensure the workspace is running prior to initiating the connection.
 
+> ⚠️ Note: `folder` should point to a remote IDEA project that has already been opened and appears in the `Projects` tab.
+> If the path refers to a project that doesn't exist, the remote IDE won’t start or load it.
+
+> Until [TBX-14952](https://youtrack.jetbrains.com/issue/TBX-14952/) is fixed, it's best to either use a path to a previously opened project or leave it empty.
+
 ## Configuring and Testing workspace polling with HTTP & SOCKS5 Proxy
 
 This section explains how to set up a local proxy (without authentication which is not yet supported) and verify that

gradle.properties

@@ -1,3 +1,3 @@
-version=0.2.3
+version=0.3.0
 group=com.coder.toolbox
 name=coder-toolbox

gradle/libs.versions.toml

@@ -1,6 +1,6 @@
 [versions]
-toolbox-plugin-api = "1.0.38881"
-kotlin = "2.1.0"
+toolbox-plugin-api = "1.1.41749"
+kotlin = "2.1.10"
 coroutines = "1.10.1"
 serialization = "1.8.0"
 okhttp = "4.12.0"
@@ -9,7 +9,7 @@ marketplace-client = "2.0.46"
 gradle-wrapper = "0.14.0"
 exec = "1.12"
 moshi = "1.15.2"
-ksp = "2.1.0-1.0.29"
+ksp = "2.1.10-1.0.31"
 retrofit = "2.11.0"
 changelog = "2.2.1"
 gettext = "0.7.0"

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

@@ -27,6 +27,7 @@ import com.squareup.moshi.Moshi
 import kotlinx.coroutines.Job
 import kotlinx.coroutines.delay
 import kotlinx.coroutines.flow.MutableStateFlow
+import kotlinx.coroutines.flow.StateFlow
 import kotlinx.coroutines.flow.update
 import kotlinx.coroutines.isActive
 import kotlinx.coroutines.launch
@@ -203,7 +204,7 @@ class CoderRemoteEnvironment(
 
     private fun File.doesNotExists(): Boolean = !this.exists()
 
-    override fun afterDisconnect() {
+    override fun afterDisconnect(isManual: Boolean) {
         context.logger.info("Stopping the network metrics poll job for $id")
         pollJob?.cancel()
         this.connectionRequest.update { false }
@@ -269,7 +270,7 @@ class CoderRemoteEnvironment(
         }
     }
 
-    override fun onDelete() {
+    override val deleteActionFlow: StateFlow<(() -> Unit)?> = MutableStateFlow {
         context.cs.launch {
             try {
                 client.removeWorkspace(workspace)

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

@@ -7,18 +7,22 @@ import com.jetbrains.toolbox.api.core.diagnostics.Logger
 import com.jetbrains.toolbox.api.core.os.LocalDesktopManager
 import com.jetbrains.toolbox.api.localization.LocalizableStringFactory
 import com.jetbrains.toolbox.api.remoteDev.connection.ClientHelper
+import com.jetbrains.toolbox.api.remoteDev.connection.RemoteToolsHelper
 import com.jetbrains.toolbox.api.remoteDev.connection.ToolboxProxySettings
 import com.jetbrains.toolbox.api.remoteDev.states.EnvironmentStateColorPalette
 import com.jetbrains.toolbox.api.remoteDev.ui.EnvironmentUiPageManager
 import com.jetbrains.toolbox.api.ui.ToolboxUi
 import kotlinx.coroutines.CoroutineScope
 import java.net.URL
+import java.util.UUID
 
+@Suppress("UnstableApiUsage")
 data class CoderToolboxContext(
     val ui: ToolboxUi,
     val envPageManager: EnvironmentUiPageManager,
     val envStateColorPalette: EnvironmentStateColorPalette,
-    val ideOrchestrator: ClientHelper,
+    val remoteIdeOrchestrator: RemoteToolsHelper,
+    val jbClientOrchestrator: ClientHelper,
     val desktop: LocalDesktopManager,
     val cs: CoroutineScope,
     val logger: Logger,
@@ -44,4 +48,44 @@ data class CoderToolboxContext(
             }
             return this.settingsStore.defaultURL.toURL()
         }
+
+    suspend fun logAndShowError(title: String, error: String) {
+        logger.error(error)
+        ui.showSnackbar(
+            UUID.randomUUID().toString(),
+            i18n.pnotr(title),
+            i18n.pnotr(error),
+            i18n.ptrl("OK")
+        )
+    }
+
+    suspend fun logAndShowError(title: String, error: String, exception: Exception) {
+        logger.error(exception, error)
+        ui.showSnackbar(
+            UUID.randomUUID().toString(),
+            i18n.pnotr(title),
+            i18n.pnotr(error),
+            i18n.ptrl("OK")
+        )
+    }
+
+    suspend fun logAndShowWarning(title: String, warning: String) {
+        logger.warn(warning)
+        ui.showSnackbar(
+            UUID.randomUUID().toString(),
+            i18n.pnotr(title),
+            i18n.pnotr(warning),
+            i18n.ptrl("OK")
+        )
+    }
+
+    suspend fun logAndShowInfo(title: String, info: String) {
+        logger.info(info)
+        ui.showSnackbar(
+            UUID.randomUUID().toString(),
+            i18n.pnotr(title),
+            i18n.pnotr(info),
+            i18n.ptrl("OK")
+        )
+    }
 }

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

@@ -13,6 +13,7 @@ import com.jetbrains.toolbox.api.localization.LocalizableStringFactory
 import com.jetbrains.toolbox.api.remoteDev.RemoteDevExtension
 import com.jetbrains.toolbox.api.remoteDev.RemoteProvider
 import com.jetbrains.toolbox.api.remoteDev.connection.ClientHelper
+import com.jetbrains.toolbox.api.remoteDev.connection.RemoteToolsHelper
 import com.jetbrains.toolbox.api.remoteDev.connection.ToolboxProxySettings
 import com.jetbrains.toolbox.api.remoteDev.states.EnvironmentStateColorPalette
 import com.jetbrains.toolbox.api.remoteDev.ui.EnvironmentUiPageManager
@@ -31,6 +32,7 @@ class CoderToolboxExtension : RemoteDevExtension {
                 serviceLocator.getService<ToolboxUi>(),
                 serviceLocator.getService<EnvironmentUiPageManager>(),
                 serviceLocator.getService<EnvironmentStateColorPalette>(),
+                serviceLocator.getService<RemoteToolsHelper>(),
                 serviceLocator.getService<ClientHelper>(),
                 serviceLocator.getService<LocalDesktopManager>(),
                 serviceLocator.getService<CoroutineScope>(),

src/main/kotlin/com/coder/toolbox/models/WorkspaceAndAgentStatus.kt

@@ -7,7 +7,7 @@ import com.coder.toolbox.sdk.v2.models.WorkspaceAgentLifecycleState
 import com.coder.toolbox.sdk.v2.models.WorkspaceAgentStatus
 import com.coder.toolbox.sdk.v2.models.WorkspaceStatus
 import com.jetbrains.toolbox.api.core.ui.color.StateColor
-import com.jetbrains.toolbox.api.remoteDev.states.CustomRemoteEnvironmentState
+import com.jetbrains.toolbox.api.remoteDev.states.CustomRemoteEnvironmentStateV2
 import com.jetbrains.toolbox.api.remoteDev.states.EnvironmentStateIcons
 import com.jetbrains.toolbox.api.remoteDev.states.StandardRemoteEnvironmentState
 
@@ -61,9 +61,9 @@ enum class WorkspaceAndAgentStatus(val label: String, val description: String) {
      * Note that a reachable environment will always display "connected" or
      * "disconnected" regardless of the label we give that status.
      */
-    fun toRemoteEnvironmentState(context: CoderToolboxContext): CustomRemoteEnvironmentState {
-        return CustomRemoteEnvironmentState(
-            label,
+    fun toRemoteEnvironmentState(context: CoderToolboxContext): CustomRemoteEnvironmentStateV2 {
+        return CustomRemoteEnvironmentStateV2(
+            context.i18n.pnotr(label),
             color = getStateColor(context),
             reachable = ready() || unhealthy(),
             // TODO@JB: How does this work?  Would like a spinner for pending states.
@@ -90,10 +90,10 @@ enum class WorkspaceAndAgentStatus(val label: String, val description: String) {
         else EnvironmentStateIcons.NoIcon
     }
 
-    fun toSshConnectingEnvState(context: CoderToolboxContext): CustomRemoteEnvironmentState {
+    fun toSshConnectingEnvState(context: CoderToolboxContext): CustomRemoteEnvironmentStateV2 {
         val existingState = toRemoteEnvironmentState(context)
-        return CustomRemoteEnvironmentState(
-            "SSHing",
+        return CustomRemoteEnvironmentStateV2(
+            context.i18n.pnotr("SSHing"),
             existingState.color,
             existingState.isReachable,
             EnvironmentStateIcons.Connecting

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

@@ -192,12 +192,12 @@ open class CoderRestClient(
     }
 
     /**
-     * Maps the list of workspaces to the associated agents.
+     * Maps the available workspaces to the associated agents.
      */
-    suspend fun groupByAgents(workspaces: List<Workspace>): Set<Pair<Workspace, WorkspaceAgent>> {
+    suspend fun workspacesByAgents(): Set<Pair<Workspace, WorkspaceAgent>> {
         // It is possible for there to be resources with duplicate names so we
         // need to use a set.
-        return workspaces.flatMap { ws ->
+        return workspaces().flatMap { ws ->
             when (ws.latestBuild.status) {
                 WorkspaceStatus.RUNNING -> ws.latestBuild.resources
                 else -> resources(ws)