20. Протокол: TUI ↔ app-server

Связь между TUI/CLI и app-server идёт через JSON-RPC-подобный протокол (без обязательного поля "jsonrpc": "2.0"), определённый в крейте app-server-protocol/. Версионирование — две неймспейс-версии (v1 / v2), сосуществующие в одном протоколе.

1. Структура сообщений

Используется в app-server-protocol/src/jsonrpc_lite.rs:

// Client → Server
JSONRPCRequest {
    id: RequestId,             // строка или число
    method: String,            // "thread/start", "turn/start", ...
    params: Option<Value>,
    trace: Option<W3cTraceContext>, // OpenTelemetry pass-through
}

// Server → Client (notification, без id)
JSONRPCNotification {
    method: String,
    params: Option<Value>,
}

// Server → Client (response на request с тем же id)
JSONRPCResponse {
    id: RequestId,
    result: Value,
}

// Error response
JSONRPCError {
    id: RequestId,
    error: { code: i64, message: String, data: Option<Value> },
}

// Server → Client (server request, требует ответа)
// Использует те же поля что и JSONRPCRequest, но идёт от сервера.

"jsonrpc": "2.0" опущено — для уменьшения размера сообщений в hot-path.

2. Транспорты

In-process реализован в app-server-client/src/in_process.rs:InProcessAppServerClient. Удалённые — в том же крейте.

Backpressure: try_send возвращает WouldBlock при переполнении канала.

Оба транспорта идут через AstraCodeMessageProcessor::process_request() — единая логика, разные транспорты.

3. Версионирование (v1 / v2)

Файлы: - app-server-protocol/src/protocol/v1.rs — legacy. - app-server-protocol/src/protocol/v2.rs — основной API (~10 000 строк типов).

Сосуществуют под одним протоколом — нет «переключения» с v1 на v2. Вместо этого: - Старые методы остаются доступны под именами v1 (getAuthStatus). - Новые/расширенные методы используют v2-имена и типы. - Экспериментальные поля помечены #[experimental(...)] и сериализуются только если клиент в Initialize сообщил experimental_api: true.

4. Handshake

Client → Server:  Initialize { request_id, params: InitializeParams }
                    params.client_info: { name, version }
                    params.capabilities: {
                      experimental_api: bool,
                      opt_out_notification_methods: Option<Vec<String>>
                    }
Server → Client:  Response { result: InitializeResponse }
                    user_agent, astracode_home, platform_family, platform_os
Client → Server:  Notification: "initialized"

opt_out_notification_methods — список нотификаций, которые клиент не хочет получать (например, нет смысла слать thread/started тестовому клиенту).

5. Client requests — полный список

Группировка по доменам. Все имена методов точные, как они идут на проводе.

Thread API

Turn API

Realtime (голосовой режим, EXP)

Review

Index

Skills

Plugin

MCP

File system

Command exec (для запуска команд из UI, не из модели)

Config

Model

Auth / Account / Device

Feature flags / permissions

Memory

Прочее

[EXP] — методы за experimental_api capability.

6. Server notifications — полный список

Notifications (без id) идут server → client стримом. Группировка:

Жизненный цикл треда

thread/started, thread/status/changed, thread/archived, thread/unarchived,
thread/closed, thread/name/updated, thread/goal/updated, thread/goal/cleared,
thread/settings/updated [EXP], thread/tokenUsage/updated, thread/compacted

Turn и item streaming

turn/started, turn/completed, turn/diff/updated, turn/plan/updated,
item/started, item/completed,
item/agentMessage/delta,        # streaming текста ассистента
item/plan/delta [EXP],          # streaming плана
item/reasoning/summaryTextDelta,  # reasoning (o1/o3, claude extended thinking)
item/reasoning/summaryPartAdded,
item/reasoning/textDelta

Command/file execution streaming

command/exec/outputDelta,
item/commandExecution/outputDelta,
item/commandExecution/terminalInteraction,
item/fileChange/outputDelta,
item/fileChange/patchUpdated

Hooks

hook/started, hook/completed

Approval / guardian

item/autoApprovalReview/started, item/autoApprovalReview/completed,
guardianWarning

MCP / tools

mcpServer/oauthLogin/completed,
mcpServer/startupStatus/updated,
item/mcpToolCall/progress

System / прочее

error, warning, deprecationNotice, configWarning,
account/updated, account/login/completed,
model/rerouted,            # fallback к другой модели
model/verification,
skills/changed,
fs/changed,                # от fs/watch
fuzzyFileSearch/sessionUpdated, fuzzyFileSearch/sessionCompleted,
windows/worldWritableWarning, windowsSandbox/setupCompleted,
externalAgentConfig/import/completed,
serverRequest/resolved     # завершение pending server request

Realtime [EXP]

thread/realtime/started, thread/realtime/itemAdded,
thread/realtime/transcript/delta, thread/realtime/transcript/done,
thread/realtime/outputAudio/delta, thread/realtime/sdp,
thread/realtime/error, thread/realtime/closed

7. Server requests (требуют ответа от UI)

Это сообщения server → client с id, на которые клиент обязан ответить. Используется для approval-диалогов и подобных интерактивных решений.

Deprecated (v1)

item/fileChange/requestApproval (v1)   → ApplyPatchApprovalParams / Response
item/commandExecution/requestApproval (v1) → ExecCommandApprovalParams / Response

UI обязан отвечать в разумное время — иначе core зависнет. Можно ответить deny, можно показать модальный диалог.

8. Обработка ошибок

Стандартные коды JSON-RPC + расширения AstraCode (определены в app-server/src/error_code.rs):

Retry-стратегия — на клиенте. AstraCode-клиент использует exponential backoff на OVERLOADED_ERROR_CODE и сетевые ошибки.

9. Trace context

Каждый JSONRPCRequest может содержать trace: Option<W3cTraceContext> — W3C trace context (traceparent, tracestate). Используется для распределённого трейсинга через otel крейт. Сервер пробрасывает trace ID в свои downstream-вызовы (LLM, MCP, tools).

10. Соответствие in-process / remote

С точки зрения логики идентичны. Удалённый режим даёт возможность переподключаться (например, после crash'а TUI app-server остался жив).

11. Где определены типы

• Сами типы методов и параметров: app-server-protocol/src/protocol/v2.rs (~10000 строк).
• Макросы генерации: app-server-protocol/src/protocol/common.rs — client_request_definitions!, server_notification_definitions!, server_request_definitions!.
• v1 legacy: app-server-protocol/src/protocol/v1.rs.
• Клиент: app-server-client/src/.
• Сервер: app-server/src/astracode_message_processor.rs.

12. Как добавить новый метод

См. 22-cookbook.md.