A complete daemon design proposal for Qwen Code, organized as a 6-chapter design series (simplified from original 14 chapters). This issue tracks implementation; the series is the source of truth.

Status (2026-05-15):

• ✅ Stage 1 merged — PR feat(cli,sdk): qwen serve daemon (Stage 1) #3889 (merge commit 870bdf2a, +12993/-194, 84 commits)
• ✅ Stage 1.5a §02 1 daemon = 1 workspace — PR refactor(serve): 1 daemon = 1 workspace (#3803 §02) #4113 (merge commit 790f2d04, +2051/-434) MERGED 2026-05-15
• ✅ Stage 1.5b A1 — createInMemoryChannel helper — PR refactor(serve): extract createInMemoryChannel helper (#4156 A1) #4160 MERGED 2026-05-15 (ff63da26, +315/-40) — extracted as reusable primitive; remaining Mode A work parked
• 🔧 Mode B prioritized (2026-05-15) — see qwen-code-daemon-design PR #131 MERGED roadmap reset: P0 production must-haves + daemon-side state CRUD; P1 typed event contract + client adapters behind flag; P2 deferred Mode A + remote-control
• 🔧 Wave 1 started (2026-05-16) — PR #4191 feat(serve): capability registry + protocol versions (Wave 1 PR 2, doudouOUC [codex], +170/-39) OPEN — first implementation PR from Issue proposal(serve): Mode B feature-priority roadmap toward v0.16 production-ready #4175 25-PR plan; closes chiga0 finding 5 FIXME (replaces hard-coded STAGE1_FEATURES array with additive registry + adds /capabilities.protocolVersions)
• ⏳ Pending: 9 production must-haves + 1.5c control-plane parity (10+ routes) + 1.5-prereq typed event contract + client adapters (TUI/channels/web/IDE behind flag) + Mode A revisit + remote-control revisit + Stage 2

Overall main-line progress ~30-35%. Issue was auto-closed by PR #4113's "closes #3803 §02" trigger but only §02 (process model decision) was implemented — reopened to track remaining stages.

Architecture (post PR #4113, with PR#131 corrections)

1 daemon process = 1 workspace × N sessions multiplexed:

qwen serve (bound to cwd = single workspace)
├─ Express HTTP front + bearer auth + Host allowlist
├─ EventBus (per-session fan-out + ring replay + Last-Event-ID reconnect)
│  └─ INTERNAL fan-out primitive — exposed to clients via HTTP/SSE projection,
│     NOT subscribed directly by external clients
└─ qwen --acp child (workspace bound)
   └─ QwenAgent.sessions: Map → {sess-1, sess-2, sess-3}
      └─ per-session Config / ToolRegistry / McpClientManager / FileReadCache

qwen serve startup binds cwd to a single workspace; daemon embeds a single qwen --acp child; N sessions multiplex via QwenAgent.sessions: Map<sessionId, Session> (packages/cli/src/acp-integration/acpAgent.ts:194). Multi-workspace deployment = multiple daemon processes (systemd / docker / k8s each 1 process per workspace).

Key invariants (corrected per PR#131)

• N sessions on same daemon share: the same qwen --acp child process + workspace bound context
• N sessions on same daemon do NOT share: Config / ToolRegistry / McpClientManager / FileReadCache — these are still created per ACP session; cross-session MCP sharing requires future pool/proxy design
• Cross-workspace = cross-daemon process = OS process-level isolation (strongest)
• Blast radius minimal (daemon crash only affects 1 workspace)
• K8s cloud-native natural fit (1 pod = 1 daemon = 1 workspace)
• WorkspaceMismatchError returned as 400 workspace_mismatch when POST /session cwd ≠ bound workspace
• --workspace <path> CLI flag overrides process.cwd() at boot; canonicalized via canonicalizeWorkspace
• Same-workspace Nth session cold start <200ms (attach existing qwen --acp child)

Client boundary (per PR#131)

Clients do NOT directly subscribe to in-memory EventBus. Clients connect to daemon HTTP/SSE API:

client (TUI / channels / web / IDE)
  -> DaemonSessionClient (SDK helper)
  -> POST /session/:id/{prompt,cancel,model,...} + GET /session/:id/events (SSE)
  -> daemon internal EventBus (fan-out projection)

EventBus lift (1.5-prereq finding #2) refers to extracting typed event schema + reducer + server-side fan-out primitive + transport adapter to a shared package — NOT exposing the memory object to external clients.

Dual deployment modes

Both modes share the same wire protocol (Express 5 + ACP NDJSON over HTTP+SSE). Mode B prioritized (2026-05-15 decision) because Mode A value depends on 1.5c daemon-side state CRUD (else remote clients in Mode A are still thin shells, creating UX gap). Ship 1.5c first → remote clients fully functional → then Mode A revisit.

Design Documents (6-chapter series)

• §01 Overview — TL;DR + 2-layer terminology + architecture diagram + resource economy + stage progress
• §02 Architectural Decisions — 7 core decisions (corrected: MCP per-session lifecycle; Mode A → parking lot)
• §03 HTTP API & Protocol — Route table + ACP wire 4-layer compatibility matrix + SSE + Last-Event-ID + reverse-RPC asynchrony + Capability negotiation + additive compatibility principle
• §04 Deployment & Client — Mode B client convergence + TUI / channels / web / IDE adapter boundary + remote-control deferred + multi-client coordination
• §05 Security & Permission — Bearer + Host allowlist + PR feat(core): add shared permission flow for tool execution unification #3723 4-mode evaluatePermissionFlow + first-responder vote + per-session permission routing (PR#131 correction)
• §06 Roadmap & Ecosystem — Timeline + Stage 1.5 with Mode B priority + client adapters subsection + remote-control subsection + 7 engineering principles + Stage 2 + External Reference Architecture

Implementation Tracker (Mode B priority — PR#131 reset)

Engineering Principles (PR#131 — every PR must satisfy)

Stage 1.5 is incremental migration, not big rewrite. Each PR must:

P0: Stage 1.5a chiga0 must-haves (9 remaining, ~2 weeks, 9 PRs in parallel)

• 🚨 Blockers (production-required):
  • pre-release: fix ci #1 Per-request sessionScope override — body { scope: 'single' | 'thread' | 'user' }
  • Where is the config saved? #2 loadSession / unstable_resumeSession HTTP — POST /session/:id/load + POST /session/:id/resume (★ biggest user pain point; PR Add background agent resume and continuation #3739 transcript on disk, only wire route missing)
  • 如何自定义密钥文件 .env可能与其他文件冲突 #3 Persistent client identity — pair tokens + revocation API + daemon-stamped originatorClientId (NOT self-declared)
• 🛡️ Reliability:
  • Are you interested in AI Terminal? #4 Client-initiated heartbeat — POST /session/:id/heartbeat
  • TypeError in Authentication Selection Interface #5 permission_already_resolved event (first-responder vote loser feedback)
  • OpenAI API Error: 401 Incorecct API Key provided #6 Larger / per-session-configurable replay ring (default 8000, query param)
  • API Key是要设成阿里云的API Key吗？ #7 slow_client_warning event before client_evicted
• 🎨 Ergonomics:
  • report error when try to auth #8 POST /session/:id/_meta (IM-style per-session context push) + close/delete session
  • API Error: Streaming setup timeout after 45s #9 /capabilities actual feature negotiation — protocol_versions: { acp, daemon_envelope } payload
  • 这个怎么调用 Qwen3-Coder，配置界面只有openai #10 First-class durability documentation ✅ shipped (commit bbc7b8b6)
• Permission per-session routing (PR#131 correction):
  • POST /session/:id/permission/:requestId (session-scoped pending map; legacy POST /permission/:requestId retained for compatibility)

P0: Stage 1.5c daemon-side state CRUD (10+ wire routes, ~1-2 weeks)

Let remote clients access daemon-side state (no longer thin shell). Reference implementation: Claude Code /agents UI Deep-Dive.

• GET / POST /workspace/memory (read/write ~/.qwen/memory.json)
• GET /workspace/mcp + POST /workspace/mcp/:server/restart (MCP status / restart)
• GET / POST /workspace/agents + :agentType CRUD
• POST /workspace/tools/:name/enable (tool allowlist)
• POST /session/:id/approval-mode
• GET /session/:id/context (context usage — new per PR#131)
• GET /session/:id/supported-commands (command palette / UI affordance — new per PR#131)
• GET /workspace/providers (provider/model runtime state — new per PR#131)
• POST /workspace/auth/device-flow or Capability RPC (auth — new per PR#131)
• POST /workspace/init (project init / trust state)

Compatibility: All new routes have capability tags; clients fallback to old behavior or hide UI when capability missing. Read-only first, mutation second.

P1: Stage 1.5-prereq typed contract + bridge primitives (~1 week)

Lift shared primitives to @qwen-code/acp-bridge package — reusable by serve/ + remoteControl/ + nonInteractive/:

• Typed SessionEvent / ControlEvent — convert data: unknown to discriminated union
• DaemonSessionClient — shared SDK helper for TUI / channels / web / IDE
• AcpChannel interface + Transport interface
• EventBus lift to shared package (fan-out primitive — internal to daemon, projected to clients via HTTP/SSE)
• PermissionMediator interface + 4 policy strategies (first-responder / designated / consensus / local-only)
• FileSystemService per-request abstraction
• Capability registry per-session
• Event reducer — build client view-model from daemon events (clients don't reinvent state machines)
• Output sinks — JSONL / stream-json / dual-output become same event stream consumers
• /capabilities protocol_versions + feature registry for graceful degradation

Compatibility: Old DaemonEvent envelope still parseable; typed union is SDK/helper layer additive enhancement.

P1 behind flag: Stage 1.5-client adapters (~2-3 weeks)

Onboard primary clients to Mode B daemon — behind flag first, default switch after P0/P1:

P2 deferred: Stage 1.5b Mode A — Issue #4156 doudouOUC 3-phase plan

• Phase A — Loopback-only minimal skeleton (~4.3d, A0/A1/A2/A3 stacked PRs):
  • A0 — extract validateAndCanonicalizeWorkspace helper from PR refactor(serve): 1 daemon = 1 workspace (#3803 §02) #4113 code (~50 LOC)
  • A1 — extract createInMemoryChannel helper — PR refactor(serve): extract createInMemoryChannel helper (#4156 A1) #4160 ✅ MERGED 2026-05-15
  • A2 — new inProcessAcpBridge.ts (~200 LOC) implementing HttpAcpBridge interface
  • A3 — gemini.tsx --serve flag integration; lazy import; boot path; default port 0
• Phase B — Remote bind + auth/CORS defaults (~1d)
• Phase C — Lifecycle coordination (~1d)

Why parked: Mode A value is "local TUI super-client + remote clients sharing same daemon". Without 1.5c, remote clients in Mode A are still thin shells. Without 1.5-prereq typed event contract, TUI adapter has no shared reducer to consume. Ship Mode B contract first → Mode A revisit cleanly.

P3: Stage 2 (~3-4 weeks, split 2a-2d)

• 2a Protocol Completion (~1 week): WebSocket bidi + /health?deep=1 + POST /ext/:method + permission policy schema + Reverse RPC 5 Client Capability classes (editor / clipboard / browser / notification / file_picker)
• 2b Ecosystem (~1 week): OpenAPI codegen + multi-token + HttpTransport SDK adapter
• 2c Observability (~3-5 days): Prometheus metrics + mDNS + --max-sessions guard rail
• 2d Perf eval + docs (~3-5 days)
• 2e (optional) Native in-process (~1-2 weeks): Remove qwen --acp child bridge; resolve acpAgent.ts:601 loadSettings(cwd) cross-workspace pollution

After Stage 2 the daemon protocol surface is locked; external integrators can build on top.

Recommended 4-week execution timeline (PR#131 finalized)

Week 0 (now, 2026-05-15)
└─ 9 × 1.5a must-have PRs launched in parallel
   ★ #2 loadSession HTTP (3-4d, biggest user pain)
   + #1 sessionScope + #3 pair tokens + per-session permission routing (blockers)
   + #4-7 reliability + #8-9 ergonomics (small PRs, 1-2d each)

Week 1
├─ must-haves PRs review + merge
├─ 1.5c daemon-side state CRUD (10+ routes) PR opens
└─ web/debug client (PR #4132) starts using daemon contract behind flag

Week 2
├─ must-haves merge complete
├─ 1.5c merge → Mode B remote clients have full state access
└─ 1.5-prereq typed event contract + DaemonSessionClient PR opens

Week 3
├─ 1.5-prereq merge → contract stabilized
├─ Wave-1 client adapters (TUI / channels / web/debug) behind flag
└─ Wave-2 client adapter (IDE) preparation

Week 4
├─ IDE adapter behind flag
├─ remote-control revisit (after primary clients converge)
└─ Mode A revisit (after Mode B contract stable)

External Reference Architecture (out of project scope)

Designed but not on qwen-code's roadmap; meant for commercial platforms / k8s operators / cloud vendors:

• Orchestrator (~1.5-2w reference) qwen-coordinator + multi-daemon spawn / route / cleanup / aggregate API
• Multi-tenancy (~3-4w reference) Tenant abstraction / OIDC + Bearer + mTLS / Quota engine / Audit log
• Shell sandbox (~4-6w reference) ShellSandbox interface + 4 local + 4 remote impls
• SaaS deployment (~3-6w reference) k8s native / Postgres + Redis + S3 / multi-region scheduling

Key design decisions matrix (PR#131 corrections)

See §02 decision matrix for details.

Related Issues / PRs

• Design: qwen-code-daemon-design series
• Roadmap reset PR: codeagents PR #131 MERGED 2026-05-15 (chiga0 — Mode B priority + corrections)
• Stage 1: PR feat(cli,sdk): qwen serve daemon (Stage 1) #3889 ✅ MERGED 2026-05-13
• Stage 1.5a §02: PR refactor(serve): 1 daemon = 1 workspace (#3803 §02) #4113 ✅ MERGED 2026-05-15
• createInMemoryChannel primitive (originally Mode A A1, now retained): PR refactor(serve): extract createInMemoryChannel helper (#4156 A1) #4160 ✅ MERGED 2026-05-15
• Stage 1.5b Mode A (parking lot): Issue proposal(serve): qwen --serve (Mode A) — TUI + in-process HTTP daemon, 3-phase plan (Stage 1.5b) #4156 (3-phase plan tracker; rest deferred)
• Web/debug validation surface: PR feat(serve): add /demo debug page for qwen serve daemon #4132 /demo OPEN
• remote-control stack (deferred): PR feat(cli): add remote-control foundation #3929 / feat(cli): add remote-control worker server #3930 / feat(cli): attach remote-control to current TUI #3931 draft
• References: Claude Code /agents Deep-Dive (Stage 1.5c reference implementation)

Runtime locality / environment contract (2026-05-15 update from chiga0 comment 4458840712)

Mode B daemon is the runtime owner. MCP / Skills / shell / LSP / tool execution / provider auth / file access all evaluated on the daemon host / pod, not the client machine. This deployment contract is documented in qwen-code-daemon-design commit 36c9927 (codeagents):

• §04 §五 Runtime locality / environment contract — new section with 5 concrete implications + reverse RPC scope clarification
• §05 §八 生产部署 best practice — deny-by-default egress + credentials locality + deployment checklist
• §06 §三 1.5c — adds 2 new diagnostic routes (GET /workspace/preflight + GET /workspace/env) + actionable failure detail requirement for GET /workspace/mcp / GET /workspace/skills (no "silent tool loss")

Concrete implications (must be documented for remote clients)

Reverse RPC scope (clarified)

§六 Client Capability reverse RPC 5 classes (editor / clipboard / browser / notification / file_picker) are explicit delegations to client-local resources, NOT general fallbacks for MCP/skill/shell execution. Future client-side MCP/skill fallback would need separate design.

Stage 1.5c route enhancements (PR pending)

• GET /workspace/preflight — daemon startup + config readiness check (providers / MCP / skills / required binaries / egress detection)
• GET /workspace/env — daemon host environment summary (available binaries / env vars masked / mount points / network reachability)
• GET /workspace/mcp enriched to return {status, error, errorKind: missing_binary | blocked_egress | auth_env_error | init_timeout | protocol_error} per server
• GET /workspace/skills enriched to return {loaded, error: missing_file | parse_error | required_binary_not_found} per skill

Deployment best practice

• Deny-by-default egress + explicit allowlist (daemon only needs network surface required by configured providers / MCP / skills)
• Credentials live on daemon host (OAuth tokens / API keys / SSH agent / kubeconfig); client credentials do NOT auto-transfer
• Deployment checklist before exposing daemon to remote clients: install MCP runtimes, sync skills, provision secrets, configure network policy, surface preflight to client UI

Implementation Tracker — Issue #4175 (25-PR Wave Plan)

Issue #4175 by @doudouOUC (2026-05-15) is the authoritative 25-PR rollout plan for Mode B v0.16 production-ready. Stage 1.5 sub-stages in this issue body map to Wave 1-5 below; Wave 6 covers release hardening + v0.16.

Critical dependency chain

capability registry -> DaemonSessionClient -> typed events
  -> daemon-stamped clientId -> session-scoped permission
  -> mutation-gating helper -> control-plane mutation routes
  -> bridge extraction -> real MCP pool + full PermissionMediator

6 Wave breakdown

Key sequencing decisions (from Issue #4175)

1. Issue/docs cleanup is not a blocking PR — body itself is source of truth
2. No full MCP shared pool in Phase 1 — McpClientManager deeply coupled to ToolRegistry/Config/WorkspaceContext; start with measurement + guardrails (PR 11), full pool in Wave 5 (PR 19)
3. Protocol skeleton before CRUD — capability tags / typed events / DaemonSessionClient before broad control-plane routes
4. Minimal client identity before mutation routes — PR 7 stamped clientId → PR 8 session-scoped permission → PR 12 mutation gate → PR 13+ CRUD
5. Read-only first, mutation second — PR 9 read-only → PR 13+ mutation
6. MCP pool + full PermissionMediator are Wave 5 follow-ups — guardrails (PR 11) can land early

Open questions

Moved to #4175 §Open questions — implementation-decision questions live next to the 25-PR rollout plan rather than the design tracker. The questions cover: npm alpha publish timing / loopback token default / token instance path / remote-control alignment / worktree interaction / client adapter requirement for v0.16. Update them on #4175 to keep one source of truth.

See §06 §三·一 Wave breakdown for full Wave 1-6 PR detail tables with dependencies.