feat(jetbrains): backend architecture, OpenAPI client, and test suite

[kirillk]

Summary

Implements the JetBrains plugin backend: CLI server lifecycle, connection management, data loading, and a comprehensive IntelliJ-independent test suite. Also adds OpenAPI client generation with post-processing fixes for kotlinx.serialization compatibility.

Architecture

The plugin uses IntelliJ's split-mode architecture with three Gradle modules:

┌──────────────────────────────────────────────────────────────────────┐
│                        JetBrains IDE (Host)                          │
│                                                                      │
│  ┌─────────────────────────┐       ┌──────────────────────────────┐  │
│  │       frontend/          │  RPC  │          backend/            │  │
│  │                          │◄─────►│                              │  │
│  │  KiloToolWindowFactory   │       │  KiloBackendAppService       │  │
│  │  KiloAppService (UI)     │       │    ├── KiloBackendCliManager │  │
│  │  Actions (restart, etc.) │       │    └── KiloConnectionService │  │
│  │                          │       │                              │  │
│  └─────────────────────────┘       └──────────┬───────────────────┘  │
│                                                │                      │
│  ┌─────────────────────────┐                   │                      │
│  │       shared/            │                   │                      │
│  │                          │                   │                      │
│  │  KiloAppRpcApi (@Rpc)    │                   │                      │
│  │  KiloAppStateDto         │                   │                      │
│  │  HealthDto               │                   │                      │
│  └─────────────────────────┘                   │                      │
└────────────────────────────────────────────────┼──────────────────────┘
                                                 │
                                                 │ HTTP + SSE
                                                 │ (OkHttp, Basic Auth)
                                                 ▼
                                    ┌────────────────────────┐
                                    │   kilo serve --port 0  │
                                    │   (CLI subprocess)     │
                                    │                        │
                                    │  GET /global/health    │
                                    │  GET /global/config    │
                                    │  GET /global/event     │ ◄── SSE stream
                                    │  GET /kilo/profile     │
                                    │  GET /kilo/notifications│
                                    └────────────────────────┘

Backend lifecycle

KiloBackendAppService (orchestrator, Mutex-serialized)
  │
  ├── KiloBackendCliManager (implements CliServer)
  │     • Extracts CLI binary from JAR resources
  │     • Spawns `kilo serve --port 0`
  │     • Reads port from stdout regex
  │     • Manages shutdown hooks and process tree
  │
  └── KiloConnectionService
        • Dual OkHttp clients (api: no timeout, health: 3s timeout)
        • SSE stream via OkHttp EventSource
        • Heartbeat monitoring (15s timeout)
        • Health polling (10s interval)
        • Automatic reconnection with process monitoring

State machine

  Disconnected ──► Connecting ──► Loading ──► Ready
       ▲                │            │          │
       │                ▼            ▼          │
       └──────────── Error ◄─────────┘          │
       │                                        │
       └────────────────────────────────────────┘
                    (restart/reinstall)

The Loading phase fetches config, notifications, and profile in parallel. Config and notifications are required (retried 3x). Profile is optional — 401 (not logged in) is fine, but other failures (500, timeout) surface as errors.

OpenAPI client generation

The CLI server HTTP API is defined in packages/sdk/openapi.json. We generate a Kotlin client using openapi-generator with jvm-okhttp4 + kotlinx_serialization. The generator produces several codegen bugs that FixGeneratedApiTask patches automatically:

#	Bug	Fix
1	const: true/false generates broken single-value boolean enums	Replace with plain kotlin.Boolean
2	HashMap<...>()() — double parentheses	Remove extra ()
3	kotlin.Double("5000") — private constructor	Convert to 5000.0 literal
4	Missing @Contextual on kotlin.Any fields	Add annotation for kotlinx.serialization
5	response.body assumed non-null	Add null guard in ApiClient.kt
6	No serializer for Any type	Inject AnySerializer backed by JsonElement
7	Empty anyOf wrapper classes	Replace with JsonElement

Test suite

43 tests across 5 classes, running as plain JVM/JUnit — no IntelliJ test framework required.

Test infrastructure

• MockCliServer — Raw ServerSocket HTTP server simulating the CLI. Handles REST endpoints with configurable JSON responses and provides full control over the SSE stream (pushEvent, closeSse, awaitSseConnection). Supports restart (stop/start cycles).
• FakeCliServer — Implements CliServer interface, delegates to MockCliServer instead of spawning a real process.
• TestLog — Captures log messages for assertions without IntelliJ Logger.

Interface seams for testability

Two interfaces were extracted from production code to decouple from IntelliJ APIs:

• CliServer — Abstracts CLI process lifecycle (init, stop, dispose, process). KiloBackendCliManager implements it; tests use FakeCliServer.
• KiloLog — Abstracts logging. IntellijLog wraps com.intellij.openapi.diagnostic.Logger; tests use TestLog.

KiloBackendAppService exposes an internal fun create() factory for tests to construct instances with injected fakes, while the public constructor remains compatible with IntelliJ service injection.

Test coverage

Class	Tests	What's covered
KiloBackendHttpClientsTest	6	Auth headers, timeouts, connection pool shutdown
KiloAppStateTest	8	Sealed class subtypes, LoadProgress, LoadError, ProfileResult
ApiModelSerializationTest	12	JSON roundtrips for Config, Health, Notifications, Profile with edge cases (nulls, unknown fields, minimal JSON)
KiloConnectionServiceTest	7	Connect lifecycle, SSE events, error states, reinstall/forceExtract, dispose
KiloBackendAppServiceTest	10	Full lifecycle to Ready, retry on failure, profile 401 tolerance, profile 500 error surfacing, health flag forwarding, SSE config refresh, health check

Bugs found and fixed

Three bugs were caught during testing and code review:

1. dispose() race in KiloConnectionService — OkHttp SSE onFailure callback fires on a background thread after dispose() sets state to Disconnected, overwriting it with Error("Socket closed"). Fixed by adding a disposed flag that gates all setState calls.

2. health() hardcoded healthy = true — globalHealth() returns the server health flag, but the RPC response always reported success. If the CLI answered with healthy = false, the frontend would still see a healthy state. Fixed to forward response.healthy.

3. fetchProfile() swallowed non-auth errors — The catch block treated every exception (500, timeout, deserialization) as NOT_LOGGED_IN, letting the app reach Ready while hiding real backend problems. Fixed to only treat 401 as not-logged-in; other failures now surface as Error state with a profile LoadError.

[kilo-code-bot]

Code Review Summary

Status: 2 Issues Found | Recommendation: Address before merge

Overview

Severity	Count
CRITICAL	0
WARNING	2
SUGGESTION	0

Issue Details (click to expand)

WARNING

File	Line	Issue
packages/kilo-jetbrains/backend/src/main/kotlin/ai/kilocode/backend/KiloBackendAppService.kt	117	health() hardcodes healthy = true instead of forwarding the server response.
packages/kilo-jetbrains/backend/src/main/kotlin/ai/kilocode/backend/KiloBackendAppService.kt	225	fetchProfile() treats every exception as NOT_LOGGED_IN, masking non-auth failures and allowing a false Ready state.

Fix these issues in Kilo Cloud

Other Observations (not in diff)

No additional issues found outside the diff.

Files Reviewed (3 files)

• packages/kilo-jetbrains/backend/src/main/kotlin/ai/kilocode/backend/KiloBackendAppService.kt - 2 carried-forward issues
• packages/kilo-jetbrains/backend/src/test/kotlin/ai/kilocode/backend/KiloAppStateTest.kt - 0 issues in incremental diff
• packages/kilo-jetbrains/gradle/libs.versions.toml - 0 issues in incremental diff

---

_{Reviewed by gpt-5.4-20260305 · 819,453 tokens}

[marius-kilocode]

All of those try catch statements smell to me. This catches and rethrows expeceptions across 4-5 layers. I think we are mixing here exceptions for control flow and and result types. Can't we use result types in every layer all the way through?

[marius-kilocode]

Should load run under the mutex too? Is this a realistic race?

connect() acquires mutex, calls connection.connect(), releases mutex
Connection succeeds, the init{} collector fires load()
load() spawns loader = cs.launch { ... } — this coroutine is now running freely on a dispatcher thread, writing to config, profile, _appState
Meanwhile, someone calls restart(), acquires the mutex, calls clear()
clear() does loader?.cancel() and then config = null
But the loader coroutine is between config = result.value and config!! — cancellation hasn't been checked yet because cancellation is cooperative, it only triggers at the next suspension point
The loader reads config!!, which is now null → NPE

[marius-kilocode]

On the top you state all public * methods are called under its mutex so no internal synchronization is needed in a comment, however this one is public too.

[marius-kilocode]

This seems quite hacky. Is the current version of openapi-generator really that problematic? If the version changes this might break?