ytahdn ea8bdeeaab Feat/daemon react cli (#4380)
* 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>
2026-05-27 10:32:17 +08:00

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 (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.

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