subochev
5bdc517988
Введение монотонного offset'а как персистентного состояния агента:
offset'ы переживают рестарт standalone-агента, клиент продолжает
синхронизацию инкрементально, без полной re-sync с нуля.
outbox-api:
- Cursor (offset: Long) — курсор в журнале событий агента.
- OffsetSequencer — интерфейс резервирования уникального offset.
- CursorStore — персистентное хранилище текущего offset'а.
- PersistentOffsetSequencer — декоратор над любым OutboxStore,
обновляет CursorStore на каждом append (atomic transaction).
- OutboxGapException — клиент запросил after < earliestCursor() →
сервер не может удовлетворить, клиент обязан делать full resync.
- DurableEvent переименован из Event.kt → DurableEvent.kt (Event.kt
был общим sealed-типом, теперь это термин из спеки).
- MutableOutboxStore и OutboxStore теперь читают offset через
CursorStore вместо in-memory counter'а.
outbox-inmemory:
- InMemoryOffsetSequencer — для тестов и dev-режима.
- InMemoryOutboxStore теперь принимает OffsetSequencer в конструкторе.
outbox-ksqlite (новый модуль):
- KsqliteCursorStore — таблица outbox_cursor (agent_id TEXT PK,
offset INTEGER NOT NULL DEFAULT 0, updated_at INTEGER NOT NULL).
- KsqliteCursorStoreTest — 4 теста (set/get, monotonic, concurrent).
proto + server:
- Snapshot.proto — server-state snapshot endpoint для клиентов,
которым нужна полная материализация (использование TBD).
- Routes.kt + SnapshotRouteTest — endpoint /agentik/snapshot (GET).
journal-ksqlite:
- KsqliteJournalStore.listFlow/append — без изменений по API,
нотации минимальные (codecs).
standalone:
- DurableLog (бывший ChatAgent-orchestration) — атомарный commit
события в OutboxStore + PersistentOffsetSequencer + materialization
(через Reducer) одной транзакцией.
- SqliteStores — добавляет KsqliteCursorStore в bundle, единая
shared-connection для всех ksqlite-сторов standalone-агента.
- ChatAgent / ConversationLoop / ConversationEvents / ReflectionScheduler /
ToolDispatcher — переход на новые абстракции.
- standalone/build.gradle.kts — implementation(project(':outbox-ksqlite'))
включено (раньше было закомментировано — модуль только создавался).
client:
- AgentikAgent / AgentClient / HttpEventStore / HttpJournalStore /
ReconnectingOutbox — используют Cursor через transport API.
- client/README.md — синхронизирован с новым поведением (468 строк
diff — это в основном оформление и примеры).
kotlinx-io: 0.8.0 → 0.9.1 в libs.versions.toml (см. sync-core tests).
SYNC-SYSTEM.md (в корне) — спецификация, на которую ссылается и
:sync-core (эта сессия), и эта Cursor-абстракция в outbox-api.
Тесты: standalone 132, journal-ksqlite 25, outbox-inmemory 20,
outbox-ksqlite 4, client 10, sync-core 74 — все зелёные на jvm;
sync-core linuxX64 74 тоже зелёный.
sync2/ (заброшенный stub с одним build.gradle.kts) удалён.
:server — HTTP/SSE фасад для :proto (KMP, JVM-only)
Что это
Ktor-маршрут, экспонирующий Agent из :proto в виде JSON-API:
POST /agentik/conversations, POST /agentik/conversations/:id/send,
GET /agentik/conversations/:id/events (SSE), GET /health,
GET /agentik/conversations.
- stateful — сервер не принимает полную историю, только новые
сообщения. История хранится там, где развёрнут
Agent. - декларативно —
interface Agent→ HTTP; никакой магии, никаких обёрток. Контракт и сериализация — тоже декларативные (kotlinx-json с snake_case-дискриминаторами).
Решает: позволяет собрать любой собственный front-end (CLI/TUI/Web/ IRC/MCP) общаясь с одним сервером по стабильному wire-контракту.
Где используется
:standaloneподключаетRoute.agentikAgent(agent)в свой embedded Netty engine.- Любые клиенты (наши
:client,:agentik-cli, или внешние web-фронтенды) идут через этот контракт.
Как подключить
// build.gradle.kts (KMP JVM target)
plugins { id("pw.binom.agentik.server-conventions") version "0.1.0" }
dependencies {
api("pw.binom.agentik:server:0.1.0")
api("pw.binom.agentik:proto:0.1.0")
}
// ваш код:
fun Application.module(agent: Agent) {
install(ContentNegotiation) { json(agentikJson) }
install(SSE)
routing {
route("/agentik") { agentikAgent(agent) }
}
}
Версии
gradle/libs.versions.toml → [versions] agentik-server.
Эндпоинты (path по умолчанию /agentik, через agentikAgent(agent, "/my"))
| Метод | Путь | Что делает |
|---|---|---|
POST |
/conversations |
Создать диалог (body: {title?}) |
GET |
/conversations |
Список диалогов (по ?offset=&limit=) |
GET |
/conversations/:id |
Снимок диалога + count |
GET |
/conversations/:id/messages |
История сообщений (по ?after=) |
POST |
/conversations/:id/rename |
Переименовать (body: {title}) |
DELETE |
/conversations/:id |
Удалить |
POST |
/conversations/:id/send |
Send-флоу (body: {content:[…]} → SSE) |
GET |
/conversations/:id/events |
Live подписка (SSE) |
POST |
/conversations/:id/interrupt |
Прервать текущий send() |
Content-Type: text/event-stream всегда для SSE, ноль-лишних
заголовков. Сообщения: event: <name> (message, start_reasoning,
start_response, append_text, append_image, end, interrupted,
error) + data: <JSON>.
Тесты
./gradlew :server:jvmTest
Покрывают: маппинг JSON ↔ Event, SSE framing, error-handling,
404 / 400 ответы, корректную обработку Instant в kotlinx-datetime.
Чего здесь НЕТ
- Никакого LLM-кода, tool-вызовов, прерываний. Только mapping Agent ↔ HTTP.
- Никакой БД, никакого storage. Это задача
Agent-имплементации. - Никакого CORS-конфига по умолчанию — добавляйте на свой engine.
Текущий статус
Используется продакшеном. Wire-контракт стабильный; новые Event'ы добавляются только с snake_case-дискриминаторами и строго обратно совместимо.