Типизированная схема событий демона v1

Обзор

Каждый фрейм SSE, отправляемый демоном через GET /session/:id/events, имеет форму { id, v, type, data, originatorClientId?, _meta? }. v: 1 — текущая версия EVENT_SCHEMA_VERSION. type берётся из закрытого, привязанного к версии набора DAEMON_KNOWN_EVENT_TYPE_VALUES в packages/sdk-typescript/src/daemon/events.ts; текущий набор содержит 43 известных типа событий. Поле конверта _meta заполняется на границе записи SSE функцией formatSseFrame() в server.ts; см. Метаданные на уровне конверта.

SDK предоставляет функцию asKnownDaemonEvent(evt). Она возвращает дискриминированный KnownDaemonEvent для известных типов событий и undefined для остальных. Таким образом, потребители SDK могут обрабатывать прямую совместимость, не требуя обязательного обновления SDK при добавлении нового типа событий более новым демоном; редьюсер сессии записывает их как unrecognizedKnownEventCount.

Формат проводов описан в ../qwen-serve-protocol.md. Эта страница представляет собой контракт полезной нагрузки для каждого события.

Обязанности

• Предоставлять единый источник истины для словаря событий (DAEMON_KNOWN_EVENT_TYPE_VALUES).
• Предоставлять типизированный конверт для каждого типа событий (DaemonEventEnvelope<TType, TData>).
• Предоставлять чистые редьюсеры (reduceDaemonSessionEvent, reduceDaemonAuthEvent), которые проецируют поток событий в состояние представления SDK.
• Транслировать тег возможности typed_event_schema как информационный сигнал. Если тег отсутствует, asKnownDaemonEvent всё равно откатывается к unknown.

Словарь событий (43 известных типа)

Сгруппированы по доменам.

Основная сессия

Синтетические кадры на уровне подписчика

Разрешения (F3 + base)

Модели

Ограничения MCP (PR 14b + F2)

Управление мутациями (Wave 4 PR 16+17)

Поток аутентификации устройства (PR 21)

Эти события привязаны к рабочей области, а не к сессии. Reducer сессии обрабатывает их как no-op; reduceDaemonAuthEvent проецирует их в состояние уровня рабочей области.

Мутация времени выполнения MCP

Жизненный цикл хода / push-уведомления ассистента

Архитектура

DaemonSessionViewState

reduceDaemonSessionEvent заполняет это состояние представления. Его потребляют TUI-адаптер CLI, DaemonChannelBridge и VS Code IDE. Ключевые поля:

• alive: boolean — становится false после терминального фрейма (session_died, session_closed, client_evicted, stream_error).
• currentModelId?: string — из model_switched.
• displayName?: string — из session_metadata_updated.
• pendingPermissions: Record<string, DaemonPermissionRequestData> — открытые запросы, ключи — requestId; очищается по permission_resolved / permission_already_resolved.
• lastSessionUpdate?: DaemonSessionUpdateData — последнее session_update.
• lastModelSwitchFailure?: DaemonModelSwitchFailedData — из model_switch_failed.
• terminalEvent? — сырое терминальное событие.
• streamError?: DaemonStreamErrorData — последний payload stream_error.
• unrecognizedKnownEventCount, lastUnrecognizedKnownEvent? — событие распознано asKnownDaemonEvent, но редьюсер ещё не имеет для него выделенного состояния.
• droppedPermissionRequestCount, lastDroppedPermissionRequestId? — некорректный запрос разрешения не смог попасть в карту ожидающих.
• unmatchedPermissionResolutionCount, lastUnmatchedPermissionResolutionId? — разрешение не имело совпадающего ожидающего запроса.
• slowClientWarningCount, lastSlowClientWarning? — из slow_client_warning.
• mcpBudgetWarningCount, lastMcpBudgetWarning? — из mcp_budget_warning.
• mcpChildRefusedBatchCount, lastMcpChildRefusedBatch? — из mcp_child_refused_batch.
• lastWorkspaceMutation?, lastWorkspaceMutationType? — из memory_changed / agent_changed.
• approvalMode?, approvalModeChangedCount, lastApprovalModeChange? — из approval_mode_changed.
• toolToggleCount, lastToolToggle? — из tool_toggled.
• workspaceInitCount, lastWorkspaceInit? — из workspace_initialized.
• mcpRestartCount, lastMcpRestart? — из mcp_server_restarted.
• mcpRestartRefusedCount, lastMcpRestartRefused? — из mcp_server_restart_refused.
• settings_changed / settings_reloaded — распознаётся asKnownDaemonEvent; редьюсер сессии не поддерживает отдельные поля состояния представления, и UI обычно обрабатывают их как сигналы к обновлению.
• permissionVoteProgress: Record<string, DaemonPermissionPartialVoteData> — прогресс консенсусного голосования.
• forbiddenVotes: DaemonPermissionForbiddenData[], forbiddenVoteCount — записи голосов, отклонённых политикой; максимум 32.
• awaitingResync: boolean — устанавливается state_resync_required; очищается, когда потребитель сбрасывает состояние представления.
• resyncRequiredCount, lastResyncRequired? — наблюдаемость повторной синхронизации.
• lastFollowupSuggestion?: DaemonFollowupSuggestionData — последняя подсказка, отправленная демоном.
• lastTurnComplete?: DaemonTurnCompleteData — последнее успешное завершение шага.
• lastTurnError?: DaemonTurnErrorData — последняя ошибка шага.
• rewindCount, lastRewind?, lastBranch? — последние события перемотки / ветвления.

DaemonAuthState

Одна запись на providerId, управляется auth_device_flow_*. Каждый поток предоставляет { deviceFlowId, status, providerId, expiresAt?, lastThrottleIntervalMs?, lastError? }.

Поток

Сторона производителя

Сторона потребителя (SDK)

Метаданные уровня конверта

Помимо полезной нагрузки data каждого события, демон проставляет два поля уровня конверта.

_meta.serverTimestamp — часы демона

formatSseFrame() в packages/cli/src/serve/server.ts проставляет метку на границе записи SSE, не внутри EventBus.publish. Тип BridgeEvent в памяти остаётся без изменений; внутренние потребители демона не видят _meta, в то время как проволочные SSE-фреймы — видят.

{
  "id": 47,
  "v": 1,
  "type": "session_update",
  "data": { ... },
  "_meta": { "serverTimestamp": 1716287345123 }
}

Объединение сохраняет любые существующие ключи _meta ({...existingMeta, serverTimestamp: Date.now()}). Ни один текущий производитель демона не записывает _meta уровня конверта. Объединение на верхнем уровне — это запасной выход для прямой совместимости.

Почему это важно: многоклиентские интерфейсы, отображающие относительное время или сортирующие блоки транскрипции, должны использовать серверное время вместо локальных часов каждого браузера/вкладки/телефона. Серверная отметка сохраняет единый порядок для всех клиентов.

Доступ из SDK: предпочтительно event._meta?.serverTimestamp. Пути совместимости могут также проверять event.serverTimestamp или event.data._meta.serverTimestamp. Не смешивайте data._meta полезной нагрузки ACP с _meta конверта демона.

originatorClientId

События, вызванные запросом, который содержал зарегистрированный X-Qwen-Client-Id, могут заполнять это поле. См. 08-session-lifecycle.md.

_meta вызова инструмента (происхождение / serverId)

Это отдельно от _meta конверта: полезные нагрузки ACP session/update могут содержать собственный _meta в event.data._meta. ToolCallEmitter (packages/cli/src/acp-integration/session/emitters/ToolCallEmitter.ts) заполняет два поля в emitStart, emitResult и emitError:

Существующее отображаемое имя _meta.toolName сохраняется. Интерфейс использует эти поля для отображения значков встроенного / MCP-сервера / субагента без повторного разбора имени инструмента.

Поведение редьюсера SDK

reduceDaemonSessionEvent(state, evt) в packages/sdk-typescript/src/daemon/events.ts проецирует поток в DaemonSessionViewState. Поля, связанные с ресинхронизацией:

• awaitingResync: boolean — устанавливается через state_resync_required; вызывающий код сбрасывает его, обычно после POST /session/:id/load, который сбрасывает состояние представления.
• resyncRequiredCount: number — счётчик наблюдаемости.
• lastResyncRequired?: DaemonStateResyncRequiredData — последняя полезная нагрузка.

Когда awaitingResync = true, редьюсер пропускает применение дельты и разрешает только замкнутый набор RESYNC_PASSTHROUGH_TYPES:

reduceDaemonAuthEvent проецирует события потока устройства в состояние авторизации уровня рабочего пространства, которое концептуально имеет вид: {deviceFlowId, status, providerId, expiresAt?, lastThrottleIntervalMs?, lastError?}. В коде редьюсер хранит status, errorKind, hint, intervalMs, lastSeenEventId, authorizedExpiresAt и accountAlias в DaemonDeviceFlowReducerState; сами полезные нагрузки событий демона остаются в форматах, перечисленных выше для каждого события.

Состояние и обратная совместимость

• Добавьте новый известный тип события, добавив его в DAEMON_KNOWN_EVENT_TYPE_VALUES. Старые SDK возвращают undefined для неизвестных типов событий через путь запасного варианта и увеличивают unrecognizedKnownEventCount; новые SDK полагаются на discriminated union.
• Добавление необязательных полей в существующую полезную нагрузку безопасно, так как полезные нагрузки являются открытыми ({ [key: string]: unknown }).
• Изменение существующей формы полезной нагрузки является критическим изменением и требует увеличения EVENT_SCHEMA_VERSION, а также объявления совместимого тега возможности, например caps.features.typed_event_schema_v2.
• id является монотонным для каждой сессии. Синтетические кадры уровня подписчика (client_evicted, slow_client_warning, stream_error, state_resync_required, replay_complete, session_snapshot) намеренно не имеют id, чтобы другие подписчики не видели пробелов.
• originatorClientId находится в конверте, а не в data. Полезные нагрузки F3 partial-vote / forbidden также объединяют его в data через mergeOriginator, чтобы потребители состояния представления не нуждались в сохранении конверта.

Зависимости

• 10-event-bus.md — канал доставки.
• 11-capabilities-versioning.md — как SDK проверяют typed_event_schema, mcp_guardrail_events и permission_mediation.
• 04-permission-mediation.md — как создаются события разрешений.
• 13-sdk-daemon-client.md — asKnownDaemonEvent, редьюсеры и форма состояния представления.

Конфигурация

• Всегда объявляются: typed_event_schema, mcp_guardrail_events и permission_mediation (с поддерживаемыми режимами политик).
• Никакие переменные окружения или флаги напрямую не управляют самой схемой. QWEN_SERVE_NO_MCP_POOL=1 изменяет scope события MCP с 'workspace' на отсутствующее или 'session'.

Оговорки и известные ограничения

• Шесть типов синтетических кадров намеренно не имеют id; код SDK не должен предполагать, что каждое событие имеет id.
• permission_partial_vote появляется только в рамках consensus. permission_forbidden появляется в рамках designated, consensus и local-only, но не в рамках first-responder.
• mcp_child_refused_batch появляется только в режиме enforce; режим warn никогда не отказывает.
• События auth_device_flow_* не привязаны к сессии. При использовании через DaemonSessionClient для них следует использовать reduceDaemonAuthEvent, а не редьюсер сессии.

Ссылки

• packages/sdk-typescript/src/daemon/events.ts
• packages/acp-bridge/src/eventBus.ts (EVENT_SCHEMA_VERSION)
• packages/cli/src/serve/capabilities.ts (typed_event_schema, mcp_guardrail_events, permission_mediation)
• Спецификация протокола: ../qwen-serve-protocol.md