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/src/in_process.rs, а InProcessAppServerClient — в app-server-client/src/lib.rs. Удалённые транспорты используют тот же protocol contract.

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

Группировка по доменам для проверенной ревизии. Канонический источник полного wire registry — client_request_definitions! в app-server-protocol/src/protocol/common.rs; experimental и legacy surface может меняться независимо от этого обзорного документа.

Thread API

Turn API

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

Review

Skills

Plugin

Slash-команды

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 стримом. Группировка:

В wire enum также существует внутреннее уведомление rawResponseItem/completed. Генератор публичной JSON schema намеренно исключает его через EXCLUDED_SERVER_NOTIFICATION_METHODS_FOR_JSON, поэтому оно не входит в поддерживаемый клиентский API и ниже не перечисляется.

Thread lifecycle

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

Обе notifications содержат threadId, опциональный turnId и run типа HookRunSummary. В summary передаются event/source, display order, running|completed|failed|blocked|stopped, status message, timestamps, duration и output entries (warning, stop, feedback, context, error). Это transport-события для UI и внешних клиентов, а не API запуска hooks: конфигурация, stdin/stdout и решения lifecycle описаны в 08-hooks.md.

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. Error handling

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

Превышение лимита пользовательского ввода возвращается как обычный JSON-RPC error с code = -32602. Строка "input_too_large" находится в error.data.input_error_code; рядом передаются max_chars и actual_chars.

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/lib.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.