docs/design/web-shell-file-upload.md
The Web Shell composer allows referencing workspace files via @path/to/file, but the file must already exist in the workspace. Users frequently need to bring local files (screenshots, data files, configs) into the workspace to reference them in prompts. The current workflow requires manually saving files via the CLI or another tool before the Web Shell can see them.
This feature adds direct file upload from the browser to the workspace:
@filename so the existing @ resolver can consume supported files.expectedHash-gated writes (CAS): the browser cannot cheaply hash a large file before upload. Can be added later if a client needs it._qwen/file/upload): REST-only for v1, see below.writeBytesAtomicWorkspaceFileSystem (packages/cli/src/serve/fs/workspace-file-system.ts) has byte reads (readBytes / readBytesWindow) but only text writes (writeTextAtomic / writeTextOverwrite / writeText / edit*), all of which apply encoding/BOM/line-ending normalization that would corrupt binary content. This feature therefore adds a symmetric binary write method to the interface first:
writeBytesAtomic(
p: ResolvedPath,
data: Buffer,
): Promise<{ sizeBytes: number; hash: ContentHash }>;
The method is a single-purpose no-clobber create primitive; it cannot modify or replace existing file content. Posture mirrors the existing writeTextAtomic({ mode: 'create' }) publication semantics:
MAX_UPLOAD_BYTES = 50 * 1024 * 1024 to fs/policy.ts and export it through fs/index.ts. writeBytesAtomic enforces enforceWriteSize(data.length, MAX_UPLOAD_BYTES); existing text writes continue using the default MAX_WRITE_BYTES = 5 * 1024 * 1024. The upload limit is a distinct binary-ingress policy, not an increase to agent text-write limits.writeBytesAtomic enforces the trust boundary itself with assertTrustedForIntent(..., 'write'); HTTP admission is only an early-rejection optimization. It checks the generation guard at entry, again inside the path lock before temp-file publication, and at the existing final publish checkpoint so a draining/removed runtime cannot commit after admission.FsError('file_already_exists') (409), including an external writer racing the final no-clobber publication.symlink_escape), consistent with the text writes; boundary resolution goes through the existing resolve(path, 'write').0o600 (not umask default).Buffer; do not copy a second binary-specific atomic-write implementation. The byte path must not pass through atomicWriteTextResolvedFile, whose internal enforceWriteSize(buf.length) intentionally applies the 5 MiB text default. Each public write path validates its final byte buffer with its own policy before calling the shared publisher.POST /file/upload endpointExtend routes/workspace-file-write.ts, which already owns the workspace file mutation routes and its private getFsFactory / parseClientId / resolveOriginatorClientId machinery. Keeping upload registration there avoids cloning the trust, identity, and workspace-resolution plumbing into a second module.
Routes (both behind deps.mutate({ strict: true })):
POST /file/uploadPOST /workspaces/:workspace/file/uploadRoute ownership/scope is identical to POST /file/write: workspace-scoped, resolved-runtime. The qualified variant follows the same failure semantics — unknown (including an already removed workspace), untrusted, or non-active workspace states are rejected and never fall back to the primary runtime.
Request:
Content-Type: application/octet-stream
X-Qwen-Client-Id: <clientId>
Query parameters:
path — target file path (relative to workspace root), required,
encoded by URLSearchParams (filenames are frequently non-ASCII);
the server validates Express's already-decoded req.query.path and
must not call decodeURIComponent again
Body: raw binary bytes
Middleware chain:
deps.mutate({ strict: true }) — unauthenticated mutations are rejected before any buffering.fileUploadAdmission — performs every cheap request-level check before buffering (final-name boundary checks happen in the handler's candidate loop, which runs after buffering):
isWorkspaceTrusted() dependency.resolveWorkspaceRuntimeFromParam → requireTrustedWorkspaceRuntime → setWorkspaceRouteContext. Unknown (including an already removed workspace), untrusted, or draining workspaces stop here and never fall back to the primary runtime.Content-Type: application/octet-stream; otherwise returns { errorKind: 'unsupported_media_type', error: 'File uploads require application/octet-stream', status: 415 } with status 415.path and a requested basename over MAX_UPLOAD_FILENAME_BYTES with a standard parse_error envelope.Content-Length is present and exceeds MAX_UPLOAD_BYTES, returns the upload-specific 413 immediately. The raw parser remains authoritative for chunked bodies and clients that omit or understate the header.parseClientId and resolveOriginatorClientId against the selected runtime's bridge. An invalid client id is rejected before buffering.path into directory + basename, resolves the directory with fs.resolve(dir, 'write'), and verifies it is an existing directory with fs.stat. Traversal, parent-link escapes, missing/non-directory parents, and other boundary failures are therefore rejected before buffering. The requested final name itself is resolved per candidate in the handler's loop after buffering; an escaping final-component symlink surfaces as the loop's boundary error.fileUploadConcurrencyGate — admits at most MAX_CONCURRENT_UPLOADS = 4 requests across the legacy and qualified routes. createServeApp creates one shared gate and injects it into both route registrations. A saturated gate returns 429 with Retry-After: 1 before body parsing. Before the upload handler starts, response finish or close releases the slot; after the handler starts, the slot remains held until the handler settles so disconnecting clients cannot bypass the memory bound.fileUploadBodyParser — wraps express.raw({ type: 'application/octet-stream', limit: MAX_UPLOAD_BYTES }). The numeric fs policy constant is the single source of truth for both parser and write limits. Its callback intercepts body-parser status === 413 and returns the upload-specific file_too_large envelope below; other errors call next(err). This prevents the global JSON parser error handler from incorrectly reporting the existing 10 MB JSON limit.Buffer.alloc(0), takes the admitted request-scoped fs instance, then executes the name-allocation flow below.Path traversal and symlink escape are blocked by the same fs.resolve boundary guards as /file/write.
Name allocation: WorkspaceFileSystem only exposes no-clobber byte creation. The route owns the upload-specific naming policy:
file_already_exists. Insert (N) before the final extension: report.pdf → report (1).pdf → report (2).pdf; no extension: README → README (1); a dotfile with no further extension stays whole: .env → .env (1). The loop makes 1000 attempts total — the requested name plus (1) through (999) — then returns file_already_exists if every name is occupied.fs.resolve(candidate, 'write'). If resolution produces a different path, that candidate is occupied by an in-workspace symlink and the route continues numbering without calling writeBytesAtomic. The no-clobber fs primitive makes concurrent uploads and external writers safe without relying on a route-level lock: if the name is already occupied by any entry, the route tries the next candidate. Boundary and I/O errors stop the loop.MAX_UPLOAD_FILENAME_BYTES = 255 is the v1 upload filename policy cap, chosen to avoid ENAMETOOLONG on common POSIX filesystems; it is not claimed as a complete cross-platform filename validator. When a suffix would exceed the cap, trim only the stem on a Unicode code-point boundary until stem + suffix + extension fits; never trim the extension or split a UTF-8 sequence. If the suffix and extension alone cannot fit, return parse_error. Platform-specific restrictions such as Windows reserved names remain fs errors from resolve/publication.Response: uploads always create, so the response is always 201. path is the final server-confirmed path — a numbered candidate when the requested name was occupied — and clients must use it (not the requested path) for the @ reference.
{
"kind": "file_upload",
"path": "relative/path/to/report (1).pdf",
"sizeBytes": 12345,
"hash": "sha256:<64 lowercase hex>"
}
The response does not include a redundant renamed flag. A client that needs to show an auto-numbering hint compares the requested path with the returned path.
Filesystem and upload-specific validation errors use { errorKind, error, status, ...details }: file_already_exists 409 when the numbered-candidate cap is exhausted, parse_error 400, unsupported_media_type 415, path_outside_workspace / symlink_escape 400, untrusted_workspace / permission_denied 403, and upload-specific 413:
{
"errorKind": "file_too_large",
"error": "Request body too large (max 50 MiB)",
"status": 413,
"maxBytes": 52428800
}
The admission check and route-level raw-parser wrapper both emit this response because parser failures occur before the handler and cannot pass through sendFsError. Authentication, client-id, and workspace-runtime failures keep their existing daemon envelopes; the SDK's existing DaemonHttpError already preserves their status and parsed response body. This route does not duplicate shared validation helpers merely to rename code to errorKind.
When all upload slots are occupied, the concurrency gate returns:
{
"errorKind": "upload_busy",
"error": "Too many uploads in progress",
"status": 429,
"retryAfterSeconds": 1
}
Limits: MAX_UPLOAD_BYTES is the shared hardcoded 50 MiB policy constant; no separate string-valued route constant or env/flag configurability without a driver. It is sized for screenshots, data files, and configs. Keeping the parser and fs boundary on the same numeric constant prevents requests from being fully buffered under one limit and rejected later under another. Because express.raw holds the complete body in memory, relying on the listener's default 256-connection cap would permit roughly 12.5 GiB of upload buffers. The shared four-slot gate instead bounds upload-body buffering to roughly 200 MiB plus normal framework overhead. Make the limit configurable or replace buffering with a streaming fs primitive only if production measurements require a different throughput/memory tradeoff.
Capability and limit discovery: add workspace_file_upload: { since: 'v1' } in capabilities.ts — convention is new route contract = new tag (same split as workspace_file_bytes from workspace_file_read). Also add optional maxWorkspaceFileUploadBytes to DaemonCapabilitiesLimits and advertise MAX_UPLOAD_BYTES when the feature is present. Web Shell checks this value before sending and falls back to 50 MiB only if a capability-compatible daemon omits it. Older daemons without the feature tag hide the entry points and return 404 if called directly. A secondary-workspace target additionally requires workspace_qualified_rest_core; update that capability's route description to include file upload.
ACP-HTTP: out of scope for v1. /file/write also exists as _qwen/file/write on the ACP-HTTP surface, but /file/upload is REST-only: the Web Shell (the only v1 consumer) talks REST directly, and the ACP-HTTP JSON wire cannot carry raw binary. No entries in acpRouteTable.ts / dispatch.ts; a base64 _qwen/file/upload can follow if a non-browser ACP client ever needs it.
Telemetry: add the /workspace/file/upload suffix to the POST allowlist in server/telemetry.ts (normalized from /workspaces/:workspace/file/upload, next to the existing /workspace/file/write entry), otherwise latency lands in the unknown bucket.
uploadWorkspaceFile() on both client classesFollows the existing request-object signature style (writeWorkspaceFile(req, clientId?)). Qualified access goes through the existing client.workspaceById() / workspaceByCwd() selectors — no uploadWorkspaceQualifiedFile on DaemonClient.
interface DaemonWorkspaceFileUploadRequest {
path: string;
data: ArrayBuffer | Uint8Array | Blob;
signal?: AbortSignal;
/** Omitted inherits the client's default; 0 disables the timeout. */
timeoutMs?: number;
/** Browser-only: requesting progress without XMLHttpRequest is an error. */
onProgress?: (event: { loaded: number; total: number }) => void;
}
interface DaemonWorkspaceFileUploadResult {
kind: 'file_upload';
path: string;
sizeBytes: number;
hash: DaemonContentHash;
}
// DaemonClient (legacy-primary), mirrors writeWorkspaceFile
async uploadWorkspaceFile(
req: DaemonWorkspaceFileUploadRequest,
clientId?: string,
): Promise<DaemonWorkspaceFileUploadResult>;
// WorkspaceDaemonClient (workspace-qualified), mirrors its writeWorkspaceFile
async uploadWorkspaceFile(
req: DaemonWorkspaceFileUploadRequest,
clientId?: string,
): Promise<DaemonWorkspaceFileUploadResult>;
Both delegate to one shared internal raw-POST helper on DaemonClient, parameterized by URL + route name, the same pairing WorkspaceDaemonClient already uses (/file/write → POST /workspaces/:workspace/file/write). This keeps authentication headers, timeout/abort composition, response parsing, and DaemonHttpError construction in one place. Build the URL with URL.searchParams.set('path', req.path); do not pre-encode path with encodeURIComponent.
Transport is XMLHttpRequest when onProgress is provided (fetch exposes no upload progress), plain fetch otherwise. onProgress is explicitly browser-only: if XMLHttpRequest is unavailable, fail before sending rather than silently losing progress. Both paths honor signal, use the same authentication/client-id headers and failOnError response shape, and apply timeoutMs. Omission inherits the client's existing timeout; 0 explicitly disables it. The Web Shell passes timeoutMs: 0 because its per-item AbortController owns cancellation and a valid 50 MiB upload can exceed the SDK's general 30-second default.
The Web Shell is multi-workspace, so uploads must use the same target as the composer's existing file actions. Do not add a second voice-style resolver:
useComposerCore has workspace and atWorkspaceCwd, use workspace.client.workspaceByCwd(atWorkspaceCwd).uploadWorkspaceFile(...), exactly as its qualified listDirectory / globWorkspace actions do today. This includes a primary workspace addressed through the qualified route.atWorkspaceCwd uses workspace.client.uploadWorkspaceFile(...); a modern multi-workspace composer with a missing cwd is unsupported rather than silently targeting the primary workspace.workspace_file_upload; a cwd-qualified target requires both workspace_file_upload and workspace_qualified_rest_core. The selected workspace must also be present exactly once and trusted in the capabilities snapshot. Otherwise hide both upload entry points.fileUploadEnabled prop (threaded through the customization context). It is an additional gate, not a replacement for the capability: fileUploadEnabled === false force-hides both entry points even when the daemon advertises workspace_file_upload, while true/omitted still requires the capability (and the trust / qualified-route checks above). It never bypasses the capability.@ consumptionThe upload endpoint is format-agnostic workspace storage. A successful upload guarantees that the bytes were created atomically at the returned path; it does not guarantee that every model/provider can inline or interpret that file. The automatically inserted reference continues through the existing @ resolver and inherits its limits:
The Web Shell does not duplicate file sniffing or maintain a second format-support matrix. User-facing copy says the file was uploaded and referenced, not that every model can read every format; any consumption failure comes from the existing resolver. E2E verification must exercise actual prompt consumption for a supported text file and image, not only file existence and inserted composer text.
useFileUpload hookNew hook at packages/web-shell/client/hooks/useFileUpload.ts:
interface UseFileUploadOptions {
/** Structural client; both daemon client classes satisfy it. */
client: FileUploadClient | undefined;
maxBytes: number;
targetKey: string;
}
interface FileUploadItem {
id: string;
file: File;
targetPath: string; // requested relative path in the target workspace
status: 'pending' | 'uploading' | 'done' | 'error';
progress: number; // 0–1
/** Locally classified failures; the render site localizes them. */
errorCode?: 'tooLarge' | 'noDaemon' | 'tooManyFiles';
error?: string; // raw failure message (server-side errors)
resultPath?: string; // server-confirmed final path
/** Set on a `tooManyFiles` notice row: how many files were not queued. */
skippedCount?: number;
}
interface UseFileUploadReturn {
uploads: FileUploadItem[];
/** True while any item is pending or in flight; gates composer submit. */
isBusy: boolean;
uploadFiles: (
files: File[],
targetDir: string,
onUploaded?: (path: string) => void,
) => number; // returns how many files were actually queued
removeUpload: (id: string) => void; // aborts the in-flight request too
}
Occupied names are always auto-numbered; safety-boundary failures, candidate exhaustion, and I/O failures still produce an error row. uploadFiles stores onUploaded with each queued item and invokes it exactly once per successful upload with the server-confirmed final path. A batch accepts at most MAX_FILES_PER_BATCH = 100 files; the overflow is not queued and surfaces as a single tooManyFiles notice row carrying the skipped count, so unbounded drops cannot keep the strictly-sequential queue busy for hours.
resultPath !== targetPath, they additionally show a short auto-numbering hint so the user sees why the name differs from what they dropped.workspace.capabilities?.features snapshot VoiceButton uses and hide the entry points when unsupported.capabilities.limits.maxWorkspaceFileUploadBytes (50 MiB fallback) locally with a clear error; the server-side 413 remains authoritative.uploadFiles batch sequentially in selection order: one item is uploading, the rest remain pending. A failed or canceled item does not block later items. This keeps browser/daemon memory bounded and makes @ insertion order deterministic; add concurrency only if measurements justify it later.targetKey changes or the hook unmounts, abort and clear the queue. Ignore any late completion from the previous generation so an upload started for workspace A cannot insert a path into workspace B's composer.dragenter / dragover / dragleave / drop on the composer surface. A batch containing only supported images remains on the existing image-attachment path; ordinary files and mixed batches use workspace upload, so one drop is never handled by both paths.event.dataTransfer.files and call uploadFiles(files, '.', onUploaded) (target workspace root).kind: 'file' composer tag whose serialized value is @<finalPath>, escaping through the same pipeline existing file items use (escapeAtReferenceText(sanitizeInsertText(path))) — screenshot filenames with spaces and non-ASCII characters are common.In useAtMentionMenu.ts's createFileProvider, when the files provider is in directory-browse mode:
AtMentionItem with a new kind: 'upload' at the top of the list. Its label/description use the existing i18n catalog. It appears only when the entry query is empty (the same condition that shows currentDirectoryItem) so it does not pollute filtered results, participates in normal keyboard navigation, and is subject to the existing ITEM_LIMIT slice.fileDirectoryRef.current, invokes an onUploadRequest(targetDir, restoreQuery) callback wired in from the composer as a UseAtMentionMenuOptions field, and closes the menu. If upload availability vanished while the menu was open (stale item), the accept closes the menu without removing the text. The callback synchronously stores targetDir and the current upload targetKey, keeps the restoreQuery callback, then calls a mounted hidden <input type="file" multiple> so the browser treats it as part of the user gesture. This is UI behavior, not a workspace filesystem action, so it does not belong on AtMentionWorkspaceActions; the menu hook stays free of DaemonClient concerns.targetDir only if the captured targetKey is still current, then clears input.value so choosing the same file again fires a new change event. A native cancel listener (React only wires cancel on <dialog>, and the event does not bubble) invokes the stored restoreQuery so a canceled picker gives the removed mention text back.close() already replaces builtinCacheRef.current; the next open fetches a fresh directory listing.Note: uploads to git-ignored paths succeed but remain invisible in the @ listing (entries.filter((entry) => !entry.ignored)); the inserted @ reference still resolves.
Browser file
↓ (drag-drop or @ panel upload item)
useFileUpload.uploadFiles() [target workspace resolved]
↓ (XHR with progress, or fetch)
DaemonClient / WorkspaceDaemonClient.uploadWorkspaceFile()
↓
POST /file/upload?path=... (raw octet-stream body)
↓ mutate gate → workspace/trust/client/metadata admission → concurrency gate → raw parser
route candidate loop
↓ fs.resolve(candidate, 'write') → fs.writeBytesAtomic (no-clobber create)
↓
201 with confirmed (possibly renumbered) path
↓
addTags([{ kind: 'file', serialized: '@<finalPath>' }], { placement: 'inline' })
fs.resolve boundary guards from the workspace-file-write.ts machinery.application/octet-stream uploads are valid and produce the SHA-256 of an empty buffer.file_too_large envelope; handler/fs failures use sendFsError; path escape or an escaping/racing symlink → 400; untrusted workspace → 403.MAX_UPLOAD_BYTES × MAX_CONCURRENT_UPLOADS (about 200 MiB with the v1 constants); auth, workspace resolution, trust, Content-Type, Content-Length, metadata, client identity, and initial path-boundary resolution all run before the concurrency gate and body buffering.MAX_UPLOAD_BYTES, generalize the existing atomic publication internals around an already validated Buffer, then add the trust- and generation-gated no-clobber writeBytesAtomic create primitive with colocated tests. Preserve the existing 5 MiB text-write policy.routes/workspace-file-write.ts with pre-buffer admission, one shared four-slot concurrency gate injected into legacy + qualified registrations, the route-owned numbered-candidate loop, upload-specific raw-parser errors, capability tag, and telemetry entry; keep route tests colocated in workspace-file-write.test.ts, with qualified cases in workspace-qualified-rest.test.ts.maxWorkspaceFileUploadBytes capability typing plus uploadWorkspaceFile() on DaemonClient and WorkspaceDaemonClient with the shared raw-POST helper, browser progress, timeout, and abort support, tests.useFileUpload hook — standalone sequential queue with local size preflight and target-generation cancellation, testable without UI.MAX_UPLOAD_BYTES succeeds, proving the text-write default is not applied to the byte path; a direct writeBytesAtomic call above MAX_UPLOAD_BYTES fails with file_too_large; existing text writes above MAX_WRITE_BYTES remain rejected. Trust/generation: a direct untrusted call fails with untrusted_workspace; a generation closed after method entry but before publication leaves no target. Atomicity: interrupted write leaves no partial target; an external create racing the no-clobber publish still yields file_already_exists; symlink target rejected; new file created at 0o600.unsupported_media_type envelope before buffering; an upload greater than 5 MiB and at most MAX_UPLOAD_BYTES succeeds; an oversized declared Content-Length is rejected immediately, while a chunked or understated body above MAX_UPLOAD_BYTES is rejected by the raw parser before the handler/fs write; both use the exact upload-specific 413 envelope (errorKind, status, and maxBytes included, with no "10 MB" message). Missing/invalid path, a requested basename over 255 UTF-8 bytes, invalid client id, missing/non-directory parents, and boundary escapes are rejected before buffering. Paths containing spaces, non-ASCII, %, and # decode exactly once; a name occupied by a file, directory, or in-workspace final-component symlink → 201 with a numbered path, with no write through the existing entry; an escaping symlink remains a boundary error. Numbering preserves the final extension, handles no-extension and dotfile names, skips taken candidates, trims a long Unicode stem to the 255-byte policy cap, and fails at the 1000-candidate cap; auto-numbering never modifies the requested target; concurrent same-name uploads land on distinct candidates. Four admitted uploads may buffer concurrently across both route forms; a fifth receives the exact 429 upload_busy response and Retry-After, and disconnect/parser-error paths release their slot. The response has no derived renamed flag. Capability tag and limits.maxWorkspaceFileUploadBytes are advertised. Qualified route: untrusted, unknown (including already removed), and draining workspaces are rejected before buffering and never fall back to the primary runtime.XMLHttpRequest fails before sending; omitted timeout inherits the client default, timeoutMs: 0 disables it, and an explicit timeout or abort signal cancels the request; filesystem errors expose errorKind while other daemon errors preserve their existing parsed bodies; both legacy-primary and workspace-qualified clients.tooManyFiles notice row with the skipped count; a batch runs one request at a time in selection order; failure/cancel does not block the next item; removing a pending item prevents it from starting; a late response after abort does not invoke onUploaded; changing the target workspace aborts and clears the old queue and ignores late completions; each successful final path creates exactly one inline file tag; removing the last tag restores the placeholder; completed rows disappear after three seconds. Pure supported-image drops stay on the image-attachment path, while ordinary files and mixed batches upload without leaving drag-active styling behind.% to cover escaping); drop a file whose requested name is occupied, including by an in-workspace symlink → upload succeeds as name (1).ext with an auto-numbering hint derived from the differing paths, the existing entry untouched, and the tag uses the final name; batch drop preserves upload/tag order. @ panel: browse into a nested directory, select upload, choose a file → the trigger @ is removed, the captured directory receives the file, and an inline file tag appears; reopening the menu fetches a fresh listing without a public cache API; selecting the same local file twice still fires two uploads. Entry points are hidden when either the upload capability or the required qualified-route capability is absent. Submit prompts that reference one uploaded text file and one uploaded image and verify the existing resolver supplies their content; an unsupported/oversized binary surfaces the resolver's existing readable error rather than being described as universally consumable.