WorkspaceFilesRuntimeCapability exposes WorkspaceFilesApi under the stable ID platform.workspace.files. It is the plugin-facing file boundary for Xpert workspace Volumes.
Use this capability instead of reading host filesystem paths or implementing plugin-owned storage. It preserves platform scope, returns portable references for asynchronous work, and integrates existing files with the platform file-understanding pipeline.
Catalogs and scope
The supported logical catalogs are:WorkspaceFileScope fields such as tenantId, organizationId, userId, catalog, scopeId, projectId, knowledgeId, rootId, and xpertId. Runtime-aware APIs infer the current Agent workspace when possible.
For runtime-relative files, the host binds a concrete data owner: Project mode binds projectId, while non-Project mode binds xpertId. A personal Xpert uses catalog: 'user-xperts', where scopeId is the Xpert ID and userId remains a separate user-isolation field. Never concatenate userId and xpertId into one scopeId.
filePath is always relative to a workspace Volume. It is not /workspace/... and is never a host/API-process filesystem path.
Resolve Workspace Files in a NestJS provider
Agent middleware usescontext.runtime.capabilities directly. A View Provider, controller or job may resolve Workspace Files from XPERT_RUNTIME_CAPABILITIES_TOKEN and use explicit scope-aware methods such as readBuffer and uploadBuffer. Each operation still resolves and authorizes its Volume.
When a provider needs Agent-style defaults for runtime-relative paths, inject XPERT_AGENT_MIDDLEWARE_RUNTIME_TOKEN and create a scoped API from host-resolved context:
WorkspaceFilesRuntimeCapability. A direct domain API and an Agent-scoped facade serve different call shapes; neither is a fallback around failed authorization. Scoped calls cannot override the bound owner with tool input. See Runtime Capabilities for the complete provider rules.
Assistant files and application state
The authoringXpertWorkspace is not an Assistant file ACL. Non-Project files use the exact published Assistant’s access policy: shared mode is collaborative for authorized users, while user mode binds the current authenticated user. Authoring workspace membership or the Assistant creator’s identity must not substitute for runtime file access. Project files retain current membership and Assistant binding checks.
files.appData({ pluginName, projectId?, requireUserIsolation? }) returns a bound WorkspaceStorage handle for durable plugin application state. The host resolves the namespace from loaded plugin metadata. Use read, write, mkdir, list, remove and withLock; paths and lock keys are canonical relative paths. Recreate handles after a workspace policy change and keep personal data in explicitly user-isolated storage. Locks coordinate writes; they do not grant access.
For Project file trees and compare-and-set editing, see Content and Editor Runtime.
Choose the right reference
A portable reference has
source: 'platform.workspace.files', a stable filePath, scope metadata, and a runtime-facing workspacePath. Persist the complete reference; do not reduce it to a sandbox path.
File operations
Read a path received from an Agent tool:
File understanding
The understanding APIs reuse the platform FileAsset and FileChunk index. They do not create a plugin-owned duplicate index.
Register and search a file:
listUnderstandingChunks() is one-based and returns hasMore. The host clamps page sizes, search limits, excerpt lengths, and per-chunk content lengths. Consumers must page rather than assume a full document is returned.
vectorIndexStatus is pending, ready, failed, or unavailable. Check it separately from the general parse status before exposing semantic search.
WorkspaceMediaFilesApi<TLocator> is a narrower type for media-generation adapters. It requires uploadBuffer() and readBuffer() and optionally exposes readRuntimeBuffer() and deleteFile(); use it when a component should not depend on the complete Workspace Files API.
Safety and lifecycle
- Derive explicit scope or create the scoped facade from trusted server context for each operation. Do not cache bound file APIs or storage handles across users, Assistants or Projects.
- Prefer
resolveFile()when only metadata or an openable URL is required; use byte-reading methods only for actual processing. - Never pass
/workspace/...paths into a delayed job. Convert them withresolveRuntimeReference()first. - Validate stored evidence with
validateUnderstandingReferences()before presenting or acting on it. - Scope every explicit operation. Do not construct
filePathfrom an untrusted absolute path. - Raw
Buffervalues belong only to the current server operation. Persist portable references for later work.