Typed Daemon Event Schema v1

Übersicht

Jeder SSE-Frame, der vom Daemon auf GET /session/:id/events ausgegeben wird, hat die Form { id, v, type, data, originatorClientId?, _meta? }. v: 1 ist die aktuelle EVENT_SCHEMA_VERSION. type stammt aus dem geschlossenen, versionsfixierten DAEMON_KNOWN_EVENT_TYPE_VALUES-Set in packages/sdk-typescript/src/daemon/events.ts; das aktuelle Set hat 43 bekannte Ereignistypen. Das Meta-Feld _meta im Umschlag wird an der SSE-Schreibgrenze von formatSseFrame() in server.ts eingestempelt; siehe Envelope-level metadata.

Das SDK stellt asKnownDaemonEvent(evt) zur Verfügung. Es gibt ein unterscheidbares KnownDaemonEvent für bekannte Ereignistypen zurück, für andere Typen undefined. SDK-Konsumenten können somit vorwärtskompatibel bleiben, ohne ein gleichzeitiges SDK-Upgrade zu benötigen, wenn ein neuerer Daemon einen Ereignistyp hinzufügt; der Session-Reducer zeichnet diese als unrecognizedKnownEventCount auf.

Das Wire-Format befindet sich in ../qwen-serve-protocol.md. Diese Seite enthält den Payload-Vertrag für jedes Ereignis.

Verantwortlichkeiten

• Bietet die einzige Quelle der Wahrheit für das Ereignisvokabular (DAEMON_KNOWN_EVENT_TYPE_VALUES).
• Bietet einen typisierten Umschlag für jeden Ereignistyp (DaemonEventEnvelope<TType, TData>).
• Bietet reine Reducer (reduceDaemonSessionEvent, reduceDaemonAuthEvent), die einen Ereignisstrom in den SDK-Ansichtszustand projizieren.
• Sendet den Fähigkeits-Tag typed_event_schema als informatives Signal. Fehlt der Tag, fällt asKnownDaemonEvent trotzdem auf unknown zurück.

Ereignisvokabular (43 bekannte Typen)

Nach Domäne gruppiert.

Core-Session

Subscriberebene synthetische Frames

Berechtigungen (F3 + Basis)

Modelle

MCP-Guardrails (PR 14b + F2)

Mutationssteuerung (Wave 4 PR 16+17)

Auth-Geräteflow (PR 21)

Diese Ereignisse sind Workspace-schlüsselig, nicht Sitzungsschlüsselig. Der Sitzungs-Reduzierer behandelt sie als No-Ops; reduceDaemonAuthEvent projiziert sie in den Zustand auf Workspace-Ebene.

MCP-Laufzeitmutation

Turn-Lebenszyklus / Assistenz-Pushes

Architektur

DaemonSessionViewState

reduceDaemonSessionEvent füllt diesen Ansichtszustand. Der CLI-TUI-Adapter, DaemonChannelBridge und die VS Code-IDE verwenden ihn. Wichtige Felder:

• alive: boolean – wird false nach einem Terminal-Frame (session_died, session_closed, client_evicted, stream_error).
• currentModelId?: string – von model_switched.
• displayName?: string – von session_metadata_updated.
• pendingPermissions: Record<string, DaemonPermissionRequestData> – offene Anfragen, indiziert nach requestId; gelöscht durch permission_resolved / permission_already_resolved.
• lastSessionUpdate?: DaemonSessionUpdateData – letztes session_update.
• lastModelSwitchFailure?: DaemonModelSwitchFailedData – von model_switch_failed.
• terminalEvent? – rohes Terminal-Ereignis.
• streamError?: DaemonStreamErrorData – letztes stream_error-Payload.
• unrecognizedKnownEventCount, lastUnrecognizedKnownEvent? – Ereignis wurde von asKnownDaemonEvent erkannt, aber der Reduzierer hat noch keinen dedizierten Zustand dafür.
• droppedPermissionRequestCount, lastDroppedPermissionRequestId? – fehlerhafte Berechtigungsanfrage konnte nicht in die ausstehende Map eingetragen werden.
• unmatchedPermissionResolutionCount, lastUnmatchedPermissionResolutionId? – Berechtigungsauflösung hatte keine passende ausstehende Anfrage.
• slowClientWarningCount, lastSlowClientWarning? – von slow_client_warning.
• mcpBudgetWarningCount, lastMcpBudgetWarning? – von mcp_budget_warning.
• mcpChildRefusedBatchCount, lastMcpChildRefusedBatch? – von mcp_child_refused_batch.
• lastWorkspaceMutation?, lastWorkspaceMutationType? – von memory_changed / agent_changed.
• approvalMode?, approvalModeChangedCount, lastApprovalModeChange? – von approval_mode_changed.
• toolToggleCount, lastToolToggle? – von tool_toggled.
• workspaceInitCount, lastWorkspaceInit? – von workspace_initialized.
• mcpRestartCount, lastMcpRestart? – von mcp_server_restarted.
• mcpRestartRefusedCount, lastMcpRestartRefused? – von mcp_server_restart_refused.
• settings_changed / settings_reloaded – von asKnownDaemonEvent erkannt; der Session-Reduzierer unterhält keine dedizierten Ansichtszustandsfelder, und UIs behandeln sie normalerweise als Aktualisierungssignale.
• permissionVoteProgress: Record<string, DaemonPermissionPartialVoteData> – Fortschritt der Konsensabstimmung.
• forbiddenVotes: DaemonPermissionForbiddenData[], forbiddenVoteCount – durch Richtlinien abgelehnte Abstimmungsdatensätze, begrenzt auf 32.
• awaitingResync: boolean – gesetzt durch state_resync_required; gelöscht, wenn der Verbraucher den Ansichtszustand zurücksetzt.
• resyncRequiredCount, lastResyncRequired? – Resync-Beobachtbarkeit.
• lastFollowupSuggestion?: DaemonFollowupSuggestionData – letzter vom Daemon übermittelter Folge-Vorschlag.
• lastTurnComplete?: DaemonTurnCompleteData – letzte erfolgreiche Abschlussrunde.
• lastTurnError?: DaemonTurnErrorData – letzter Rundenfehler.
• rewindCount, lastRewind?, lastBranch? – neueste Rewind/Branch-Ereignisse.

DaemonAuthState

Ein Eintrag pro providerId, gesteuert durch auth_device_flow_*. Jeder Flow stellt { deviceFlowId, status, providerId, expiresAt?, lastThrottleIntervalMs?, lastError? } bereit.

Ablauf

Produzentenseite

Konsumentenseite (SDK)

Metadaten auf Envelope-Ebene

Über die data-Nutzlast jedes Ereignisses hinaus fügt der Daemon zwei Felder auf Envelope-Ebene hinzu.

_meta.serverTimestamp – Daemon-Uhr

formatSseFrame() in packages/cli/src/serve/server.ts fügt dies am SSE-Schreibrand ein, nicht innerhalb von EventBus.publish. Der In-Memory-Typ BridgeEvent bleibt unverändert; interne Daemon-Konsumenten sehen _meta nicht, wohl aber die SSE-Frames auf der Leitung.

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

Die Merge-Operation bewahrt vorhandene _meta-Schlüssel ({...existingMeta, serverTimestamp: Date.now()}). Kein aktueller Daemon-Produzent schreibt _meta auf Envelope-Ebene. Der Merge auf oberster Ebene ist eine Vorwärtskompatibilitäts-Notluke.

Warum das wichtig ist: Multi-Client-UIs, die relative Zeiten anzeigen oder Transkriptblöcke sortieren, sollten die Serverzeit anstelle der lokalen Uhr jedes Browsers/Tabs/Telefons verwenden. Das Server-Stempeln sorgt für konsistente Reihenfolge über alle Clients hinweg.

SDK-Zugriff: Bevorzugt event._meta?.serverTimestamp. Kompatibilitätspfade können auch event.serverTimestamp oder event.data._meta.serverTimestamp abfragen. Mischen Sie nicht ACP-Nutzlast data._meta mit Daemon-Envelope _meta.

originatorClientId

Ereignisse, die durch eine Anfrage mit einer registrierten X-Qwen-Client-Id ausgelöst wurden, können dieses Feld setzen. Siehe 08-session-lifecycle.md.

Tool-Aufruf _meta (Provenienz / serverId)

Dies ist getrennt vom Envelope-_meta: ACP session/update-Nutzlasten können ihr eigenes _meta in event.data._meta tragen. ToolCallEmitter (packages/cli/src/acp-integration/session/emitters/ToolCallEmitter.ts) setzt zwei Felder bei emitStart, emitResult und emitError:

Der vorhandene Anzeigename _meta.toolName bleibt erhalten. Die UI verwendet diese Felder, um Abzeichen für Builtin / MCP-Server / Subagent anzuzeigen, ohne den Tool-Namen neu parsen zu müssen.

SDK-Reducer-Verhalten

reduceDaemonSessionEvent(state, evt) in packages/sdk-typescript/src/daemon/events.ts projiziert den Stream in DaemonSessionViewState. Die auf Resync bezogenen Felder sind:

• awaitingResync: boolean – wird durch state_resync_required gesetzt; der Aufrufer löscht es, typischerweise nachdem POST /session/:id/load den Ansichtszustand zurückgesetzt hat.
• resyncRequiredCount: number – Beobachtbarkeitszähler.
• lastResyncRequired?: DaemonStateResyncRequiredData – letzte Nutzlast.

Solange awaitingResync = true ist, überspringt der Reducer die Deltakumulation und erlaubt nur die geschlossene Menge RESYNC_PASSTHROUGH_TYPES:

reduceDaemonAuthEvent projiziert Device-Flow-Ereignisse in Arbeitsbereichs-Authentifizierungsstatus-Einträge mit der Struktur {deviceFlowId, status, providerId, expiresAt?, lastThrottleIntervalMs?, lastError?} konzeptionell. Im Code speichert der Reducer status, errorKind, hint, intervalMs, lastSeenEventId, authorizedExpiresAt und accountAlias in DaemonDeviceFlowReducerState; die Daemon-Ereignis-Payloads selbst behalten die oben aufgeführten Pro-Ereignis-Formen.

Zustand und Vorwärtskompatibilität

• Füge einen bekannten Ereignistyp hinzu, indem du ihn an DAEMON_KNOWN_EVENT_TYPE_VALUES anhängst. Alte SDKs geben für nicht erkannte Ereignistypen über den Fallback-Pfad undefined zurück und erhöhen unrecognizedKnownEventCount; neue SDKs verlassen sich auf die diskriminierte Union.
• Das Hinzufügen optionaler Felder zu einer vorhandenen Payload ist sicher, da Payloads offen sind ({ [key: string]: unknown }).
• Das Ändern der Form einer vorhandenen Payload ist ein Breaking Change und muss EVENT_SCHEMA_VERSION erhöhen sowie ein kompatibles Capability-Tag wie caps.features.typed_event_schema_v2 bewerben.
• id ist pro Sitzung monoton. Synthetische Frames auf Subscriber-Ebene (client_evicted, slow_client_warning, stream_error, state_resync_required, replay_complete, session_snapshot) haben absichtlich keine id, damit andere Subscriber keine Lücken sehen.
• originatorClientId befindet sich im Envelope und nicht in data. F3 partial-vote- / forbidden-Payloads führen es ebenfalls über mergeOriginator in data zusammen, sodass View-State-Consumer den Envelope nicht behalten müssen.

Abhängigkeiten

• 10-event-bus.md - Auslieferungskanal.
• 11-capabilities-versioning.md - wie SDKs typed_event_schema, mcp_guardrail_events und permission_mediation vorab prüfen.
• 04-permission-mediation.md - wie Berechtigungsereignisse erzeugt werden.
• 13-sdk-daemon-client.md - asKnownDaemonEvent, Reducer und View-State-Form.

Konfiguration

• Immer beworben: typed_event_schema, mcp_guardrail_events und permission_mediation (mit unterstützten Policy-Modi).
• Keine Umgebungsvariable oder Flag steuert das Schema selbst direkt. QWEN_SERVE_NO_MCP_POOL=1 ändert den MCP-Ereignis-scope von 'workspace' auf nicht vorhanden oder 'session'.

Hinweise und bekannte Einschränkungen

• Sechs synthetische Frame-Typen haben absichtlich keine id; SDK-Code darf nicht annehmen, dass jedes Ereignis eine id hat.
• permission_partial_vote erscheint nur unter consensus. permission_forbidden erscheint unter designated, consensus und local-only, aber nicht unter first-responder.
• mcp_child_refused_batch erscheint nur im mode: 'enforce'; der warn-Modus lehnt nie ab.
• auth_device_flow_*-Ereignisse sind nicht sitzungsschlüsselgebunden. Bei der Verarbeitung über DaemonSessionClient verwende für sie reduceDaemonAuthEvent anstelle des Session-Reducers.

Verweise

• 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)
• Wire-Referenz: ../qwen-serve-protocol.md