Esquema de Eventos Tipados do Daemon v1

Visão geral

Cada quadro SSE emitido pelo daemon em GET /session/:id/events possui a forma { id, v, type, data, originatorClientId?, _meta? }. v: 1 é a versão atual de EVENT_SCHEMA_VERSION. O type provém do conjunto fechado e fixo de versão DAEMON_KNOWN_EVENT_TYPE_VALUES, definido em packages/sdk-typescript/src/daemon/events.ts; o conjunto atual possui 43 tipos de eventos conhecidos. O campo de envelope _meta é carimbado no limite de escrita SSE por formatSseFrame() em server.ts; veja Metadados no nível do envelope.

O SDK expõe asKnownDaemonEvent(evt). Ele retorna um KnownDaemonEvent discriminado para tipos de eventos conhecidos e undefined para outros tipos. Consumidores do SDK podem, portanto, lidar com compatibilidade futura sem exigir uma atualização sincronizada do SDK quando um daemon mais novo adiciona um tipo de evento; o redutor da sessão registra esses como unrecognizedKnownEventCount.

O formato de transmissão está em ../qwen-serve-protocol.md. Esta página é o contrato de payload para cada evento.

Responsabilidades

• Fornecer a única fonte da verdade para o vocabulário de eventos (DAEMON_KNOWN_EVENT_TYPE_VALUES).
• Fornecer um envelope tipado para cada tipo de evento (DaemonEventEnvelope<TType, TData>).
• Fornecer redutores puros (reduceDaemonSessionEvent, reduceDaemonAuthEvent) que projetam um fluxo de eventos no estado de visualização do SDK.
• Transmitir a tag de capacidade typed_event_schema como um sinal informativo. Se a tag estiver ausente, asKnownDaemonEvent ainda recai para unknown.

Vocabulário de eventos (43 tipos conhecidos)

Agrupados por domínio.

Sessão principal

Quadros sintéticos no nível do assinante

Permissões (F3 + base)

Modelos

Proteções MCP (PR 14b + F2)

Controle de mutação (Wave 4 PR 16+17)

Fluxo de dispositivo de autenticação (PR 21)

Estes eventos são chaveados por workspace, não por sessão. O reducer de sessão os trata como no-ops; reduceDaemonAuthEvent os projeta no estado de nível de workspace.

Mutação em tempo de execução do MCP

Ciclo de vida de turno / pushes do assistente

Arquitetura

DaemonSessionViewState

reduceDaemonSessionEvent preenche este estado de visualização. O adaptador CLI TUI, o DaemonChannelBridge e o VS Code IDE o consomem. Campos principais:

• alive: boolean - torna-se false após um frame terminal (session_died, session_closed, client_evicted, stream_error).
• currentModelId?: string - de model_switched.
• displayName?: string - de session_metadata_updated.
• pendingPermissions: Record<string, DaemonPermissionRequestData> - solicitações abertas indexadas por requestId; limpas por permission_resolved / permission_already_resolved.
• lastSessionUpdate?: DaemonSessionUpdateData - último session_update.
• lastModelSwitchFailure?: DaemonModelSwitchFailedData - de model_switch_failed.
• terminalEvent? - evento terminal bruto.
• streamError?: DaemonStreamErrorData - último payload de stream_error.
• unrecognizedKnownEventCount, lastUnrecognizedKnownEvent? - evento foi reconhecido por asKnownDaemonEvent mas o redutor ainda não possui estado dedicado para ele.
• droppedPermissionRequestCount, lastDroppedPermissionRequestId? - solicitação de permissão malformada não pôde entrar no mapa de pendentes.
• unmatchedPermissionResolutionCount, lastUnmatchedPermissionResolutionId? - resolução de permissão não teve solicitação pendente correspondente.
• slowClientWarningCount, lastSlowClientWarning? - de slow_client_warning.
• mcpBudgetWarningCount, lastMcpBudgetWarning? - de mcp_budget_warning.
• mcpChildRefusedBatchCount, lastMcpChildRefusedBatch? - de mcp_child_refused_batch.
• lastWorkspaceMutation?, lastWorkspaceMutationType? - de memory_changed / agent_changed.
• approvalMode?, approvalModeChangedCount, lastApprovalModeChange? - de approval_mode_changed.
• toolToggleCount, lastToolToggle? - de tool_toggled.
• workspaceInitCount, lastWorkspaceInit? - de workspace_initialized.
• mcpRestartCount, lastMcpRestart? - de mcp_server_restarted.
• mcpRestartRefusedCount, lastMcpRestartRefused? - de mcp_server_restart_refused.
• settings_changed / settings_reloaded - reconhecidos por asKnownDaemonEvent; o redutor de sessão não mantém campos de estado de visualização dedicados, e as interfaces geralmente os tratam como sinais de atualização.
• permissionVoteProgress: Record<string, DaemonPermissionPartialVoteData> - progresso de votação por consenso.
• forbiddenVotes: DaemonPermissionForbiddenData[], forbiddenVoteCount - registros de votos rejeitados por política, limitados a 32.
• awaitingResync: boolean - definido por state_resync_required; limpo quando o consumidor redefine o estado de visualização.
• resyncRequiredCount, lastResyncRequired? - observabilidade de ressincronização.
• lastFollowupSuggestion?: DaemonFollowupSuggestionData - última sugestão de acompanhamento enviada pelo daemon.
• lastTurnComplete?: DaemonTurnCompleteData - última conclusão de turno bem-sucedida.
• lastTurnError?: DaemonTurnErrorData - último erro de turno.
• rewindCount, lastRewind?, lastBranch? - últimos eventos de retrocesso / ramificação.

DaemonAuthState

Uma entrada por providerId, orientada por auth_device_flow_*. Cada fluxo expõe { deviceFlowId, status, providerId, expiresAt?, lastThrottleIntervalMs?, lastError? }.

Fluxo

Lado produtor

Lado consumidor (SDK)

Metadados em nível de envelope

Além do payload data de cada evento, o daemon carimba dois campos em nível de envelope.

_meta.serverTimestamp - relógio do daemon

formatSseFrame() em packages/cli/src/serve/server.ts carimba isso no limite de escrita SSE, não dentro de EventBus.publish. O tipo BridgeEvent em memória permanece inalterado; consumidores internos do daemon não veem _meta, enquanto os quadros SSE na fio veem.

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

A mesclagem preserva quaisquer chaves _meta existentes ({...existingMeta, serverTimestamp: Date.now()}). Nenhum produtor atual do daemon escreve _meta em nível de envelope. A mesclagem de alto nível é uma válvula de escape de compatibilidade futura.

Por que é importante: UIs com vários clientes que renderizam tempo relativo ou ordenam blocos de transcrição devem usar o tempo do servidor em vez do relógio local de cada navegador/aba/telefone. O carimbo do servidor mantém a ordenação consistente entre clientes.

Acesso no SDK: prefira event._meta?.serverTimestamp. Caminhos de compatibilidade também podem sondar event.serverTimestamp ou event.data._meta.serverTimestamp. Não misture data._meta do payload ACP com _meta do envelope do daemon.

originatorClientId

Eventos acionados por uma requisição que continha um X-Qwen-Client-Id registrado podem carimbar este campo. Veja 08-session-lifecycle.md.

_meta de chamada de ferramenta (procedência / serverId)

Isso é separado do _meta do envelope: os payloads ACP session/update podem carregar seu próprio _meta em event.data._meta. ToolCallEmitter (packages/cli/src/acp-integration/session/emitters/ToolCallEmitter.ts) carimba dois campos em emitStart, emitResult e emitError:

O nome de exibição _meta.toolName existente é preservado. A UI usa esses campos para renderizar emblemas de ferramenta builtin / servidor MCP / subagente sem precisar reanalisar o nome da ferramenta.

Comportamento do redutor do SDK

reduceDaemonSessionEvent(state, evt) em packages/sdk-typescript/src/daemon/events.ts projeta o fluxo em DaemonSessionViewState. Os campos relacionados à ressincronização são:

• awaitingResync: boolean - definido por state_resync_required; o chamador limpa, tipicamente após POST /session/:id/load redefinir o estado da visão.
• resyncRequiredCount: number - contador de observabilidade.
• lastResyncRequired?: DaemonStateResyncRequiredData - payload mais recente.

Enquanto awaitingResync = true, o redutor pula a aplicação de delta e permite apenas o conjunto fechado RESYNC_PASSTHROUGH_TYPES:

reduceDaemonAuthEvent projeta eventos de fluxo de dispositivo em entradas de estado de autenticação no nível do workspace formatadas como {deviceFlowId, status, providerId, expiresAt?, lastThrottleIntervalMs?, lastError?} conceitualmente. No código, o redutor armazena status, errorKind, hint, intervalMs, lastSeenEventId, authorizedExpiresAt e accountAlias em DaemonDeviceFlowReducerState; os payloads dos eventos do daemon permanecem nos formatos por evento listados acima.

Estado e compatibilidade futura

• Adicione um tipo de evento conhecido anexando a DAEMON_KNOWN_EVENT_TYPE_VALUES. SDKs antigos retornam undefined para tipos de evento não reconhecidos através do caminho de fallback e incrementam unrecognizedKnownEventCount; SDKs novos dependem da união discriminada.
• Adicionar campos opcionais a um payload existente é seguro porque os payloads são abertos ({ [key: string]: unknown }).
• Alterar a forma de um payload existente é uma quebra e deve incrementar EVENT_SCHEMA_VERSION além de anunciar uma tag de capacidade compatível como caps.features.typed_event_schema_v2.
• id é monotônico por sessão. Frames sintéticos no nível do assinante (client_evicted, slow_client_warning, stream_error, state_resync_required, replay_complete, session_snapshot) intencionalmente não possuem id para que outros assinantes não vejam lacunas.
• originatorClientId vive no envelope em vez de data. Payloads de voto parcial proibido do F3 também o mesclam em data através de mergeOriginator para que consumidores do estado da visão não precisem reter o envelope.

Dependências

• 10-event-bus.md - canal de entrega.
• 11-capabilities-versioning.md - como SDKs fazem preflight de typed_event_schema, mcp_guardrail_events e permission_mediation.
• 04-permission-mediation.md - como eventos de permissão são produzidos.
• 13-sdk-daemon-client.md - asKnownDaemonEvent, redutores e formato do estado da visão.

Configuração

• Sempre anunciados: typed_event_schema, mcp_guardrail_events e permission_mediation (com os modos de política suportados).
• Nenhuma variável de ambiente ou flag controla diretamente o esquema em si. QWEN_SERVE_NO_MCP_POOL=1 altera o scope do evento MCP de 'workspace' para ausente ou 'session'.

Riscos e limitações conhecidas

• Seis tipos de frame sintéticos intencionalmente não possuem id; o código do SDK não deve presumir que todo evento tem um id.
• permission_partial_vote aparece apenas sob consensus. permission_forbidden aparece sob designated, consensus e local-only, mas não sob first-responder.
• mcp_child_refused_batch aparece apenas em mode: 'enforce'; o modo warn nunca recusa.
• Eventos auth_device_flow_* não são chaveados por sessão. Ao consumir através de DaemonSessionClient, use reduceDaemonAuthEvent para eles em vez do redutor de sessão.

Referências

• 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)
• Referência do protocolo: ../qwen-serve-protocol.md