型付きデーモンイベントスキーマ v1

概要

デーモンが GET /session/:id/events で送出するすべての 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 セットに閉じたバージョン固定の値で、現在 43 種類のイベントタイプが定義されています。エンベロープの _meta フィールドは server.ts の formatSseFrame() が SSE 書き込み境界でスタンプします。詳細はエンベロープレベルのメタデータを参照してください。

SDK は asKnownDaemonEvent(evt) を公開しています。既知のイベントタイプに対しては判別済みの KnownDaemonEvent を返し、それ以外のタイプには undefined を返します。これにより SDK コンシューマーは、新しいデーモンがイベントタイプを追加した際にもロックステップな SDK アップグレードを必要とせず前方互換性を維持できます。セッションリデューサーはそれらを unrecognizedKnownEventCount として記録します。

ワイヤーフォーマットは ../qwen-serve-protocol.md に記載されています。このページは各イベントのペイロードコントラクトです。

責務

• イベントボキャブラリー（DAEMON_KNOWN_EVENT_TYPE_VALUES）の唯一の信頼できる情報源を提供する。
• 各イベントタイプの型付きエンベロープ（DaemonEventEnvelope<TType, TData>）を提供する。
• イベントストリームを SDK ビュー状態に投影する純粋なリデューサー（reduceDaemonSessionEvent、reduceDaemonAuthEvent）を提供する。
• 情報シグナルとして typed_event_schema ケーパビリティタグをブロードキャストする。タグが存在しない場合、asKnownDaemonEvent は引き続き unknown にフォールバックします。

イベントボキャブラリー（43 種類の既知タイプ）

ドメインごとにグループ化しています。

コアセッション

サブスクライバーレベルの合成フレーム

パーミッション（F3 + ベース）

モデル

MCP ガードレール（PR 14b + F2）

ミューテーション制御（Wave 4 PR 16+17）

認証デバイスフロー（PR 21）

これらのイベントはセッションキーではなくワークスペースキーです。セッションリデューサーはこれらをノーオペレーションとして扱います。reduceDaemonAuthEvent がワークスペースレベルの状態に投影します。

MCP ランタイムミューテーション

ターンライフサイクル / アシスタントプッシュ

アーキテクチャ

DaemonSessionViewState

reduceDaemonSessionEvent がこのビュー状態を埋めます。CLI TUI アダプター、DaemonChannelBridge、VS Code IDE が使用します。主要フィールド：

• alive: boolean - 終端フレーム（session_died、session_closed、client_evicted、stream_error）の後に false になります。
• currentModelId?: string - model_switched から。
• displayName?: string - session_metadata_updated から。
• pendingPermissions: Record<string, DaemonPermissionRequestData> - requestId でキーされたオープンリクエスト。permission_resolved / permission_already_resolved でクリアされます。
• lastSessionUpdate?: DaemonSessionUpdateData - 最新の session_update。
• lastModelSwitchFailure?: DaemonModelSwitchFailedData - model_switch_failed から。
• terminalEvent? - 生の終端イベント。
• streamError?: DaemonStreamErrorData - 最新の stream_error ペイロード。
• unrecognizedKnownEventCount、lastUnrecognizedKnownEvent? - asKnownDaemonEvent で認識されたがリデューサーにまだ専用状態がないイベント。
• droppedPermissionRequestCount、lastDroppedPermissionRequestId? - 不正なパーミッションリクエストがペンディングマップに入れなかった。
• unmatchedPermissionResolutionCount、lastUnmatchedPermissionResolutionId? - パーミッション解決に対応するペンディングリクエストがなかった。
• 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 で認識されます。セッションリデューサーは専用のビュー状態フィールドを持たず、UI は通常リフレッシュシグナルとして扱います。
• permissionVoteProgress: Record<string, DaemonPermissionPartialVoteData> - コンセンサス投票の進捗。
• forbiddenVotes: DaemonPermissionForbiddenData[]、forbiddenVoteCount - ポリシーに拒否された投票レコード。最大 32 件。
• awaitingResync: boolean - state_resync_required で設定。コンシューマーがビュー状態をリセットするとクリアされます。
• resyncRequiredCount、lastResyncRequired? - リシンク可観測性。
• lastFollowupSuggestion?: DaemonFollowupSuggestionData - デーモンがプッシュした最新のフォローアップ提案。
• lastTurnComplete?: DaemonTurnCompleteData - 最新の正常なターン完了。
• lastTurnError?: DaemonTurnErrorData - 最新のターンエラー。
• rewindCount、lastRewind?、lastBranch? - 最新のリワインド / ブランチイベント。

DaemonAuthState

auth_device_flow_* によって駆動される providerId ごとのエントリー。各フローは { deviceFlowId, status, providerId, expiresAt?, lastThrottleIntervalMs?, lastError? } を公開します。

フロー

プロデューサー側

コンシューマー側（SDK）

エンベロープレベルのメタデータ

各イベントの data ペイロードに加え、デーモンは 2 つのエンベロープレベルフィールドをスタンプします。

_meta.serverTimestamp - デーモンクロック

packages/cli/src/serve/server.ts の formatSseFrame() が SSE 書き込み境界でスタンプします。EventBus.publish の内部ではありません。インメモリの BridgeEvent 型は変更されず、内部デーモンコンシューマーは _meta を参照しませんが、ワイヤー SSE フレームには含まれます。

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

マージは既存の _meta キーを保持します （{...existingMeta, serverTimestamp: Date.now()}）。現在のデーモンプロデューサーは エンベロープレベルの _meta を書き込みません。トップレベルのマージは前方互換性の エスケープハッチです。

重要な理由：相対時間をレンダリングしたりトランスクリプトブロックをソートするマルチクライアント UI は、各ブラウザ/タブ/デバイスのローカルクロックではなくサーバー時間を使用すべきです。サーバースタンプによりクライアント間で順序が一貫します。

SDK アクセス：event._meta?.serverTimestamp を推奨します。互換パスは event.serverTimestamp や event.data._meta.serverTimestamp も参照する場合があります。ACP ペイロードの data._meta とデーモンエンベロープの _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/ToolCallEmitter.ts）は emitStart、emitResult、emitError 時に 2 つのフィールドをスタンプします。

既存の _meta.toolName 表示名は保持されます。UI はツール名を再パースせずにこれらのフィールドを使用して builtin / MCP サーバー / subagent のバッジをレンダリングします。

SDK リデューサーの動作

packages/sdk-typescript/src/daemon/events.ts の reduceDaemonSessionEvent(state, evt) がストリームを DaemonSessionViewState に投影します。リシンク関連フィールドは次の通りです：

• awaitingResync: boolean - state_resync_required で設定。呼び出し元がクリアします。通常は POST /session/:id/load でビュー状態をリセットした後。
• resyncRequiredCount: number - 可観測性カウンター。
• lastResyncRequired?: DaemonStateResyncRequiredData - 最新のペイロード。

awaitingResync = true の間、リデューサーはデルタ適用をスキップし、閉じた RESYNC_PASSTHROUGH_TYPES セットのみを許可します：

lastEventId はリシンク中も advanceLastEventId(base) を通じて単調に進みます。呼び出し元がリセットして awaitingResync をクリアした後、後続のデルタは正しいカーソルに整合します。

reduceDaemonAuthEvent はデバイスフローイベントをワークスペースレベルの認証 状態エントリーに投影します。概念的には {deviceFlowId, status, providerId, expiresAt?, lastThrottleIntervalMs?, lastError?} の形です。コードでは、リデューサーは DaemonDeviceFlowReducerState に status、errorKind、hint、 intervalMs、lastSeenEventId、authorizedExpiresAt、accountAlias を格納します。 デーモンイベントペイロード自体は上記のイベントごとの形式のままです。

状態と前方互換性

• 既知のイベントタイプを追加するには DAEMON_KNOWN_EVENT_TYPE_VALUES に追記します。古い SDK はフォールバックパスを通じて未認識のイベントタイプに undefined を返し、unrecognizedKnownEventCount をインクリメントします。新しい SDK は判別済みユニオンに依存します。
• 既存のペイロードへのオプションフィールド追加は安全です。ペイロードはオープン（{ [key: string]: unknown }）です。
• 既存のペイロードシェイプの変更は破壊的変更であり、EVENT_SCHEMA_VERSION をバンプし、caps.features.typed_event_schema_v2 などの互換ケーパビリティタグをアドバタイズする必要があります。
• id はセッションごとに単調増加します。サブスクライバーレベルの合成フレーム（client_evicted、slow_client_warning、stream_error、state_resync_required、replay_complete、session_snapshot）は意図的に id を持たないため、他のサブスクライバーはギャップを見ません。
• originatorClientId は data ではなくエンベロープに存在します。F3 の部分投票 / 拒否ペイロードも mergeOriginator を通じて data にマージされるため、ビュー状態コンシューマーはエンベロープを保持する必要がありません。

依存関係

• 10-event-bus.md - 配信チャネル。
• 11-capabilities-versioning.md - SDK が typed_event_schema、mcp_guardrail_events、permission_mediation をプリフライトする方法。
• 04-permission-mediation.md - パーミッションイベントが生成される方法。
• 13-sdk-daemon-client.md - asKnownDaemonEvent、リデューサー、ビュー状態シェイプ。

設定

• 常にアドバタイズされます：typed_event_schema、mcp_guardrail_events、permission_mediation（サポートされているポリシーモードを含む）。
• スキーマ自体を直接制御する環境変数やフラグはありません。QWEN_SERVE_NO_MCP_POOL=1 は MCP イベントの scope を 'workspace' から absent または '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 を通じて消費する場合、セッションリデューサーではなく 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）
• ワイヤーリファレンス：../qwen-serve-protocol.md