Serve Runtime

Overview

packages/cli/src/serve/ is the boot layer for qwen serve. It translates CLI flags into ServeOptions, validates startup configuration, builds the Express app, wires middleware, registers routes, exposes daemon-host preflight/status providers, maintains the permission audit ring, and owns the two-phase graceful shutdown sequence. HTTP-facing work lives in this layer; ACP-facing work lives one layer below in @qwen-code/acp-bridge (see 03-acp-bridge.md).

Responsibilities

• Parse and validate ServeOptions: listen address, auth, workspace, session / connection caps, MCP budget / pool, CORS, prompt / SSE / session idle timeouts, rate limit, and related toggles.
• Canonicalize the primary workspace exactly once, and canonicalize every repeated --workspace before registering session runtimes. The primary canonical form is shared by /capabilities.workspaceCwd, the POST /session fallback, and the primary bridge.
• Reject unsafe or invalid startup configurations: non-loopback bind without token, --require-auth without token, --allow-origin '*' without token, mcpBudgetMode='enforce' without a positive mcpClientBudget, a nonexistent or non-directory --workspace, and invalid timeout or rate-limit values.
• Construct the WorkspaceFileSystem factory, permission audit publisher, DaemonStatusProvider, and acp-bridge.
• Build the Express app, wire middleware (allowOriginCors over the mutable origin allowlist -> hostAllowlist -> access log -> bearerAuth -> rate limit -> JSON parser -> telemetry -> per-route mutationGate), and mount session, workspace CRUD, file, device-flow auth, permission vote, and ACP HTTP routes. (The unconditional denyBrowserOriginCors wall remains only in the bootstrap app, run-qwen-serve.ts.)
• Bind the listening port and register signal handlers.
• Run two-phase shutdown on SIGINT/SIGTERM; force-exit on a second signal.

Architecture

Entry: runQwenServe(opts, deps) in packages/cli/src/serve/run-qwen-serve.ts. Returns a RunHandle ({ url, port, close, ... }).

App factory: createServeApp(opts, getPort, deps) in packages/cli/src/serve/server.ts. Builds the Express Application. Direct embedders and tests call it without the bootstrap wrapper.

Capability registry: SERVE_CAPABILITY_REGISTRY in packages/cli/src/serve/capabilities.ts. Each tag has a since version and optional modes. Conditional tags are omitted when their deployment or runtime predicate is false; the registry and predicate map are the source of truth. See 11-capabilities-versioning.md.

Middleware (packages/cli/src/serve/auth.ts and server.ts):

Subsystems:

ACP bridge package imports:

• Event-bus primitives are imported from @qwen-code/acp-bridge/eventBus.
• Status primitives are imported from @qwen-code/acp-bridge/status.
• serve/acp-session-bridge.ts remains as the CLI-local compatibility facade for the broader bridge surface.

Flow

Boot sequence

Before runQwenServe() starts this sequence, the CLI-only --open-with-auth mode validates loopback/Web Shell eligibility and fills ServeOptions.token with the selected configured token, or with 32 random bytes encoded as base64url when that selection is empty. Direct embedders and invocations without that default-off flag do not generate a token.

1. Resolve and trim token from opts.token or QWEN_SERVER_TOKEN; this avoids a trailing newline from cat token.txt silently breaking bearer comparison.
2. Hostname typo guard: --hostname localhost:4170 errors and suggests --port.
3. Auth preflight: non-loopback without token refuses; --require-auth without token refuses.
4. Workspace validation: absolute path, exists, directory. EACCES / EPERM are wrapped to point at the flag.
5. Canonicalize workspace: canonicalizeWorkspace(rawWorkspace) runs realpathSync.native once and feeds /capabilities, the POST /session fallback, and the bridge.
6. MCP budget validation: positive integer; enforce requires a budget.
7. MCP pool toggle inference: parent env QWEN_SERVE_NO_MCP_POOL=1 makes mcpPoolActive=false, so capabilities honestly omit mcp_workspace_pool and mcp_pool_restart.
8. CORS / timeout / rate-limit validation: --allow-origin '*' requires token; prompt, writer, channel idle, session idle, reaper, and rate-limit window values fail fast when invalid.
9. Per-handle childEnvOverrides: pass QWEN_SERVE_MCP_CLIENT_BUDGET and QWEN_SERVE_MCP_BUDGET_MODE to the ACP child through BridgeOptions.childEnvOverrides instead of mutating process.env.
10. Load settings.json once: read context.fileName, policy.permissionStrategy, and policy.consensusQuorum. Corrupt files fall back to defaults. validatePolicyConfig() checks policy.* against SERVE_CAPABILITY_REGISTRY.permission_mediation.modes; unknown strategies or non-positive consensusQuorum throw InvalidPolicyConfigError. A quorum set under a non-consensus strategy logs a stderr warning.
11. Allocate PermissionAuditRing (512 entries).
12. Build fsFactory: runQwenServe defaults to trusted: true; direct createServeApp callers default to trusted: false and warn once.
13. createHttpAcpBridge, see 03-acp-bridge.md.
14. createServeApp assembles Express.
15. Create and lifecycle-bind the HTTP(S) server before listening, then call server.listen(port, hostname) and resolve the actual getPort() for host allowlist. Conversations ownership cannot start until this listener and the remaining host startup gates are ready.
16. Register SIGINT / SIGTERM handlers for graceful shutdown through the shared app lifecycle.

Graceful shutdown

1. Seal admission and begin all drains on the first signal:
   • Dispose the device-flow registry and cancel pending flows.
   • bridge.shutdown() marks each channel isDying = true, sends graceful close to each ACP child stdin, waits KILL_HARD_DEADLINE_MS (10s) per channel, then calls channel.kill() if needed.
2. Close the listener while app and host drains run:
   • server.close() stops accepting new connections and lets in-flight requests finish.
   • SHUTDOWN_FORCE_CLOSE_MS (5s) triggers server.closeAllConnections().
   • A second 2s deadline escalates again if needed.
3. Release Conversations ownership only after positive shutdown proof from the listener, app-local work, host-owned work, Live discovery cleanup, and runtime drains. Any incomplete proof rejects shutdown instead of allowing an unsafe handoff.
4. Second signal while exiting:
   • bridge.killAllSync() + process.exit(1) to avoid orphaned children blocking daemon exit.

State and lifecycle

RunHandle exposes:

• url: resolved listen URL, after ephemeral port resolution.
• port: actual port, including 0 resolution.
• close(): programmatic shutdown for embedders and tests.

Calling createServeApp directly still returns only an Application. An embedder that needs Live/Conversations must create the actual Node server, call getServeAppLifecycle(app).bindServer(server) before its first listen(), and await lifecycle.close() during shutdown. Without binding, ordinary routes remain available but Live/Conversations fail closed. Calling raw server.close() triggers event-driven cleanup, but the embedder must still await lifecycle.close() to observe drain or ownership-release failures.

Dependencies

Configuration

See 17-configuration.md for the merged reference.

Caveats and known limits

• Direct createServeApp without deps.fsFactory or deps.bridge defaults to trusted: false; agent-side ACP writeTextFile rejects as untrusted_workspace. The warning is printed once.
• The runtime app runs allowOriginCors over the mutable allowlist; unmatched Origin values get the 403 deny envelope (the unconditional denyBrowserOriginCors wall survives only in the bootstrap app). The loopback Web Shell works because another middleware strips matching loopback same-origin values first — non-loopback binds require --allow-origin for the shell’s XHRs.
• Body-parser ordering: routes using mutate({ strict: true }) return 401 only after express.json(). The worst case is --max-connections × express.json({limit: '10mb'}), up to about 2.5 GB of transient memory on a saturated loopback listener; this tradeoff is intentional.
• Multiple daemons in one process must use per-handle childEnvOverrides; mutating process.env races because defaultSpawnChannelFactory snapshots env at spawn time.

References

• packages/cli/src/serve/run-qwen-serve.ts (bootstrap, boot validation, graceful shutdown)
• packages/cli/src/serve/server.ts (createServeApp(), middleware and route assembly)
• packages/cli/src/serve/auth.ts (CORS, Host allowlist, bearer auth, mutation gate)
• packages/cli/src/serve/rate-limit.ts (per-tier HTTP rate limit)
• packages/cli/src/serve/capabilities.ts (capability registry and conditional advertisement)
• packages/cli/src/serve/types.ts (ServeOptions, CapabilitiesEnvelope)
• packages/cli/src/serve/daemon-status-provider.ts
• packages/cli/src/serve/permission-audit.ts
• Issues: #3803 , #4175