agentik/proto/README.md

# `:proto` — протокол общения с агентом (KMP, jvm + native)

## Что это

Типы и контракт in-house протокола `agentik`, заменившего AG-UI:

- **stateful** — сервер сам владеет диалогом; клиент шлёт только новые
  сообщения, а не всю историю (в отличие от AG-UI, где клиент обязан
  повторять `messages[]` каждый раз).
- **declarative история vs. события** — `Message` это то, что уже легло
  в БД, `Event` это live-стрим от агента во время `send()` или `events()`.
- **чистые интерфейсы** — никаких сетевых и storage зависимостей внутри
  `:proto`; это контракт.

Решает проблему: AG-UI клиент вынужден каждый раз знать и пересобирать
полную историю, а его серверная часть (`AbstractAgent`) — постоянно
сериализовать-десериализовать всю переписку. В `:proto` сервер один,
контракт тонкий, переписка персистится нативно (SQLite, файлы, что
хотите). Можно подменить front-end или back-end, протокол остаётся.

## Где используется

- `:server` — Ktor-фасад, маппит `Agent` ↔ HTTP/SSE.
- `:client` — Ktor-клиент, маппит HTTP/SSE ↔ `Agent/Conversation`.
- `:agentik-cli`, `:agentik-tui` — оба работают поверх `:client`,
  а следовательно поверх `:proto`.
- `:standalone` — реализует `Agent` (через `ChatAgent`) и пишет/читает
  `Message`/`Event` напрямую через storage.

## Как подключить

```kotlin
// build.gradle.kts
kotlin {
    sourceSets.commonMain.dependencies {
        api("pw.binom.agentik:proto:0.1.0")
    }
}
```

Артефакт `pw.binom.agentik:proto:0.1.0` живёт в Nexus-репозитории
`caffeine` (HTTP `http://<your-nexus>/repository/caffeine/`, plain-HTTP,
credentials — через переменные `binom.repo.user/password/url`).

## Версии

Каталог `gradle/libs.versions.toml`, секция `[versions]` → `agentik-proto`.
Поднять версию → переопубликовать все KMP-таргеты через `./gradlew
:proto:publish -Pversion=...` (или триггернуть Gitea release).

Текущие KMP-таргеты: `jvm + macosX64/macosArm64 +
iosX64/iosArm64/iosSimulatorArm64 + linuxX64/linuxArm64 + mingwX64`.

## Публикация

Настройки в `gradle.properties` / env: `binom.repo.url`, `binom.repo.user`,
`binom.repo.password`. `./gradlew :proto:publish` публикует все
target-specific артефакты + общий `kotlinMultiplatform`.

## Основные типы

```kotlin
interface Agent {
    fun id: String
    suspend fun createConversation(title: String? = null): Conversation
    suspend fun getConversation(id: String): Conversation?
    suspend fun getConversations(offset: Int = 0): Flow<Conversation>
    suspend fun events(after: Instant): Flow<AgentEvent>   // created/deleted/renamed
}

interface Conversation : AutoCloseable {
    val id: String
    val updatedAt: Instant
    val isSupportImageInput: Boolean
    val isSupportImageOutput: Boolean
    suspend fun send(content: List<Content>): Flow<Event>     // write+read вместе, как раньше
    suspend fun events(after: Instant): Flow<Event>           // отдельная live-подписка
    suspend fun getMessages(offset: Int = 0): Flow<Message>
    suspend fun rename(title: String): Boolean
    fun interrupt()
}

sealed interface Content {
    class Text(val body: String) : Content
    class Image(val data: ByteArray, val mime: String) : Content
}

sealed interface Message {
    val id: String
    val date: Instant
    interface Body : Message { val content: List<Content> }
    interface System : Message
    class UserMessage(...) : Body
    class AssistantMessage(...) : Body
    class ToolCall(...) : System
    class ToolResult(...) : System
}

sealed interface Event {
    enum ResponseType { TEXT, IMAGE }
    class StartReasoning(...) : Event
    class StartResponse(val type: ResponseType) : Event
    class AppendText(val body: String) : Event
    class AppendImage(val body: ByteArray, val mime: String) : Event
    class End(...) : Event
    class Interrupted(...) : Event
    class Error(val message: String, val code: Int? = null) : Event
    class ToolCall(...) : Event
    class ToolResult(...) : Event
}
```

## Чего здесь НЕТ

- Никакого HTTP/SSE/JSON. Это контракт. Сериализация живёт в `:server`
  и `:client`.
- Никакого хранения. Реализации `MessageStore` живут в `:storage-*`.
- Никакой логики прерывания / инструментов / LLM-вызовов. Это всё
  внутри `:standalone` (ChatAgent) и выше.

## Тесты

```
./gradlew :proto:jvmTest
./gradlew :proto:allTests     # дополнительно linuxX64 (если Linux) / iosSimulator (если macOS)
```

## Текущий статус

Используется продакшеном. Иммутабельный API (после рефакторинга из
AG-UI). Возможные будущие расширения: typed tool-result, multi-modal
contents, server-pushed references — все обсуждаются через общий
[IRC-QUESTIONS.md](../IRC-QUESTIONS.md).