Workspace Files Runtime

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:

type WorkspaceFileCatalog =
  | 'projects'
  | 'users'
  | 'knowledges'
  | 'skills'
  | 'xperts'
  | 'user-xperts'

Explicit APIs accept 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 files in the current Agent runtime, the host exposes the capability only after binding 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 uses context.runtime.capabilities directly. A View Provider, controller, or other NestJS service must inject XPERT_AGENT_MIDDLEWARE_RUNTIME_TOKEN and create a scoped API from host-resolved context:

import { Inject, Optional } from '@nestjs/common'
import {
  WorkspaceFilesRuntimeCapability,
  XPERT_AGENT_MIDDLEWARE_RUNTIME_TOKEN,
  type AgentMiddlewareRuntimeScope,
  type AgentMiddlewareRuntimeServiceApi
} from '@xpert-ai/plugin-sdk'

export class DocumentService {
  constructor(
    @Optional()
    @Inject(XPERT_AGENT_MIDDLEWARE_RUNTIME_TOKEN)
    private readonly runtimeService?: AgentMiddlewareRuntimeServiceApi
  ) {}

  workspaceFiles(scope: AgentMiddlewareRuntimeScope) {
    const files = this.runtimeService
      ?.createScopedApi(scope)
      .capabilities?.get(WorkspaceFilesRuntimeCapability)

    if (!files) {
      throw new Error('Workspace Files is unavailable in the current runtime scope')
    }

    return files
  }
}

Do not resolve Workspace Files only from XPERT_RUNTIME_CAPABILITIES_TOKEN inside a provider. That token represents the global capability set without a bound data owner, and current hosts intentionally omit WorkspaceFilesRuntimeCapability from it. See Runtime Capabilities for the complete provider rules.

Choose the right reference

Type	Use
`WorkspaceFileReference`	Address a known file with explicit scope and a Volume-relative `filePath`.
`WorkspaceRuntimeFileDescriptor`	Accept paths and metadata produced by Agent tools, including `/workspace/...` aliases.
`WorkspacePortableFileReference`	Persist or enqueue a scope-aware reference for a later callback, queue retry, Artifact version, or Sandbox Job.
`WorkspaceFileLocator`	Accept a string, runtime descriptor, or portable reference in a runtime-aware API.

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

Method	Result	Use
`uploadBuffer(input)`	`WorkspaceFile`	Upload bytes into an explicitly scoped Volume.
`resolveFile(input)`	`WorkspaceFile`	Resolve metadata and an openable URL without loading bytes.
`readBuffer(input)`	`WorkspaceFileBuffer`	Read bytes from an explicitly scoped file.
`deleteFile(input)`	`void`	Delete an explicitly scoped file.
`resolveRuntimeReference(input)`	`WorkspacePortableFileReference`	Normalize a runtime locator without reading bytes.
`readRuntimeBuffer(input)`	`WorkspaceRuntimeFileBuffer`	Resolve and read a locator in the current Agent workspace.
`writeRuntimeBuffer(input)`	`WorkspaceFile` plus `reference`	Write generated bytes into the current runtime workspace.

Read a path received from an Agent tool:

import { WorkspaceFilesRuntimeCapability } from '@xpert-ai/plugin-sdk'

const files = context.runtime.capabilities?.require(
  WorkspaceFilesRuntimeCapability
)

if (!files) throw new Error('Workspace Files is unavailable')

const input = await files.readRuntimeBuffer('/workspace/input/specification.pdf')

console.log(input.mimeType, input.size)
// input.buffer contains the bytes for this operation.
// input.reference can be persisted or sent to a background job.

Write a generated result:

const output = await files.writeRuntimeBuffer({
  buffer: reportBuffer,
  originalName: 'quality-report.pdf',
  mimeType: 'application/pdf',
  folder: 'reports',
  metadata: {
    resourceType: 'inspection',
    resourceId: inspectionId
  }
})

await queue.enqueue({
  // Store output.reference in the typed queue payload, not output.buffer.
})

File understanding

The understanding APIs reuse the platform FileAsset and FileChunk index. They do not create a plugin-owned duplicate index.

Method	Use
`understandFile(input)`	Register an existing workspace file for parsing and semantic indexing.
`getUnderstandingStatus(input)`	Read compact parse and vector-index readiness without returning parsed text.
`retryUnderstanding(input)`	Retry parsing and indexing for one failed FileAsset.
`listUnderstandingChunks(input)`	Page through bounded chunks in parser order.
`searchUnderstandingChunks(input)`	Run hybrid search against the existing chunk index.
`validateUnderstandingReferences(input)`	Validate bounded `fileAssetId`/`chunkId` evidence and obtain excerpts.

const understood = await files.understandFile({
  catalog: 'projects',
  projectId,
  filePath: uploaded.filePath,
  originalName: uploaded.name,
  mimeType: uploaded.mimeType,
  purpose: 'workspace',
  parseMode: 'deep'
})

const status = await files.getUnderstandingStatus({
  catalog: 'projects',
  projectId,
  fileAssetId: understood.fileAssetId
})

if (status.vectorIndexStatus === 'ready') {
  const chunks = await files.searchUnderstandingChunks({
    catalog: 'projects',
    projectId,
    fileAssetId: understood.fileAssetId,
    query: 'acceptance criteria for operating pressure',
    limit: 8,
    contentLength: 1200
  })
}

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

Create a scoped API from host-resolved server context for each request. Do not cache file capability instances across users, Xperts, Projects, or requests.
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 with resolveRuntimeReference() first.
Validate stored evidence with validateUnderstandingReferences() before presenting or acting on it.
Scope every explicit operation. Do not construct filePath from an untrusted absolute path.
Raw Buffer values belong only to the current server operation. Persist portable references for later work.

Default

Plugin SDK Core

Trigger

Integration

Feishu Document Example

Triggers

Integrations

Workspace Files Runtime

Catalogs and scope

Resolve Workspace Files in a NestJS provider

Choose the right reference

File operations

File understanding

Safety and lifecycle

​Catalogs and scope

​Resolve Workspace Files in a NestJS provider

​Choose the right reference

​File operations

​File understanding

​Safety and lifecycle

Catalogs and scope

Resolve Workspace Files in a NestJS provider

Choose the right reference

File operations

File understanding

Safety and lifecycle