Typed Daemon Event Schema v1

Overview

Every SSE frame emitted by the daemon on GET /session/:id/events has the shape { id, v, type, data, originatorClientId?, _meta? }. v: 1 is the current EVENT_SCHEMA_VERSION. type comes from the closed, version-pinned DAEMON_KNOWN_EVENT_TYPE_VALUES set in packages/sdk-typescript/src/daemon/events.ts. The envelope _meta field is stamped at the SSE write boundary by formatSseFrame() in packages/cli/src/serve/routes/sse-events.ts; see Envelope-level metadata.

The SDK exposes asKnownDaemonEvent(evt). It returns a discriminated KnownDaemonEvent for known event types and undefined for other types. SDK consumers can therefore handle forward compatibility without requiring a lockstep SDK upgrade when a newer daemon adds an event type; the session reducer records those as unrecognizedKnownEventCount.

The wire format lives in ../qwen-serve-protocol.md. This page is the payload contract for each event.

Responsibilities

• Provide the single source of truth for the event vocabulary (DAEMON_KNOWN_EVENT_TYPE_VALUES).
• Provide a typed envelope for each event type (DaemonEventEnvelope<TType, TData>).
• Provide pure reducers (reduceDaemonSessionEvent, reduceDaemonAuthEvent) that project an event stream into SDK view state.
• Broadcast the typed_event_schema capability tag as an informational signal. If the tag is absent, asKnownDaemonEvent still falls back to unknown.

Event vocabulary

Grouped by domain.

Core session

Subscriber-level synthetic frames

fullTranscriptAvailable is a boolean capability flag, not a literal true type. Current daemons emit true when /session/:id/transcript can be used to page the persisted transcript; older or constrained daemons may emit false, and clients should keep rendering the bounded replay normally.

Resync reasons and ordering

For the current v1 daemon, state_resync_required.data.reason is one of the four values below. Let N be the requested Last-Event-ID and nextId the next id the session’s event bus will assign.

epoch_reset prevents a cursor from a previous daemon instance from being mistaken for a caught-up cursor when the new ring is empty. Comparing epoch tokens also detects stale cursors after the new sequence has caught up numerically. Clients should retain the response’s X-Qwen-Event-Epoch with their cursor and send both on reconnect.

An initial resync signal can be followed by replay_budget_exceeded on the same subscription. None of these frames consumes an event id or closes the stream. replay_complete ends the replay phase; it does not clear awaitingResync. Clients must rebuild from loadSession before applying further deltas; see SDK reducer behavior. The SDK accepts other non-empty reason strings for forward compatibility and applies the same recovery behavior.

History truncation anchor

The history_truncated marker in compactedReplay may also carry recordId?: string, a fallback beforeRecordId pagination anchor. When an anchor is available at the first replay-window eviction, it is frozen there: prefer the first retained record id, falling back to the last dropped record id if the retained window has none. Later events must not advance an existing anchor into the displayed history, which would duplicate records when older pages are prepended. The marker omits recordId when no anchor is available. This status marker does not set awaitingResync.

Permissions (F3 + base)

Models

MCP guardrails (PR 14b + F2)

Mutation control (Wave 4 PR 16+17)

Skill toggle APIs attach optional mutation: { id, kind: 'skill_toggle', skills: [{ name, enabled }], activation, sessionsRefreshed, sessionsFailed }. Every skills.disabled / skills.enabled event from the same request shares one mutation id. Other settings writes omit mutation. Workspace-service writes include scope; some other emitters (for example session model switches) omit it. The SDK normalizer defaults missing scope to 'workspace'.

memory_changed also covers sessionless managed-memory tasks. For those payloads, scope is "managed", source is one of "workspace_memory_remember", "workspace_memory_forget", or "workspace_memory_dream", taskId is the queued task id, and touchedScopes lists the managed memory scopes that changed ("user" and/or "project"). No event is emitted when a remember/forget/dream task completes without touching managed memory.

Auth device flow (PR 21)

These events are workspace-keyed, not session-keyed. The session reducer treats them as no-ops; reduceDaemonAuthEvent projects them into workspace-level state.

MCP runtime mutation

Extensions lifecycle

Mid-turn message injection

Turn lifecycle / assistant pushes

Architecture

DaemonSessionViewState

reduceDaemonSessionEvent fills this view state. CLI TUI adapter, DaemonChannelBridge, and VS Code IDE consume it. Key fields:

• alive: boolean - becomes false after a terminal frame (session_died, session_closed, client_evicted, stream_error).
• currentModelId?: string - from model_switched.
• displayName?: string - from session_metadata_updated.
• recordingDegraded: boolean - sticky session recording state from session_recording_degraded; an explicit session_snapshot.recordingDegraded value is authoritative.
• pendingPermissions: Record<string, DaemonPermissionRequestData> - open requests keyed by requestId; cleared by permission_resolved / permission_already_resolved.
• lastSessionUpdate?: DaemonSessionUpdateData - latest session_update.
• lastModelSwitchFailure?: DaemonModelSwitchFailedData - from model_switch_failed.
• terminalEvent? - raw terminal event.
• streamError?: DaemonStreamErrorData - latest stream_error payload.
• unrecognizedKnownEventCount, lastUnrecognizedKnownEvent? - event was recognized by asKnownDaemonEvent but the reducer has no dedicated state for it yet.
• droppedPermissionRequestCount, lastDroppedPermissionRequestId? - malformed permission request could not enter the pending map.
• unmatchedPermissionResolutionCount, lastUnmatchedPermissionResolutionId? - permission resolution had no matching pending request.
• slowClientWarningCount, lastSlowClientWarning? - from slow_client_warning.
• mcpBudgetWarningCount, lastMcpBudgetWarning? - from mcp_budget_warning.
• mcpChildRefusedBatchCount, lastMcpChildRefusedBatch? - from mcp_child_refused_batch.
• lastWorkspaceMutation?, lastWorkspaceMutationType? - from memory_changed / agent_changed.
• approvalMode?, approvalModeChangedCount, lastApprovalModeChange? - from approval_mode_changed.
• toolToggleCount, lastToolToggle? - from tool_toggled.
• workspaceInitCount, lastWorkspaceInit? - from workspace_initialized.
• mcpRestartCount, lastMcpRestart? - from mcp_server_restarted.
• mcpRestartRefusedCount, lastMcpRestartRefused? - from mcp_server_restart_refused.
• settings_changed / settings_reloaded - recognized by asKnownDaemonEvent; the session reducer does not maintain dedicated view-state fields. Skill-toggle settings_changed events carry optional mutation metadata so hosts can apply Skill-only changes incrementally instead of reloading the task. Other UIs may still treat the event as a refresh signal.
• permissionVoteProgress: Record<string, DaemonPermissionPartialVoteData> - consensus voting progress.
• forbiddenVotes: DaemonPermissionForbiddenData[], forbiddenVoteCount - policy-rejected vote records, capped at 32.
• awaitingResync: boolean - set by state_resync_required; cleared when consumer resets view state.
• resyncRequiredCount, lastResyncRequired? - resync observability.
• lastFollowupSuggestion?: DaemonFollowupSuggestionData - latest follow-up suggestion pushed by daemon.
• lastTurnComplete?: DaemonTurnCompleteData - latest successful turn completion.
• lastTurnError?: DaemonTurnErrorData - latest turn error.
• rewindCount, lastRewind?, lastBranch? - latest rewind / branch events.

DaemonAuthState

One entry per providerId, driven by auth_device_flow_*. Each flow exposes { deviceFlowId, status, providerId, expiresAt?, lastThrottleIntervalMs?, lastError? }.

Flow

Producer side

Consumer side (SDK)

Envelope-level metadata

Beyond each event’s data payload, the daemon stamps two envelope-level fields.

_meta.serverTimestamp - daemon clock

EventBus.publish() in packages/acp-bridge/src/eventBus.ts stamps _meta.serverTimestamp when the event enters the bus. The BridgeEvent type includes _meta?: Record<string, unknown>, so internal daemon consumers do see _meta on every bus-published event. formatSseFrame() in packages/cli/src/serve/routes/sse-events.ts provides a fallback timestamp only for synthetic frames (e.g. stream_error) that bypass EventBus.publish.

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

The merge preserves any existing _meta keys from the input event ({...input._meta, serverTimestamp: Date.now()}). Producers may attach additional envelope-level _meta keys; EventBus.publish merges them with the timestamp rather than overwriting.

Why it matters: multi-client UIs that render relative time or sort transcript blocks should use server time instead of each browser/tab/phone local clock. Server stamping keeps ordering consistent across clients.

SDK access: prefer event._meta?.serverTimestamp. Compatibility paths may also probe event.serverTimestamp or event.data._meta.serverTimestamp. Do not mix ACP payload data._meta with daemon envelope _meta.

originatorClientId

Events triggered by a request that carried a registered X-Qwen-Client-Id may stamp this field. See 08-session-lifecycle.md.

Tool-call _meta (provenance / serverId)

This is separate from envelope _meta: ACP session/update payloads can carry their own _meta in event.data._meta. ToolCallEmitter (packages/cli/src/acp-integration/session/emitters/tool-call-emitter.ts) stamps two fields on emitStart, emitResult, and emitError:

The existing _meta.toolName display name is preserved. UI uses these fields to render builtin / MCP server / subagent badges without reparsing the tool name.

SDK reducer behavior

reduceDaemonSessionEvent(state, evt) in packages/sdk-typescript/src/daemon/events.ts projects the stream into DaemonSessionViewState. The resync-related fields are:

• awaitingResync: boolean - set by state_resync_required; caller clears it, typically after POST /session/:id/load resets view state.
• resyncRequiredCount: number - observability counter.
• lastResyncRequired?: DaemonStateResyncRequiredData - latest payload.

While awaitingResync = true, the reducer skips delta application and only allows the closed RESYNC_PASSTHROUGH_TYPES set:

lastEventId still advances monotonically through advanceLastEventId(base) during resync. After the caller resets and clears awaitingResync, subsequent deltas align to the correct cursor.

reduceDaemonAuthEvent projects device-flow events into workspace-level auth state entries shaped like {deviceFlowId, status, providerId, expiresAt?, lastThrottleIntervalMs?, lastError?} conceptually. In code the reducer stores status, errorKind, hint, intervalMs, lastSeenEventId, authorizedExpiresAt, and accountAlias on DaemonDeviceFlowReducerState; the daemon event payloads themselves remain the per-event shapes listed above.

State and forward compatibility

• Add a known event type by appending to DAEMON_KNOWN_EVENT_TYPE_VALUES. Old SDKs return undefined for unrecognized event types through the fallback path and increment unrecognizedKnownEventCount; new SDKs rely on the discriminated union.
• Adding optional fields to an existing payload is safe because payloads are open ({ [key: string]: unknown }).
• Changing an existing payload shape is breaking and must bump EVENT_SCHEMA_VERSION plus advertise a compatible capability tag such as caps.features.typed_event_schema_v2.
• id is per-session monotonic. Subscriber-level synthetic frames (client_evicted, slow_client_warning, stream_error, state_resync_required, replay_complete, session_snapshot) intentionally have no id so other subscribers do not see gaps.
• A rejected publish must not consume an id: an unserializable event is neither retained nor delivered, and the next accepted event uses the same next id. Otherwise a rejection would look like a replay gap to subscribers.
• originatorClientId lives on the envelope rather than data. F3 partial-vote / forbidden payloads also merge it into data through mergeOriginator so view-state consumers do not need to retain the envelope.

Dependencies

• 10-event-bus.md - delivery channel.
• 11-capabilities-versioning.md - how SDKs preflight typed_event_schema, mcp_guardrail_events, and permission_mediation.
• 04-permission-mediation.md - how permission events are produced.
• 13-sdk-daemon-client.md - asKnownDaemonEvent, reducers, and view-state shape.

Configuration

• Always advertised: typed_event_schema, mcp_guardrail_events, and permission_mediation (with supported policy modes).
• No env var or flag directly controls the schema itself. QWEN_SERVE_NO_MCP_POOL=1 changes MCP event scope from 'workspace' to absent or 'session'.

Caveats and known limits

• Six synthetic frame types intentionally have no id; SDK code must not assume every event has an id.
• permission_partial_vote only appears under consensus. permission_forbidden appears under designated, consensus, and local-only, but not under first-responder.
• mcp_child_refused_batch only appears in mode: 'enforce'; warn mode never refuses.
• auth_device_flow_* events are not session-keyed. When consuming through DaemonSessionClient, use reduceDaemonAuthEvent for them rather than the session reducer.

References

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