@xpert-ai/plugin-sdk 3.15.11 → 3.15.12

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # @xpert-ai/plugin-sdk
 
+## 3.15.12
+
+### Patch Changes
+
+- b8bac1f: Add system-plugin Sandbox Actions, the action-oriented Sandbox Jobs Core, provider-neutral Runtime Definitions, the minimal Runtime Provider/workspace mapper SPI, Worker heartbeat health, and Browser execution-pool capability discovery.
+- Updated dependencies [b8bac1f]
+- Updated dependencies [b905a58]
+  - @xpert-ai/contracts@3.15.12
+
 ## 3.15.11
 
 ### Patch Changes

package/index.cjs.js

@@ -529,10 +529,12 @@ class BaseStrategyRegistry {
         }
     }
     upsert(instance) {
-        const type = this.reflector.get(this.strategyKey, instance.constructor);
+        const target = resolveStrategyMetadataTarget(instance);
+        if (!target) {
+            return;
+        }
+        const type = this.reflector.get(this.strategyKey, target);
         if (type) {
-            var _instance_metatype;
-            const target = (_instance_metatype = instance.metatype) != null ? _instance_metatype : instance.constructor;
             const pluginName = this.reflector.get(PLUGIN_METADATA_KEY, target);
             var _this_reflector_get;
             const organizationId = (_this_reflector_get = this.reflector.get(ORGANIZATION_METADATA_KEY, target)) != null ? _this_reflector_get : pluginName ? GLOBAL_ORGANIZATION_SCOPE : BUILTIN_GLOBAL_SCOPE;
@@ -640,6 +642,23 @@ __decorate([
     common.Inject(exports.StrategyBus),
     __metadata("design:type", exports.StrategyBus)
 ], BaseStrategyRegistry.prototype, "bus", void 0);
+/** Returns whether a discovered provider can carry decorator metadata. */ function isStrategyInstance(instance) {
+    return typeof instance === 'object' && instance !== null || typeof instance === 'function';
+}
+/** Resolves the class used for plugin and organization metadata without reflecting over primitive provider values. */ function resolveStrategyMetadataTarget(instance) {
+    if (!isStrategyInstance(instance)) {
+        return null;
+    }
+    if (typeof instance === 'function') {
+        return instance;
+    }
+    const metatype = instance.metatype;
+    if (typeof metatype === 'function') {
+        return metatype;
+    }
+    const constructor = instance.constructor;
+    return typeof constructor === 'function' ? constructor : null;
+}
 
 exports.IntegrationStrategyRegistry = class IntegrationStrategyRegistry extends BaseStrategyRegistry {
     constructor(discoveryService, reflector){
@@ -2794,6 +2813,37 @@ const WorkspaceFilesRuntimeCapability = createRuntimeCapability('platform.worksp
     description: 'Upload, understand, read, and delete raw files in Xpert workspace volumes.'
 });
 
+/** Stable machine-readable failures emitted by the Sandbox Jobs capability. */ const SANDBOX_JOB_ERROR_CODES = [
+    'SANDBOX_ACTION_UNAVAILABLE',
+    'SANDBOX_ACTION_INVALID',
+    'SANDBOX_PROFILE_UNAVAILABLE',
+    'SANDBOX_RUNTIME_UNAVAILABLE',
+    'SANDBOX_VERSION_MISMATCH',
+    'SANDBOX_CAPACITY_UNAVAILABLE',
+    'SANDBOX_START_FAILED',
+    'BROWSER_LAUNCH_FAILED',
+    'EXPORT_TIMEOUT',
+    'EXPORT_OOM',
+    'EXPORT_INPUT_INVALID',
+    'EXPORT_OUTPUT_INVALID',
+    'SANDBOX_CANCELLED'
+];
+/** Error carrying retry policy and Job identity across plugin queue handlers. */ class SandboxJobRuntimeError extends Error {
+    constructor(code, message, retryable, jobId){
+        super(message);
+        this.code = code;
+        this.retryable = retryable;
+        this.jobId = jobId;
+        this.name = 'SandboxJobRuntimeError';
+    }
+}
+/** Narrows an unknown failure to the structured Sandbox Jobs runtime error contract. */ function isSandboxJobRuntimeError(error) {
+    return error instanceof SandboxJobRuntimeError;
+}
+/** Runtime capability key used to resolve SandboxJobsApi from the platform registry. */ const SandboxJobsRuntimeCapability = createRuntimeCapability('platform.sandbox.jobs', {
+    description: 'Run registered plugin actions in isolated, short-lived Sandbox Runtime jobs.'
+});
+
 const SKILL_SOURCE_PROVIDER = 'SKILL_SOURCE_PROVIDER';
 const SkillSourceProviderStrategy = (provider)=>common.applyDecorators(common.SetMetadata(SKILL_SOURCE_PROVIDER, provider), common.SetMetadata(STRATEGY_META_KEY, SKILL_SOURCE_PROVIDER));
 
@@ -4159,6 +4209,76 @@ function resolveSandboxTerminalAdapter(sandbox) {
     return isSandboxTerminalAdapter(candidate) ? candidate : null;
 }
 
+const SANDBOX_RUNTIME_PROVIDER = 'SANDBOX_RUNTIME_PROVIDER';
+/** Marks a built-in or system-plugin class as a named Sandbox Runtime Provider strategy. */ const SandboxRuntimeProviderStrategy = (provider)=>common.applyDecorators(common.SetMetadata(SANDBOX_RUNTIME_PROVIDER, provider), common.SetMetadata(STRATEGY_META_KEY, SANDBOX_RUNTIME_PROVIDER));
+
+var SandboxRuntimeProviderRegistry_1;
+/** Discovers Runtime Provider strategies and rejects organization-scoped executable infrastructure. */ exports.SandboxRuntimeProviderRegistry = SandboxRuntimeProviderRegistry_1 = class SandboxRuntimeProviderRegistry extends BaseStrategyRegistry {
+    upsert(instance) {
+        const target = resolveStrategyMetadataTarget(instance);
+        if (!target) {
+            return;
+        }
+        if (!this.reflector.get(SANDBOX_RUNTIME_PROVIDER, target)) {
+            return;
+        }
+        const pluginName = this.reflector.get(PLUGIN_METADATA_KEY, target);
+        var _this_reflector_get;
+        const scope = (_this_reflector_get = this.reflector.get(ORGANIZATION_METADATA_KEY, target)) != null ? _this_reflector_get : BUILTIN_GLOBAL_SCOPE;
+        if (pluginName && scope !== SYSTEM_GLOBAL_SCOPE) {
+            this.runtimeLogger.warn(`Ignored Sandbox Runtime Provider from non-system plugin ${pluginName} in scope ${scope}.`);
+            return;
+        }
+        super.upsert(instance);
+    }
+    constructor(discoveryService, reflector){
+        super(SANDBOX_RUNTIME_PROVIDER, discoveryService, reflector);
+        this.runtimeLogger = new common.Logger(SandboxRuntimeProviderRegistry_1.name);
+    }
+};
+exports.SandboxRuntimeProviderRegistry = SandboxRuntimeProviderRegistry_1 = __decorate([
+    common.Injectable(),
+    __metadata("design:paramtypes", [
+        core.DiscoveryService,
+        core.Reflector
+    ])
+], exports.SandboxRuntimeProviderRegistry);
+
+const SANDBOX_WORKSPACE_MAPPER = 'SANDBOX_WORKSPACE_MAPPER';
+/** Associates a workspace path mapper with a named Runtime Provider strategy. */ const SandboxWorkspaceMapperStrategy = (provider)=>common.applyDecorators(common.SetMetadata(SANDBOX_WORKSPACE_MAPPER, provider), common.SetMetadata(STRATEGY_META_KEY, SANDBOX_WORKSPACE_MAPPER));
+
+var SandboxWorkspaceMapperRegistry_1;
+/** Discovers Provider path mappers while enforcing the same system-level trust boundary as Providers. */ exports.SandboxWorkspaceMapperRegistry = SandboxWorkspaceMapperRegistry_1 = class SandboxWorkspaceMapperRegistry extends BaseStrategyRegistry {
+    upsert(instance) {
+        const target = resolveStrategyMetadataTarget(instance);
+        if (!target) {
+            return;
+        }
+        if (!this.reflector.get(SANDBOX_WORKSPACE_MAPPER, target)) {
+            return;
+        }
+        const pluginName = this.reflector.get(PLUGIN_METADATA_KEY, target);
+        var _this_reflector_get;
+        const scope = (_this_reflector_get = this.reflector.get(ORGANIZATION_METADATA_KEY, target)) != null ? _this_reflector_get : BUILTIN_GLOBAL_SCOPE;
+        if (pluginName && scope !== SYSTEM_GLOBAL_SCOPE) {
+            this.mapperLogger.warn(`Ignored Sandbox Workspace Mapper from non-system plugin ${pluginName} in scope ${scope}.`);
+            return;
+        }
+        super.upsert(instance);
+    }
+    constructor(discoveryService, reflector){
+        super(SANDBOX_WORKSPACE_MAPPER, discoveryService, reflector);
+        this.mapperLogger = new common.Logger(SandboxWorkspaceMapperRegistry_1.name);
+    }
+};
+exports.SandboxWorkspaceMapperRegistry = SandboxWorkspaceMapperRegistry_1 = __decorate([
+    common.Injectable(),
+    __metadata("design:paramtypes", [
+        core.DiscoveryService,
+        core.Reflector
+    ])
+], exports.SandboxWorkspaceMapperRegistry);
+
 const MANAGED_CONNECTION_REGISTRY_TOKEN = 'XPERT_MANAGED_CONNECTION_REGISTRY';
 const CONNECTION_COMMAND_ROUTER_TOKEN = 'XPERT_CONNECTION_COMMAND_ROUTER';
 
@@ -4818,8 +4938,11 @@ exports.RequestContext = RequestContext;
 exports.RequirePermissionOperation = RequirePermissionOperation;
 exports.RerankModel = RerankModel;
 exports.RetrieverStrategy = RetrieverStrategy;
+exports.SANDBOX_JOB_ERROR_CODES = SANDBOX_JOB_ERROR_CODES;
 exports.SANDBOX_PROVIDER = SANDBOX_PROVIDER;
+exports.SANDBOX_RUNTIME_PROVIDER = SANDBOX_RUNTIME_PROVIDER;
 exports.SANDBOX_SHELL_TIMEOUT_LIMITS_SEC = SANDBOX_SHELL_TIMEOUT_LIMITS_SEC;
+exports.SANDBOX_WORKSPACE_MAPPER = SANDBOX_WORKSPACE_MAPPER;
 exports.SKILL_SOURCE_PROVIDER = SKILL_SOURCE_PROVIDER;
 exports.SPEECH_TO_TEXT_PERMISSION_SERVICE_TOKEN = SPEECH_TO_TEXT_PERMISSION_SERVICE_TOKEN;
 exports.SPEECH_TO_TEXT_SERVICE_TOKEN = SPEECH_TO_TEXT_SERVICE_TOKEN;
@@ -4828,7 +4951,11 @@ exports.SSO_BINDING_PERMISSION_SERVICE_TOKEN = SSO_BINDING_PERMISSION_SERVICE_TO
 exports.SSO_PROVIDER = SSO_PROVIDER;
 exports.STRATEGY_META_KEY = STRATEGY_META_KEY;
 exports.SYSTEM_GLOBAL_SCOPE = SYSTEM_GLOBAL_SCOPE;
+exports.SandboxJobRuntimeError = SandboxJobRuntimeError;
+exports.SandboxJobsRuntimeCapability = SandboxJobsRuntimeCapability;
 exports.SandboxProviderStrategy = SandboxProviderStrategy;
+exports.SandboxRuntimeProviderStrategy = SandboxRuntimeProviderStrategy;
+exports.SandboxWorkspaceMapperStrategy = SandboxWorkspaceMapperStrategy;
 exports.SkillSourceProviderStrategy = SkillSourceProviderStrategy;
 exports.Speech2TextChatModel = Speech2TextChatModel;
 exports.SpeechToTextModel = SpeechToTextModel;
@@ -4881,9 +5008,11 @@ exports.getRequiredPermissionOperation = getRequiredPermissionOperation;
 exports.getTenantGlobalScopeKey = getTenantGlobalScopeKey;
 exports.isRemoteFile = isRemoteFile;
 exports.isSandboxBackend = isSandboxBackend;
+exports.isSandboxJobRuntimeError = isSandboxJobRuntimeError;
 exports.isSandboxManagedServiceAdapter = isSandboxManagedServiceAdapter;
 exports.isSandboxServiceProxyAdapter = isSandboxServiceProxyAdapter;
 exports.isSandboxTerminalAdapter = isSandboxTerminalAdapter;
+exports.isStrategyInstance = isStrategyInstance;
 exports.isStructuredMessageType = isStructuredMessageType;
 exports.isTenantGlobalScopeKey = isTenantGlobalScopeKey;
 exports.loadYamlFile = loadYamlFile;
@@ -4899,6 +5028,7 @@ exports.resolveSandboxExecutionOptions = resolveSandboxExecutionOptions;
 exports.resolveSandboxManagedServiceAdapter = resolveSandboxManagedServiceAdapter;
 exports.resolveSandboxServiceProxyAdapter = resolveSandboxServiceProxyAdapter;
 exports.resolveSandboxTerminalAdapter = resolveSandboxTerminalAdapter;
+exports.resolveStrategyMetadataTarget = resolveStrategyMetadataTarget;
 exports.resolveTenantGlobalScopeKey = resolveTenantGlobalScopeKey;
 exports.runWithRequestContext = runWithRequestContext;
 exports.secondsToMilliseconds = secondsToMilliseconds;

package/index.esm.js

@@ -510,10 +510,12 @@ class BaseStrategyRegistry {
         }
     }
     upsert(instance) {
-        const type = this.reflector.get(this.strategyKey, instance.constructor);
+        const target = resolveStrategyMetadataTarget(instance);
+        if (!target) {
+            return;
+        }
+        const type = this.reflector.get(this.strategyKey, target);
         if (type) {
-            var _instance_metatype;
-            const target = (_instance_metatype = instance.metatype) != null ? _instance_metatype : instance.constructor;
             const pluginName = this.reflector.get(PLUGIN_METADATA_KEY, target);
             var _this_reflector_get;
             const organizationId = (_this_reflector_get = this.reflector.get(ORGANIZATION_METADATA_KEY, target)) != null ? _this_reflector_get : pluginName ? GLOBAL_ORGANIZATION_SCOPE : BUILTIN_GLOBAL_SCOPE;
@@ -621,6 +623,23 @@ __decorate([
     Inject(StrategyBus),
     __metadata("design:type", StrategyBus)
 ], BaseStrategyRegistry.prototype, "bus", void 0);
+/** Returns whether a discovered provider can carry decorator metadata. */ function isStrategyInstance(instance) {
+    return typeof instance === 'object' && instance !== null || typeof instance === 'function';
+}
+/** Resolves the class used for plugin and organization metadata without reflecting over primitive provider values. */ function resolveStrategyMetadataTarget(instance) {
+    if (!isStrategyInstance(instance)) {
+        return null;
+    }
+    if (typeof instance === 'function') {
+        return instance;
+    }
+    const metatype = instance.metatype;
+    if (typeof metatype === 'function') {
+        return metatype;
+    }
+    const constructor = instance.constructor;
+    return typeof constructor === 'function' ? constructor : null;
+}
 
 let IntegrationStrategyRegistry = class IntegrationStrategyRegistry extends BaseStrategyRegistry {
     constructor(discoveryService, reflector){
@@ -2775,6 +2794,37 @@ const WorkspaceFilesRuntimeCapability = createRuntimeCapability('platform.worksp
     description: 'Upload, understand, read, and delete raw files in Xpert workspace volumes.'
 });
 
+/** Stable machine-readable failures emitted by the Sandbox Jobs capability. */ const SANDBOX_JOB_ERROR_CODES = [
+    'SANDBOX_ACTION_UNAVAILABLE',
+    'SANDBOX_ACTION_INVALID',
+    'SANDBOX_PROFILE_UNAVAILABLE',
+    'SANDBOX_RUNTIME_UNAVAILABLE',
+    'SANDBOX_VERSION_MISMATCH',
+    'SANDBOX_CAPACITY_UNAVAILABLE',
+    'SANDBOX_START_FAILED',
+    'BROWSER_LAUNCH_FAILED',
+    'EXPORT_TIMEOUT',
+    'EXPORT_OOM',
+    'EXPORT_INPUT_INVALID',
+    'EXPORT_OUTPUT_INVALID',
+    'SANDBOX_CANCELLED'
+];
+/** Error carrying retry policy and Job identity across plugin queue handlers. */ class SandboxJobRuntimeError extends Error {
+    constructor(code, message, retryable, jobId){
+        super(message);
+        this.code = code;
+        this.retryable = retryable;
+        this.jobId = jobId;
+        this.name = 'SandboxJobRuntimeError';
+    }
+}
+/** Narrows an unknown failure to the structured Sandbox Jobs runtime error contract. */ function isSandboxJobRuntimeError(error) {
+    return error instanceof SandboxJobRuntimeError;
+}
+/** Runtime capability key used to resolve SandboxJobsApi from the platform registry. */ const SandboxJobsRuntimeCapability = createRuntimeCapability('platform.sandbox.jobs', {
+    description: 'Run registered plugin actions in isolated, short-lived Sandbox Runtime jobs.'
+});
+
 const SKILL_SOURCE_PROVIDER = 'SKILL_SOURCE_PROVIDER';
 const SkillSourceProviderStrategy = (provider)=>applyDecorators(SetMetadata(SKILL_SOURCE_PROVIDER, provider), SetMetadata(STRATEGY_META_KEY, SKILL_SOURCE_PROVIDER));
 
@@ -4140,6 +4190,76 @@ function resolveSandboxTerminalAdapter(sandbox) {
     return isSandboxTerminalAdapter(candidate) ? candidate : null;
 }
 
+const SANDBOX_RUNTIME_PROVIDER = 'SANDBOX_RUNTIME_PROVIDER';
+/** Marks a built-in or system-plugin class as a named Sandbox Runtime Provider strategy. */ const SandboxRuntimeProviderStrategy = (provider)=>applyDecorators(SetMetadata(SANDBOX_RUNTIME_PROVIDER, provider), SetMetadata(STRATEGY_META_KEY, SANDBOX_RUNTIME_PROVIDER));
+
+var SandboxRuntimeProviderRegistry_1;
+/** Discovers Runtime Provider strategies and rejects organization-scoped executable infrastructure. */ let SandboxRuntimeProviderRegistry = SandboxRuntimeProviderRegistry_1 = class SandboxRuntimeProviderRegistry extends BaseStrategyRegistry {
+    upsert(instance) {
+        const target = resolveStrategyMetadataTarget(instance);
+        if (!target) {
+            return;
+        }
+        if (!this.reflector.get(SANDBOX_RUNTIME_PROVIDER, target)) {
+            return;
+        }
+        const pluginName = this.reflector.get(PLUGIN_METADATA_KEY, target);
+        var _this_reflector_get;
+        const scope = (_this_reflector_get = this.reflector.get(ORGANIZATION_METADATA_KEY, target)) != null ? _this_reflector_get : BUILTIN_GLOBAL_SCOPE;
+        if (pluginName && scope !== SYSTEM_GLOBAL_SCOPE) {
+            this.runtimeLogger.warn(`Ignored Sandbox Runtime Provider from non-system plugin ${pluginName} in scope ${scope}.`);
+            return;
+        }
+        super.upsert(instance);
+    }
+    constructor(discoveryService, reflector){
+        super(SANDBOX_RUNTIME_PROVIDER, discoveryService, reflector);
+        this.runtimeLogger = new Logger(SandboxRuntimeProviderRegistry_1.name);
+    }
+};
+SandboxRuntimeProviderRegistry = SandboxRuntimeProviderRegistry_1 = __decorate([
+    Injectable(),
+    __metadata("design:paramtypes", [
+        DiscoveryService,
+        Reflector
+    ])
+], SandboxRuntimeProviderRegistry);
+
+const SANDBOX_WORKSPACE_MAPPER = 'SANDBOX_WORKSPACE_MAPPER';
+/** Associates a workspace path mapper with a named Runtime Provider strategy. */ const SandboxWorkspaceMapperStrategy = (provider)=>applyDecorators(SetMetadata(SANDBOX_WORKSPACE_MAPPER, provider), SetMetadata(STRATEGY_META_KEY, SANDBOX_WORKSPACE_MAPPER));
+
+var SandboxWorkspaceMapperRegistry_1;
+/** Discovers Provider path mappers while enforcing the same system-level trust boundary as Providers. */ let SandboxWorkspaceMapperRegistry = SandboxWorkspaceMapperRegistry_1 = class SandboxWorkspaceMapperRegistry extends BaseStrategyRegistry {
+    upsert(instance) {
+        const target = resolveStrategyMetadataTarget(instance);
+        if (!target) {
+            return;
+        }
+        if (!this.reflector.get(SANDBOX_WORKSPACE_MAPPER, target)) {
+            return;
+        }
+        const pluginName = this.reflector.get(PLUGIN_METADATA_KEY, target);
+        var _this_reflector_get;
+        const scope = (_this_reflector_get = this.reflector.get(ORGANIZATION_METADATA_KEY, target)) != null ? _this_reflector_get : BUILTIN_GLOBAL_SCOPE;
+        if (pluginName && scope !== SYSTEM_GLOBAL_SCOPE) {
+            this.mapperLogger.warn(`Ignored Sandbox Workspace Mapper from non-system plugin ${pluginName} in scope ${scope}.`);
+            return;
+        }
+        super.upsert(instance);
+    }
+    constructor(discoveryService, reflector){
+        super(SANDBOX_WORKSPACE_MAPPER, discoveryService, reflector);
+        this.mapperLogger = new Logger(SandboxWorkspaceMapperRegistry_1.name);
+    }
+};
+SandboxWorkspaceMapperRegistry = SandboxWorkspaceMapperRegistry_1 = __decorate([
+    Injectable(),
+    __metadata("design:paramtypes", [
+        DiscoveryService,
+        Reflector
+    ])
+], SandboxWorkspaceMapperRegistry);
+
 const MANAGED_CONNECTION_REGISTRY_TOKEN = 'XPERT_MANAGED_CONNECTION_REGISTRY';
 const CONNECTION_COMMAND_ROUTER_TOKEN = 'XPERT_CONNECTION_COMMAND_ROUTER';
 
@@ -4681,4 +4801,4 @@ CollaborationDocumentProviderRegistry = __decorate([
     ])
 ], CollaborationDocumentProviderRegistry);
 
-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, ArtifactsRuntimeCapability, AssistantTaskRuntimeCapability, BOUND_IDENTITY_LOGIN_PERMISSION_SERVICE_TOKEN, BUILTIN_GLOBAL_SCOPE, BaseHTTPQueryRunner, BaseQueryRunner, BaseSQLQueryRunner, BaseSandbox, BaseStrategyRegistry, BaseTool, BaseToolset, BuiltinToolset, CHAT_CHANNEL, CHAT_CHANNEL_TEXT_LIMITS, COLLABORATION_DOCUMENT_PROVIDER, CONNECTION_COMMAND_ROUTER_TOKEN, CONNECTOR_STRATEGY, CancelConversationCommand, ChatChannel, ChatChannelRegistry, ChatOAICompatReasoningModel, CollaborationDocumentProvider, CollaborationDocumentProviderRegistry, CollaborationRuntimeCapability, CommonParameterRules, ConnectorRuntimeCapability, ConnectorStrategyKey, ConnectorStrategyRegistry, 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, derivePluginArtifactNamespace, downloadRemoteFile, formatSandboxTimeout, getDefaultTenantId, getErrorMessage, getModelContextSize, getPermissionOperationMetadata, getPositionList, getPositionMap, getRequestContext, getRequiredPermissionOperation, getTenantGlobalScopeKey, isRemoteFile, isSandboxBackend, isSandboxManagedServiceAdapter, isSandboxServiceProxyAdapter, isSandboxTerminalAdapter, isStructuredMessageType, isTenantGlobalScopeKey, loadYamlFile, mergeCredentials, mergeParentChildChunks, normalizeContextSize, pluginArtifactTableName, renderRemoteModuleIframeHtml, renderRemoteReactIframeHtml, renderRemoteVueIframeHtml, 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, ArtifactsRuntimeCapability, AssistantTaskRuntimeCapability, BOUND_IDENTITY_LOGIN_PERMISSION_SERVICE_TOKEN, BUILTIN_GLOBAL_SCOPE, BaseHTTPQueryRunner, BaseQueryRunner, BaseSQLQueryRunner, BaseSandbox, BaseStrategyRegistry, BaseTool, BaseToolset, BuiltinToolset, CHAT_CHANNEL, CHAT_CHANNEL_TEXT_LIMITS, COLLABORATION_DOCUMENT_PROVIDER, CONNECTION_COMMAND_ROUTER_TOKEN, CONNECTOR_STRATEGY, CancelConversationCommand, ChatChannel, ChatChannelRegistry, ChatOAICompatReasoningModel, CollaborationDocumentProvider, CollaborationDocumentProviderRegistry, CollaborationRuntimeCapability, CommonParameterRules, ConnectorRuntimeCapability, ConnectorStrategyKey, ConnectorStrategyRegistry, 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_JOB_ERROR_CODES, SANDBOX_PROVIDER, SANDBOX_RUNTIME_PROVIDER, SANDBOX_SHELL_TIMEOUT_LIMITS_SEC, SANDBOX_WORKSPACE_MAPPER, 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, SandboxJobRuntimeError, SandboxJobsRuntimeCapability, SandboxProviderRegistry, SandboxProviderStrategy, SandboxRuntimeProviderRegistry, SandboxRuntimeProviderStrategy, SandboxWorkspaceMapperRegistry, SandboxWorkspaceMapperStrategy, 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, derivePluginArtifactNamespace, downloadRemoteFile, formatSandboxTimeout, getDefaultTenantId, getErrorMessage, getModelContextSize, getPermissionOperationMetadata, getPositionList, getPositionMap, getRequestContext, getRequiredPermissionOperation, getTenantGlobalScopeKey, isRemoteFile, isSandboxBackend, isSandboxJobRuntimeError, isSandboxManagedServiceAdapter, isSandboxServiceProxyAdapter, isSandboxTerminalAdapter, isStrategyInstance, isStructuredMessageType, isTenantGlobalScopeKey, loadYamlFile, mergeCredentials, mergeParentChildChunks, normalizeContextSize, pluginArtifactTableName, renderRemoteModuleIframeHtml, renderRemoteReactIframeHtml, renderRemoteVueIframeHtml, resolveSandboxBackend, resolveSandboxExecutionOptions, resolveSandboxManagedServiceAdapter, resolveSandboxServiceProxyAdapter, resolveSandboxTerminalAdapter, resolveStrategyMetadataTarget, resolveTenantGlobalScopeKey, runWithRequestContext, secondsToMilliseconds, setDefaultTenantId, sumTokenUsage };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xpert-ai/plugin-sdk",
-  "version": "3.15.11",
+  "version": "3.15.12",
   "license": "AGPL-3.0",
   "repository": {
     "type": "git",
@@ -17,7 +17,7 @@
   },
   "dependencies": {
     "@langchain/openai": "0.6.9",
-    "@xpert-ai/contracts": "3.15.11",
+    "@xpert-ai/contracts": "3.15.12",
     "express": "^4.22.1",
     "js-tiktoken": "^1.0.21"
   },

package/src/lib/core/runtime-capability.d.ts

@@ -7,6 +7,7 @@ export declare function createRuntimeCapability<T>(id: string, options?: {
     description?: string;
 }): RuntimeCapabilityKey<T>;
 export interface RuntimeCapabilityRegistry {
+    register<T>(key: RuntimeCapabilityKey<T> | string, implementation: T): this;
     has<T>(key: RuntimeCapabilityKey<T> | string): boolean;
     get<T>(key: RuntimeCapabilityKey<T> | string): T | undefined;
     require<T>(key: RuntimeCapabilityKey<T> | string): T;

package/src/lib/managed-queue/index.d.ts

@@ -15,6 +15,15 @@ export type PluginJobProcessorMetadata = {
     jobName: string;
     concurrency?: number;
 };
+/** Physical worker pool chosen independently from a plugin's logical queue name. */
+export type ManagedQueueExecutionPool = 'default' | 'sandbox-browser';
+/** Readiness signal used to reject work before it is stranded in an unconsumed pool. */
+export type ManagedQueueExecutionPoolHealth = {
+    executionPool: ManagedQueueExecutionPool;
+    available: boolean;
+    workerCount: number;
+    warning?: string;
+};
 export type ManagedQueueRemoveOption = boolean | number | {
     age?: number;
     count?: number;
@@ -47,12 +56,15 @@ export type ManagedQueueEnqueueInput<TPayload = unknown> = {
     backoffMs?: ManagedQueueBackoffInput;
     removeOnComplete?: ManagedQueueRemoveOption;
     removeOnFail?: ManagedQueueRemoveOption;
+    /** Defaults to `default`; browser-heavy jobs must explicitly select the isolated pool. */
+    executionPool?: ManagedQueueExecutionPool;
 };
 export type ManagedQueueEnqueueResult = {
     jobId: string;
 };
 export type ManagedQueueCancelInput = {
     jobId: string;
+    executionPool?: ManagedQueueExecutionPool;
 };
 export type ManagedQueueCancelResult = {
     success: boolean;
@@ -100,7 +112,12 @@ export interface ManagedQueueService {
     cancel(input: ManagedQueueCancelInput): Promise<ManagedQueueCancelResult>;
     getJob<TPayload = unknown>(input: {
         jobId: string;
+        executionPool?: ManagedQueueExecutionPool;
     }): Promise<ManagedQueueJobSnapshot<TPayload> | null>;
+    /** Reports active BullMQ consumers for a physical execution pool. */
+    getExecutionPoolHealth(input: {
+        executionPool: ManagedQueueExecutionPool;
+    }): Promise<ManagedQueueExecutionPoolHealth>;
     getRedis(): Promise<ManagedQueueRedis>;
 }
 export declare function PluginJobProcessor(options: PluginJobProcessorOptions): ClassDecorator;

package/src/lib/runtime/capabilities/artifacts.d.ts

@@ -43,6 +43,10 @@ export type ArtifactVersionInput = {
 export type CreateArtifactVersionInput = ArtifactVersionInput & {
     artifactId: string;
 };
+/** Idempotently creates or reuses one immutable Artifact content version. */
+export type EnsureArtifactVersionInput = CreateArtifactVersionInput & {
+    idempotencyKey: string;
+};
 /** Access policy requested for an Artifact link. */
 export type ArtifactLinkAccessInput = {
     mode: ArtifactAccessMode;
@@ -66,6 +70,10 @@ export type CreateArtifactLinkInput = {
     presentation?: ArtifactLinkPresentationInput | null;
     metadata?: Record<string, unknown> | null;
 };
+/** Stable plugin-owned slot for one active durable share policy. */
+export type ArtifactShareInput = CreateArtifactLinkInput & {
+    shareKey: string;
+};
 /** Creates a short-lived signed preview link; never use this as a durable share URL. */
 export type CreateSignedArtifactPreviewLinkInput = Omit<CreateArtifactLinkInput, 'access'> & {
     ttlSeconds?: number | null;
@@ -76,6 +84,7 @@ export type ArtifactVersionRecord = {
     artifactId: string;
     versionNumber: number;
     status: ArtifactVersionStatus;
+    idempotencyKey?: string | null;
     sourceVersionId?: string | null;
     checksum?: string | null;
     mimeType: string;
@@ -84,6 +93,8 @@ export type ArtifactVersionRecord = {
     description?: string | null;
     size?: number | null;
     sha256?: string | null;
+    workspaceFileRef?: WorkspacePortableFileReference | null;
+    metadata?: Record<string, unknown> | null;
     createdAt?: string | Date;
 };
 /** Durable Artifact container returned to plugins. */
@@ -99,6 +110,7 @@ export type ArtifactRecord = ArtifactScopeInput & {
     description?: string | null;
     currentVersionId?: string | null;
     currentVersion?: ArtifactVersionRecord | null;
+    metadata?: Record<string, unknown> | null;
     createdAt?: string | Date;
     updatedAt?: string | Date;
 };
@@ -107,6 +119,7 @@ export type ArtifactLinkRecord = ArtifactScopeInput & {
     id: string;
     artifactId: string;
     artifactVersionId?: string | null;
+    shareKey?: string | null;
     versionMode: ArtifactLinkVersionMode;
     slug: string;
     publicUrl: string;
@@ -120,6 +133,7 @@ export type ArtifactLinkRecord = ArtifactScopeInput & {
     disposition: ArtifactLinkDisposition;
     allowDownload: boolean;
     safeHtmlProfile?: ArtifactSafeHtmlProfile | null;
+    metadata?: Record<string, unknown> | null;
     createdAt?: string | Date;
     updatedAt?: string | Date;
     artifact?: ArtifactRecord;
@@ -140,6 +154,27 @@ export type ListArtifactsResult = {
     page: number;
     pageSize: number;
 };
+export type FindArtifactBySourceInput = Pick<ArtifactSourceInput, 'pluginName' | 'resourceType' | 'resourceId'> & {
+    includeDeleted?: boolean | null;
+};
+export type ListArtifactVersionsInput = {
+    artifactId: string;
+    idempotencyKey?: string | null;
+    status?: ArtifactVersionStatus | 'all' | null;
+};
+export type EnsureArtifactVersionResult = {
+    version: ArtifactVersionRecord;
+    outcome: 'created' | 'reused';
+};
+export type ArtifactShareKeyInput = {
+    artifactId: string;
+    shareKey: string;
+};
+export type EnsureArtifactShareResult = {
+    link: ArtifactLinkRecord;
+    outcome: 'created' | 'reused' | 'replaced';
+    replacedLinkId?: string | null;
+};
 /** Mutable parts of an Artifact link; content versions remain immutable. */
 export type UpdateArtifactLinkAccessInput = {
     access?: ArtifactLinkAccessInput | null;
@@ -150,12 +185,18 @@ export type UpdateArtifactLinkAccessInput = {
 /** Platform runtime capability exposed to plugins for managing generated Artifacts. */
 export interface ArtifactsApi {
     createArtifact(input: CreateArtifactInput): Promise<ArtifactRecord>;
+    findArtifactBySource(input: FindArtifactBySourceInput): Promise<ArtifactRecord | null>;
     createArtifactVersion(input: CreateArtifactVersionInput): Promise<ArtifactVersionRecord>;
+    listArtifactVersions(input: ListArtifactVersionsInput): Promise<ArtifactVersionRecord[]>;
+    ensureArtifactVersion(input: EnsureArtifactVersionInput): Promise<EnsureArtifactVersionResult>;
     getArtifact(idOrSlug: string): Promise<ArtifactRecord>;
     listArtifacts(input?: ListArtifactsInput): Promise<ListArtifactsResult>;
     archiveArtifact(idOrSlug: string): Promise<ArtifactRecord>;
     deleteArtifact(idOrSlug: string): Promise<ArtifactRecord>;
     createArtifactLink(input: CreateArtifactLinkInput): Promise<ArtifactLinkRecord>;
+    getArtifactShare(input: ArtifactShareKeyInput): Promise<ArtifactLinkRecord | null>;
+    ensureArtifactShare(input: ArtifactShareInput): Promise<EnsureArtifactShareResult>;
+    revokeArtifactShare(input: ArtifactShareKeyInput): Promise<ArtifactLinkRecord | null>;
     createSignedPreviewLink(input: CreateSignedArtifactPreviewLinkInput): Promise<ArtifactLinkRecord>;
     updateArtifactLinkAccess(idOrSlug: string, patch: UpdateArtifactLinkAccessInput): Promise<ArtifactLinkRecord>;
     revokeArtifactLink(idOrSlug: string): Promise<ArtifactLinkRecord>;

package/src/lib/runtime/capabilities/index.d.ts

@@ -2,3 +2,4 @@ export * from './knowledgebase';
 export * from './knowledgebase-documents';
 export * from './artifacts';
 export * from './workspace-files';
+export * from './sandbox-jobs';

package/src/lib/runtime/capabilities/sandbox-jobs.d.ts

@@ -0,0 +1,142 @@
+import type { JSONValue } from '@xpert-ai/contracts';
+import type { WorkspaceFileScope, WorkspacePortableFileReference } from './workspace-files';
+/** Stable machine-readable failures emitted by the Sandbox Jobs capability. */
+export declare const SANDBOX_JOB_ERROR_CODES: readonly ["SANDBOX_ACTION_UNAVAILABLE", "SANDBOX_ACTION_INVALID", "SANDBOX_PROFILE_UNAVAILABLE", "SANDBOX_RUNTIME_UNAVAILABLE", "SANDBOX_VERSION_MISMATCH", "SANDBOX_CAPACITY_UNAVAILABLE", "SANDBOX_START_FAILED", "BROWSER_LAUNCH_FAILED", "EXPORT_TIMEOUT", "EXPORT_OOM", "EXPORT_INPUT_INVALID", "EXPORT_OUTPUT_INVALID", "SANDBOX_CANCELLED"];
+export type SandboxJobErrorCode = (typeof SANDBOX_JOB_ERROR_CODES)[number];
+/** Persisted lifecycle states for a generic isolated background execution. */
+export type SandboxJobStatus = 'waiting' | 'starting' | 'running' | 'succeeded' | 'failed' | 'cancelled' | 'lost';
+/** Portable Workspace Files input materialized under `/workspace/input`. */
+export type SandboxJobFileInput = {
+    /** Tenant-scoped portable reference; raw bytes never enter queue state. */
+    reference: WorkspacePortableFileReference;
+    /** Safe relative path below `/workspace/input`. */
+    targetPath: string;
+    /** Expected immutable byte length checked during materialization. */
+    size: number;
+    /** Expected lowercase SHA-256 checked during materialization. */
+    sha256: string;
+};
+/** Declares one output to validate and persist back into Workspace Files. */
+export type SandboxJobOutputRequest = {
+    path: string;
+    originalName: string;
+    mimeType: string;
+    destination: WorkspaceFileScope & {
+        folder: string;
+    };
+};
+/** Tenant and business ownership recorded for authorization, audit, and cleanup. */
+export type SandboxJobScope = {
+    tenantId: string;
+    organizationId?: string | null;
+    userId?: string | null;
+    pluginName: string;
+    businessResourceType: string;
+    businessResourceId: string;
+};
+/** Action-oriented request accepted from a plugin background handler. */
+export type SandboxJobRunInput = {
+    /** Optional caller-known UUID used when cancellation must be possible while run() is awaiting completion. */
+    jobId?: string;
+    action: string;
+    actionVersion: string;
+    /** Stable tenant-scoped key combining business identity and immutable input checksum. */
+    idempotencyKey: string;
+    scope: SandboxJobScope;
+    /** Small structured request; file bytes must be supplied through `files`. */
+    payload: JSONValue;
+    files?: SandboxJobFileInput[];
+    outputs: SandboxJobOutputRequest[];
+    /** Soft execution limit capped by the Runtime Definition's hard deadline. */
+    timeoutMs?: number;
+};
+/** Validated output evidence returned as a portable Workspace Files reference. */
+export type SandboxJobOutput = {
+    path: string;
+    originalName: string;
+    mimeType: string;
+    size: number;
+    sha256: string;
+    reference: WorkspacePortableFileReference;
+    fileUrl?: string;
+    workspacePath?: string;
+};
+/** Provider-neutral persisted view of a Sandbox Job and its runtime evidence. */
+export type SandboxJobSnapshot = {
+    id: string;
+    runtimeProfile: string;
+    sandboxRuntimeVersion: string;
+    action: string;
+    actionVersion: string;
+    status: SandboxJobStatus;
+    /** Attempt number; a new failed-job attempt may select a newly healthy Binding. */
+    attempt: number;
+    /** Provider and Binding are persisted so cleanup never depends on current selection. */
+    provider?: string | null;
+    runtimeBindingId?: string | null;
+    /** Opaque Provider identity used for reattachment and idempotent destruction. */
+    runtimeRef?: string | null;
+    artifactDigest?: string | null;
+    /** @deprecated Use runtimeRef. Kept for one compatibility cycle. */
+    containerRef?: string | null;
+    outputs: SandboxJobOutput[];
+    errorCode?: SandboxJobErrorCode | null;
+    errorMessage?: string | null;
+    createdAt?: Date | string | null;
+    startedAt?: Date | string | null;
+    finishedAt?: Date | string | null;
+};
+/** Successful `run()` result; failed executions reject with SandboxJobRuntimeError. */
+export type SandboxJobRunResult = SandboxJobSnapshot & {
+    status: 'succeeded';
+};
+/** Aggregated readiness of an Action, Runtime Definition, Worker, Binding, and Provider. */
+export type SandboxJobActionHealth = {
+    pluginName: string;
+    action: string;
+    actionVersion: string;
+    runtimeProfile?: string;
+    sandboxRuntimeVersion?: string;
+    provider?: string;
+    runtimeBindingId?: string;
+    artifactDigest?: string;
+    available: boolean;
+    reason?: 'ACTION_MISSING' | 'ACTION_INVALID' | 'PROFILE_MISSING' | 'VERSION_MISMATCH' | 'RUNTIME_UNBOUND' | 'PROVIDER_UNAVAILABLE' | 'PROFILE_UNHEALTHY';
+    message?: string;
+    manifest?: Record<string, string>;
+};
+/**
+ * Plugin-facing API for registered, structured Sandbox Actions.
+ *
+ * Callers choose only an Action and its version; images, commands, entrypoints,
+ * environment variables, and Provider options are resolved and enforced by Core.
+ */
+export interface SandboxJobsApi {
+    /** Starts, reattaches, or reuses a successful execution by tenant-scoped idempotency key. */
+    run(input: SandboxJobRunInput): Promise<SandboxJobRunResult>;
+    /** Cancels the logical Job and terminates its active Runtime when one exists. */
+    cancel(input: {
+        jobId: string;
+    }): Promise<SandboxJobSnapshot>;
+    /** Returns the active tenant's persisted Job snapshot, or null when inaccessible or absent. */
+    getJob(input: {
+        jobId: string;
+    }): Promise<SandboxJobSnapshot | null>;
+    /** Checks readiness before a product exposes or enqueues a browser-backed operation. */
+    getActionHealth(input: {
+        pluginName: string;
+        action: string;
+        actionVersion: string;
+    }): Promise<SandboxJobActionHealth>;
+}
+/** Error carrying retry policy and Job identity across plugin queue handlers. */
+export declare class SandboxJobRuntimeError extends Error {
+    readonly code: SandboxJobErrorCode;
+    readonly retryable: boolean;
+    readonly jobId?: string;
+    constructor(code: SandboxJobErrorCode, message: string, retryable: boolean, jobId?: string);
+}
+/** Narrows an unknown failure to the structured Sandbox Jobs runtime error contract. */
+export declare function isSandboxJobRuntimeError(error: unknown): error is SandboxJobRuntimeError;
+/** Runtime capability key used to resolve SandboxJobsApi from the platform registry. */
+export declare const SandboxJobsRuntimeCapability: import("../../core/runtime-capability").RuntimeCapabilityKey<SandboxJobsApi>;

package/src/lib/sandbox/index.d.ts

@@ -6,6 +6,12 @@ export * from './sandbox.decorator';
 export * from './sandbox.interface';
 export * from './sandbox.registry';
 export * from './terminal';
+export * from './runtime-provider';
+export * from './runtime-provider.decorator';
+export * from './runtime-provider.registry';
+export * from './workspace-mapper';
+export * from './workspace-mapper.decorator';
+export * from './workspace-mapper.registry';
 export * from './sandbox.interface';
 export * from './sandbox.decorator';
 export * from './sandbox.registry';

package/src/lib/sandbox/protocol.d.ts

@@ -155,6 +155,8 @@ export interface ExecuteResponse {
     truncated: boolean;
     /** Whether the command exceeded its timeout and was terminated */
     timedOut?: boolean;
+    /** Provider-observed container/process termination reason. */
+    terminationReason?: 'oom' | 'deadline' | 'cancelled' | 'container-died';
 }
 /**
  * Standardized error codes for file upload/download operations.
@@ -346,6 +348,8 @@ export interface SandboxBackendProtocol extends BackendProtocol {
     readonly id: string;
     /** Canonical sandbox environment identifier bound to this backend */
     readonly environmentId?: string | null;
+    /** Best-effort immediate termination for an ephemeral job sandbox. */
+    terminate?(): MaybePromise<void>;
 }
 export declare function isSandboxBackend(backend: unknown): backend is SandboxBackendProtocol;
 export declare function resolveSandboxBackend(sandbox: TSandboxConfigurable | SandboxBackendProtocol | null | undefined | unknown): SandboxBackendProtocol | null;

package/src/lib/sandbox/runtime-provider.d.ts

@@ -0,0 +1,181 @@
+/** Per-execution limits applied to the Runtime Definition's fixed Runner command. */
+export type SandboxRuntimeExecutionOptions = {
+    timeoutMs?: number;
+    maxOutputBytes?: number;
+};
+/** Provider-observed reason why a Runtime execution stopped without a normal exit. */
+export type SandboxRuntimeTerminationReason = 'oom' | 'deadline' | 'cancelled' | 'runtime-died';
+/** Normalized process result returned by every Sandbox Runtime implementation. */
+export type SandboxRuntimeExecuteResponse = {
+    output: string;
+    exitCode: number | null;
+    truncated: boolean;
+    timedOut?: boolean;
+    terminationReason?: SandboxRuntimeTerminationReason;
+};
+/** Portable failure categories for Runtime workspace file operations. */
+export type SandboxRuntimeFileOperationError = 'file_not_found' | 'permission_denied' | 'is_directory' | 'invalid_path';
+export type SandboxRuntimeFileUploadResponse = {
+    path: string;
+    error: SandboxRuntimeFileOperationError | null;
+};
+export type SandboxRuntimeFileDownloadResponse = {
+    path: string;
+    content: Uint8Array | null;
+    error: SandboxRuntimeFileOperationError | null;
+};
+/** Resource policy requested by a provider-neutral Runtime Definition. */
+export type SandboxRuntimeResources = {
+    memoryMb: number;
+    cpu: number;
+    shmSizeMb: number;
+    tempDiskMb: number;
+};
+/** Network access that a Provider must enforce for the Runtime instance. */
+export type SandboxRuntimeNetworkPolicy = {
+    mode: 'none' | 'internal-only';
+    allowedHosts?: string[];
+};
+/** Mandatory process and filesystem hardening for a Runtime instance. */
+export type SandboxRuntimeSecurity = {
+    runAsNonRoot: boolean;
+    readOnlyRootFilesystem: boolean;
+    noNewPrivileges: boolean;
+    dropCapabilities: 'all';
+};
+/** Isolation guarantees a Provider advertises before it can be selected. */
+export type SandboxRuntimeProviderCapabilities = {
+    isolation: 'process' | 'hardened';
+    ephemeral: boolean;
+    resourceLimits: boolean;
+    networkPolicy: boolean;
+    readOnlyRootFilesystem: boolean;
+};
+/** Minimum Provider guarantees required by a Runtime Definition. */
+export type SandboxRuntimeRequirements = SandboxRuntimeProviderCapabilities;
+/**
+ * Provider-neutral execution profile published by the Sandbox Runtime Suite.
+ *
+ * Definitions select no image, engine, plugin, or host path. The platform owns
+ * the fixed Runner command and matches it to a compatible Provider Binding.
+ */
+export type SandboxRuntimeDefinition = {
+    /** Stable profile identity referenced by Action manifests. */
+    name: string;
+    /** Trusted Runner Host argv. Plugin callers cannot override this value. */
+    command: readonly string[];
+    /** Runner Host protocol version shared with compatible Action Bundles. */
+    contractVersion: string;
+    /** Version of the Runtime Suite contents, independent of Provider version. */
+    sandboxRuntimeVersion: string;
+    timeoutMs: number;
+    hardDeadlineMs: number;
+    resources: SandboxRuntimeResources;
+    networkPolicy: SandboxRuntimeNetworkPolicy;
+    security: SandboxRuntimeSecurity;
+    requirements: SandboxRuntimeRequirements;
+    expectedManifest: Record<string, string>;
+};
+/** Immutable or provider-addressable runtime artifact selected by a Binding. */
+export type SandboxRuntimeArtifact = {
+    kind: 'oci-image' | 'filesystem' | 'remote-runtime';
+    /** Provider-native immutable address; OCI production references must include a digest. */
+    reference: string;
+    /** Normalized digest retained separately as runtime evidence when available. */
+    digest?: string;
+};
+/** Provider-owned mapping from one Runtime Definition to an executable artifact. */
+export type SandboxRuntimeBinding = {
+    /** Stable Provider-owned Binding identity persisted on every attempt. */
+    id: string;
+    runtimeProfile: string;
+    /** Must match the registered Provider strategy type. */
+    provider: string;
+    /** Lower values are preferred. Ties are resolved by provider and binding id. */
+    priority: number;
+    providerVersion: string;
+    artifact: SandboxRuntimeArtifact;
+};
+/** Result of verifying an engine, artifact, security guarantees, and Runtime manifest. */
+export type SandboxRuntimeBindingHealth = {
+    available: boolean;
+    reason?: string;
+    manifest?: Record<string, string>;
+};
+/** Job-isolated storage roots passed to a Provider without exposing them to plugins. */
+export type SandboxRuntimeVolume = {
+    /** Path visible to the Xpert process. */
+    serverRoot: string;
+    /** Path suitable for a provider-side bind mount. */
+    hostRoot: string;
+};
+/** Fully resolved policy used to create or reattach one ephemeral Job Runtime. */
+export type SandboxRuntimeCreateOptions = {
+    tenantId: string;
+    workFor: {
+        type: 'job';
+        id: string;
+    };
+    definition: SandboxRuntimeDefinition;
+    binding: SandboxRuntimeBinding;
+    volume: SandboxRuntimeVolume;
+    ephemeral: true;
+    resources: SandboxRuntimeResources;
+    networkPolicy: SandboxRuntimeNetworkPolicy;
+    security: SandboxRuntimeSecurity;
+    hardDeadlineMs: number;
+};
+/** Persisted evidence required to destroy a Runtime even after Provider reload. */
+export type SandboxRuntimeDestroyOptions = {
+    tenantId: string;
+    workFor: {
+        type: 'job';
+        id: string;
+    };
+    runtimeProfile: string;
+    runtimeBindingId: string;
+    artifact: SandboxRuntimeArtifact;
+    runtimeRef?: string | null;
+};
+/**
+ * Minimal execution surface required by Sandbox Jobs.
+ *
+ * Implementations must constrain `execute()` to the Definition's trusted Runner
+ * argv and must confine all file operations to `workspaceRoot`.
+ */
+export interface SandboxRuntimeInstance {
+    readonly id: string;
+    /** Absolute path visible inside the isolated Runtime, normally `/workspace`. */
+    readonly workspaceRoot: string;
+    /** Executes Core-supplied argv after the Provider verifies the trusted Runner prefix. */
+    execute(argv: readonly string[], options?: SandboxRuntimeExecutionOptions): Promise<SandboxRuntimeExecuteResponse>;
+    /** Writes files only inside the instance workspace and returns per-path failures. */
+    uploadFiles(files: Array<[string, Uint8Array]>): Promise<SandboxRuntimeFileUploadResponse[]>;
+    /** Reads files only inside the instance workspace and returns per-path failures. */
+    downloadFiles(paths: string[]): Promise<SandboxRuntimeFileDownloadResponse[]>;
+    /** Best-effort immediate termination used by cancellation and deadline handling. */
+    terminate?(): Promise<void> | void;
+}
+/**
+ * Small Provider SPI for background Sandbox Jobs.
+ *
+ * This interface is intentionally independent from the interactive Agent Sandbox
+ * backend protocol. Providers are registered only by built-ins or system plugins,
+ * are selected from declared Bindings, and must make `destroy()` idempotent.
+ */
+export interface ISandboxRuntimeProvider {
+    readonly type: string;
+    readonly version: string;
+    readonly capabilities: SandboxRuntimeProviderCapabilities;
+    /** Lists immutable artifacts this Provider can bind to Runtime Definitions. */
+    listBindings(): Promise<readonly SandboxRuntimeBinding[]> | readonly SandboxRuntimeBinding[];
+    /** Probes the engine and artifact without creating a business Job instance. */
+    getBindingHealth(input: {
+        definition: SandboxRuntimeDefinition;
+        binding: SandboxRuntimeBinding;
+    }): Promise<SandboxRuntimeBindingHealth>;
+    /** Creates or reattaches the unique Runtime instance for the supplied Job scope. */
+    create(options: SandboxRuntimeCreateOptions): Promise<SandboxRuntimeInstance>;
+    /** Idempotently reclaims a Runtime by persisted scope, Binding, and runtimeRef evidence. */
+    destroy(options: SandboxRuntimeDestroyOptions): Promise<void>;
+}

package/src/lib/sandbox/runtime-provider.decorator.d.ts

@@ -0,0 +1,3 @@
+export declare const SANDBOX_RUNTIME_PROVIDER = "SANDBOX_RUNTIME_PROVIDER";
+/** Marks a built-in or system-plugin class as a named Sandbox Runtime Provider strategy. */
+export declare const SandboxRuntimeProviderStrategy: (provider: string) => <TFunction extends Function, Y>(target: TFunction | object, propertyKey?: string | symbol, descriptor?: TypedPropertyDescriptor<Y>) => void;

package/src/lib/sandbox/runtime-provider.registry.d.ts

@@ -0,0 +1,9 @@
+import { DiscoveryService, Reflector } from '@nestjs/core';
+import { BaseStrategyRegistry } from '../strategy';
+import type { ISandboxRuntimeProvider } from './runtime-provider';
+/** Discovers Runtime Provider strategies and rejects organization-scoped executable infrastructure. */
+export declare class SandboxRuntimeProviderRegistry extends BaseStrategyRegistry<ISandboxRuntimeProvider> {
+    private readonly runtimeLogger;
+    constructor(discoveryService: DiscoveryService, reflector: Reflector);
+    upsert(instance: unknown): void;
+}

package/src/lib/sandbox/sandbox.interface.d.ts

@@ -39,6 +39,30 @@ export type SandboxProviderCreateOptions = {
      * Tenant identifier
      */
     tenantId?: string;
+    /** Registered runtime profile. Providers resolve this to an immutable image. */
+    profile?: string;
+    /** Immutable image reference selected by the profile registry. */
+    image?: string;
+    /** Job sandboxes are never reused after the action completes. */
+    ephemeral?: boolean;
+    resources?: {
+        memoryMb?: number;
+        cpu?: number;
+        shmSizeMb?: number;
+        tempDiskMb?: number;
+    };
+    networkPolicy?: {
+        mode: 'none' | 'internal-only';
+        allowedHosts?: string[];
+    };
+    security?: {
+        runAsNonRoot: boolean;
+        readOnlyRootFilesystem: boolean;
+        noNewPrivileges: boolean;
+        dropCapabilities: 'all';
+    };
+    /** Provider-enforced absolute lifetime for the sandbox. */
+    hardDeadlineMs?: number;
     workFor: {
         type: TSandboxWorkForType;
         id: string;
@@ -53,6 +77,22 @@ export interface ISandboxProvider<T extends SandboxBackendProtocol = SandboxBack
      * @param options
      */
     create(options?: SandboxProviderCreateOptions): Promise<T>;
+    /** Destroy an ephemeral sandbox by its stable work identity after process loss or cancellation. */
+    destroy?(options: SandboxProviderCreateOptions & {
+        containerRef?: string | null;
+    }): Promise<void>;
+    /** Provider-side image/runner readiness check used by profile health. */
+    getProfileHealth?(input: {
+        profile: string;
+        image?: string;
+        /** Exact trusted command used to read the runner manifest. */
+        manifestCommand?: readonly string[];
+        expectedManifest?: Record<string, string>;
+    }): Promise<{
+        available: boolean;
+        reason?: string;
+        manifest?: Record<string, string>;
+    }>;
     /**
      * Get default working directory for the sandbox instances
      */

package/src/lib/sandbox/workspace-mapper.d.ts

@@ -0,0 +1,20 @@
+import type { SandboxWorkspaceBinding } from './sandbox.interface';
+/** Server-visible and Provider-visible roots for the same isolated volume. */
+export type SandboxWorkspaceVolume = {
+    serverRoot: string;
+    hostRoot: string;
+};
+/** Optional server path to translate within a mapped volume. */
+export type SandboxWorkspaceMappingOptions = {
+    serverPath?: string;
+};
+/**
+ * Translates paths between platform volumes and Provider-visible workspaces.
+ * Engine-specific path logic belongs here instead of in OSS Volume services.
+ */
+export interface SandboxWorkspaceMapper {
+    /** Produces a Provider-visible binding for one path inside the isolated platform volume. */
+    mapVolumeToWorkspace(volume: SandboxWorkspaceVolume, options?: SandboxWorkspaceMappingOptions): SandboxWorkspaceBinding;
+    /** Converts a Provider-visible path back to its server path, rejecting escapes. */
+    mapWorkspaceToVolume(binding: SandboxWorkspaceBinding, workspacePath: string): string;
+}

package/src/lib/sandbox/workspace-mapper.decorator.d.ts

@@ -0,0 +1,3 @@
+export declare const SANDBOX_WORKSPACE_MAPPER = "SANDBOX_WORKSPACE_MAPPER";
+/** Associates a workspace path mapper with a named Runtime Provider strategy. */
+export declare const SandboxWorkspaceMapperStrategy: (provider: string) => <TFunction extends Function, Y>(target: TFunction | object, propertyKey?: string | symbol, descriptor?: TypedPropertyDescriptor<Y>) => void;

package/src/lib/sandbox/workspace-mapper.registry.d.ts

@@ -0,0 +1,9 @@
+import { DiscoveryService, Reflector } from '@nestjs/core';
+import { BaseStrategyRegistry } from '../strategy';
+import type { SandboxWorkspaceMapper } from './workspace-mapper';
+/** Discovers Provider path mappers while enforcing the same system-level trust boundary as Providers. */
+export declare class SandboxWorkspaceMapperRegistry extends BaseStrategyRegistry<SandboxWorkspaceMapper> {
+    private readonly mapperLogger;
+    constructor(discoveryService: DiscoveryService, reflector: Reflector);
+    upsert(instance: unknown): void;
+}

package/src/lib/strategy.d.ts

@@ -1,4 +1,4 @@
-import { OnModuleInit } from '@nestjs/common';
+import { OnModuleInit, type Type } from '@nestjs/common';
 import { DiscoveryService, Reflector } from '@nestjs/core';
 import { StrategyBus } from './core/strategy-bus';
 export declare class BaseStrategyRegistry<S> implements OnModuleInit {
@@ -11,7 +11,7 @@ export declare class BaseStrategyRegistry<S> implements OnModuleInit {
     protected pluginStrategies: Map<string, Set<string>>;
     constructor(strategyKey: string, discoveryService: DiscoveryService, reflector: Reflector);
     onModuleInit(): void;
-    upsert(instance: any): void;
+    upsert(instance: unknown): void;
     /**
      * Remove all strategies registered by the given plugin for the given scope.
      */
@@ -38,3 +38,7 @@ export declare class BaseStrategyRegistry<S> implements OnModuleInit {
      */
     list(organizationId?: string): S[];
 }
+/** Returns whether a discovered provider can carry decorator metadata. */
+export declare function isStrategyInstance(instance: unknown): instance is object;
+/** Resolves the class used for plugin and organization metadata without reflecting over primitive provider values. */
+export declare function resolveStrategyMetadataTarget(instance: unknown): Type<unknown> | null;