Schéma d’événements typés du démon v1

Vue d’ensemble

Chaque trame SSE émise par le démon sur GET /session/:id/events a la forme { id, v, type, data, originatorClientId?, _meta? }. v: 1 est la EVENT_SCHEMA_VERSION actuelle. type provient de l’ensemble fermé et épinglé par version DAEMON_KNOWN_EVENT_TYPE_VALUES dans packages/sdk-typescript/src/daemon/events.ts ; l’ensemble actuel compte 47 types d’événements connus. Le champ d’enveloppe _meta est estampillé à la limite d’écriture SSE par formatSseFrame() dans packages/cli/src/serve/routes/sse-events.ts ; voir Métadonnées au niveau de l’enveloppe.

Le SDK expose asKnownDaemonEvent(evt). Il retourne un KnownDaemonEvent discriminé pour les types d’événements connus et undefined pour les autres types. Les consommateurs du SDK peuvent ainsi gérer la compatibilité ascendante sans nécessiter une mise à jour du SDK au même rythme lorsqu’un démon plus récent ajoute un type d’événement ; le réducteur de session les enregistre sous unrecognizedKnownEventCount.

Le format de transmission se trouve dans ../qwen-serve-protocol.md. Cette page définit le contrat de charge utile pour chaque événement.

Responsabilités

• Fournir la source unique de vérité pour le vocabulaire des événements (DAEMON_KNOWN_EVENT_TYPE_VALUES).
• Fournir une enveloppe typée pour chaque type d’événement (DaemonEventEnvelope<TType, TData>).
• Fournir des réducteurs purs (reduceDaemonSessionEvent, reduceDaemonAuthEvent) qui projettent un flux d’événements dans l’état de vue du SDK.
• Diffuser le tag de capacité typed_event_schema comme signal informatif. Si le tag est absent, asKnownDaemonEvent retombe tout de même sur unknown.

Vocabulaire des événements (47 types connus)

Regroupés par domaine.

Session principale

Trames synthétiques au niveau de l’abonné

Permissions (F3 + base)

Modèles

Garde-fous MCP (PR 14b + F2)

Contrôle des mutations (Wave 4 PR 16+17)

memory_changed couvre également les tâches de mémoire managée sans session. Pour ces payloads, scope est "managed", source est l’un des éléments suivants : "workspace_memory_remember", "workspace_memory_forget" ou "workspace_memory_dream", taskId est l’identifiant de la tâche en file d’attente, et touchedScopes liste les scopes de mémoire managée qui ont changé ("user" et/ou "project"). Aucun événement n’est émis lorsqu’une tâche remember/forget/dream se termine sans toucher la mémoire managée.

Flux d’authentification par appareil (PR 21)

Ces événements sont indexés par workspace, et non par session. Le reducer de session les traite comme des no-ops ; reduceDaemonAuthEvent les projette dans l’état au niveau du workspace.

Mutation runtime MCP

Cycle de vie des extensions

Injection de messages en cours de tour

Cycle de vie du tour / pushes de l’assistant

Architecture

DaemonSessionViewState

reduceDaemonSessionEvent remplit cet état de vue. L’adaptateur CLI TUI, DaemonChannelBridge et l’IDE VS Code le consomment. Champs clés :

• alive: boolean - devient false après une frame terminale (session_died, session_closed, client_evicted, stream_error).
• currentModelId?: string - provenant de model_switched.
• displayName?: string - provenant de session_metadata_updated.
• pendingPermissions: Record<string, DaemonPermissionRequestData> - requêtes ouvertes indexées par requestId ; vidées par permission_resolved / permission_already_resolved.
• lastSessionUpdate?: DaemonSessionUpdateData - dernier session_update.
• lastModelSwitchFailure?: DaemonModelSwitchFailedData - provenant de model_switch_failed.
• terminalEvent? - événement terminal brut.
• streamError?: DaemonStreamErrorData - dernier payload stream_error.
• unrecognizedKnownEventCount, lastUnrecognizedKnownEvent? - l’événement a été reconnu par asKnownDaemonEvent mais le reducer n’a pas encore d’état dédié pour celui-ci.
• droppedPermissionRequestCount, lastDroppedPermissionRequestId? - une requête de permission malformée n’a pas pu entrer dans la map pending.
• unmatchedPermissionResolutionCount, lastUnmatchedPermissionResolutionId? - la résolution de permission n’avait aucune requête pending correspondante.
• slowClientWarningCount, lastSlowClientWarning? - provenant de slow_client_warning.
• mcpBudgetWarningCount, lastMcpBudgetWarning? - provenant de mcp_budget_warning.
• mcpChildRefusedBatchCount, lastMcpChildRefusedBatch? - provenant de mcp_child_refused_batch.
• lastWorkspaceMutation?, lastWorkspaceMutationType? - provenant de memory_changed / agent_changed.
• approvalMode?, approvalModeChangedCount, lastApprovalModeChange? - provenant de approval_mode_changed.
• toolToggleCount, lastToolToggle? - provenant de tool_toggled.
• workspaceInitCount, lastWorkspaceInit? - provenant de workspace_initialized.
• mcpRestartCount, lastMcpRestart? - provenant de mcp_server_restarted.
• mcpRestartRefusedCount, lastMcpRestartRefused? - provenant de mcp_server_restart_refused.
• settings_changed / settings_reloaded - reconnus par asKnownDaemonEvent ; le reducer de session ne maintient pas de champs d’état de vue dédiés, et les UI les traitent généralement comme des signaux d’actualisation.
• permissionVoteProgress: Record<string, DaemonPermissionPartialVoteData> - progression du vote par consensus.
• forbiddenVotes: DaemonPermissionForbiddenData[], forbiddenVoteCount - enregistrements de votes rejetés par la politique, plafonnés à 32.
• awaitingResync: boolean - défini par state_resync_required ; vidé lorsque le consommateur réinitialise l’état de vue.
• resyncRequiredCount, lastResyncRequired? - observabilité de la resynchronisation.
• lastFollowupSuggestion?: DaemonFollowupSuggestionData - dernière suggestion de suivi poussée par le daemon.
• lastTurnComplete?: DaemonTurnCompleteData - dernière complétion de tour réussie.
• lastTurnError?: DaemonTurnErrorData - dernière erreur de tour.
• rewindCount, lastRewind?, lastBranch? - derniers événements rewind / branch.

DaemonAuthState

Une entrée par providerId, pilotée par auth_device_flow_*. Chaque flux expose { deviceFlowId, status, providerId, expiresAt?, lastThrottleIntervalMs?, lastError? }.

Flux

Côté producteur

Côté consommateur (SDK)

Métadonnées au niveau de l’enveloppe

Au-delà de la charge utile data de chaque événement, le démon ajoute deux champs au niveau de l’enveloppe.

_meta.serverTimestamp - horloge du démon

EventBus.publish() dans packages/acp-bridge/src/eventBus.ts ajoute _meta.serverTimestamp lorsque l’événement entre dans le bus. Le type BridgeEvent inclut _meta?: Record<string, unknown>, ainsi les consommateurs internes du démon voient bien _meta sur chaque événement publié dans le bus. formatSseFrame() dans packages/cli/src/serve/routes/sse-events.ts fournit un timestamp de secours uniquement pour les trames synthétiques (par ex. stream_error) qui contournent EventBus.publish.

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

La fusion préserve toutes les clés _meta existantes de l’événement d’entrée ({...input._meta, serverTimestamp: Date.now()}). Les producteurs peuvent attacher des clés _meta supplémentaires au niveau de l’enveloppe ; EventBus.publish les fusionne avec le timestamp au lieu de les écraser.

Pourquoi c’est important : les interfaces multi-clients qui affichent un temps relatif ou trient les blocs de transcription doivent utiliser l’heure du serveur au lieu de l’horloge locale de chaque navigateur/onglet/téléphone. L’horodatage par le serveur maintient un ordre cohérent entre les clients.

Accès SDK : préférez event._meta?.serverTimestamp. Les chemins de compatibilité peuvent aussi sonder event.serverTimestamp ou event.data._meta.serverTimestamp. Ne mélangez pas le _meta de la charge utile ACP data._meta avec le _meta de l’enveloppe du démon.

originatorClientId

Les événements déclenchés par une requête portant un X-Qwen-Client-Id enregistré peuvent renseigner ce champ. Voir 08-session-lifecycle.md.

_meta des appels d’outils (provenance / serverId)

Ceci est distinct du _meta de l’enveloppe : les charges utiles ACP session/update peuvent porter leur propre _meta dans event.data._meta. ToolCallEmitter (packages/cli/src/acp-integration/session/emitters/ToolCallEmitter.ts) ajoute deux champs lors de emitStart, emitResult et emitError :

Le nom d’affichage existant _meta.toolName est conservé. L’interface utilisateur utilise ces champs pour afficher les badges builtin / serveur MCP / subagent sans avoir à reparser le nom de l’outil.

Comportement du reducer SDK

reduceDaemonSessionEvent(state, evt) dans packages/sdk-typescript/src/daemon/events.ts projette le flux dans DaemonSessionViewState. Les champs liés à la resynchronisation sont :

• awaitingResync: boolean - défini par state_resync_required ; l’appelant le réinitialise, généralement après que POST /session/:id/load a réinitialisé l’état de la vue.
• resyncRequiredCount: number - compteur d’observabilité.
• lastResyncRequired?: DaemonStateResyncRequiredData - dernière charge utile.

Tant que awaitingResync = true, le reducer ignore l’application des deltas et n’autorise que l’ensemble fermé RESYNC_PASSTHROUGH_TYPES :

lastEventId continue d’avancer de manière monotone via advanceLastEventId(base) pendant la resynchronisation. Après que l’appelant a réinitialisé et effacé awaitingResync, les deltas suivants s’alignent sur le bon curseur.

reduceDaemonAuthEvent projette les événements de flux d’appareil (device-flow) dans des entrées d’état d’authentification au niveau du workspace, ayant conceptuellement la forme {deviceFlowId, status, providerId, expiresAt?, lastThrottleIntervalMs?, lastError?}. Dans le code, le reducer stocke status, errorKind, hint, intervalMs, lastSeenEventId, authorizedExpiresAt et accountAlias sur DaemonDeviceFlowReducerState ; les charges utiles des événements du démon restent quant à elles conformes aux formes par événement listées ci-dessus.

État et compatibilité ascendante

• Ajoutez un type d’événement connu en l’ajoutant à DAEMON_KNOWN_EVENT_TYPE_VALUES. Les anciens SDKs retournent undefined pour les types d’événements non reconnus via le chemin de secours et incrémentent unrecognizedKnownEventCount ; les nouveaux SDKs s’appuient sur l’union discriminée.
• L’ajout de champs optionnels à une charge utile existante est sûr car les charges utiles sont ouvertes ({ [key: string]: unknown }).
• Modifier la forme d’une charge utile existante est un changement cassant (breaking) et doit incrémenter EVENT_SCHEMA_VERSION ainsi qu’annoncer un tag de capacité compatible tel que caps.features.typed_event_schema_v2.
• id est monotone par session. Les trames synthétiques au niveau de l’abonné (client_evicted, slow_client_warning, stream_error, state_resync_required, replay_complete, session_snapshot) n’ont volontairement pas d’id afin que les autres abonnés ne voient pas de trous.
• originatorClientId se trouve sur l’enveloppe plutôt que dans data. Les charges utiles F3 partial-vote / forbidden le fusionnent également dans data via mergeOriginator afin que les consommateurs de l’état de la vue n’aient pas besoin de conserver l’enveloppe.

Dépendances

• 10-event-bus.md - canal de livraison.
• 11-capabilities-versioning.md - comment les SDKs pré-vérifient typed_event_schema, mcp_guardrail_events et permission_mediation.
• 04-permission-mediation.md - comment les événements de permission sont produits.
• 13-sdk-daemon-client.md - asKnownDaemonEvent, reducers et forme de l’état de la vue.

Configuration

• Toujours annoncées : typed_event_schema, mcp_guardrail_events et permission_mediation (avec les modes de politique supportés).
• Aucune variable d’environnement ou flag ne contrôle directement le schéma lui-même. QWEN_SERVE_NO_MCP_POOL=1 change le scope des événements MCP de 'workspace' à absent ou 'session'.

Mises en garde et limites connues

• Six types de trames synthétiques n’ont volontairement pas d’id ; le code du SDK ne doit pas supposer que chaque événement a un id.
• permission_partial_vote n’apparaît que sous consensus. permission_forbidden apparaît sous designated, consensus et local-only, mais pas sous first-responder.
• mcp_child_refused_batch n’apparaît qu’en mode: 'enforce' ; le mode warn ne refuse jamais.
• Les événements auth_device_flow_* ne sont pas liés à une session. Lors de la consommation via DaemonSessionClient, utilisez reduceDaemonAuthEvent pour ceux-ci plutôt que le reducer de session.

Références

• 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)
• Référence wire : ../qwen-serve-protocol.md