타입화된 Daemon 이벤트 스키마 v1

개요

GET /session/:id/events에서 daemon이 내보내는 모든 SSE 프레임은 { id, v, type, data, originatorClientId?, _meta? } 형태를 갖는다. v: 1은 현재 EVENT_SCHEMA_VERSION이다. type은 packages/sdk-typescript/src/daemon/events.ts의 닫힌 집합인 DAEMON_KNOWN_EVENT_TYPE_VALUES에서 온다. 엔벨로프의 _meta 필드는 packages/cli/src/serve/routes/sse-events.ts의 formatSseFrame()에 의해 SSE 기록 시점에 찍힌다. 엔벨로프 수준 메타데이터를 참조.

SDK는 asKnownDaemonEvent(evt)를 노출한다. 알려진 이벤트 타입에 대해 판별된 KnownDaemonEvent를 반환하고, 그 외 타입에는 undefined를 반환한다. 따라서 SDK 사용자는 최신 daemon이 새 이벤트 타입을 추가할 때 SDK와 동시에 업그레이드할 필요 없이 forward compatibility를 처리할 수 있다. 세션 reducer는 이를 unrecognizedKnownEventCount로 기록한다.

wire 형식은 ../qwen-serve-protocol.md에 있다. 이 페이지는 각 이벤트의 페이로드 계약이다.

책임

• 이벤트 어휘(DAEMON_KNOWN_EVENT_TYPE_VALUES)의 단일 정보 소스를 제공한다.
• 각 이벤트 타입에 대해 타입화된 엔벨로프(DaemonEventEnvelope<TType, TData>)를 제공한다.
• 이벤트 스트림을 SDK 뷰 상태로 투영하는 순수 reducer(reduceDaemonSessionEvent, reduceDaemonAuthEvent)를 제공한다.
• typed_event_schema capability 태그를 정보 신호로 브로드캐스트한다. 태그가 없어도 asKnownDaemonEvent는 unknown으로 폴백한다.

이벤트 어휘

도메인별로 그룹화한다.

Core session

구독자 수준 합성 프레임

fullTranscriptAvailable은 불리언 capability 플래그이며 리터럴 true 타입이 아니다. 현재 daemon은 /session/:id/transcript로 영구화된 트랜스크립트를 페이지할 수 있을 때 true를 내보낸다. 오래되었거나 제한된 daemon은 false를 내보낼 수 있으며, 클라이언트는 제한된 replay를 정상적으로 계속 렌더링해야 한다.

Permissions (F3 + base)

Models

MCP guardrails (PR 14b + F2)

Mutation control (Wave 4 PR 16+17)

Skill 토글 API는 선택적 mutation: { id, kind: 'skill_toggle', skills: [{ name, enabled }], activation, sessionsRefreshed, sessionsFailed }을 첨부합니다. 동일한 요청의 모든 skills.disabled / skills.enabled 이벤트는 하나의 mutation id를 공유합니다. 다른 설정 쓰기는 mutation을 생략합니다. 워크스페이스 서비스 쓰기는 scope를 포함하며, 다른 일부 이미터(예: 세션 모델 전환)는 생략합니다. SDK normalizer는 누락된 scope의 기본값을 'workspace'로 설정합니다.

memory_changed는 세션 없는 관리 메모리 작업도 포함한다. 해당 페이로드에서 scope는 "managed"이고, source는 "workspace_memory_remember", "workspace_memory_forget", "workspace_memory_dream" 중 하나이며, taskId는 큐에 대기된 작업 id이고, touchedScopes는 변경된 관리 메모리 scope("user" 및/또는 "project")를 나열한다. remember/forget/dream 작업이 관리 메모리를 변경하지 않고 완료되면 이벤트가 발행되지 않는다.

Auth device flow (PR 21)

이 이벤트는 세션이 아닌 워크스페이스 기준이다. 세션 reducer는 이를 no-op로 처리하며, reduceDaemonAuthEvent가 이를 워크스페이스 수준 상태로 투영한다.

MCP 런타임 변경

Extensions 라이프사이클

Mid-turn 메시지 주입

Turn 라이프사이클 / 어시스턴트 푸시

아키텍처

DaemonSessionViewState

reduceDaemonSessionEvent이 채우는 뷰 상태. CLI TUI 어댑터, DaemonChannelBridge, VS Code IDE가 소비한다. 주요 필드:

• alive: boolean - terminal 프레임(session_died, session_closed, client_evicted, stream_error) 이후 false가 됨.
• currentModelId?: string - model_switched에서.
• displayName?: string - session_metadata_updated에서.
• recordingDegraded: boolean - session_recording_degraded의 sticky 세션 녹화 상태. 명시적 session_snapshot.recordingDegraded 값이 우선.
• pendingPermissions: Record<string, DaemonPermissionRequestData> - requestId 기준 열린 요청. permission_resolved / permission_already_resolved에 의해 정리됨.
• lastSessionUpdate?: DaemonSessionUpdateData - 최신 session_update.
• lastModelSwitchFailure?: DaemonModelSwitchFailedData - model_switch_failed에서.
• terminalEvent? - 원시 terminal 이벤트.
• streamError?: DaemonStreamErrorData - 최신 stream_error 페이로드.
• unrecognizedKnownEventCount, lastUnrecognizedKnownEvent? - 이벤트가 asKnownDaemonEvent에 의해 인식되었지만 reducer에 전용 상태가 아직 없음.
• droppedPermissionRequestCount, lastDroppedPermissionRequestId? - 잘못된 권한 요청이 pending map에 진입하지 못함.
• unmatchedPermissionResolutionCount, lastUnmatchedPermissionResolutionId? - 권한 resolution에 매칭되는 pending 요청이 없음.
• slowClientWarningCount, lastSlowClientWarning? - slow_client_warning에서.
• mcpBudgetWarningCount, lastMcpBudgetWarning? - mcp_budget_warning에서.
• mcpChildRefusedBatchCount, lastMcpChildRefusedBatch? - mcp_child_refused_batch에서.
• lastWorkspaceMutation?, lastWorkspaceMutationType? - memory_changed / agent_changed에서.
• approvalMode?, approvalModeChangedCount, lastApprovalModeChange? - approval_mode_changed에서.
• toolToggleCount, lastToolToggle? - tool_toggled에서.
• workspaceInitCount, lastWorkspaceInit? - workspace_initialized에서.
• mcpRestartCount, lastMcpRestart? - mcp_server_restarted에서.
• mcpRestartRefusedCount, lastMcpRestartRefused? - mcp_server_restart_refused에서.
• settings_changed / settings_reloaded - asKnownDaemonEvent에 의해 인식됨. 세션 reducer는 전용 뷰 상태 필드를 유지하지 않음. Skill 토글 settings_changed 이벤트는 선택적 mutation 메타데이터를 포함하므로 호스트가 작업을 다시 로드하지 않고 Skill 전용 변경을 증분적으로 적용할 수 있음. 다른 UI는 여전히 이벤트를 새로고침 신호로 처리할 수 있음.
• permissionVoteProgress: Record<string, DaemonPermissionPartialVoteData> - 합의 투표 진행 상태.
• forbiddenVotes: DaemonPermissionForbiddenData[], forbiddenVoteCount - 정책에 의해 거부된 투표 기록. 최대 32개.
• awaitingResync: boolean - state_resync_required에 의해 설정됨. 소비자가 뷰 상태를 초기화하면 해제됨.
• resyncRequiredCount, lastResyncRequired? - resync 관측성.
• lastFollowupSuggestion?: DaemonFollowupSuggestionData - daemon이 푸시한 최신 후속 제안.
• lastTurnComplete?: DaemonTurnCompleteData - 최신 성공적 turn 완료.
• lastTurnError?: DaemonTurnErrorData - 최신 turn 오류.
• rewindCount, lastRewind?, lastBranch? - 최신 rewind / branch 이벤트.

DaemonAuthState

providerId당 하나의 엔트리. auth_device_flow_*에 의해 구동됨. 각 flow는 { deviceFlowId, status, providerId, expiresAt?, lastThrottleIntervalMs?, lastError? }를 노출한다.

흐름

Producer 측

Consumer 측 (SDK)

엔벨로프 수준 메타데이터

각 이벤트의 data 페이로드 외에도, daemon은 두 개의 엔벨로프 수준 필드를 찍는다.

_meta.serverTimestamp - daemon 클록

packages/acp-bridge/src/eventBus.ts의 EventBus.publish()는 이벤트가 bus에 진입할 때 _meta.serverTimestamp를 찍는다. BridgeEvent 타입은 _meta?: Record<string, unknown>을 포함하므로, daemon 내부 소비자는 bus에 발행된 모든 이벤트에서 _meta를 볼 수 있다. packages/cli/src/serve/routes/sse-events.ts의 formatSseFrame()은 EventBus.publish를 우회하는 합성 프레임(예: stream_error)에 대해서만 폴백 타임스탬프를 제공한다.

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

병합은 입력 이벤트의 기존 _meta 키를 유지한다({...input._meta, serverTimestamp: Date.now()}). producer는 추가 엔벨로프 수준 _meta 키를 첨부할 수 있으며, EventBus.publish는 타임스탬프와 병합할 뿐 덮어쓰지 않는다.

중요한 이유: 상대적 시간을 렌더링하거나 트랜스크립트 블록을 정렬하는 다중 클라이언트 UI는 각 브라우저/탭/폰의 로컬 클록 대신 서버 시간을 사용해야 한다. 서버 스탬핑은 클라이언트 간 순서를 일관되게 유지한다.

SDK 접근: event._meta?.serverTimestamp를 선호한다. 호환 경로에서 event.serverTimestamp 또는 event.data._meta.serverTimestamp를_probe_할 수도 있다. ACP 페이로드 data._meta와 daemon 엔벨로프 _meta를 혼동하지 말 것.

originatorClientId

등록된 X-Qwen-Client-Id를 포함한 요청에 의해 트리거된 이벤트는 이 필드를 찍을 수 있다. 08-session-lifecycle.md를 참조.

도구 호출 _meta (출처 / serverId)

이것은 엔벨로프 _meta와 별개이다. ACP session/update 페이로드는 event.data._meta에 자체 _meta를 가질 수 있다. ToolCallEmitter(packages/cli/src/acp-integration/session/emitters/tool-call-emitter.ts)는 emitStart, emitResult, emitError에서 두 필드를 찍는다:

기존 _meta.toolName 표시 이름은 유지된다. UI는 이 필드를 사용하여 도구 이름을 다시 파싱하지 않고도 builtin / MCP 서버 / 서브에이전트 배지를 렌더링한다.

SDK reducer 동작

packages/sdk-typescript/src/daemon/events.ts의 reduceDaemonSessionEvent(state, evt)는 스트림을 DaemonSessionViewState로 투영한다. resync 관련 필드는 다음과 같다:

• awaitingResync: boolean - state_resync_required에 의해 설정됨. 호출자가 해제하며, 일반적으로 POST /session/:id/load가 뷰 상태를 초기화한 이후.
• resyncRequiredCount: number - 관측성 카운터.
• lastResyncRequired?: DaemonStateResyncRequiredData - 최신 페이로드.

awaitingResync = true인 동안, reducer는 delta 적용을 건너뛰고 닫힌 RESYNC_PASSTHROUGH_TYPES 집합만 허용한다:

lastEventId는 resync 중에도 advanceLastEventId(base)를 통해 단조롭게 증가한다. 호출자가 초기화하고 awaitingResync를 해제한 후, 후속 delta는 올바른 커서에 정렬된다.

reduceDaemonAuthEvent는 device flow 이벤트를 워크스페이스 수준 auth 상태 엔트리로 투영한다. 개념적으로 {deviceFlowId, status, providerId, expiresAt?, lastThrottleIntervalMs?, lastError?} 형태이다. 코드에서 reducer는 DaemonDeviceFlowReducerState에 status, errorKind, hint, intervalMs, lastSeenEventId, authorizedExpiresAt, accountAlias를 저장한다. daemon 이벤트 페이로드 자체는 위에 나열된 이벤트별 형태를 유지한다.

상태와 forward compatibility

• 알려진 이벤트 타입을 추가하려면 DAEMON_KNOWN_EVENT_TYPE_VALUES에 추가하면 된다. 오래된 SDK는 폴백 경로를 통해 인식되지 않는 이벤트 타입에 대해 undefined를 반환하고 unrecognizedKnownEventCount를 증가시킨다. 새로운 SDK는 판별된 유니언에 의존한다.
• 기존 페이로드에 선택적 필드를 추가하는 것은 안전하다. 페이로드는 개방적({ [key: string]: unknown })이기 때문이다.
• 기존 페이로드 형태를 변경하는 것은 breaking change이며 EVENT_SCHEMA_VERSION을 올리고 caps.features.typed_event_schema_v2와 같은 호환 capability 태그를 광고해야 한다.
• id는 세션별 단조 증가값이다. 구독자 수준 합성 프레임(client_evicted, slow_client_warning, stream_error, state_resync_required, replay_complete, session_snapshot)은 의도적으로 id가 없어서 다른 구독자가 갭을 보지 않는다.
• originatorClientId는 data가 아닌 엔벨로프에 위치한다. F3 partial-vote / forbidden 페이로드는 mergeOriginator를 통해 data에도 병합하므로 뷰 상태 소비자가 엔벨로프를 유지할 필요가 없다.

의존성

• 10-event-bus.md - 전달 채널.
• 11-capabilities-versioning.md - SDK가 typed_event_schema, mcp_guardrail_events, permission_mediation을 preflight하는 방법.
• 04-permission-mediation.md - 권한 이벤트가 생성되는 방법.
• 13-sdk-daemon-client.md - asKnownDaemonEvent, reducer, 뷰 상태 형태.

설정

• 항상 광고됨: typed_event_schema, mcp_guardrail_events, permission_mediation(지원되는 정책 모드와 함께).
• 스키마 자체를 직접 제어하는 환경 변수나 플래그는 없다. QWEN_SERVE_NO_MCP_POOL=1은 MCP 이벤트 scope를 'workspace'에서 없거나 'session'으로 변경한다.

주의사항 및 알려진 제한

• 6개의 합성 프레임 타입은 의도적으로 id가 없다. SDK 코드는 모든 이벤트에 id가 있다고 가정하면 안 된다.
• permission_partial_vote는 consensus에서만 나타난다. permission_forbidden은 designated, consensus, local-only에서 나타나지만 first-responder에서는 나타나지 않는다.
• mcp_child_refused_batch는 mode: 'enforce'에서만 나타난다. warn 모드는 절대 거부하지 않는다.
• auth_device_flow_* 이벤트는 세션 기준이 아니다. DaemonSessionClient를 통해 소비할 때는 세션 reducer 대신 reduceDaemonAuthEvent를 사용해야 한다.

참고 자료

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