@xpert-ai/plugin-sdk 3.15.2 → 3.15.4

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # @xpert-ai/plugin-sdk
 
+## 3.15.4
+
+### Patch Changes
+
+- 693806f: workspace files
+- Updated dependencies [693806f]
+  - @xpert-ai/contracts@3.15.5
+
+## 3.15.3
+
+### Patch Changes
+
+- bdcb73b: handoff messages
+- Updated dependencies [bdcb73b]
+  - @xpert-ai/contracts@3.15.4
+
 ## 3.15.2
 
 ### Patch Changes

package/index.cjs.js

@@ -2767,6 +2767,7 @@ const KnowledgebaseDocumentsRuntimeCapability = createRuntimeCapability('platfor
     description: 'Upload, import, create, process, inspect, and delete persistent knowledgebase documents.'
 });
 
+/** Stable source identifier for portable workspace file references. */ const WORKSPACE_FILES_SOURCE = 'platform.workspace.files';
 const WorkspaceFilesRuntimeCapability = createRuntimeCapability('platform.workspace.files', {
     description: 'Upload, understand, read, and delete raw files in Xpert workspace volumes.'
 });
@@ -4742,6 +4743,7 @@ exports.VectorStoreStrategy = VectorStoreStrategy;
 exports.ViewExtensionProvider = ViewExtensionProvider;
 exports.WORKFLOW_NODE_STRATEGY = WORKFLOW_NODE_STRATEGY;
 exports.WORKFLOW_TRIGGER_STRATEGY = WORKFLOW_TRIGGER_STRATEGY;
+exports.WORKSPACE_FILES_SOURCE = WORKSPACE_FILES_SOURCE;
 exports.WorkflowNodeStrategy = WorkflowNodeStrategy;
 exports.WorkflowTriggerStrategy = WorkflowTriggerStrategy;
 exports.WorkspaceFilesRuntimeCapability = WorkspaceFilesRuntimeCapability;

package/index.esm.js

@@ -2747,6 +2747,7 @@ const KnowledgebaseDocumentsRuntimeCapability = createRuntimeCapability('platfor
     description: 'Upload, import, create, process, inspect, and delete persistent knowledgebase documents.'
 });
 
+/** Stable source identifier for portable workspace file references. */ const WORKSPACE_FILES_SOURCE = 'platform.workspace.files';
 const WorkspaceFilesRuntimeCapability = createRuntimeCapability('platform.workspace.files', {
     description: 'Upload, understand, read, and delete raw files in Xpert workspace volumes.'
 });
@@ -4587,4 +4588,4 @@ function escapeHtmlAttribute(value) {
 
 const VIEW_EXTENSION_CACHE_SERVICE_TOKEN = 'XPERT_PLUGIN_VIEW_EXTENSION_CACHE_SERVICE';
 
-export { ACCOUNT_BINDING_PERMISSION_SERVICE_TOKEN, AGENT_CHAT_DISPATCH_MESSAGE_TYPE, AGENT_MIDDLEWARE_STRATEGY, AIModelProviderNotFoundException, AIModelProviderRegistry, AIModelProviderStrategy, AI_MODEL_PROVIDER, ANALYTICS_PERMISSION_SERVICE_TOKEN, AdapterDataSourceStrategy, AgentMiddlewareRegistry, AgentMiddlewareStrategy, AiModelNotFoundException, AssistantTaskRuntimeCapability, BOUND_IDENTITY_LOGIN_PERMISSION_SERVICE_TOKEN, BUILTIN_GLOBAL_SCOPE, BaseHTTPQueryRunner, BaseQueryRunner, BaseSQLQueryRunner, BaseSandbox, BaseStrategyRegistry, BaseTool, BaseToolset, BuiltinToolset, CHAT_CHANNEL, CHAT_CHANNEL_TEXT_LIMITS, CONNECTION_COMMAND_ROUTER_TOKEN, CancelConversationCommand, ChatChannel, ChatChannelRegistry, ChatOAICompatReasoningModel, CommonParameterRules, CreateModelClientCommand, CredentialsValidateFailedError, DATASOURCE_STRATEGY, DBCreateTableMode, DBProtocolEnum, DBSyntaxEnum, DBTableAction, DBTableDataAction, DEFAULT_EXECUTION_CONFIG, DEFAULT_SANDBOX_EXECUTION_MAX_OUTPUT_BYTES, DEFAULT_SANDBOX_FILE_OPERATION_EXECUTION_OPTIONS, DEFAULT_SANDBOX_FILE_OPERATION_TIMEOUT_MS, DEFAULT_SANDBOX_FILE_OPERATION_TIMEOUT_SEC, DEFAULT_SANDBOX_FILE_SEARCH_EXECUTION_OPTIONS, DEFAULT_SANDBOX_FILE_SEARCH_TIMEOUT_MS, DEFAULT_SANDBOX_FILE_SEARCH_TIMEOUT_SEC, DEFAULT_SANDBOX_SHELL_EXECUTION_OPTIONS, DEFAULT_SANDBOX_SHELL_TIMEOUT_MS, DEFAULT_SANDBOX_SHELL_TIMEOUT_SEC, DOCUMENT_SOURCE_STRATEGY, DOCUMENT_TRANSFORMER_STRATEGY, DataSourceStrategy, DataSourceStrategyRegistry, DefaultRuntimeCapabilityRegistry as DefaultAgentMiddlewareRuntimeCapabilityRegistry, DefaultRuntimeCapabilityRegistry, DocumentSourceRegistry, DocumentSourceStrategy, DocumentTransformerRegistry, DocumentTransformerStrategy, FILE_STORAGE_PROVIDER, FILE_UPLOAD_TARGET_STRATEGY, FileRuntimeCapability, FileStorageProvider, FileStorageProviderRegistry, FileUploadTargetRegistry, FileUploadTargetStrategy, GLOBAL_ORGANIZATION_SCOPE, HANDOFF_PERMISSION_SERVICE_TOKEN, HANDOFF_PROCESSOR_STRATEGY, HANDOFF_QUEUE_SERVICE_TOKEN, HandoffProcessorRegistry, HandoffProcessorStrategy, IMAGE_UNDERSTANDING_STRATEGY, INTEGRATION_PERMISSION_SERVICE_TOKEN, INTEGRATION_STRATEGY, ImageUnderstandingRegistry, ImageUnderstandingStrategy, IntegrationStrategyKey, IntegrationStrategyRegistry, JUMP_TO_TARGETS, JsonSchemaValidator, KNOWLEDGE_STRATEGY, KnowledgeStrategyKey, KnowledgeStrategyRegistry, KnowledgebaseDocumentsRuntimeCapability, KnowledgebaseRuntimeCapability, LLMUsage, LargeLanguageModel, MANAGED_CONNECTION_REGISTRY_TOKEN, MANAGED_QUEUE_HANDLER_REGISTRY_TOKEN, MANAGED_QUEUE_SERVICE_TOKEN, ModelProvider, ORGANIZATION_METADATA_KEY, OpenAICompatibleReranker, PERMISSION_OPERATION_METADATA_KEY, PLUGIN_CONFIG_RESOLVER_TOKEN, PLUGIN_JOB_PROCESSOR_METADATA, PLUGIN_METADATA, PLUGIN_METADATA_KEY, PLUGIN_WEBHOOK_AUTH_METADATA_KEY, PLUGIN_WEBHOOK_AUTH_SERVICE_TOKEN, PROVIDE_AI_MODEL_LLM, PROVIDE_AI_MODEL_MODERATION, PROVIDE_AI_MODEL_RERANK, PROVIDE_AI_MODEL_SPEECH2TEXT, PROVIDE_AI_MODEL_TEXT_EMBEDDING, PROVIDE_AI_MODEL_TTS, PluginJobProcessor, PluginWebhookAuth, PluginWebhookAuthGuard, RETRIEVER_STRATEGY, RequestContext, RequestContextMiddleware, RequirePermissionOperation, RerankModel, RetrieverRegistry, RetrieverStrategy, SANDBOX_PROVIDER, SANDBOX_SHELL_TIMEOUT_LIMITS_SEC, SKILL_SOURCE_PROVIDER, SPEECH_TO_TEXT_PERMISSION_SERVICE_TOKEN, SPEECH_TO_TEXT_SERVICE_TOKEN, SSOProviderRegistry, SSOProviderStrategyKey, SSO_BINDING_PERMISSION_SERVICE_TOKEN, SSO_PROVIDER, STRATEGY_META_KEY, SYSTEM_GLOBAL_SCOPE, SandboxProviderRegistry, SandboxProviderStrategy, SkillSourceProviderRegistry, SkillSourceProviderStrategy, Speech2TextChatModel, SpeechToTextModel, StrategyBus, TENANT_GLOBAL_SCOPE_PREFIX, TENANT_GLOBAL_SCOPE_SUFFIX, TEXT_SPLITTER_STRATEGY, TOOLSET_STRATEGY, TextEmbeddingModelManager, TextSplitterRegistry, TextSplitterStrategy, TextToSpeechModel, ToolsetRegistry, ToolsetStrategy, USER_PERMISSION_SERVICE_TOKEN, VECTOR_STORE_STRATEGY, VIEW_EXTENSION_CACHE_SERVICE_TOKEN, VIEW_EXTENSION_PROVIDER, VectorStoreRegistry, VectorStoreStrategy, ViewExtensionProvider, ViewExtensionProviderRegistry, WORKFLOW_NODE_STRATEGY, WORKFLOW_TRIGGER_STRATEGY, WorkflowNodeRegistry, WorkflowNodeStrategy, WorkflowTriggerRegistry, WorkflowTriggerStrategy, WorkspaceFilesRuntimeCapability, WrapWorkflowNodeExecutionCommand, XPERT_RUNTIME_CAPABILITIES_TOKEN, XpFileSystem, XpertServerPlugin, als, appendSandboxMessage, buildSandboxTimeoutMessage, calcTokenUsage, chunkText, countTokensSafe, createI18nInstance, createPluginLogger, createRuntimeCapability, defineAgentMessageType, defineChannelMessageType, downloadRemoteFile, formatSandboxTimeout, getDefaultTenantId, getErrorMessage, getModelContextSize, getPermissionOperationMetadata, getPositionList, getPositionMap, getRequestContext, getRequiredPermissionOperation, getTenantGlobalScopeKey, isRemoteFile, isSandboxBackend, isSandboxManagedServiceAdapter, isSandboxServiceProxyAdapter, isSandboxTerminalAdapter, isStructuredMessageType, isTenantGlobalScopeKey, loadYamlFile, mergeCredentials, mergeParentChildChunks, normalizeContextSize, renderRemoteReactIframeHtml, resolveSandboxBackend, resolveSandboxExecutionOptions, resolveSandboxManagedServiceAdapter, resolveSandboxServiceProxyAdapter, resolveSandboxTerminalAdapter, resolveTenantGlobalScopeKey, runWithRequestContext, secondsToMilliseconds, setDefaultTenantId, sumTokenUsage };
+export { ACCOUNT_BINDING_PERMISSION_SERVICE_TOKEN, AGENT_CHAT_DISPATCH_MESSAGE_TYPE, AGENT_MIDDLEWARE_STRATEGY, AIModelProviderNotFoundException, AIModelProviderRegistry, AIModelProviderStrategy, AI_MODEL_PROVIDER, ANALYTICS_PERMISSION_SERVICE_TOKEN, AdapterDataSourceStrategy, AgentMiddlewareRegistry, AgentMiddlewareStrategy, AiModelNotFoundException, AssistantTaskRuntimeCapability, BOUND_IDENTITY_LOGIN_PERMISSION_SERVICE_TOKEN, BUILTIN_GLOBAL_SCOPE, BaseHTTPQueryRunner, BaseQueryRunner, BaseSQLQueryRunner, BaseSandbox, BaseStrategyRegistry, BaseTool, BaseToolset, BuiltinToolset, CHAT_CHANNEL, CHAT_CHANNEL_TEXT_LIMITS, CONNECTION_COMMAND_ROUTER_TOKEN, CancelConversationCommand, ChatChannel, ChatChannelRegistry, ChatOAICompatReasoningModel, CommonParameterRules, CreateModelClientCommand, CredentialsValidateFailedError, DATASOURCE_STRATEGY, DBCreateTableMode, DBProtocolEnum, DBSyntaxEnum, DBTableAction, DBTableDataAction, DEFAULT_EXECUTION_CONFIG, DEFAULT_SANDBOX_EXECUTION_MAX_OUTPUT_BYTES, DEFAULT_SANDBOX_FILE_OPERATION_EXECUTION_OPTIONS, DEFAULT_SANDBOX_FILE_OPERATION_TIMEOUT_MS, DEFAULT_SANDBOX_FILE_OPERATION_TIMEOUT_SEC, DEFAULT_SANDBOX_FILE_SEARCH_EXECUTION_OPTIONS, DEFAULT_SANDBOX_FILE_SEARCH_TIMEOUT_MS, DEFAULT_SANDBOX_FILE_SEARCH_TIMEOUT_SEC, DEFAULT_SANDBOX_SHELL_EXECUTION_OPTIONS, DEFAULT_SANDBOX_SHELL_TIMEOUT_MS, DEFAULT_SANDBOX_SHELL_TIMEOUT_SEC, DOCUMENT_SOURCE_STRATEGY, DOCUMENT_TRANSFORMER_STRATEGY, DataSourceStrategy, DataSourceStrategyRegistry, DefaultRuntimeCapabilityRegistry as DefaultAgentMiddlewareRuntimeCapabilityRegistry, DefaultRuntimeCapabilityRegistry, DocumentSourceRegistry, DocumentSourceStrategy, DocumentTransformerRegistry, DocumentTransformerStrategy, FILE_STORAGE_PROVIDER, FILE_UPLOAD_TARGET_STRATEGY, FileRuntimeCapability, FileStorageProvider, FileStorageProviderRegistry, FileUploadTargetRegistry, FileUploadTargetStrategy, GLOBAL_ORGANIZATION_SCOPE, HANDOFF_PERMISSION_SERVICE_TOKEN, HANDOFF_PROCESSOR_STRATEGY, HANDOFF_QUEUE_SERVICE_TOKEN, HandoffProcessorRegistry, HandoffProcessorStrategy, IMAGE_UNDERSTANDING_STRATEGY, INTEGRATION_PERMISSION_SERVICE_TOKEN, INTEGRATION_STRATEGY, ImageUnderstandingRegistry, ImageUnderstandingStrategy, IntegrationStrategyKey, IntegrationStrategyRegistry, JUMP_TO_TARGETS, JsonSchemaValidator, KNOWLEDGE_STRATEGY, KnowledgeStrategyKey, KnowledgeStrategyRegistry, KnowledgebaseDocumentsRuntimeCapability, KnowledgebaseRuntimeCapability, LLMUsage, LargeLanguageModel, MANAGED_CONNECTION_REGISTRY_TOKEN, MANAGED_QUEUE_HANDLER_REGISTRY_TOKEN, MANAGED_QUEUE_SERVICE_TOKEN, ModelProvider, ORGANIZATION_METADATA_KEY, OpenAICompatibleReranker, PERMISSION_OPERATION_METADATA_KEY, PLUGIN_CONFIG_RESOLVER_TOKEN, PLUGIN_JOB_PROCESSOR_METADATA, PLUGIN_METADATA, PLUGIN_METADATA_KEY, PLUGIN_WEBHOOK_AUTH_METADATA_KEY, PLUGIN_WEBHOOK_AUTH_SERVICE_TOKEN, PROVIDE_AI_MODEL_LLM, PROVIDE_AI_MODEL_MODERATION, PROVIDE_AI_MODEL_RERANK, PROVIDE_AI_MODEL_SPEECH2TEXT, PROVIDE_AI_MODEL_TEXT_EMBEDDING, PROVIDE_AI_MODEL_TTS, PluginJobProcessor, PluginWebhookAuth, PluginWebhookAuthGuard, RETRIEVER_STRATEGY, RequestContext, RequestContextMiddleware, RequirePermissionOperation, RerankModel, RetrieverRegistry, RetrieverStrategy, SANDBOX_PROVIDER, SANDBOX_SHELL_TIMEOUT_LIMITS_SEC, SKILL_SOURCE_PROVIDER, SPEECH_TO_TEXT_PERMISSION_SERVICE_TOKEN, SPEECH_TO_TEXT_SERVICE_TOKEN, SSOProviderRegistry, SSOProviderStrategyKey, SSO_BINDING_PERMISSION_SERVICE_TOKEN, SSO_PROVIDER, STRATEGY_META_KEY, SYSTEM_GLOBAL_SCOPE, SandboxProviderRegistry, SandboxProviderStrategy, SkillSourceProviderRegistry, SkillSourceProviderStrategy, Speech2TextChatModel, SpeechToTextModel, StrategyBus, TENANT_GLOBAL_SCOPE_PREFIX, TENANT_GLOBAL_SCOPE_SUFFIX, TEXT_SPLITTER_STRATEGY, TOOLSET_STRATEGY, TextEmbeddingModelManager, TextSplitterRegistry, TextSplitterStrategy, TextToSpeechModel, ToolsetRegistry, ToolsetStrategy, USER_PERMISSION_SERVICE_TOKEN, VECTOR_STORE_STRATEGY, VIEW_EXTENSION_CACHE_SERVICE_TOKEN, VIEW_EXTENSION_PROVIDER, VectorStoreRegistry, VectorStoreStrategy, ViewExtensionProvider, ViewExtensionProviderRegistry, WORKFLOW_NODE_STRATEGY, WORKFLOW_TRIGGER_STRATEGY, WORKSPACE_FILES_SOURCE, WorkflowNodeRegistry, WorkflowNodeStrategy, WorkflowTriggerRegistry, WorkflowTriggerStrategy, WorkspaceFilesRuntimeCapability, WrapWorkflowNodeExecutionCommand, XPERT_RUNTIME_CAPABILITIES_TOKEN, XpFileSystem, XpertServerPlugin, als, appendSandboxMessage, buildSandboxTimeoutMessage, calcTokenUsage, chunkText, countTokensSafe, createI18nInstance, createPluginLogger, createRuntimeCapability, defineAgentMessageType, defineChannelMessageType, downloadRemoteFile, formatSandboxTimeout, getDefaultTenantId, getErrorMessage, getModelContextSize, getPermissionOperationMetadata, getPositionList, getPositionMap, getRequestContext, getRequiredPermissionOperation, getTenantGlobalScopeKey, isRemoteFile, isSandboxBackend, isSandboxManagedServiceAdapter, isSandboxServiceProxyAdapter, isSandboxTerminalAdapter, isStructuredMessageType, isTenantGlobalScopeKey, loadYamlFile, mergeCredentials, mergeParentChildChunks, normalizeContextSize, renderRemoteReactIframeHtml, resolveSandboxBackend, resolveSandboxExecutionOptions, resolveSandboxManagedServiceAdapter, resolveSandboxServiceProxyAdapter, resolveSandboxTerminalAdapter, resolveTenantGlobalScopeKey, runWithRequestContext, secondsToMilliseconds, setDefaultTenantId, sumTokenUsage };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xpert-ai/plugin-sdk",
-  "version": "3.15.2",
+  "version": "3.15.4",
   "license": "AGPL-3.0",
   "repository": {
     "type": "git",

package/src/lib/agent/handoff/types.d.ts

@@ -79,6 +79,8 @@ export interface HandoffMessageHeaders extends Record<string, string> {
     source?: RunSource;
     requestedLane?: LaneName;
     integrationId?: string;
+    policyTimeoutMs?: string;
+    policyIdleTimeoutMs?: string;
 }
 /**
  * Processor execution policy: declared by the Processor, executed uniformly by the Dispatcher.
@@ -86,11 +88,14 @@ export interface HandoffMessageHeaders extends Record<string, string> {
 export interface ProcessorPolicy {
     lane: LaneName;
     timeoutMs?: number;
+    idleTimeoutMs?: number;
 }
 export interface ProcessContext {
     runId: string;
     traceId: string;
     abortSignal: AbortSignal;
+    heartbeat?: (reason?: string) => void;
+    getAbortReason?: () => string | undefined;
     /**
      * Optional local-process event channel for queue waiters (e.g. SSE connection awaiting this message).
      * This is intentionally process-local and best-effort.

package/src/lib/runtime/capabilities/workspace-files.d.ts

@@ -1,4 +1,13 @@
+/** Logical workspace volume catalog supported by plugin-facing file APIs. */
 export type WorkspaceFileCatalog = 'projects' | 'users' | 'knowledges' | 'skills' | 'xperts';
+/** Stable source identifier for portable workspace file references. */
+export declare const WORKSPACE_FILES_SOURCE: "platform.workspace.files";
+/**
+ * Scope fields used to resolve a workspace Volume.
+ *
+ * Explicit APIs can provide catalog plus the matching id directly. Runtime-aware
+ * APIs usually receive these fields from the current Agent execution context.
+ */
 export type WorkspaceFileScope = {
     tenantId?: string | null;
     userId?: string | null;
@@ -10,6 +19,12 @@ export type WorkspaceFileScope = {
     xpertId?: string | null;
     isolateByUser?: boolean | null;
 };
+/**
+ * Input for uploading raw bytes into an explicitly scoped workspace Volume.
+ *
+ * Use `writeRuntimeBuffer()` instead when a plugin writes into the current Agent
+ * runtime workspace and wants the platform to infer project/Xpert scope.
+ */
 export type WorkspaceUploadBufferInput = WorkspaceFileScope & {
     buffer: Buffer;
     originalName: string;
@@ -19,9 +34,54 @@ export type WorkspaceUploadBufferInput = WorkspaceFileScope & {
     fileName?: string | null;
     metadata?: Record<string, unknown>;
 };
+/**
+ * Scoped reference to an existing workspace file.
+ *
+ * `filePath` is always a Volume-relative path, not a sandbox absolute path such
+ * as `/workspace/...` and not a host/API-process filesystem path.
+ */
 export type WorkspaceFileReference = WorkspaceFileScope & {
     filePath: string;
 };
+/**
+ * Agent-facing locator for a file in the current runtime workspace.
+ *
+ * Callers may provide sandbox paths such as `/workspace/report.docx`,
+ * workspace-relative paths such as `report.docx`, or metadata aliases commonly
+ * produced by tool calls.
+ */
+export type WorkspaceRuntimeFileDescriptor = {
+    path?: string | null;
+    filePath?: string | null;
+    workspacePath?: string | null;
+    originalName?: string | null;
+    name?: string | null;
+    mimeType?: string | null;
+    mimetype?: string | null;
+    size?: number | null;
+};
+/**
+ * Persistable workspace file reference produced by the platform.
+ *
+ * Unlike a sandbox absolute path, this reference carries enough scope metadata
+ * to read the same file later from queues, callbacks, or async jobs.
+ */
+export type WorkspacePortableFileReference = WorkspaceFileReference & {
+    source: typeof WORKSPACE_FILES_SOURCE;
+    workspacePath: string;
+    originalName?: string | null;
+    name?: string | null;
+    mimeType?: string | null;
+    size?: number | null;
+};
+/** Input accepted by runtime-aware workspace file APIs. */
+export type WorkspaceFileLocator = string | WorkspaceRuntimeFileDescriptor | WorkspacePortableFileReference;
+/**
+ * Metadata returned by workspace file operations.
+ *
+ * `filePath` is the stable Volume-relative path. `workspacePath` is the
+ * runtime/sandbox-facing path when one is available.
+ */
 export type WorkspaceFile = {
     name: string;
     filePath: string;
@@ -34,9 +94,34 @@ export type WorkspaceFile = {
     scopeId?: string;
     metadata?: Record<string, unknown>;
 };
+/** Workspace file metadata plus raw file bytes. */
 export type WorkspaceFileBuffer = WorkspaceFile & {
     buffer: Buffer;
 };
+/** Workspace file bytes plus the portable reference used to retrieve them. */
+export type WorkspaceRuntimeFileBuffer = WorkspaceFileBuffer & {
+    reference: WorkspacePortableFileReference;
+};
+/**
+ * Runtime-aware write input for bytes created by tools or plugins.
+ *
+ * If a path is provided, it is interpreted as a workspace path in the scoped
+ * runtime, not as a host/API-process filesystem path.
+ */
+export type WorkspaceRuntimeWriteInput = WorkspaceFileScope & WorkspaceRuntimeFileDescriptor & {
+    buffer: Buffer;
+    originalName?: string | null;
+    folder?: string | null;
+    fileName?: string | null;
+    metadata?: Record<string, unknown>;
+};
+/**
+ * Input for registering an existing workspace file with the file-understanding
+ * pipeline.
+ *
+ * The file must already exist in the scoped workspace Volume identified by
+ * `filePath` and the scope fields.
+ */
 export type WorkspaceUnderstandFileInput = WorkspaceFileReference & {
     originalName?: string | null;
     mimeType?: string | null;
@@ -52,6 +137,7 @@ export type WorkspaceUnderstandFileInput = WorkspaceFileReference & {
     metadata?: Record<string, unknown>;
     runInline?: boolean | null;
 };
+/** File-understanding asset metadata created from a workspace file. */
 export type WorkspaceUnderstoodFile = WorkspaceFile & {
     id: string;
     fileId: string;
@@ -65,10 +151,37 @@ export type WorkspaceUnderstoodFile = WorkspaceFile & {
     capabilities?: string[];
     summary?: string;
 };
+/**
+ * Runtime capability contract for reading, writing, uploading, deleting, and
+ * understanding files in Xpert workspace Volumes.
+ */
 export interface WorkspaceFilesApi {
+    /** Upload raw bytes into an explicitly scoped workspace Volume. */
     uploadBuffer(input: WorkspaceUploadBufferInput): Promise<WorkspaceFile>;
+    /** Register an existing workspace file with the platform understanding pipeline. */
     understandFile(input: WorkspaceUnderstandFileInput): Promise<WorkspaceUnderstoodFile>;
+    /** Read raw bytes from an explicitly scoped workspace file reference. */
     readBuffer(input: WorkspaceFileReference): Promise<WorkspaceFileBuffer>;
+    /** Delete an explicitly scoped workspace file. */
     deleteFile(input: WorkspaceFileReference): Promise<void>;
+    /**
+     * Normalize a runtime locator into a portable, scope-aware reference without
+     * reading the file bytes.
+     */
+    resolveRuntimeReference(input: WorkspaceFileLocator): Promise<WorkspacePortableFileReference>;
+    /**
+     * Read bytes from a runtime locator using the current Agent workspace scope.
+     *
+     * This is the preferred API for plugin tools that receive `/workspace/...`
+     * paths from sandbox commands.
+     */
+    readRuntimeBuffer(input: WorkspaceFileLocator): Promise<WorkspaceRuntimeFileBuffer>;
+    /**
+     * Write bytes into the current runtime workspace and return a portable
+     * reference suitable for delayed processing or queue retries.
+     */
+    writeRuntimeBuffer(input: WorkspaceRuntimeWriteInput): Promise<WorkspaceFile & {
+        reference: WorkspacePortableFileReference;
+    }>;
 }
 export declare const WorkspaceFilesRuntimeCapability: import("../../core/runtime-capability").RuntimeCapabilityKey<WorkspaceFilesApi>;