feat(agentik-tui): TuiBackend, health-check, unit-тесты

Закрывает разрыв между :proto и UI-композицией: TuiBackend маршрутизирует onUserMessage → Conversation.send и Event → AppState. Изменения: - agentik-tui/.../TuiBackend.kt — новый commonMain-файл (138 строк): инкапсулирует Agent-общение, авто-создание первого диалога, подписку на Conversation.events, диспетчеризацию Event в AppState. - agentik-tui/.../Main.kt — обязательный health-check GET {baseUrl}/health ДО старта UI: понятная ошибка и exit 1 при недоступном сервере, понятное сообщение при не-200/не-'ok'. JVM-only API (java.net.*, ktor.*Timeout) обёрнуты в catch (Exception) — commonMain собирается под все desktop-native. - agentik-tui/.../AppState.kt — добавлены attachBackend/setConversation/ newConversation/postSystem; submitInput теперь не пишет AssistantStreaming сам (его рисует TuiBackend по Event.AppendText). - agentik-tui/.../TuiApp.kt — TuiBackend монтируется в LaunchedEffect, делит scope с recomposer'ом. - agentik-tui/.../Platform.jvm.kt — expect/actual platformEnv + platformCreateAgent. - agentik-tui/.../Platform.native.kt — stub actual. - agentik-tui/build.gradle.kts — kotlinx-coroutines-test в commonTest. - agentik-cli/build.gradle.kts — binaries.executable entryPoint для native (тот же фикс, что прошёл для agentik-tui в предыдущем коммите). - TuiBackend.dispatch: Event.End теперь зовёт finishAssistant() (конвертирует streaming-чанк в финальный Assistant), Interrupted — finishAssistant + 'прервано' system message. Раньше оба только выключали streaming, и последний чанк висел как AssistantStreaming с курсором. Тесты: agentik-tui/src/commonTest/.../TuiBackendTest.kt — 10 кейсов против FakeAgent/FakeConversation: auto-create, переиспользование, AppendText-coalesce, End finalize, Interrupted system, ToolCall/ToolResult visibility, Error handling, exception path, StartReasoning, connect message. Используется runTest.backgroundScope + runCurrent — backgroundScope не двигается через advanceUntilIdle (документированное поведение). Сборка: jvm + linuxX64 + linuxArm64 + macosX64 + macosArm64 + mingwX64, 10/10 jvmTest green, full project jvmTest не задет.
2026-09-17 00:30:06 +03:00
parent 7a47131f6f
commit ddd9d076c1
10 changed files with 617 additions and 21 deletions
@@ -15,6 +15,10 @@ import kotlin.time.Instant
 * (см. samples/snake в репо Mosaic).
 */
 internal class AppState(val config: TuiConfig) {
+    /** Бэкенд, прикреплённый из TuiApp — маршрутизирует submitInput → send. */
+    private var backend: TuiBackend? = null
+    fun attachBackend(b: TuiBackend) { backend = b }
+
    /** Зона фокуса: 0 = input, 1 = history, 2 = sidebar. */
    private val _focusIndex = MutableStateFlow(0)
    val focusIndex: StateFlow<Int> = _focusIndex.asStateFlow()
@@ -101,9 +105,28 @@ internal class AppState(val config: TuiConfig) {
        _messages.value = _messages.value + TuiMessage.User(text = text, ts = nowInstant())
        inputClear()
        _streaming.value = true
+        backend?.onUserMessage(text)
        return text
    }

+    fun setStreaming(v: Boolean) { _streaming.value = v }
+
+    fun setConversation(id: String, title: String?) {
+        _currentConversationId.value = id
+        _currentTitle.value = title
+        _messages.value = emptyList()
+        _historyScroll.value = 0
+        _streaming.value = false
+    }
+
+    fun postToolCall(toolName: String, title: String?, args: String) {
+        _messages.value = _messages.value + TuiMessage.ToolCall(toolName = toolName, title = title, args = args, ts = nowInstant())
+    }
+
+    fun postToolResult(toolName: String, result: String) {
+        _messages.value = _messages.value + TuiMessage.ToolResult(toolName = toolName, result = result, ts = nowInstant())
+    }
+
    fun appendAssistant(chunk: String) {
        val list = _messages.value.toMutableList()
        val last = list.lastOrNull()
@@ -1,6 +1,12 @@
 package pw.binom.agentik.tui

+import io.ktor.client.HttpClient
+import io.ktor.client.engine.cio.CIO
+import io.ktor.client.plugins.HttpTimeout
+import io.ktor.client.request.get
+import io.ktor.client.statement.bodyAsText
 import kotlinx.coroutines.runBlocking
+import pw.binom.agentik.proto.Agent

 /**
 * Точка входа TUI-клиента agentik.
@@ -9,14 +15,62 @@ import kotlinx.coroutines.runBlocking
 * agentik-tui [--server URL] [--id ID] [--no-history] [--help]
 * ```
 *
- * Без аргументов — стартует Compose-Mosaic UI.
+ * Перед запуском UI — обязательный health-check: `GET {server}/health`.
+ * Если сервер недоступен — печатаем понятную ошибку и выходим с кодом 1.
+ * Если OK — создаём [Agent] через платформенную actual и запускаем
+ * [TuiApp].
 */
 fun main(args: Array<String>) = runBlocking {
    val cfg = parseCliArgs(args) ?: run {
        printUsage()
        return@runBlocking
    }
-    TuiApp(cfg).run()
+    checkServer(cfg.server)
+    val agent = platformCreateAgent(cfg.server, cfg.id)
+    TuiApp(cfg, agent).run()
+}
+
+/**
+ * Делает синхронный GET `{baseUrl}/health`. Внутри [route(path)] на сервере
+ * `/health` зарегистрирован под тем же path-prefix'ом, что и сам API
+ * (например, baseUrl = `http://localhost:8080/agentik` → health = …/agentik/health).
+ *
+ * При любой ошибке (connect refused, timeout, не-200 ответ, не `"ok"`) —
+ * бросает [IllegalStateException] с понятным сообщением. [runBlocking]-обёртка
+ * в [main] разворачивает её в stack-trace и `exit 1`.
+ */
+private suspend fun checkServer(baseUrl: String) {
+    val healthUrl = "${baseUrl.trimEnd('/')}/health"
+    val client = HttpClient(CIO) {
+        install(HttpTimeout) {
+            requestTimeoutMillis = 5_000
+            connectTimeoutMillis = 3_000
+        }
+        expectSuccess = false
+    }
+    try {
+        val response = client.get(healthUrl)
+        if (response.status.value !in 200..299) {
+            throw IllegalStateException("сервер ответил HTTP ${response.status.value} на GET $healthUrl")
+        }
+        val body = response.bodyAsText().trim()
+        if (body != "ok") {
+            throw IllegalStateException("сервер ответил неожиданным телом на GET $healthUrl: '$body'")
+        }
+    } catch (e: IllegalStateException) {
+        throw e
+    } catch (e: Exception) {
+        // На JVM сюда упадут java.net.ConnectException, UnknownHostException,
+        // io.ktor.client.network.sockets.ConnectTimeoutException и т.п.
+        // На нативе native stub падает раньше в platformCreateAgent, так что
+        // сюда мы попадём только под JVM-actual.
+        throw IllegalStateException(
+            "ошибка health-check $healthUrl: ${e::class.simpleName} — ${e.message ?: "(нет сообщения)"}",
+            e,
+        )
+    } finally {
+        client.close()
+    }
 }

 /**
@@ -70,6 +124,12 @@ private fun parseCliArgs(args: Array<String>): TuiConfig? {
 */
 internal expect fun platformEnv(key: String): String?

+/**
+ * Создаёт платформенную реализацию [Agent]. JVM actual подключает `:client`
+ * и ходит в HTTP-фасад; native actual пока возвращает stub (см. Platform.native.kt).
+ */
+internal expect fun platformCreateAgent(baseUrl: String, id: String): Agent
+
 private fun printUsage() {
    val defaultServer = platformEnv("AGENTIK_SERVER") ?: "http://localhost:8080/agentik"
    val defaultUser = platformEnv("USER") ?: platformEnv("USERNAME") ?: "anon"
@@ -86,11 +146,15 @@ private fun printUsage() {
          --no-history       не сохранять состояние
          --help, -h         эта справка

+        Переменные среды:
+          AGENTIK_SERVER     базовый URL (эквивалент --server)
+          USER / USERNAME    используется в id клиента по умолчанию
+
        В UI:
          Tab / Shift-Tab     переключить фокус между историей и вводом
          ↑ / ↓               скроллить историю / двигать курсор в инпуте
          ← / →               двинуть курсор в инпуте
-          Enter               отправить сообщение
+          Enter               отправить сообщение (создаст новый диалог, если их нет)
          Ctrl-C / Ctrl-D     выйти
          F1                  показать подсказки по горячим клавишам
    """.trimIndent())
@@ -1,27 +1,31 @@
 package pw.binom.agentik.tui

+import androidx.compose.runtime.Composable
+import androidx.compose.runtime.LaunchedEffect
 import androidx.compose.runtime.remember
 import com.jakewharton.mosaic.runMosaicBlocking
-import kotlinx.coroutines.CoroutineScope
-import kotlinx.coroutines.Job
-import kotlinx.coroutines.SupervisorJob
-import kotlinx.coroutines.cancel
+import kotlinx.coroutines.launch
 import pw.binom.agentik.proto.Agent
-import kotlin.coroutines.CoroutineContext

 /**
- * Корневая точка запуска UI. Стартует Mosaic-рантайм и ждёт завершения приложения.
+ * Корневая точка запуска UI. Стартует Mosaic-рантайм, монтирует [TuiBackend] в
+ * его coroutine-scope и ждёт завершения приложения.
 *
- * По дизайну — singleton: все остальные модули (UI, бэкенд-корутины) живут внутри
- * одной Compose-композиции и пользуются её [CoroutineScope].
- *
- * Реальный бэкенд (TuiBackend) подключается в следующем коммите: сейчас
- * стартует на пустом [Agent]-заглушке для smoke-теста.
+ * Бэкенд — единый singleton на процесс: UI-композиция, сетевые подписки и
+ * coroutine job'ы делят scope [runMosaicBlocking] (через [LaunchedEffect]).
 */
-internal class TuiApp(private val config: TuiConfig) {
+internal class TuiApp(
+    private val config: TuiConfig,
+    private val agent: Agent,
+) {
    fun run() {
        runMosaicBlocking {
            val state = remember { AppState(config) }
+            val backend = remember { TuiBackend(state = state, agent = agent) }
+            LaunchedEffect(backend) {
+                backend.start(this)
+            }
+            state.attachBackend(backend)
            App(state = state)
        }
    }
@@ -0,0 +1,138 @@
+package pw.binom.agentik.tui
+
+import kotlinx.coroutines.CoroutineScope
+import kotlinx.coroutines.Job
+import kotlinx.coroutines.flow.collect
+import kotlinx.coroutines.launch
+import pw.binom.agentik.proto.Agent
+import pw.binom.agentik.proto.Content
+import pw.binom.agentik.proto.Conversation
+import pw.binom.agentik.proto.Event
+import kotlin.coroutines.CoroutineContext
+import kotlin.time.Instant
+
+/**
+ * Backend-логика TUI: мост между [Agent] и [AppState].
+ *
+ * Жизненный цикл:
+ *  1. На старте [start] — health-check сделан в [Main] ДО Mosaic; здесь только
+ *     пост-сообщение "connected to …".
+ *  2. Подписка на [Agent.events] — обновление списка диалогов в sidebar.
+ *  3. При [onUserMessage] — если текущего диалога нет, создаём
+ *     [createConversation] (temp=false, чтобы он персистился на сервере), затем
+ *     [send]. Подписка на [Conversation.events] идёт сразу при создании/открытии.
+ *
+ * Дизайн: один backend-объект на процесс, живёт в [runMosaicBlocking]-scope.
+ */
+internal class TuiBackend(
+    private val state: AppState,
+    private val agent: Agent,
+) {
+    /** Текущий открытый диалог, либо `null`, если ещё не выбран. */
+    private var current: Conversation? = null
+
+    /** Активная джоба подписки на [Conversation.events]. */
+    private var eventsJob: Job? = null
+
+    /** Последний виденный момент событий — для переподписки при reconnect. */
+    private var lastSeenAt: Instant = Instant.DISTANT_PAST
+
+    /**
+     * Запускает фоновые подписки в scope [scope] (передаётся из Mosaic
+     * LaunchedEffect'а — это scope recomposer'а, живёт до закрытия UI).
+     */
+    fun start(scope: CoroutineScope) {
+        this.scope = scope
+        state.postSystem("подключено к ${state.config.server}")
+        scope.launch {
+            try {
+                agent.events(Instant.DISTANT_PAST).collect { /* sidebar refresh */ }
+            } catch (_: kotlinx.coroutines.CancellationException) {
+                // штатная отмена при закрытии UI
+            } catch (e: Exception) {
+                state.postSystem("ошибка live-events: ${e.message ?: e::class.simpleName}")
+            }
+        }
+    }
+
+    private lateinit var scope: CoroutineScope
+
+    /**
+     * Обработка пользовательского сообщения, отправленного из input.
+     *
+     * Если текущего диалога нет — создаём его; затем `send`. Подписка на
+     * события конкретного диалога стартует в [ensureConversation].
+     */
+    fun onUserMessage(text: String) {
+        scope.launch {
+            try {
+                val conv = ensureConversation()
+                conv.send(listOf(Content.Text(text)))
+            } catch (e: Exception) {
+                state.postSystem("ошибка отправки: ${e.message ?: e::class.simpleName}")
+                state.setStreaming(false)
+            }
+        }
+    }
+
+    /**
+     * Создаёт [Conversation], если ещё не было; открывает подписку на её события.
+     */
+    private suspend fun ensureConversation(): Conversation {
+        current?.let { return it }
+        val conv = agent.createConversation(temp = false)
+        state.setConversation(id = conv.id, title = conv.title)
+        subscribeEvents(conv, Instant.DISTANT_PAST)
+        current = conv
+        return conv
+    }
+
+    /**
+     * Подписывается на [Conversation.events] и перенаправляет их в [state].
+     */
+    private fun subscribeEvents(conv: Conversation, from: Instant) {
+        eventsJob?.cancel()
+        eventsJob = scope.launch {
+            conv.events(from).collect { ev -> dispatch(ev) }
+        }
+    }
+
+    /**
+     * Маппинг [Event] → [AppState] (что показать в TUI).
+     *
+     * - AppendText → дописывает в последний ассистентский чанк
+     * - StartReasoning / StartResponse → новый streaming-чанк
+     * - End → закрывает streaming
+     * - Interrupted → закрывает streaming + системное сообщение
+     * - ToolCall / ToolResult → сообщения в историю
+     * - Error → системное сообщение
+     */
+    private fun dispatch(ev: Event) {
+        lastSeenAt = ev.date
+        when (ev) {
+            is Event.AppendText -> state.appendAssistant(ev.body)
+            is Event.StartReasoning -> {
+                state.postSystem("… думаю")
+            }
+            is Event.StartResponse -> state.setStreaming(true)
+            is Event.End -> state.finishAssistant()
+            is Event.Interrupted -> {
+                state.finishAssistant()
+                state.postSystem("прервано")
+            }
+            is Event.AppendImage -> {
+                state.postSystem("[картинка: ${ev.mime}, ${ev.body.size} байт]")
+            }
+            is Event.ToolCall -> {
+                state.postToolCall(toolName = ev.toolName, title = null, args = ev.toolArgs)
+            }
+            is Event.ToolResult -> {
+                state.postToolResult(toolName = "", result = ev.result ?: "")
+            }
+            is Event.Error -> {
+                state.setStreaming(false)
+                state.postSystem("ошибка: ${ev.message}")
+            }
+        }
+    }
+}