Skip to content

Commit e7be6ce

Browse files
doudouOUCqwencoder
doudouOUC
and
qwencoder
committed
docs: Align daemon docs with main implementation
Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com>
1 parent 8b64e80 commit e7be6ce

17 files changed

Lines changed: 793 additions & 182 deletions

‎docs/developers/daemon/00-index.md‎

Lines changed: 23 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,7 @@ Pick the path that matches your goal:
2323
- **Adding a new client adapter**: `01 -> 09 -> 10 -> 13 -> (14 / 15 / 16)`.
2424
- **Working on the MCP pool or budget**: `01 -> 03 -> 05 -> 06`.
2525
- **Working on permissions**: `01 -> 03 -> 04 -> 12`.
26-
- **Debugging a production daemon**: `17 -> 19 -> 18`.
26+
- **Debugging a production daemon**: `19 -> 18 -> 17 -> 20`.
2727

2828
## Document set
2929

@@ -79,6 +79,26 @@ Pick the path that matches your goal:
7979
- **SSE** - Server-Sent Events. The daemon outbound event channel (`GET /session/:id/events`).
8080
- **Workspace** - the directory the daemon was bound to at boot (`--workspace` or `cwd`). One daemon process equals one workspace.
8181

82+
## Implementation source anchors
83+
84+
Use these anchors when moving from the docs into the latest `main` code:
85+
86+
| Surface | Implementation anchors | Primary docs |
87+
| ----------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
88+
| Bootstrap and HTTP assembly | `packages/cli/src/serve/runQwenServe.ts`, `server.ts`, `/demo` | [`02`](./02-serve-runtime.md), [`20`](./20-quickstart-operations.md) |
89+
| ACP bridge and session multiplexing | `packages/acp-bridge/src/bridge.ts`, `packages/acp-bridge/src/bridgeTypes.ts`, `@qwen-code/acp-bridge` | [`03`](./03-acp-bridge.md), [`08`](./08-session-lifecycle.md) |
90+
| Permission mediation | `packages/acp-bridge/src/permissionMediator.ts`, `fromLoopback: boolean`, `policy.*` | [`04`](./04-permission-mediation.md), [`12`](./12-auth-security.md) |
91+
| MCP transport pool | `packages/core/src/tools/mcp-transport-pool.ts`, `mcp-pool-key.ts`, `pid-descendants.ts`, `session-mcp-view.ts`, `/mcp refresh`, `MCPCallInterruptedError` | [`05`](./05-mcp-transport-pool.md), [`06`](./06-mcp-budget-guardrails.md) |
92+
| MCP budget guardrails | `packages/core/src/tools/mcp-workspace-budget.ts`, `ServeMcpBudgetStatusCell.scope`, `budgets[]` | [`06`](./06-mcp-budget-guardrails.md) |
93+
| Workspace filesystem | `packages/cli/src/serve/fs/`, `assertTrustedForIntent(trusted, intent)`, `meta.matchedIgnore`, `includeIgnored` | [`07`](./07-workspace-filesystem.md) |
94+
| Event schema and SSE writer | `packages/sdk-typescript/src/daemon/events.ts`, `packages/cli/src/serve/server.ts`, `formatSseFrame`, `packages/cli/src/acp-integration/session/emitters/ToolCallEmitter.ts`, `ToolCallEmitter.resolveToolProvenance`, `tool_call.provenance`, `serverId` | [`09`](./09-event-schema.md), [`10`](./10-event-bus.md) |
95+
| Event resync | `state_resync_required`, `awaitingResync`, `RESYNC_PASSTHROUGH_TYPES`, `asKnownDaemonEvent`, `unrecognizedKnownEventCount` | [`09`](./09-event-schema.md), [`10`](./10-event-bus.md) |
96+
| Capabilities | `packages/cli/src/serve/capabilities.ts`, `mcp_server_restart_refused.reason`, `MCP_RESTART_REFUSED_REASONS.has` | [`11`](./11-capabilities-versioning.md) |
97+
| Auth and device flow | `packages/cli/src/serve/auth.ts`, `packages/cli/src/serve/auth/deviceFlow.ts` | [`12`](./12-auth-security.md) |
98+
| TypeScript SDK daemon client | `packages/sdk-typescript/src/daemon/{DaemonClient,DaemonSessionClient,DaemonAuthFlow,sse,events,types}.ts`, `MCP_RESTART_DEFAULT_TIMEOUT_MS` | [`13`](./13-sdk-daemon-client.md) |
99+
| Shared UI transcript layer | `DaemonUiEventType`, `DaemonSessionProvider`, `packages/webui/src/daemon/` | [`13`](./13-sdk-daemon-client.md), [`14`](./14-cli-tui-adapter.md), [`../daemon-ui/README.md`](../daemon-ui/README.md) |
100+
| Channels and IDE adapters | `packages/channels/`, `packages/vscode-ide-companion/src/services/daemonIdeConnection.ts` | [`15`](./15-channel-adapters.md), [`16`](./16-vscode-ide-adapter.md) |
101+
82102
## What is intentionally out of scope
83103

84104
- **Java / Python SDK daemon clients** - only the TypeScript SDK ships a daemon client today. Doc 13 is TypeScript-only.
@@ -88,7 +108,7 @@ Pick the path that matches your goal:
88108

89109
## Current daemon mode coverage
90110

91-
### Server core
111+
### Server core coverage
92112

93113
| Area | Current state | Primary docs |
94114
| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
@@ -144,4 +164,4 @@ Pick the path that matches your goal:
144164

145165
## Version provenance
146166

147-
This doc set reflects the daemon mode surface after `daemon_mode_b_main` was merged into `main` through [#4412](https://github.com/QwenLM/qwen-code/pull/4412). It intentionally describes the current `main` behavior instead of the earlier F-series planning snapshots.
167+
This doc set reflects the daemon mode surface currently merged into `main`, including the follow-up work from [#4412](https://github.com/QwenLM/qwen-code/pull/4412). It intentionally describes current behavior instead of earlier F-series planning snapshots.

‎docs/developers/daemon/01-architecture.md‎

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -2,7 +2,7 @@
22

33
## Overview
44

5-
A `qwen serve` process is **one daemon = one workspace**. It hosts a single Express HTTP server, owns an `acp-bridge` instance, and spawns one ACP child process (`qwen --acp`) that runs the actual agent runtime. Multiple clients (CLI TUI, IDE companion, IM channel bots, web BFFs, custom scripts) connect over HTTP + SSE and either share one ACP session (`sessionScope: 'single'`, default) or split sessions by conversation thread (`sessionScope: 'thread'`).
5+
A `qwen serve` process is **one daemon = one workspace**. It hosts a single Express HTTP server, owns an `@qwen-code/acp-bridge` instance, and spawns one ACP child process (`qwen --acp`) that runs the actual agent runtime. Multiple clients (CLI TUI, IDE companion, IM channel bots, web BFFs, custom scripts) connect over HTTP + SSE and either share one ACP session (`sessionScope: 'single'`, default) or split sessions by conversation thread (`sessionScope: 'thread'`).
66

77
Inside the ACP child, MCP servers are shared workspace-wide through `McpTransportPool` (F2): a single (server-name + config-fingerprint) tuple maps to one MCP transport, regardless of how many sessions discover it. The bridge's `MultiClientPermissionMediator` (F3) coordinates permission votes across all connected clients under one of four policies.
88

@@ -275,11 +275,15 @@ sequenceDiagram
275275
P->>E: drain + close
276276
P->>E: spawn replacement
277277
E->>SRV: reconnect
278-
P->>EB: publish mcp_server_restarted
278+
P->>EB: publish mcp_server_restarted<br/>with stable entryIndex
279+
P-->>S: single result or {entries: RestartResult[]}
279280
```
280281

281282
`releaseSession(sessionId)` uses the reverse `sessionToEntries` index to release every entry the session holds in O(refs). On daemon shutdown, `drainAll()` sets the `draining` flag (refusing new acquires) and waits for every entry to close under a configurable timeout.
282283

284+
The deep design reference for this state machine is
285+
[`../../design/f2-mcp-transport-pool.md`](../../design/f2-mcp-transport-pool.md).
286+
283287
## Workflow 5: Lifecycle — startup and graceful shutdown
284288

285289
```mermaid

0 commit comments

Comments
 (0)