QwenLM · wenshao · Aug 13, 2026 · Aug 10, 2026 · Aug 10, 2026 · Aug 10, 2026
diff --git a/docs/design/web-shell-file-upload.md b/docs/design/web-shell-file-upload.md
diff --git a/docs/developers/daemon/07-workspace-filesystem.md b/docs/developers/daemon/07-workspace-filesystem.md
@@ -40,7 +40,7 @@ That text-read capability slice covers direct `read_file` plus the shared pre-re
 | File                       | Purpose                                                                                                                                                                                                                                               |
 | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `paths.ts`                 | `canonicalizeWorkspace`, `resolveWithinWorkspace`, `hasSuspiciousPathPattern`, branded `ResolvedPath`, `Intent` union (`read \| write \| list \| stat \| glob`).                                                                                      |
-| `policy.ts`                | `MAX_READ_BYTES`, `MAX_TEXT_SCAN_BYTES`, `MAX_WRITE_BYTES`, `BINARY_PROBE_BYTES`, `assertTrustedForIntent`, `detectBinary`, `enforceReadBytesSize`, `enforceReadSize`, `enforceWriteSize`, `shouldIgnore`.                                            |
+| `policy.ts`                | `MAX_READ_BYTES`, `MAX_TEXT_SCAN_BYTES`, `MAX_WRITE_BYTES`, `MAX_UPLOAD_BYTES`, `BINARY_PROBE_BYTES`, `assertTrustedForIntent`, `detectBinary`, `enforceReadBytesSize`, `enforceReadSize`, `enforceWriteSize`, `shouldIgnore`.                        |
 | `audit.ts`                 | `FS_ACCESS_EVENT_TYPE`, `FS_DENIED_EVENT_TYPE`, `createAuditPublisher`, audit payload types.                                                                                                                                                          |
 | `errors.ts`                | `FsError` class, `isFsError`, `FsErrorKind` union (14 kinds), `FsErrorStatus` union (`400 / 403 / 404 / 409 / 413 / 422 / 500 / 503`).                                                                                                                |
 | `workspace-file-system.ts` | `createWorkspaceFileSystemFactory`, `WorkspaceFileSystem` (the orchestrator that reads/writes/lists), `WriteMode`, `ContentHash`, `FsEntry`, `FsStat`, `ListOptions`, `GlobOptions`, `ReadTextOptions`, `ReadBytesOptions`, `WriteTextAtomicOptions`. |
@@ -235,15 +235,16 @@ flowchart LR
 
 ## Configuration
 
-| Source                                            | Knob                                                                  | Effect                                                                                                            |
-| ------------------------------------------------- | --------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
-| `WorkspaceFileSystemFactoryDeps.trusted: boolean` | Constructor input                                                     | Whether writes are allowed; defaults to `true` from `runQwenServe`, `false` from `createServeApp` (with warning). |
-| Constant                                          | `MAX_READ_BYTES = 256 KiB`                                            | Full-snapshot and returned-text cap; larger text requires an explicit window argument.                            |
-| Constant                                          | `MAX_TEXT_SCAN_BYTES = 8 MiB`                                         | Bytes a large-text read may scan to locate a line offset; past it, `file_too_large`.                              |
-| Constant                                          | `MAX_WRITE_BYTES = 5 MiB`                                             | Write cap; sized below `express.json({ limit: '10mb' })`.                                                         |
-| Constant                                          | `BINARY_PROBE_BYTES = 4096`                                           | Sample size for content-based binary detection.                                                                   |
-| Capability tags                                   | `workspace_file_read`, `workspace_file_bytes`, `workspace_file_write` | See [`11-capabilities-versioning.md`](./11-capabilities-versioning.md).                                           |
-| Workspace files                                   | `.gitignore`, `.qwenignore`                                           | Ignored paths surface as `ignored: true` from `shouldIgnore`.                                                     |
+| Source                                            | Knob                                                                                           | Effect                                                                                                            |
+| ------------------------------------------------- | ---------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
+| `WorkspaceFileSystemFactoryDeps.trusted: boolean` | Constructor input                                                                              | Whether writes are allowed; defaults to `true` from `runQwenServe`, `false` from `createServeApp` (with warning). |
+| Constant                                          | `MAX_READ_BYTES = 256 KiB`                                                                     | Full-snapshot and returned-text cap; larger text requires an explicit window argument.                            |
+| Constant                                          | `MAX_TEXT_SCAN_BYTES = 8 MiB`                                                                  | Bytes a large-text read may scan to locate a line offset; past it, `file_too_large`.                              |
+| Constant                                          | `MAX_WRITE_BYTES = 5 MiB`                                                                      | Write cap; sized below `express.json({ limit: '10mb' })`.                                                         |
+| Constant                                          | `MAX_UPLOAD_BYTES = 50 MiB`                                                                    | Binary upload cap for `POST /file/upload`; uploads never overwrite and auto-number occupied names.                |
+| Constant                                          | `BINARY_PROBE_BYTES = 4096`                                                                    | Sample size for content-based binary detection.                                                                   |
+| Capability tags                                   | `workspace_file_read`, `workspace_file_bytes`, `workspace_file_write`, `workspace_file_upload` | See [`11-capabilities-versioning.md`](./11-capabilities-versioning.md).                                           |
+| Workspace files                                   | `.gitignore`, `.qwenignore`                                                                    | Ignored paths surface as `ignored: true` from `shouldIgnore`.                                                     |
 
 ## Caveats & Known Limits
 

diff --git a/docs/developers/daemon/11-capabilities-versioning.md b/docs/developers/daemon/11-capabilities-versioning.md
@@ -122,7 +122,7 @@ Extension management: `extension_management_v2` adds the global `/extensions/*`
 
 Workspace-qualified session reads: `workspace_persisted_transcript`, `workspace_session_export`, `workspace_archived_session_export`. The active and archived export tags are independent from each other and from `session_export` and `workspace_qualified_rest_core`, so clients must pre-flight the exact storage state they intend to export. Persisted transcript paging permits an untrusted secondary under its bounded read policy; both full export paths remain trusted-only.
 
-Workspace mutation (Wave 4+): `workspace_memory`, `workspace_agents`, `workspace_agent_generate`, `workspace_acp_preheat`, `workspace_tool_toggle`, **`workspace_settings`** (conditional), `workspace_permissions`, `workspace_init`, `workspace_github_setup`, `workspace_trust`, `workspace_mcp_restart`, `workspace_mcp_manage`, `workspace_file_read`, `workspace_file_bytes`, `workspace_file_read_cursor`, `workspace_file_write`, **`workspace_reload`** (conditional).
+Workspace mutation (Wave 4+): `workspace_memory`, `workspace_agents`, `workspace_agent_generate`, `workspace_acp_preheat`, `workspace_tool_toggle`, **`workspace_settings`** (conditional), `workspace_permissions`, `workspace_init`, `workspace_github_setup`, `workspace_trust`, `workspace_mcp_restart`, `workspace_mcp_manage`, `workspace_file_read`, `workspace_file_bytes`, `workspace_file_read_cursor`, `workspace_file_write`, `workspace_file_upload`, **`workspace_reload`** (conditional).
 
 MCP guardrails: **`mcp_guardrails`** (`modes: ['warn', 'enforce']`), `mcp_guardrail_events`, `mcp_server_runtime_mutation`, **`mcp_workspace_pool`** (conditional), **`mcp_pool_restart`** (conditional).
 

diff --git a/docs/developers/qwen-serve-protocol.md b/docs/developers/qwen-serve-protocol.md
@@ -195,6 +195,7 @@ registry. Clients **must** gate UI off `features`, not off `mode` (per design
  'workspace_mcp_manage', 'mcp_guardrail_events',
  'mcp_server_runtime_mutation',
  'workspace_file_read', 'workspace_file_bytes', 'workspace_file_write',
+ 'workspace_file_upload',
  'session_approval_mode_control', 'workspace_tool_toggle', 'workspace_skill_toggle',
  'workspace_skill_batch_toggle',
  'workspace_settings', 'workspace_init', 'workspace_mcp_restart',
@@ -277,8 +278,13 @@ the hash-aware text mutation routes (`POST /file/write`, `POST /file/edit`).
 The write tag means the route contract exists; it does not mean the current
 deployment is open for anonymous mutation. Write/edit are strict mutation
 routes and require a configured bearer token even on loopback.
+`workspace_file_upload` covers `POST /file/upload`, the binary ingress route:
+an `application/octet-stream` body capped at `MAX_UPLOAD_BYTES` (50 MiB) is
+written into the workspace without ever overwriting — an occupied name is
+auto-numbered (`name (1).ext`, `name (2).ext`, ...). It is also a strict
+mutation route.
 
-When `workspace_qualified_rest_core` is advertised, the same file surface is also available at `/workspaces/:workspace/file`, `/workspaces/:workspace/file/bytes`, `/workspaces/:workspace/stat`, `/workspaces/:workspace/list`, `/workspaces/:workspace/glob`, `/workspaces/:workspace/file/write`, and `/workspaces/:workspace/file/edit`.
+When `workspace_qualified_rest_core` is advertised, the same file surface is also available at `/workspaces/:workspace/file`, `/workspaces/:workspace/file/bytes`, `/workspaces/:workspace/stat`, `/workspaces/:workspace/list`, `/workspaces/:workspace/glob`, `/workspaces/:workspace/file/write`, `/workspaces/:workspace/file/edit`, and `/workspaces/:workspace/file/upload`.
 
 The same tag also exposes workspace-qualified project-agent CRUD at `/workspaces/:workspace/agents` and `/workspaces/:workspace/agents/:agentType`. These plural routes only read or mutate project-level agents for the selected workspace; `global` and `user` scope requests return `400 { code: "global_scope_not_supported_for_workspace_route" }`. Workspace-less `/workspace/agents` routes retain their existing primary-workspace behavior and remain the only REST surface for user-level agent scope.
 

diff --git a/integration-tests/cli/qwen-serve-routes.test.ts b/integration-tests/cli/qwen-serve-routes.test.ts
@@ -364,6 +364,7 @@ describe('qwen serve — capabilities envelope', () => {
       'workspace_file_bytes',
       'workspace_file_read_cursor',
       'workspace_file_write',
+      'workspace_file_upload',
       'session_approval_mode_control',
       'workspace_tool_toggle',
       'workspace_skill_toggle',

diff --git a/packages/cli/src/serve/bridge-file-system-adapter.test.ts b/packages/cli/src/serve/bridge-file-system-adapter.test.ts
@@ -979,6 +979,7 @@ describe('createBridgeFileSystemAdapter', () => {
             })),
             edit: vi.fn(),
             editAtomic: vi.fn(),
+            writeBytesAtomic: vi.fn(),
           };
         },
       };
@@ -1030,6 +1031,7 @@ describe('createBridgeFileSystemAdapter', () => {
             })),
             edit: vi.fn(),
             editAtomic: vi.fn(),
+            writeBytesAtomic: vi.fn(),
           };
         },
       };

diff --git a/packages/cli/src/serve/capabilities.ts b/packages/cli/src/serve/capabilities.ts
@@ -162,6 +162,12 @@ export const SERVE_CAPABILITY_REGISTRY = {
   // gate. Clients should still pre-flight `require_auth` separately for
   // deployment posture; this tag only means the route contract exists.
   workspace_file_write: { since: 'v1' },
+  // Daemon hosts binary file upload (`POST /file/upload`) behind the strict
+  // mutation gate. Uploads never overwrite; occupied names auto-number. New
+  // route contract = new tag (same split as `workspace_file_bytes` from
+  // `workspace_file_read`). The advertised upload byte cap is surfaced via
+  // `limits.maxWorkspaceFileUploadBytes`.
+  workspace_file_upload: { since: 'v1' },
   // Daemon hosts the session-level approval-mode
   // control route `POST /session/:id/approval-mode` (gated by the
   // mutation gate, strict). The route accepts `{mode, persist?}` —
@@ -345,8 +351,8 @@ export const SERVE_CAPABILITY_REGISTRY = {
   scratch_workspace_registration: { since: 'v1' },
   workspace_runtime_removal: { since: 'v1' },
   // Workspace-qualified core REST routes under `/workspaces/:workspace/...`.
-  // Covers core file/status/permissions/trust/lifecycle/MCP/tool, memory,
-  // workspace agent CRUD, and persisted session organization surfaces.
+  // Covers core file read/write/upload, status/permissions/trust/lifecycle/MCP/tool,
+  // memory, workspace agent CRUD, and persisted session organization surfaces.
   // Workspace-qualified settings also require the existing
   // `workspace_settings` tag because that surface depends on settings
   // persistence. ACP/WebSocket and auth stay outside this core tag;

diff --git a/packages/cli/src/serve/fs/index.ts b/packages/cli/src/serve/fs/index.ts
@@ -21,6 +21,7 @@ export {
 export {
   MAX_READ_BYTES,
   MAX_WRITE_BYTES,
+  MAX_UPLOAD_BYTES,
   BINARY_PROBE_BYTES,
   assertTrustedForIntent,
   detectBinary,

diff --git a/packages/cli/src/serve/fs/policy.ts b/packages/cli/src/serve/fs/policy.ts
@@ -60,6 +60,17 @@ export const MAX_TEXT_SCAN_BYTES = 8 * 1024 * 1024;
  */
 export const MAX_WRITE_BYTES = 5 * 1024 * 1024;
 
+/**
+ * Maximum bytes accepted by the binary upload write path
+ * (`writeBytesAtomic`). This is a distinct binary-ingress policy, NOT an
+ * increase to the agent text-write limit: text writes keep
+ * `MAX_WRITE_BYTES`. Sized for screenshots, data files, and configs that a
+ * user drags into the Web Shell. The daemon's upload route and the fs
+ * boundary share this single constant so a request buffered under the parser
+ * cap is never rejected later under a different limit.
+ */
+export const MAX_UPLOAD_BYTES = 50 * 1024 * 1024;
+
 /**
  * Sample size used for content-based binary detection. Aligned with
  * `isBinaryFile` from `packages/core/src/utils/fileUtils.ts:414` so