QwenLM
diff --git a/‎docs/developers/daemon-ui/MIGRATION.md‎
Lines changed: 266 additions & 0 deletions b/‎docs/developers/daemon-ui/MIGRATION.md‎
Lines changed: 266 additions & 0 deletions
@@ -0,0 +1,266 @@
+# Migrating to `@qwen-code/sdk/daemon` v2
+
+PR #4328 shipped the v1 daemon UI layer. PR #4353 (this PR) ships v2 with
+seven additive feature commits. This guide walks through the changes for
+adapter authors (TUI / web / IDE / channel / mobile maintainers).
+
+## TL;DR for existing consumers
+
+**No breaking changes.** Every commit in this PR is additive:
+
+- v1 fields still work (`createdAt` preserved as `@deprecated` alias for
+  `clientReceivedAt`)
+- v1 normalizer still maps the same 13 event types the same way
+- v1 reducer still produces the same blocks for chat events
+- New API is opt-in via additional parameters and helpers
+
+The PR is safe to merge without any consumer changes. **Adoption of the
+new features is incremental.**
+
+## Recommended adoption order
+
+For each adapter, in order of effort/value ratio:
+
+### 1. Ordering: switch sort key from `createdAt` to `eventId`
+
+**Before:**
+
+```ts
+const ordered = [...state.blocks].sort((a, b) => a.createdAt - b.createdAt);
+```
+
+**After:**
+
+```ts
+import { selectTranscriptBlocksOrderedByEventId } from '@qwen-code/sdk/daemon';
+const ordered = selectTranscriptBlocksOrderedByEventId(state);
+```
+
+**Why**: `eventId` is daemon-monotonic; survives SSE replay-after-reconnect.
+`createdAt` is client clock and shifts under replay.
+
+### 2. Display: switch `createdAt` to `serverTimestamp ?? clientReceivedAt`
+
+**Before:**
+
+```tsx
+<TimeLabel ms={block.createdAt} />
+```
+
+**After:**
+
+```tsx
+import { formatBlockTimestamp } from '@qwen-code/sdk/daemon';
+<TimeLabel text={formatBlockTimestamp(block, { locale })} />
+```
+
+**Why**: Multiple clients see consistent "X minutes ago" only when both
+read daemon clock. Renderer plus `formatBlockTimestamp` handles tz +
+locale.
+
+**Note**: Daemon needs to stamp `_meta.serverTimestamp` on envelopes for
+this to take effect. SDK forward-compat-ready; falls back to
+`clientReceivedAt` until then.
+
+### 3. Listen for new event types — pick subset to render
+
+The 16 new event types (session-meta, workspace, auth) don't push transcript
+blocks. They are sidechannel observations. Each adapter picks which to surface:
+
+```ts
+// In your SSE consumer
+const uiEvents = normalizeDaemonEvent(envelope, { clientId, suppressOwnUserEcho: true });
+store.dispatch(uiEvents);
+
+// Then in your UI side
+for (const event of uiEvents) {
+  switch (event.type) {
+    case 'session.approval_mode.changed':
+      myApprovalModeBadge.update(event.next);
+      break;
+    case 'workspace.mcp.budget_warning':
+      myToast.show(`MCP servers approaching budget: ${event.liveCount}/${event.budget}`);
+      break;
+    case 'auth.device_flow.started':
+      myAuthModal.show({
+        deviceFlowId: event.deviceFlowId,
+        providerId: event.providerId,
+        expiresAt: event.expiresAt,
+      });
+      break;
+    // ... etc, opt into what your UI needs
+  }
+}
+```
+
+Or use selectors for state-mirrored sidechannels:
+
+```ts
+import { selectApprovalMode, selectCurrentTool } from '@qwen-code/sdk/daemon';
+
+const mode = selectApprovalMode(state);          // mirrored from approval_mode.changed
+const currentTool = selectCurrentTool(state);    // current in-flight tool
+```
+
+### 4. Render contract: use `daemonBlockToMarkdown` (or HTML / plainText)
+
+**Before** (each adapter does its own projection):
+
+```ts
+function blockToString(block: DaemonTranscriptBlock): string {
+  switch (block.kind) {
+    case 'user': return `You: ${block.text}`;
+    case 'assistant': return block.text;
+    case 'tool': return `[${block.title}]\n${block.status}`;
+    // ... etc
+  }
+}
+```
+
+**After** (delegate to SDK):
+
+```ts
+import { daemonBlockToMarkdown } from '@qwen-code/sdk/daemon';
+const md = daemonBlockToMarkdown(block);
+```
+
+For HTML SSR:
+
+```ts
+import MarkdownIt from 'markdown-it';
+import DOMPurify from 'dompurify';
+const html = DOMPurify.sanitize(md.render(daemonBlockToMarkdown(block)));
+```
+
+For plain text:
+
+```ts
+import { daemonBlockToPlainText } from '@qwen-code/sdk/daemon';
+const plain = daemonBlockToPlainText(block);
+```
+
+### 5. Conformance test
+
+Add to your adapter's test suite:
+
+```ts
+import { runAdapterConformanceSuite } from '@qwen-code/sdk/daemon';
+
+it('adapter projects daemon UI corpus correctly', () => {
+  const result = runAdapterConformanceSuite({
+    reduce: (events) => myReduce(events),
+    renderToText: (state) => myRender(state),
+  });
+  expect(result.failed).toEqual([]);
+});
+```
+
+This will run your adapter against 10 fixture scenarios and surface any
+projection drift before it reaches users.
+
+### 6. Tool icon dispatch via `provenance`
+
+**Before** (string match on toolName):
+
+```tsx
+const isMcp = toolName?.startsWith('mcp__');
+const isBuiltin = ['Bash', 'Edit', 'Read'].includes(toolName);
+```
+
+**After** (typed provenance from PR-A):
+
+```tsx
+import type { DaemonUiToolUpdateEvent } from '@qwen-code/sdk/daemon';
+
+function toolIcon(event: DaemonUiToolUpdateEvent): React.ReactNode {
+  switch (event.provenance) {
+    case 'mcp':      return <McpIcon server={event.serverId} />;
+    case 'subagent': return <SubagentIcon />;
+    case 'builtin':  return <BuiltinIcon name={event.toolName} />;
+    case 'unknown':
+    default:         return <GenericIcon />;
+  }
+}
+```
+
+SDK has a `mcp__<server>__<tool>` naming heuristic fallback — works today
+even when daemon doesn't explicitly stamp provenance.
+
+### 7. Error categorization via `errorKind`
+
+**Before** (regex on text):
+
+```ts
+if (error.text.includes('auth')) showAuthRetry();
+else if (error.text.includes('file not found')) showFilePicker();
+```
+
+**After** (closed enum from PR-A):
+
+```ts
+import type { DaemonErrorKind } from '@qwen-code/sdk/daemon';
+
+function errorAction(errorKind?: DaemonErrorKind): React.ReactNode {
+  switch (errorKind) {
+    case 'auth_env_error': return <RetryAuthButton />;
+    case 'missing_file':   return <FilePicker />;
+    case 'blocked_egress': return <CheckProxyHint />;
+    case 'init_timeout':   return <RestartDaemonButton />;
+    default:               return null;
+  }
+}
+```
+
+**Note**: Daemon needs to stamp `data.errorKind` on session_died /
+stream_error for this to populate. SDK already reads it.
+
+### 8. Cancellation handling — already automatic
+
+In v1, cancelled prompts left in-flight tool blocks spinning forever.
+In v2 (PR-E), `propagateCancellationToInFlightTools` runs automatically
+on `assistant.done.reason === 'cancelled'`.
+
+**No adapter changes needed** — your spinners will resolve correctly.
+
+### 9. Tool preview taxonomy — pick subset to render with custom components
+
+PR-D + PR-F bring 13 preview kinds:
+
+- 4 file-shaped: `file_diff`, `file_read`, `web_fetch`, `mcp_invocation`
+- 5 content-shaped: `code_block`, `search`, `tabular`, `image_generation`, `subagent_delegation`
+- 2 control: `ask_user_question`, `command`
+- 2 generic: `key_value`, `generic`
+
+Each adapter dispatches on `preview.kind`:
+
+```tsx
+function ToolPreviewComponent({ preview }: { preview: DaemonToolPreview }) {
+  switch (preview.kind) {
+    case 'file_diff':   return <UnifiedDiffView path={preview.path} old={preview.oldText} new={preview.newText} />;
+    case 'mcp_invocation': return <McpCard serverId={preview.serverId} toolName={preview.toolName} />;
+    case 'tabular':     return <DataTable columns={preview.columns} rows={preview.rows} />;
+    case 'image_generation': return <ImagePreview thumbnailUrl={preview.thumbnailUrl} prompt={preview.prompt} />;
+    // ... or fall back to:
+    default: return <Markdown text={daemonToolPreviewToMarkdown(preview)} />;
+  }
+}
+```
+
+Adapters without custom components for all 13 kinds can fall back to the
+SDK's `daemonToolPreviewToMarkdown` for any unhandled kind.
+
+## Backward-compat checklist
+
+| Concern | Status |
+|---|---|
+| Existing `block.createdAt` reads | ✅ still works (alias for `clientReceivedAt`) |
+| Existing reducer event handling | ✅ unchanged for v1 event types |
+| `daemonTranscriptToUnifiedMessages(blocks)` call sites | ✅ new options param is optional |
+| Existing `selectTranscriptBlocks` consumers | ✅ unchanged |
+| New event types in v1 reducer | ✅ no-op, `lastEventId` still advances |
+
+## Cross-references
+
+- [PR #4353 SUMMARY](https://github.com/QwenLM/qwen-code/pull/4353)
+- [Daemon UI README](./README.md) — full API reference
+- [PR #4328](https://github.com/QwenLM/qwen-code/pull/4328) — base PR with shared UI transcript layer