* feat(daemon): add shared UI transcript layer * fix(daemon): address ui review feedback * test(daemon): cover raw event diagnostics option * fix(daemon): address latest ui review * fix(daemon): cover reconnect and status edge cases * fix(daemon): guard prompt busy cleanup * feat(daemon): add shared UI transcript layer * fix(daemon): address ui review feedback * test(daemon): cover raw event diagnostics option * fix(daemon): address latest ui review * fix(daemon): cover reconnect and status edge cases * fix(daemon): guard prompt busy cleanup * fix(daemon): handle trimmed tool updates * fix(daemon): cap transcript text blocks * fix(daemon): dedupe trimmed tool diagnostics * fix(daemon): harden webui transcript edge cases * fix(daemon): preserve webui daemon events * fix(daemon): address latest ui review comments * feat(web-shell): add daemon-backed UI shell * feat(web-shell): improve session routing and slash commands * feat(daemon): add shared UI transcript layer * fix(daemon): address ui review feedback * test(daemon): cover raw event diagnostics option * fix(daemon): address latest ui review * fix(daemon): cover reconnect and status edge cases * fix(daemon): guard prompt busy cleanup * fix(daemon): handle trimmed tool updates * fix(daemon): cap transcript text blocks * fix(daemon): dedupe trimmed tool diagnostics * fix(daemon): harden webui transcript edge cases * fix(daemon): preserve webui daemon events * fix(daemon): address latest ui review comments * fix(daemon): close latest ui review nits * fix(daemon): harden ui review edges * fix(daemon-ui): address wenshao 2 Critical findings (#4328 review) ## Critical #1 — 401/403 reconnect storm + transcript wipe `DaemonSessionProvider`'s reconnect loop kept retrying `createOrAttach` on 401/403 even with `autoReconnect: true`. Each cycle: - hit the daemon with the same bad token → 401 again - cleared the session handle - the next successful attempt (if token magically recovered) would receive a different sessionId, triggering the `store.reset()` branch at line 143 and wiping the user's transcript - no terminal "auth failed" state surfaced to the user Fix: split `TERMINAL_SESSION_HTTP_STATUSES` into `AUTH_FAILURE_HTTP_STATUSES` (401, 403) and the rest (404, 410). On auth failure, return from the reconnect loop unconditionally regardless of the `autoReconnect` flag — these are credential failures, not transient. The user must update credentials; daemon spam must stop. `extractHttpStatus` helper factored out of `isTerminalSessionHttpError` to share between the two predicates. ## Critical #2 — rawInput / rawOutput leaking secrets to UI `normalizer.normalizeToolUpdate` forwarded `rawInput` / `rawOutput` verbatim onto `DaemonUiToolUpdateEvent` → `DaemonToolTranscriptBlock`. The `details` projection was redacted via `stringifyRedactedJson` / `redactSensitiveFields`, but the underlying `rawInput` / `rawOutput` fields were unredacted. Any UI component that read those fields directly (ShellToolCall, WriteToolCall, JSON debug panels) leaked the raw values to the DOM. Example: `{ command: 'curl', apiKey: 'sk-prod-...' }` had `apiKey` redacted in `details` but exposed verbatim on `rawInput`. Fix: apply `redactSensitiveFields` to both `rawInput` and `rawOutput` ONCE at the normalizer boundary, then reuse the redacted shape for the `details` projection. Downstream is uniformly safe; no double traversal. ## Tests (49/49 pass) - SDK `daemonUi.test.ts` (36 tests, +1) — new test `redacts sensitive fields in tool.update rawInput and rawOutput at normalizer boundary` verifies full-event string scan finds zero secret values + structural keys preserved with values `'[redacted]'`. - WebUI `DaemonSessionProvider.test.tsx` (13 tests, +2) — new tests `breaks out of the reconnect loop on 401 / 403 auth failures even when autoReconnect is true` and `still reconnects on 404 / 410 session-not-found errors when autoReconnect is true` lock in the asymmetry: auth failure → 1 attempt only; session-not-found → retries until success. ## Out of scope (declined / deferred — see PR review reply) - CRIT #3 `withActionTimeout` test coverage gap → behavior correct, test-only follow-up (avoids PR bloat) - Suggestions #4-7 → 4 nice-to-haves, deferred to keep PR focused on production-correctness fixes Generated with AI Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com> * fix(daemon-ui): redact tool details in web transcript * feat(web-shell): align daemon UI interactions * fix(web-shell): address daemon UI review comments * feat(web-shell): sync independent web-shell with lib build, i18n, and daemon serve enhancements Bring in the independently developed web-shell package with full lib build support (vite.lib.config.ts, tsconfig.lib.json), i18n layer, new dialogs (Help, Theme, ReleaseSession), composer hiding during approvals, and SDK dependency restructured as peerDependency. Also adds daemon serve routes (detach endpoint, rename persistence) and fixes acp-bridge testUtils missing cancelImpl. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * fix(web-shell): address daemon UI review comments - Strip token from URL after caching (prevents Referer/history leak) - Add URL scheme allowlist for markdown links/images (block javascript:) - Add CORS restriction in vite dev server - Handle state_resync_required event (reset store) - Reset promptStatus on SSE disconnect - Handle 401/403 in reconnect loop (no retry on auth failures) - Heartbeat consecutive failure detection (3 strikes → disconnect) - Strip <style> tags in SVG sanitization - Replace naive diff with LCS-based buildUnifiedDiff - Fix inputHighlight decoration ordering (sort before add) - Add isEditableTarget guard in useDelayedGlobalKeyDown - Fix AskUserQuestion keyboard handler (no capture phase) Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * fix(web-shell): address second-round review Critical issues - Add size guard to buildUnifiedDiff (fallback when n*m > 250k) - Strip SVG animation elements (animate, set, animateTransform, animateMotion) - Reset promptStatus to idle on state_resync_required - Restrict getAllowedDaemonOrigin to same port as page origin Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * fix(web-shell): address remaining PR #4380 review issues - SVG sanitizer: strip style/use/image/feImage/mpath, block external hrefs - Markdown: split isSafeHref/isSafeImageSrc (allow data:image for img only) - Heartbeat: fire disconnect once at 3 failures, self-heal on success - state_resync_required: reset store and reconnect (remove dead code) - Auth 401/403: log error, stop reconnect loop, show error state - replaceSessionUrl: delete ?token param to prevent leak - removeDaemonTokenFromUrl() called at module init - Vite dev server: cors: false - killSession: forgetSession before byId.delete (prevent lost events) - inputHighlight: collect ranges and sort before adding to builder - useDelayedGlobalKeyDown: isEditableTarget guard from shared utils - buildUnifiedDiff: proper O(nm) LCS, hasDiffContent lightweight check - detachDaemonClient: restore console.warn for observability - App.tsx: use rAF-coalesced messageBlocks in extractPendingPermission - extractPendingPermission: extract toolCallId from toolCall record - vite.lib.config: wrap CSS injection in try/catch for CSP - Add test coverage: server routes, SDK methods, transcriptAdapter Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * fix(web-shell): address third-round PR #4380 review issues Critical fixes: - ToolApproval: reset submittedRef via useEffect on request.id change - Effect cleanup: reject pendingSessionLoadRef on dispose - sanitizeSvg: strip style attributes with external url() values Suggestion fixes: - <use> elements: keep fragment-only href, strip external (+ xlink:href fallback) - SAFE_IMAGE_DATA_URI: remove svg+xml (can load external subresources) - extractStreamingState: accept blocks directly, remove state dependency - coalescedState useMemo removed — rAF coalescing no longer defeated - Auth failure log: use missingSessionId instead of already-cleared vars - newSession(): reject pending loadSession promise - COPY_MESSAGES: wire constants to copyFromLastAssistantMessage - Add 39 tests for isSafeHref, isSafeImageSrc, sanitizeSvg - Add 3 tests for toolCallId extraction fallback - Fix test fixtures: resolved: undefined, clientReceivedAt: 1 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * fix(web-shell): delegate readWorkspaceFile to SDK client Replaces the manual fetch() call with session.client.readWorkspaceFile() which provides fetchWithTimeout (30s default) and error normalization. Ensures DaemonClient baseUrl is always absolute by falling back to window.location.origin in proxy mode. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * fix(web-shell): address fourth-round PR #4380 review issues - Fix suppressedOwnUserEchoCountRef not decrementing on prompt failure - Add heartbeat status guard to prevent overwriting 'connecting' state - Abort stale activePrompts when SSE session disconnects - Truncate displayName to 256 chars in renameSession endpoint - Fix DiffView counting +++ / --- header lines as additions/deletions - Preserve existing command properties in mergeCommands - Fix bridge cwd override by params spread order - Validate all href attributes on SVG <use> elements - Extend external url() check to all SVG attributes, not just style - Unify detachDaemonClient baseUrl with DaemonClient construction - Delegate loadMcpTools to SDK client instead of returning stub - Add createAtCompletionSource factory with baseUrl/token fallback - Reset AskUserQuestion state on request.id change - Add useEffect cleanup for queue drain setTimeout - Suppress replay_complete from reaching UI as unrecognized event Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * fix(web-shell): address fifth-round PR #4380 review issues - Use safeWorkspaceCwd in buildWorkspaceToolsStatus for consistency - Wire loadMcpTools to return SDK tools instead of hardcoded empty array - Consolidate WebShellMcpToolsStatus types (remove duplicate in McpDialog) - Abort active prompts in loadSession before switching sessions - Pass daemon credentials to @-completion source via Editor props Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * fix(web-shell,cli): address PR #4380 review issues and fix duplicate user message - Remove Session#executePrompt's emitUserMessage() call to eliminate duplicate user_message_chunk events (bridge-echo is the single source) - Move removeDaemonTokenFromUrl() to main.tsx entry point (S19) - Add mount-grace, interaction guard, safe default index to ToolApproval (Critical#1) - Fix stale credential capture in Editor @-completion (Critical#3) - Add submittedRef guard to AskUserQuestion, remove unsafe fallback (S18/S23) - Use .then() pattern for clipboard writeText (S17) - Add i18n for approval dialog and rename messages (S20) - Add session load timeout (S15) - Distinguish MCP error types with DaemonHttpError (S12) - Clear stale heartbeat error on success (S13) - Fix null vs undefined clientId check in server detach (S16) - Add daemon.test.ts for origin validation coverage Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * fix(web-shell,cli): address PR #4380 R9 review — detach loose equality, ToolApproval stale refs, session load timeout leak - server.ts: change `clientId == null` to `=== null` so absent header falls through to detachClient instead of hanging the request - server.test.ts: add test for detach without X-Qwen-Client-Id header - ToolApproval.tsx: use refs to fix stale closures in handleKeyDown, reset submittedRef on request.id change, sync selectedRef on mouse hover, remove unstable request.options from effect deps - useDaemonSession.ts: store and clear timeout handle in PendingSessionLoad across all resolution paths Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * fix(web-shell): add submittedRef guard to AskUserQuestion handleCancel Prevents double-submission on rapid Escape+Enter and avoids sending empty optionId when no reject option exists. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> --------- Co-authored-by: 秦奇 <gary.gq@alibaba-inc.com> Co-authored-by: ytahdn <ytahdn@gmail.com> Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>
9.9 KiB
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 web chat and web terminal adapter authors first. Native local TUI, channel, and IDE maintainers can reuse the same primitives later, but those default product paths are not migrated by this PR.
TL;DR for existing consumers
No breaking changes. Every commit in this PR is additive:
- v1 fields still work (
createdAtpreserved as@deprecatedalias forclientReceivedAt) - 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:
const ordered = [...state.blocks].sort((a, b) => a.createdAt - b.createdAt);
After:
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:
<TimeLabel ms={block.createdAt} />
After:
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:
// 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:
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):
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):
import { daemonBlockToMarkdown } from '@qwen-code/sdk/daemon';
const md = daemonBlockToMarkdown(block);
For HTML SSR:
import MarkdownIt from 'markdown-it';
import DOMPurify from 'dompurify';
const html = DOMPurify.sanitize(md.render(daemonBlockToMarkdown(block)));
For plain text:
import { daemonBlockToPlainText } from '@qwen-code/sdk/daemon';
const plain = daemonBlockToPlainText(block);
5. Conformance test
Add to your adapter's test suite:
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):
const isMcp = toolName?.startsWith('mcp__');
const isBuiltin = ['Bash', 'Edit', 'Read'].includes(toolName);
After (typed provenance from PR-A):
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):
if (error.text.includes('auth')) showAuthRetry();
else if (error.text.includes('file not found')) showFilePicker();
After (closed enum from PR-A):
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'. Sub-agent children are
cancelled together with their parent.
No adapter changes needed — your spinners will resolve correctly.
8a. Sub-agent nesting — opt in to nested rendering (PR-K)
Tool blocks invoked inside a sub-agent delegation now carry
parentToolCallId, subagentType, and (when the parent is in state)
parentBlockId. Adapters can opt in to nested rendering:
Before (flat list, sub-agent calls visually indistinguishable from top-level):
state.blocks.map((b) => <ToolBlock block={b} />);
After (recursive nested rendering):
import {
selectSubagentChildBlocks,
isSubagentChildBlock,
} from '@qwen-code/sdk/daemon';
function renderTool(block) {
const children = selectSubagentChildBlocks(state, block.toolCallId);
return (
<ToolBlock block={block}>
{block.subagentType && <SubagentBadge type={block.subagentType} />}
{children.length > 0 && <Indent>{children.map(renderTool)}</Indent>}
</ToolBlock>
);
}
const topLevel = state.blocks.filter((b) => !isSubagentChildBlock(b));
return topLevel.map(renderTool);
No adapter changes needed if you prefer the flat view — the new fields are additive and ignored by code that doesn't read them.
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:
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
- Daemon UI README — full API reference
- PR #4328 — base PR with shared UI transcript layer