diff --git a/docs/developers/daemon/02-serve-runtime.md b/docs/developers/daemon/02-serve-runtime.md index ddf703ba892..7fbee49bc1e 100644 --- a/docs/developers/daemon/02-serve-runtime.md +++ b/docs/developers/daemon/02-serve-runtime.md @@ -113,25 +113,25 @@ Calling `createServeApp` directly returns only an `Application`; the embedder ow ## Configuration -| Source | Key | Effect | -| --------------- | ----------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | -| Env | `QWEN_SERVER_TOKEN` | Bearer token after trim. | -| Env | `QWEN_SERVE_NO_MCP_POOL=1` | Forces `mcpPoolActive=false`. | -| ACP child env | `QWEN_SERVE_MCP_CLIENT_BUDGET` / `QWEN_SERVE_MCP_BUDGET_MODE` | Generated from `--mcp-client-budget` / `--mcp-budget-mode` and forwarded through `childEnvOverrides`. | -| Env | `QWEN_SERVE_PROMPT_DEADLINE_MS` / `QWEN_SERVE_WRITER_IDLE_TIMEOUT_MS` | Default prompt / SSE idle timeouts. | -| Env | `QWEN_SERVE_RATE_LIMIT*` | Rate-limit switch, prompt / mutation / read caps, and window default. | -| Env | `QWEN_SERVE_DEBUG=1` | Verbose stderr logs. See [`19-observability.md`](./19-observability.md). | -| Flags | `--hostname`, `--port` | Listen binding. | -| Flags | `--token`, `--require-auth`, `--enable-session-shell` | Bearer token, loopback auth hardening, and explicit shell execution switch. | -| Flag | `--workspace` | Overrides `process.cwd()`; repeat to register additional isolated workspace runtimes. | -| Flags | `--max-sessions`, `--max-pending-prompts-per-session`, `--max-connections`, `--event-ring-size` | Bridge / Express caps. | -| Flags | `--mcp-client-budget=N`, `--mcp-budget-mode={off,warn,enforce}` | Forwarded to the ACP child. | -| Flags | `--allow-origin`, `--allow-private-auth-base-url` | Browser CORS allowlist and localhost/private auth provider installation switch. | -| Flags | `--prompt-deadline-ms`, `--writer-idle-timeout-ms`, `--channel-idle-timeout-ms` | Prompt, SSE writer, and ACP child idle lifecycle control. | -| Flags | `--session-reap-interval-ms`, `--session-idle-timeout-ms` | Disconnected-session reaping control. | -| Flags | `--rate-limit*` | Per-tier HTTP rate limit. | -| `settings.json` | `policy.permissionStrategy`, `policy.consensusQuorum` | `MultiClientPermissionMediator` policy and quorum. | -| `settings.json` | `context.fileName` | `getCurrentGeminiMdFilename` override for the bridge. | +| Source | Key | Effect | +| --------------- | ---------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | +| Env | `QWEN_SERVER_TOKEN` | Bearer token after trim. | +| Env | `QWEN_SERVE_NO_MCP_POOL=1` | Forces `mcpPoolActive=false`. | +| ACP child env | `QWEN_SERVE_MCP_CLIENT_BUDGET` / `QWEN_SERVE_MCP_BUDGET_MODE` | Generated from `--mcp-client-budget` / `--mcp-budget-mode` and forwarded through `childEnvOverrides`. | +| Env | `QWEN_SERVE_PROMPT_DEADLINE_MS` / `QWEN_SERVE_WRITER_IDLE_TIMEOUT_MS` | Default prompt / SSE idle timeouts. | +| Env | `QWEN_SERVE_RATE_LIMIT*` | Rate-limit switch, prompt / mutation / read caps, and window default. | +| Env | `QWEN_SERVE_DEBUG=1` | Verbose stderr logs. See [`19-observability.md`](./19-observability.md). | +| Flags | `--hostname`, `--port` | Listen binding. | +| Flags | `--token`, `--require-auth`, `--enable-session-shell` | Bearer token, loopback auth hardening, and explicit shell execution switch. | +| Flag | `--workspace` | Overrides `process.cwd()`; repeat to register additional isolated workspace runtimes. | +| Flags | `--max-sessions`, `--max-pending-prompts-per-session`, `--max-connections`, `--event-ring-size` | Bridge / Express caps. | +| Flags | `--mcp-client-budget=N`, `--mcp-budget-mode={off,warn,enforce}` | Forwarded to the ACP child. | +| Flags | `--allow-origin`, `--allow-private-auth-base-url` | Browser CORS allowlist and localhost/private auth provider installation switch. | +| Flags | `--prompt-deadline-ms`, `--writer-idle-timeout-ms`, `--channel-idle-timeout-ms`, `--initialize-timeout-ms` | Prompt, SSE writer, ACP child idle lifecycle, and ACP child request timeout control. | +| Flags | `--session-reap-interval-ms`, `--session-idle-timeout-ms` | Disconnected-session reaping control. | +| Flags | `--rate-limit*` | Per-tier HTTP rate limit. | +| `settings.json` | `policy.permissionStrategy`, `policy.consensusQuorum` | `MultiClientPermissionMediator` policy and quorum. | +| `settings.json` | `context.fileName` | `getCurrentGeminiMdFilename` override for the bridge. | See [`17-configuration.md`](./17-configuration.md) for the merged reference. diff --git a/docs/developers/daemon/17-configuration.md b/docs/developers/daemon/17-configuration.md index 5d4e33d3d14..9917dc85cb1 100644 --- a/docs/developers/daemon/17-configuration.md +++ b/docs/developers/daemon/17-configuration.md @@ -28,6 +28,7 @@ This page collects every setting that affects the `qwen serve` daemon and its ad | `--prompt-deadline-ms ` | positive integer | unset | Server-side prompt wallclock limit in ms. Timeout aborts and returns an error. | | `--writer-idle-timeout-ms ` | positive integer | unset | Per-SSE-connection idle timeout in ms. The daemon closes the SSE connection when no event is sent for this duration. | | `--channel-idle-timeout-ms ` | non-negative integer | `0` | How long to keep the ACP child alive after the last session closes. `0` means reclaim immediately. | +| `--initialize-timeout-ms ` | positive integer | `10000` | ACP child request timeout, including the initialize handshake (ms). | | `--session-reap-interval-ms ` | non-negative integer | `60000` | Session reaper scan interval; `0` disables it. | | `--session-idle-timeout-ms ` | non-negative integer | `1800000` | Disconnected-session idle reaping time; `0` disables it. | | `--rate-limit` / `--no-rate-limit` | boolean | env / off | Enables per-tier HTTP rate limiting for prompt, mutation, and read routes. | @@ -101,6 +102,7 @@ The daemon constructs each workspace runtime from that workspace's merged settin | `promptDeadlineMs` | Prompt wallclock limit. | | `writerIdleTimeoutMs` | SSE writer idle timeout. | | `channelIdleTimeoutMs` | How long to keep the ACP child warm after the last session closes. | +| `initializeTimeoutMs` | ACP child request timeout, including the initialize handshake. | | `sessionReapIntervalMs` | Session reaper scan interval. | | `sessionIdleTimeoutMs` | Disconnected-session idle reaping time. | | `rateLimit*` | Per-tier HTTP rate limit switch, thresholds, and window. | diff --git a/docs/developers/daemon/20-quickstart-operations.md b/docs/developers/daemon/20-quickstart-operations.md index 18546d22be6..0e6008b298d 100644 --- a/docs/developers/daemon/20-quickstart-operations.md +++ b/docs/developers/daemon/20-quickstart-operations.md @@ -94,6 +94,7 @@ The CLI is defined in **`packages/cli/src/commands/serve.ts`**: | `--prompt-deadline-ms ` | number | none | - | Server-side prompt wallclock limit in ms; timeout aborts the prompt. | | `--writer-idle-timeout-ms ` | number | none | - | Per-SSE-connection idle timeout in ms. | | `--channel-idle-timeout-ms ` | number | `0` | - | Keeps the ACP child alive after the last session closes. `0` means reclaim immediately. | +| `--initialize-timeout-ms ` | number | `10000` | - | ACP child request timeout, including the initialize handshake (ms). | | `--session-reap-interval-ms ` | number | `60000` | - | Session reaper scan interval. `0` disables it. | | `--session-idle-timeout-ms ` | number | `1800000` | - | Disconnected-session idle timeout. `0` disables it. | | `--rate-limit` / `--no-rate-limit` | boolean | env / off | - | Enables or disables per-tier HTTP rate limiting. | @@ -156,6 +157,7 @@ Settings I/O failure, such as malformed JSON, falls back to defaults. `InvalidPo | `--event-ring-size > 1_000_000` | Thrown during bridge construction | | `--allow-origin '*'` without token | `Refusing to start with --allow-origin '*' but no bearer token configured` | | `--prompt-deadline-ms` / `--writer-idle-timeout-ms` is not a positive integer | `Must be a positive integer` | +| `--initialize-timeout-ms` is not a positive integer or exceeds `2^31-1` | `Must be a positive integer` / `Exceeds maximum JS timer delay` | | Unknown `policy.permissionStrategy` or non-positive `policy.consensusQuorum` | `InvalidPolicyConfigError` | ## 7. Curl verification checklist diff --git a/docs/users/qwen-serve.md b/docs/users/qwen-serve.md index 5edd1c8c3c3..55c931727c4 100644 --- a/docs/users/qwen-serve.md +++ b/docs/users/qwen-serve.md @@ -397,6 +397,7 @@ Notes: | `--mcp-client-budget ` | — | Positive integer cap on live MCP clients. When `mcp_workspace_pool` is advertised, the cap and transports are shared per workspace runtime; when the tag is absent, the legacy per-session manager enforces it. Combine with `--mcp-budget-mode`. When unset, no accounting-driven enforcement (but `GET /workspace/mcp` still reports `clientCount`). Distinct from claude-code's `MCP_SERVER_CONNECTION_BATCH_SIZE`, which gates startup concurrency rather than total live clients. Pre-flight `caps.features.mcp_guardrails` and `caps.features.mcp_workspace_pool`. | | `--mcp-budget-mode ` | `warn` / `off` | How `--mcp-client-budget` is enforced. `warn` (default when budget set): no refusal, snapshot's `budgets[0].status` flips to `warning` at ≥75% of budget. `enforce`: connects past the cap are refused, per-server cell shows `disabledReason: 'budget'`, deterministic by `mcpServers` declaration order. `off` (default when budget unset): pure observability. Boot rejects `enforce` without a budget. | | `--http-bridge` | `true` | Stage 1 mode: production attempts to preheat one primary `qwen --acp` child for compatibility and retries on first use after failure, while each trusted secondary can start one child on demand. Sessions targeting a runtime multiplex onto its child via ACP `newSession()`; untrusted secondaries cannot start ACP. Stage 2 native in-process becomes available later. | +| `--initialize-timeout-ms ` | `10000` | ACP child request timeout, including the `initialize` handshake (ms). Must be a positive integer up to `2147483647`. Values above the JS timer ceiling (`2^31-1`) are rejected at boot because Node silently compresses them to 1 ms. Cold-container deployments that need extra headroom for child startup can raise this; the same value governs `newSession`, workspace-status polls, and other ACP ext-method deadlines. | | `--allow-origin ` | — | T2.4 ([#4514](https://github.com/QwenLM/qwen-code/issues/4514)). Cross-origin allowlist for browser webui clients. Repeatable. Each value is `*` (any origin — boot refuses if no bearer token is configured; `--require-auth` on loopback is recommended so `/health` and `/demo` are also bearer-gated, since both are pre-auth on loopback by default) or a canonical URL origin (`://[:]`, no trailing slash / path / userinfo / query). **Subdomain wildcards (`https://*.example.com`) are intentionally unsupported** — list each subdomain explicitly, or use `*` with a configured token (and `--require-auth` for full hardening). Matched origins receive CORS response headers (`Access-Control-Allow-Origin`, `Vary: Origin`, methods, headers, max-age, and exposed `Retry-After`); unmatched origins still get a 403 with the same envelope as today's wall. `Origin: null` (sandboxed iframes, file:// docs) is always rejected, even under `*`. Pre-flight via `caps.features.allow_origin`. Loopback self-origin hits are unaffected. | | `--web` / `--no-web` | `true` | Serve the built Web Shell SPA at the daemon root (`GET /`, `/assets/*`, and SPA deep-link fallback). The static shell is registered **before** the bearer-auth gate — a browser can't attach a token to a `