Typed Daemon Event Schema v1

Übersicht

Jeder vom Daemon auf GET /session/:id/events ausgegebene SSE-Frame hat die Form { id, v, type, data, originatorClientId?, _meta? }. v: 1 ist die aktuelle EVENT_SCHEMA_VERSION. type stammt aus dem abgeschlossenen, versionsgebundenen DAEMON_KNOWN_EVENT_TYPE_VALUES-Set in packages/sdk-typescript/src/daemon/events.ts; das aktuelle Set umfasst 47 bekannte Event-Typen. Das _meta-Feld des Envelopes wird an der SSE-Schreibgrenze von formatSseFrame() in packages/cli/src/serve/routes/sse-events.ts gestempelt; siehe Metadaten auf Envelope-Ebene.

Das SDK stellt asKnownDaemonEvent(evt) bereit. Es gibt ein diskriminiertes KnownDaemonEvent für bekannte Event-Typen und undefined für andere Typen zurück. SDK-Consumer können dadurch Forward Compatibility handhaben, ohne ein gleichzeitiges SDK-Upgrade zu benötigen, wenn ein neuerer Daemon einen Event-Typ hinzufügt; der Session-Reducer erfasst diese als unrecognizedKnownEventCount.

Das Wire-Format befindet sich in ../qwen-serve-protocol.md. Diese Seite definiert den Payload-Vertrag für jedes Event.

Verantwortlichkeiten

• Bereitstellung der Single Source of Truth für das Event-Vokabular (DAEMON_KNOWN_EVENT_TYPE_VALUES).
• Bereitstellung eines typisierten Envelopes für jeden Event-Typ (DaemonEventEnvelope<TType, TData>).
• Bereitstellung reiner Reducer (reduceDaemonSessionEvent, reduceDaemonAuthEvent), die einen Event-Stream in den SDK-View-State projizieren.
• Broadcast des typed_event_schema Capability-Tags als Informationssignal. Wenn das Tag fehlt, fällt asKnownDaemonEvent dennoch auf unknown zurück.

Event-Vokabular (47 bekannte Typen)

Gruppiert nach Domäne.

Core-Session

Synthetic Frames auf Subscriber-Ebene

Permissions (F3 + base)

Models

MCP-Guardrails (PR 14b + F2)

Mutationskontrolle (Wave 4 PR 16+17)

memory_changed umfasst auch sitzungslose Managed-Memory-Tasks. Für diese Payloads ist scope "managed", source ist einer der Werte "workspace_memory_remember", "workspace_memory_forget" oder "workspace_memory_dream", taskId ist die ID des Tasks in der Warteschlange und touchedScopes listet die geänderten Managed-Memory-Scopes auf ("user" und/oder "project"). Es wird kein Event ausgelöst, wenn ein Remember/Forget/Dream-Task abgeschlossen wird, ohne den Managed Memory zu verändern.

Auth-Device-Flow (PR 21)

Diese Events sind auf den Workspace bezogen (workspace-keyed), nicht auf die Session. Der Session-Reducer behandelt sie als No-Ops; reduceDaemonAuthEvent projiziert sie in den State auf Workspace-Ebene.

MCP Runtime Mutation

Extensions-Lifecycle

Mid-Turn Message Injection

Turn-Lifecycle / Assistant Pushes

Architektur

DaemonSessionViewState

reduceDaemonSessionEvent füllt diesen View-State. CLI-TUI-Adapter, DaemonChannelBridge und die VS Code IDE konsumieren ihn. Wichtige Felder:

• alive: boolean - wird nach einem Terminal-Frame (session_died, session_closed, client_evicted, stream_error) auf false gesetzt.
• currentModelId?: string - aus model_switched.
• displayName?: string - aus session_metadata_updated.
• pendingPermissions: Record<string, DaemonPermissionRequestData> - offene Requests, gekeyed nach requestId; bereinigt durch permission_resolved / permission_already_resolved.
• lastSessionUpdate?: DaemonSessionUpdateData - neuestes session_update.
• lastModelSwitchFailure?: DaemonModelSwitchFailedData - aus model_switch_failed.
• terminalEvent? - rohes Terminal-Event.
• streamError?: DaemonStreamErrorData - neueste stream_error-Payload.
• unrecognizedKnownEventCount, lastUnrecognizedKnownEvent? - Event wurde von asKnownDaemonEvent erkannt, aber der Reducer hat noch keinen dedizierten State dafür.
• droppedPermissionRequestCount, lastDroppedPermissionRequestId? - fehlerhafter Permission-Request konnte nicht in die Pending-Map aufgenommen werden.
• unmatchedPermissionResolutionCount, lastUnmatchedPermissionResolutionId? - Permission-Resolution hatte keinen passenden Pending-Request.
• slowClientWarningCount, lastSlowClientWarning? - aus slow_client_warning.
• mcpBudgetWarningCount, lastMcpBudgetWarning? - aus mcp_budget_warning.
• mcpChildRefusedBatchCount, lastMcpChildRefusedBatch? - aus mcp_child_refused_batch.
• lastWorkspaceMutation?, lastWorkspaceMutationType? - aus memory_changed / agent_changed.
• approvalMode?, approvalModeChangedCount, lastApprovalModeChange? - aus approval_mode_changed.
• toolToggleCount, lastToolToggle? - aus tool_toggled.
• workspaceInitCount, lastWorkspaceInit? - aus workspace_initialized.
• mcpRestartCount, lastMcpRestart? - aus mcp_server_restarted.
• mcpRestartRefusedCount, lastMcpRestartRefused? - aus mcp_server_restart_refused.
• settings_changed / settings_reloaded - werden von asKnownDaemonEvent erkannt; der Session-Reducer pflegt keine dedizierten View-State-Felder dafür und UIs behandeln sie üblicherweise als Refresh-Signale.
• permissionVoteProgress: Record<string, DaemonPermissionPartialVoteData> - Fortschritt des Consensus-Votings.
• forbiddenVotes: DaemonPermissionForbiddenData[], forbiddenVoteCount - von der Policy abgelehnte Vote-Datensätze, begrenzt auf 32.
• awaitingResync: boolean - gesetzt durch state_resync_required; bereinigt, wenn der Consumer den View-State zurücksetzt.
• resyncRequiredCount, lastResyncRequired? - Resync-Observability.
• lastFollowupSuggestion?: DaemonFollowupSuggestionData - neuester Follow-up-Vorschlag, gepusht vom Daemon.
• lastTurnComplete?: DaemonTurnCompleteData - neuester erfolgreicher Turn-Abschluss.
• lastTurnError?: DaemonTurnErrorData - neuester Turn-Fehler.
• rewindCount, lastRewind?, lastBranch? - neueste Rewind-/Branch-Events.

DaemonAuthState

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

Flow

Producer-Seite

Consumer-Seite (SDK)

Metadaten auf Envelope-Ebene

Zusätzlich zum data-Payload jedes Events versieht der Daemon zwei Felder auf Envelope-Ebene mit einem Timestamp.

_meta.serverTimestamp - Daemon-Uhr

EventBus.publish() in packages/acp-bridge/src/eventBus.ts versieht _meta.serverTimestamp mit einem Timestamp, wenn das Event den Bus betritt. Der BridgeEvent-Typ enthält _meta?: Record<string, unknown>, sodass interne Daemon-Consumer _meta bei jedem über den Bus veröffentlichten Event sehen. formatSseFrame() in packages/cli/src/serve/routes/sse-events.ts stellt nur für synthetische Frames (z. B. stream_error), die EventBus.publish umgehen, einen Fallback-Timestamp bereit.

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

Der Merge behält alle vorhandenen _meta-Keys aus dem Input-Event bei ({...input._meta, serverTimestamp: Date.now()}). Producer können zusätzliche _meta-Keys auf Envelope-Ebene anhängen; EventBus.publish führt diese mit dem Timestamp zusammen, anstatt sie zu überschreiben.

Warum das wichtig ist: Multi-Client-UIs, die relative Zeiten rendern oder Transcript-Blöcke sortieren, sollten die Serverzeit anstelle der lokalen Uhr des jeweiligen Browsers/Tabs/Smartphones verwenden. Server-Timestamps halten die Reihenfolge clientübergreifend konsistent.

SDK-Zugriff: bevorzuge event._meta?.serverTimestamp. Kompatibilitätspfade können auch event.serverTimestamp oder event.data._meta.serverTimestamp abfragen. Vermische nicht das ACP-Payload data._meta mit dem Daemon-Envelope _meta.

originatorClientId

Events, die durch einen Request mit einer registrierten X-Qwen-Client-Id ausgelöst werden, können dieses Feld mit einem Timestamp versehen. Siehe 08-session-lifecycle.md.

Tool-Call _meta (Provenance / serverId)

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

Der vorhandene _meta.toolName-Anzeigename bleibt erhalten. Die UI verwendet diese Felder, um Builtin-/MCP-Server-/Subagent-Badges zu rendern, ohne den Tool-Namen erneut parsen zu müssen.

SDK-Reducer-Verhalten

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

• awaitingResync: boolean - wird durch state_resync_required gesetzt; der Caller setzt es zurück, typischerweise nachdem POST /session/:id/load den View-State zurückgesetzt hat.
• resyncRequiredCount: number - Observability-Counter.
• lastResyncRequired?: DaemonStateResyncRequiredData - neuestes Payload.

Während awaitingResync = true ist, überspringt der Reducer die Delta-Anwendung und lässt nur das abgeschlossene RESYNC_PASSTHROUGH_TYPES-Set zu:

lastEventId schreitet auch während des Resyncs monoton durch advanceLastEventId(base) fort. Nachdem der Caller zurückgesetzt und awaitingResync gelöscht hat, richten sich nachfolgende Deltas am korrekten Cursor aus.

reduceDaemonAuthEvent projiziert Device-Flow-Events konzeptionell in Workspace-level Auth-State-Einträge in der Form {deviceFlowId, status, providerId, expiresAt?, lastThrottleIntervalMs?, lastError?}. Im Code speichert der Reducer status, errorKind, hint, intervalMs, lastSeenEventId, authorizedExpiresAt und accountAlias auf DaemonDeviceFlowReducerState; die Daemon-Event-Payloads selbst behalten die oben aufgeführten Formen pro Event bei.

State und Forward-Compatibility

• Füge einen bekannten Event-Typ hinzu, indem du an DAEMON_KNOWN_EVENT_TYPE_VALUES anhängst. Alte SDKs geben für nicht erkannte Event-Typen über den Fallback-Pfad undefined zurück und inkrementieren unrecognizedKnownEventCount; neue SDKs verlassen sich auf die Discriminated Union.
• Das Hinzufügen optionaler Felder zu einem bestehenden Payload ist sicher, da Payloads offen sind ({ [key: string]: unknown }).
• Das Ändern der Form eines bestehenden Payloads ist ein Breaking Change und muss EVENT_SCHEMA_VERSION erhöhen sowie einen kompatiblen Capability-Tag wie caps.features.typed_event_schema_v2 bekannt geben.
• id ist pro Session 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 auf dem Envelope und nicht in data. F3-Partial-Vote-/Forbidden-Payloads führen es auch über mergeOriginator in data zusammen, damit View-State-Consumer den Envelope nicht vorhalten müssen.

Abhängigkeiten

• 10-event-bus.md - Delivery-Channel.
• 11-capabilities-versioning.md - wie SDKs typed_event_schema, mcp_guardrail_events und permission_mediation im Preflight prüfen.
• 04-permission-mediation.md - wie Permission-Events 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 Env-Var oder Flag steuert direkt das Schema selbst. QWEN_SERVE_NO_MCP_POOL=1 ändert den MCP-Event-scope von 'workspace' zu absent oder 'session'.

Einschränkungen und bekannte Limits

• Sechs synthetische Frame-Typen haben absichtlich keine id; SDK-Code darf nicht davon ausgehen, dass jedes Event 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_*-Events sind nicht session-keyed. Verwende bei der Konsumierung über DaemonSessionClient dafür reduceDaemonAuthEvent anstatt des Session-Reducers.

Referenzen

• 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